coordination-engine/spec/cross-owner-wait-mode-v0.1.md

Cross-owner wait handling mode v0.1

Status: specified (COORDINATION-WP-0005-T02). Not a live wake enablement. Owner: coordination-engine. Reconciles with: spec/worker-coordination-service-v0.1.md (do not fork leases, safety, TAMQ, or receipts). Ontology: spec/coordination-model-v0.2.md.

Problem

Repo A sets a task wait because repo B’s owner has not returned. Nobody observes B. The wait becomes a stranded inbox. That pattern is the top theme holding the open-workplan count up.

Mode (replace “set wait and hope”)

Entry

Any of:

1. A task is wait / needs_human and names another repo, owner, or workplan id.
2. A workplan is blocked on a depends_on target whose repo is not this repo.
3. A prj- driver lists both repos (preferred). If no driver exists, still open a case object from the waiting plan — do not author a new workplan.

Do not enter this mode for flavor: residual unless the flavor has been promoted.

Observe

Read the foreign owner’s record from State Hub (workplan, tasks, depends_on, flavor, repo classification). Do not copy their task list into this repo. Do not PATCH their tasks.

Attach

Open or attach a CoordinationCase (scenario_type: project_driver when a prj- workplan exists, otherwise scenario_type: cross_owner_wait). The waiting plan is the beneficiary. The foreign plan is the obligor commitment.

Act (only if the v0.1 service is already running)

Lease/wakeup only selected gita-registered worker targets for the implementer that is actually unblocked. Safety, sensitive-text stops, human flags, and “no silent reroute” are exactly the v0.1 worker service. This mode does not add a second wakeup path.

If the service is not running, the case still exists as a derived object and a hub-projectable receipt of observed / waiting. Agents follow the instruction pack instead of injecting workers.

Checkpoint

Reuse v0.1 checkpoint shape (summary, files_changed, next_action, blocked_reason, 8 KiB, local). blocked_reason stops automatic continuation. A checkpoint is not completion.

Fail closed

Missing authorization, unregistered target, residual-as-driver, or attempt to reassign another owner’s task → stopped with reason. Never silently re-assign.

Exit

Exit	Condition
satisfied	Obligor workplan/task reaches done/finished/archived
stopped	Safety, human, missing auth, residual driver
waiting	Foreign record still open; case remains attached

Receipt shape (hub-projectable)

Extends the v0.1 sanitized receipt (state, reason, lease/trigger ids). Additional fields (no payloads, no secrets):

scenario_type: project_driver | cross_owner_wait
case_id: string
driver_workplan_id: string?
driver_repo: string?
obligor_workplan_id: string
beneficiary_workplan_id: string
flavor: string?

Projection remains POST /progress/ with event_type: coordination_receipt as in the v0.1 Hub adapter. Queued edge-relay receipts are not proof of central publication.

Common estate pattern

Repo A (e.g. net-kingdom) blocked on repo B (e.g. key-cape, flex-auth, OpenBao owner). If HFACT-WP-0001 (or another prj- driver) already lists both, attach there. Otherwise derive cross_owner_wait from A’s waiting workplan. Observe B. Do not implement B’s tasks from A’s session. Do not message ops-warden for a secret.

Anti-patterns

• Stranded wait with no case and no observer
• Copying B’s tasks into A’s workplan
• Treating flavor: residual as a driver
• Inventing warden secret / asking ops-warden for API keys
• Enabling live worker injection as a side effect of documenting this mode