state-hub/docs/owner-return-handoff.md

Owner-return pickup preparation

STATE-WP-0094-T03 selects the existing Activity Core ActivityDefinition → ops_run → admitted owner harness path for recurring pickup. State Hub does not claim ops runs and its workplan launch queue is retired. This selection is a source integration boundary, not evidence that a definition or owner harness is admitted.

scripts/owner_return_handoff.py consumes the existing consistency checker's C-25 JSON. It produces deterministic event identities from repository, task record ID and message UUID. Duplicate findings and reordered scans yield the same candidates. Eligible candidates are reviewable owner returns, not unblocked tasks. The event is suitable for TaskSpec.triggering_event_id; the existing Activity Core idempotency key also includes the admitted definition and source IDs. Supply the approved ActivityDefinition UUID explicitly.

Before any future dispatch, obtain fresh Activity Core /ops-runs rows for the configured definition/repository. The planner correlates definition, repository and event: open/claimed remain pending, succeeded is completed pickup, and failed/expired require owner reconciliation. Duplicate correlated rows fail closed. Completed pickup does not imply the task's blocker is resolved or its file status should change. Malformed identities and checker collection errors fail closed. The module never opens a socket, schedules, dispatches, persists a receipt or changes a task. It does not invent a competing receipt ledger.

Remaining T03 integration

The Activity Core owner must identify an admitted definition, pinned harness profile and repository authority for the pickup; accept event/source binding; and supply the callable submission/receipt adapter. Use the existing ops-run unique key, lease and exact-repeat terminal close semantics. A list snapshot alone is not atomic dispatch: actual insertion must retain that server-side uniqueness. Message results must be paginated upstream: C-25 currently fetches at most 200 replies per counterpart, so a planner cannot claim complete coverage. An owner-approved review must precede live activation. No schedule was changed.

References: Activity Core docs/execution-queue-boundary.md, docs/ops-run-queue.md, src/activity_core/ops_run_queue.py (TaskSpec key and row projection); State Hub api/services/execution_queue.py and api/routers/ops_runs.py (read-only summary).

T05 graph freshness assessment

The authorized receiving rollout and immutable qualifier/null-clear parity are recorded separately in docs/evidence/2026-10-04-receiving-rollout.json. They do not establish task-edge or scheduled freshness coverage.

Current api/services/forge_projection.py neither derives depends_on edges nor reconciles WorkplanDependency rows. The snapshot returns existing edges, which is not evidence that normal Forge receiving maintains them. In contrast, scripts/consistency_check.py C-20 indexes frontmatter and task-block edges, using from_task_id; its fix path calls the dependency API. C-40 independently reads authoritative source target status. Task-level dependency schema support therefore exists while the normal receiving gap remains real.

A bounded next receiving design must define full source edge ownership, cross-repository target resolution, missing/ambiguous targets, edge removal, transactional failure and repeat noop; it must preserve externally authored relations instead of deleting every dependency row. Adding graph receiving without that contract would create another destructive projection risk.

Current chart values disable legacy sweep; workstation checkout traversal is excluded by ADR-002. Activity Core owns scheduling and Repo Manager owns the C-rule engine. No source reading or one successful normal sync establishes actual live schedule coverage, freshness SLA or full repository coverage. Retain T05 progress until accepted edge receiving and bounded freshness evidence include exact runner revision, active definition, per-repository source commit, last successful receipt, failed/queued receipts and measured freshness window. Historical registrar failures remain explicit coverage holes. Do not revive legacy --all --remote sweeping or collapse T03 pickup into T05 index freshness.

Validation

The staged offline module and regression suite passed 13 tests on 2026-10-04. The tests cover pair identity and replay, existing pending/success/failure rows, wrong-definition/repository/event receipts, ambiguous duplicate receipts, malformed message identity, collection error and legacy workplan-only warnings. This proves source planning behavior, not deployed pickup or owner acceptance.

Current eligibility guard (review refinement)

C-25 alone also reports owner replies on tasks that still require a human. The first 13-test preparation did not model this independent gate. Review found that omission before commit/activation; the refinement requires current_tasks and an explicit observed_on date. Its 30 offline tests pass. No automated pickup was dispatched by either preparation.

Callers must build the mapping from fresh authoritative source, keyed by task record ID, and bind it to the same repository/source revision used for the scan. Each row explicitly includes target_repo, task_record_id, task status, workplan_status, workplan_flavor, boolean needs_human, blocked_on, depends_on, predecessor_statuses, wait_until, decision_id and decision_status. Resolve every task/workplan predecessor and the decision from the authoritative current graph; missing targets remain unknown. The offline module cannot authenticate a supplied source snapshot, so acquisition/binding is a mandatory part of the pending adapter contract. Never manufacture an empty predecessor list to compensate for the existing Forge dependency-edge gap.

Missing eligibility fields refuse planning. Human-needed work, unresolved or unknown decisions, residual flavor, closed workplans, non-wait tasks, mismatched repo/task/owner marker, nonterminal or unknown predecessors and future windows produce stopped. Even matching successful ops-run history cannot override a current safety stop. Residual promotion means an authoritative flavor change; a comment or receipt does not promote it. Terminal predecessors/resolved non-human decisions and elapsed windows can leave an owner-return wait reviewable; that disposition permits review preparation only and never clears the wait marker, task status, human gate or any other field.