Summary

• add a plugin host workflow API for requesting one same-session continuation lease
• add a matching clear API for terminal/paused states
• pass trusted session context through the API instead of accepting model-selected session routing
• expose the workflow API through the plugin SDK
• add focused scheduled-turn contract coverage

Why

Agents can already continue work when the model stays on target and the runtime path is lucky. The missing runtime primitive is a narrow, reviewable way for a feature to ask for one follow-up turn in the same trusted session, with host-owned routing and an explicit clear path.

This PR adds that primitive without adding a new autonomous product surface. A bundled plugin can ask the host to enqueue the next turn for the same trusted session, without introducing cross-session targeting, fanout, or model-selected routing.

This is intentionally narrower than #79925. It does not add silent wake modes, cross-session delegation, trusted insertion into sibling sessions, or host-wide fanout. It is also complementary to #85232: that PR recovers an already-queued stuck session; this API gives a plugin a narrow way to create one same-session follow-up turn in the first place.

Safety

• session identity comes from host-owned command/tool context
• callers pass session: ctx; the model does not provide a target sessionKey
• continuation leases are same-session only
• replacement is best-effort on the existing scheduled-turn host hook
• clear removes the matching same-session lease when a feature reaches a stop state
• the SDK test helper exposes no-op defaults for both workflow APIs, so downstream plugin tests can use the new facade without custom stubs

Tests

pnpm exec vitest run --config test/vitest/vitest.contracts-plugin.config.ts \
  src/plugins/contracts/host-hooks.contract.test.ts \
  src/plugins/contracts/scheduled-turns.contract.test.ts \
  src/plugins/contracts/plugin-sdk-index.test.ts \
  src/plugins/contracts/plugin-sdk-index.bundle.test.ts \
  src/plugins/contracts/plugin-sdk-subpaths.test.ts

pnpm tsgo:core:test
pnpm build

Also verified as part of the stacked branch:

pnpm exec vitest run --config test/vitest/vitest.contracts-plugin.config.ts \
  src/plugins/contracts/host-hooks.contract.test.ts \
  src/plugins/contracts/scheduled-turns.contract.test.ts \
  src/plugins/contracts/plugin-sdk-index.test.ts \
  src/plugins/contracts/plugin-sdk-index.bundle.test.ts \
  src/plugins/contracts/plugin-sdk-subpaths.test.ts \
  src/plugins/contracts/package-manifest.contract.test.ts \
  src/plugins/contracts/plugin-entry-guardrails.test.ts \
  src/plugins/contracts/plugin-tool-contracts.test.ts

Real behavior proof

• Behavior or issue addressed: Plugin code can request and clear a same-session continuation lease through the new SDK workflow facade without taking a model-provided session target.
• Real environment tested: Local OpenClaw checkout tmp/upstream-prs/openclaw-goal on branch goal-command-minimal, commit 1e24225457, with the scaffold commit 325f4c1f27 underneath.
• Exact steps or command run after this patch: Ran a live pnpm exec tsx command in the checkout that imports createTestPluginApi() from src/plugin-sdk/plugin-test-api.ts, then calls api.session.workflow.requestSessionContinuationLease(...) and api.session.workflow.clearSessionContinuationLease(...) with sessionKey: "agent:proof:session" and leaseKey: "active-goal".
• Evidence after fix: Terminal output from that command:

{"request":{"enqueued":false,"reason":"test plugin api"},"clear":{"removed":0,"failed":0}}

• Observed result after fix: The SDK test API exposes both workflow methods and they return structured results instead of throwing or being absent. The contract tests cover the real scheduled-turn host hook replacement/clear behavior; this live command verifies the public SDK facade is callable from a real checkout.
• What was not tested: No production gateway was started for this scaffold-only PR; the follow-up /goal PR includes a live command-handler proof for the user-facing flow.

Follow-up

A stacked follow-up PR adds the user-facing /goal command on top of this API: #85723.

That PR is the concrete product proof for this runtime primitive: humans get lifecycle controls and lightweight observability, while the model only gets bounded same-session continuation through goal_status.

I am happy to keep the two PRs stacked for easier review or combine them if maintainers prefer one review thread.