Summary

• Problem: detached task lifecycle calls were imported directly from src/tasks/task-executor.ts across ACP, cron, gateway, subagent, and background-task paths, leaving no clean seam for alternate detached-work execution.
• Why it matters: we want to explore plugin-backed or externally managed detached execution without forking Tasks/TaskFlow or duplicating task state logic in core.
• What changed: added src/tasks/detached-task-runtime.ts as a behavior-preserving lifecycle seam, rerouted detached-run callers to it, and added seam contract coverage.
• What did NOT change (scope boundary): no task schema changes, no TaskFlow changes, no executor semantics changes, no retry/crash-recovery/stall-detection implementation, and no plugin registration yet.

Change Type (select all)

• Bug fix
• Feature
• Refactor required for the fix
• Docs
• Security hardening
• Chore/infra

Scope (select all touched areas)

• Gateway / orchestration
• Skills / tool execution
• Auth / tokens
• Memory / storage
• Integrations
• API / contracts
• UI / DX
• CI/CD / infra

Linked Issue/PR

• Closes #
• Related minions: durable SQLite-backed job queue for subagents, ACP, CLI, and cron #68718
• This PR fixes a bug or regression

Root Cause (if applicable)

• Root cause: detached-work lifecycle was coupled directly to core task-executor imports in each caller, so there was no narrow override point for alternate executor/runtime ownership.
• Missing detection / guardrail: no seam-contract test existed to prove callers routed through an overridable lifecycle runtime.
• Contributing context (if known): PR minions: durable SQLite-backed job queue for subagents, ACP, CLI, and cron #68718 explored a second detached execution substrate; this PR is the first extraction step so that future work can extend Tasks rather than bypass them.

Regression Test Plan (if applicable)

• Coverage level that should have caught this:
  • Unit test
  • Seam / integration test
  • End-to-end test
  • Existing coverage already sufficient
• Target test or file:
  • src/tasks/detached-task-runtime.test.ts
  • src/gateway/server-methods/agent.test.ts
  • Existing touched-surface tests in ACP, cron, agents, and gateway
• Scenario the test should lock in: detached-run callers use the seam, and existing task-registry behavior is preserved after rerouting imports.
• Why this is the smallest reliable guardrail: it proves both the seam dispatch itself and one representative caller path, while existing behavior tests cover the rest of the touched surfaces.
• Existing test that already covers this (if any): ACP manager, gateway async agent runs, cron manual/timer runs, ACP spawn, subagent lifecycle, media background flows, and context-engine maintenance already covered preserved behavior.
• If no new test is added, why not: N/A

User-visible / Behavior Changes

None.

Diagram (if applicable)

Before:
[detached caller] -> task-executor lifecycle functions

After:
[detached caller] -> detached-task-runtime seam -> default task-executor lifecycle functions

Security Impact (required)

• New permissions/capabilities? No
• Secrets/tokens handling changed? No
• New/changed network calls? No
• Command/tool execution surface changed? No
• Data access scope changed? No
• If any Yes, explain risk + mitigation:

Repro + Verification

Environment

• OS: macOS on mb-server
• Runtime/container: Node 22 / pnpm workspace
• Model/provider: N/A
• Integration/channel (if any): gateway, ACP, cron, subagent runtime paths
• Relevant config (redacted): default test harness config

Steps

1. Add src/tasks/detached-task-runtime.ts as a delegating lifecycle seam.
2. Reroute detached lifecycle call sites to import the seam instead of task-executor directly.
3. Add a seam-contract unit test and a gateway caller-level seam dispatch test.
4. Rebase onto latest origin/main and run the targeted touched-surface tests.

Expected

• Existing detached task behavior remains unchanged.
• Callers can be intercepted through the seam.

Actual

• Targeted tests passed.
• pnpm build on mb-server hit an existing runtime-postbuild bundled-plugin dependency staging issue in the installed workspace graph, not an error in the seam diff itself.

Evidence

• Failing test/log before + passing after
• Trace/log snippets
• Screenshot/recording
• Perf numbers (if relevant)

Human Verification (required)

• Verified scenarios:
  • targeted tests for tasks seam, gateway agent, ACP manager, cron ops/timer, ACP spawn, subagent lifecycle, sessions-spawn lifecycle, media background flows, and context-engine maintenance
  • rebase onto latest origin/main
  • branch push to origin
• Edge cases checked:
  • seam dispatch can be overridden in tests
  • gateway async run still creates task records through the seam
  • cron still tolerates ledger create/update failures through the seam
• What you did not verify:
  • full repo-wide build on mb-server due unrelated runtime-postbuild dependency staging issue in the installed workspace graph
  • any alternate executor/plugin implementation beyond the seam extraction

Review Conversations

• I replied to or resolved every bot review conversation I addressed in this PR.
• I left unresolved only the conversations that still need reviewer or maintainer judgment.

Compatibility / Migration

• Backward compatible? Yes
• Config/env changes? No
• Migration needed? No
• If yes, exact upgrade steps:

Risks and Mitigations

• Risk: future callers might bypass the seam and import task-executor directly again.
  • Mitigation: added direct seam dispatch coverage plus a representative caller-level seam test.
• Risk: this seam alone does not solve executor ownership, crash recovery, retry, or stall detection.
  • Mitigation: kept scope explicit; those belong in follow-up work, not hidden inside this PR.