@moretea-labs/forge 1.6.0 → 1.7.1

package/docs/architecture/current/human-interaction-plane.md

@@ -1,87 +0,0 @@
-# Human Interaction Plane
-
-## Purpose
-
-The Human Interaction Plane preserves a provider session while a person completes CAPTCHA, login, two-factor authentication, device unlock, biometric approval, or another step that automation must not perform.
-
-## Current Browser Implementation
-
-```text
-bounded plugin action
-  -> durable interaction record
-  -> detached browser handoff host
-  -> visible persistent browser + foreground presentation
-  -> explicit resolve_handoff(resume|cancel)
-  -> close browser context
-  -> write terminal state and release profile
-```
-
-The host is not a Controller, scheduler, Gateway, or MCP server. It owns one browser profile and survives the bounded Worker that requested the handoff.
-Browser CDP attach mode is not a human handoff owner; handoff still launches and fences the managed profile path for the saved session, then releases it only through the terminal handoff state.
-
-Records live below `.forge/interactions/<provider>/` as atomic session, launch, and command files. They contain provider/session identity, Work ownership, host PID/heartbeat, expiry, bounded URL/title results, and capability-local errors. They never copy cookies, passwords, verification codes, or user-entered form values.
-
-## State and Ownership
-
-```text
-starting -> waiting_for_user -> closing -> completed | closed | failed
-                         \-----------------> failed
-```
-
-- `starting`, `waiting_for_user`, and `closing` own the selected profile.
-- Ordinary browser actions and session deletion are rejected while the profile is owned.
-- Resume/cancel use separate command files, avoiding concurrent state-file writers.
-- Status reads derive stale/dead state without writing files or signalling processes; the next handoff start persists dead-host outcomes and prunes old terminal records to a bounded set.
-- The host enforces its own expiry and remains `closing`; the profile is released only after the browser context closes and terminal state is written.
-- Final URL/title are saved only after an explicit resume request.
-
-## Security and Failure Isolation
-
-- Existing domain allowlists apply during handoff and again on resume.
-- The host uses Playwright foregrounding plus best-effort macOS application activation.
-- Human actions are not represented as automated evidence.
-- Handoff does not weaken authorization or strong-confirmation requirements for purchases, payment, deletion, or other irreversible actions.
-- Host failure is capability-local and must not degrade Controller, repository, or unrelated plugin readiness.
-
-## Public Contract
-
-The browser plugin exposes three actions:
-
-- `request_human_handoff` — start and foreground a saved session.
-- `get_handoff_status` — read/reconcile durable state.
-- `resolve_handoff` — explicitly resume or cancel.
-
-The small surface limits additional plugin schema growth and avoids alias actions with overlapping semantics.
-
-## Optional agent-device iOS Provider
-
-The existing `ios` plugin includes an optional `agent-device` provider with these boundaries:
-
-- The local CLI must satisfy the reviewed `>=0.19.3 <0.21.0` capability/help contract. Status and evidence record its resolved executable, actual version and contract fingerprint. Forge never downloads tooling at action time.
-- The exact optional `agent-device@0.20.2` package provides the typed read-only snapshot backend on Node 22.12 or newer; Node 20 and unavailable/mismatched typed packages fall back to the reviewed CLI contract with explicit evidence. CLI absence or incompatibility degrades only this optional provider. Existing Xcode, `simctl`, build, launch, screenshot, and smoke-review readiness remains unchanged.
-- Device inventory comes from bounded `agent-device devices --platform ios --json` output. Simulator selection resolves to exactly one already-booted simulator. A physical iPhone is accepted only through an explicit exact name or UDID and must be connected; unavailable targets and ambiguous names are rejected before app actions.
-- Physical sessions use the shared `ios-device` ownership fence while simulator sessions continue to use `ios-simulator`. The interaction record separately declares the `agent-device` or `coredevice` execution engine, so the two implementations cannot consume each other's sessions while still mutually excluding access to the same phone. Legacy schema-v1 records use bounded prefix/reason inference only. Signing inputs are limited to non-secret team and reverse-DNS bundle identifiers, are stored beside the Controller-owned interaction state, and are mapped to agent-device environment variables without persisting certificates, profiles, pairing records, or credentials.
-- `agent_device_prepare` explicitly builds, signs, installs, and health-checks the XCTest Runner. Readiness is never inferred from inventory alone: a paired phone can be listed while Runner preparation still fails because the phone is locked, the developer tunnel is unreachable, or signing is incomplete.
-- `agent_device_jd_search` is a narrow physical-device workflow for `com.360buy.jdmobile`. It accepts a bounded product-information query, uses accessibility evidence to locate the search field, submits through an explicit target or keyboard return, and returns bounded visible result text. Fresh one-shot calls retain the compatibility behavior of writing one Controller-owned PNG and closing. A caller may instead supply one active physical-iPhone JD `interaction_id`; the trusted warm path reuses that exact fenced session, skips device inventory and app open, defaults to no screenshot, and leaves the session active for the next bounded action. Non-JD, simulator, terminal, expired, or unknown interactions fail before the search batch. Credentials, verification, biometrics, checkout, purchase, order submission, and payment semantics are rejected before mutation.
-- Each interaction receives an isolated `AGENT_DEVICE_STATE_DIR` and explicit session name. Direct session commands are serialized by exact interaction identity before process launch, while the provider session lock rejects cross-process collision; only a fixed argv allowlist is exposed, and the provider never invokes `agent-device mcp` or arbitrary commands. The MCP request cancellation signal and the caller's bounded timeout flow only through the current action, are never persisted, and terminate the complete child process group before cleanup. A command cancelled while waiting for its interaction turn never touches or terminalizes that session.
-- Screenshots stay in Controller-owned artifact storage. JSON responses are capped before entering evidence; event payload fields and direct fill results are redacted.
-- Open accepts only an app name or bundle identifier, not a URL or token-bearing deep link. `fill` is limited to non-sensitive text; passwords and verification codes must be entered manually.
-- Command failure, explicit close, or the next access after expiry attempts to close the provider session. Terminal state is written only after close succeeds. For an exact session inside its isolated `AGENT_DEVICE_STATE_DIR`, provider code `SESSION_NOT_FOUND` is also terminal success: it proves there is no provider-owned session left, so the local fence is released rather than remaining permanently `closing`. Other cleanup failures remain `closing`, keep device ownership fenced, and can be retried through the idempotent close action. Fill arguments and diagnostics are redacted from failure evidence. The lightweight interaction record remains bounded, while the provider daemon and a healthy XCTest Runner use configurable finite idle retention (five minutes by default) so adjacent trusted actions do not repeatedly pay cold-start cost; explicit close still terminates ownership immediately.
-- Physical iPhone mutation is limited to an explicitly selected device, a healthy signed Runner, authorized typed actions, and the same cleanup/redaction fence. Closing never shuts down a physical phone.
-
-
-## Physical iOS Computer Use boundary
-
-The iOS plugin treats a paired physical iPhone as a separate `ios-device` ownership provider. CoreDevice remains the baseline path, while agent-device is an optional signed XCTest engine for bounded direct UI automation.
-
-The CoreDevice layer is authoritative for bounded device discovery, exact installed-app lookup, foreground application launch, and native PNG screen capture. Device selection is exact by CoreDevice identifier, UDID, or an unambiguous exact name. Responses omit serial numbers, ECIDs, application container paths, pairing records, and signing material.
-
-UI-tree inspection and input injection are optional. They can use either a separately installed WebDriverAgent-compatible runner forwarded to the configured unauthenticated localhost endpoint, or the pinned local agent-device XCTest Runner prepared with an explicitly supplied Apple team and unique runner bundle identifier. Forge never downloads automation tooling at action time or persists signing credentials. A missing or unhealthy runner leaves CoreDevice launch and screenshot available while UI actions fail closed with typed prerequisite errors.
-
-Every physical-device mutation is serialized through the interaction session. Text input is removed from results and event evidence. Passwords, passcodes, verification codes, biometric prompts, account recovery, purchases, checkout submission, order confirmation, and payment semantics are human-only. The provider does not jailbreak devices, bypass device locks, solve CAPTCHAs, accept tokenized deep links, or shut down or erase the phone when a session closes.
-
-## Browser CDP execution boundary
-
-Browser interaction sessions keep one durable session and tab-resume model across all Browser modes. When the Gateway is Bun-hosted and the selected mode is `attach_preferred`, the interaction plane crosses a narrow Node process boundary for the complete Browser page action. This boundary exists solely to host Playwright's CDP WebSocket connection; policy checks, domain allowlisting, tab matching, session persistence, diagnostics, and action behavior remain implemented by the shared Browser adapter.
-
-The bridge uses bounded stdin/stdout JSON, a minimal child environment, an explicitly resolved Node executable, no shell, and bounded startup/action lifetime. A host marker prevents recursion. Test runtime hooks bypass the bridge so deterministic adapter unit tests remain in-process. Attached-browser teardown is `disconnect`, preserving the user's Chrome process and login state; managed persistent and isolated contexts retain their existing close semantics.

package/docs/architecture/current/implementation-status.md

@@ -1,128 +0,0 @@
-# Forge Runtime Implementation Status
-
-> Status: **Runtime Authority**  
-> Baseline: **Canonical Forge Runtime — 2026-08-06**
-
-## Completion Statement
-
-The **Canonical Single Runtime vertical slice** is implemented in executable code:
-
-```text
-forge-runtime
-  -> MCP Transport
-  -> Controller Services
-  -> Scheduler and Repository Actors
-  -> Process Runtime and Workers
-  -> Evidence, Artifact, and Projection planes
-```
-
-One Runtime Root owns lifecycle, readiness, scheduling, process fencing, and the active whole-release identity. Standalone Recovery owns independent observation, bounded restart, and active/previous whole-release rollback. Supervisor, runtime slots, independent Daemon authority, component rollout, KeepAlive commands, and compatibility configuration authority are deleted.
-
-## Capability Matrix
-
-| Capability | Status | Runtime evidence |
-| --- | --- | --- |
-| Thin MCP Gateway | Implemented | `src/runtime/gateway/mcp/router.ts`, `src/cli/mcp/server.ts`, `src/cli/mcp/transports/http.ts` |
-| Thin Harness V1 Fast Path | Implemented | `src/runtime/execution/thin-harness/` router, fast executor, receipts, typed batch, lightweight lanes; eligible short repository commands skip Local Job / ExecutionJob; docs in `thin-harness-v1.md` |
-| Deterministic MCP transport lifecycle | Implemented | global `McpSessionRegistry`, stream leases, active-POST protection, capacity-aware `/ready`, and recoverable tool-surface fencing that keeps the stale transport alive until replacement initialize supersedes it |
-| Unified Process Runtime | Implemented | `src/runtime/execution/process-runtime/`; repository commands and checks spawn once, return stable Process handles, preserve output/completion state, and attach later status/wait/log/cancel calls without re-execution |
-| Independent daemon lifecycle | Deleted | `runtime-status-client.ts` is read-only observation over Canonical Forge Runtime state and cannot start, replace, recover, or fence Workers |
-| Canonical Single Runtime | Implemented in source; live activation separately authorized | `src/runtime/root/` starts Controller Services, SQLite, Scheduler, Gateway Adapter, and MCP Transport under one lifecycle owner |
-| Legacy Supervisor/Ingress/slot lifecycle | Deleted | Supervisor, Stable Ingress, slots, bootstrap authority, restart coordinator, component rollout/rollback, and repository lifecycle scripts are absent and guarded against reintroduction |
-| Isolated Worker processes | Implemented | `src/runtime/execution/workers/worker-entry.ts`, Scheduler process spawning |
-| Per-Repository Actor | Implemented | `src/runtime/control-plane/repo-actor/actor.ts`, actor registry and repository mailbox lock |
-| Resource Claims | Implemented | `src/runtime/gateway/mcp/resource-policy.ts`, `resources/claims/conflicts.ts` |
-| Renewable Leases and fencing tokens | Implemented | `src/runtime/resources/leases/store.ts` |
-| Zombie Worker exclusion | Implemented | attempt/PID/exact-Lease ownership on heartbeat, renewal, release and terminal writes |
-| Workspace single writer | Implemented | Workspace Claim conflicts and eligible automatic Worktree placement |
-| Concurrent Worktrees with serialized integration | Implemented | unique Worktree Claims plus exclusive Integration/Git-ref Claims |
-| Global fair scheduler | Implemented | priority aging, persisted repository fairness, global/repository quotas |
-| Provider and host budgets | Implemented | Worker, Agent provider, Heavy Check, memory and CPU-load admission limits |
-| Durable reconciliation | Implemented | heartbeat, deadline, Operation Receipt recovery, safe retry and ambiguous-mutation stop |
-| Startup recovery before readiness | Implemented in Canonical Runtime | SQLite, Controller Services and in-process Scheduler initialize before MCP end-to-end probe; any fatal core failure makes the one Runtime readiness false and stops the complete Runtime |
-| Canonical repository command input | Implemented | typed argv is validated and direct-spawned without shell reparsing; legacy strings use one explicit compatibility shell boundary |
-| Active/recent/request indexes | Implemented | Execution Job, Agent Run, Task-to-Run, pending integration, Local Job, Occurrence, Portfolio and Finding indexes |
-| Schedule, Trigger, Decision and Occurrence | Implemented | interval/manual/UTC cron/calendar/condition/event/dependency triggers, bounded Occurrence and persisted Decision |
-| Schedule safety policy | Implemented | Shadow Mode, max-active, daily budget, cooldown, exponential backoff, failure circuit breaker and stop conditions |
-| Candidate Finding governance | Implemented | semantic dedupe, evidence, observation count and explicit human promotion |
-| Personal-assistant plugin manifests and registry | Implemented | `src/runtime/plugins/`, Controller Home `plugins/`, MCP and Local Controller discovery |
-| Portfolio DAG and Saga | Implemented | dependency-cycle rejection, deterministic stop and compensation under `src/runtime/workflow/portfolio/` |
-| Evidence Plane | Implemented | unified append-only events, exact-revision evidence, Operation Receipts and bounded Artifacts |
-| Materialized projections | Implemented | dirty-marker invalidation, indexed runtime projections and non-blocking Controller Context refresh |
-| Release Freeze and Gate | Implemented | exclusive `release:<repoId>` Lease and deterministic exact-revision release manifest |
-| External side-effect authorization | Implemented | Gateway/Portfolio/Schedule/Worker defense-in-depth policy |
-| Whole-Runtime readiness | Implemented in the Canonical Runtime source path | Public readiness is one `ready: boolean`; database, Scheduler, release coherence, MCP transport and repository checks are diagnostic evidence rather than independent lifecycle states |
-| Legacy compatibility | Implemented | stable MCP facade, unchanged compatibility fingerprint, Local Job projection into Execution Job |
-| Work-only execution contract convergence | Implemented for Work-backed Tasks | `WorkContract` owns objective/scope/check/risk/status/phase and completion receipt; linked Task fields are read projections, PlanStep retains `workId`, and receipt/revision/cleanup gates fail closed |
-| Node/Bun process portability | Implemented | project TypeScript Loader and bounded Worker/child process execution; Bun remains the supported package/test runtime |
-
-## Public Contract and Tool Surface
-
-The normal ChatGPT-facing MCP surface is a bounded **19-tool** schema. The five preferred orchestration facades are `rh_status`, `rh_access`, `rh_inbox`, `rh_context`, and `rh_work`. Repository selection, `repository_command_execute`, bounded source read/patch, focused checks, typed plugin dispatch, Process lifecycle, and bounded result access complete the default surface defined by `src/cli/mcp/toolset-names.ts`.
-
-The Runtime keeps internal atomic handlers and an exhaustive `full` compatibility profile without advertising them to ordinary ChatGPT discovery. `core` remains a compatibility label for the same bounded default surface. Request/Full Access changes execution authorization, not tool discovery.
-
-Small understood work is Direct-first. Repository commands and checks use Unified Process Runtime and return one stable Process lifecycle; known-long calls can return a handle immediately, while later `process_get`, `process_wait`, `process_logs`, and `process_cancel` attach to that same physical execution. Durable Work, isolated worktrees, or workers are introduced when recovery, dependency tracking, isolation, parallelism, or a longer lifecycle actually requires them.
-
-Tool names and input schemas are fingerprinted. A stale MCP session receives `MCP_TOOL_SURFACE_CHANGED` with a reinitialize instruction while its transport remains available for the host to observe the reset. Replacement initialize then supersedes and closes the old session; schema rotation must not unregister the Forge namespace from the host conversation.
-
-Capability descriptors identify domain group, operation class, risk, facade route, and schema source. Plugin completeness is separate from the core Runtime baseline: optional plugin health does not redefine repository execution or Runtime readiness unless the requested operation explicitly depends on that plugin.
-
-## Runtime Truth
-
-Controller Home owns runtime state:
-
-```text
-repositories/<repoId>/
-  execution-jobs/
-  plugins/
-  leases/
-  schedules/
-    records/
-    occurrences/
-    decisions/
-    indexes/
-  findings/
-  artifacts/
-  evidence/
-  events/
-  projections/
-  runs/
-  edit-sessions/
-
-indexes/execution-jobs/
-scheduler/state.json
-portfolio/workflows/
-```
-
-Repository files under `plans/`, `tasks/` and Issue storage remain business intent and audit material. They are not scanned as a hot execution queue.
-
-## Compatibility Boundary
-
-The following remain supported:
-
-- original Issue and Task lifecycle;
-- Task/Run separation and retry history;
-- Direct Edit sessions;
-- Local Bridge API and UI;
-- repository registry and GitHub mapping;
-- Agent Run and Worktree integration records;
-- legacy MCP schemas and stored-state readers;
-- historical plans and architecture documents for audit.
-
-`src/cli/mcp/tools.ts` is now a thin stable facade. `legacy-tool-service.ts` contains compatibility implementations invoked inside isolated Workers when work is durable. No product capability was removed to reduce source size or latency.
-
-## Validation Authority
-
-Completion is guarded by:
-
-- strict TypeScript checking across `src`, `scripts` and `tests`;
-- architecture invariant checks;
-- MCP compatibility fingerprint checks;
-- recovery, fencing and ambiguous-side-effect smoke tests;
-- Schedule trigger/Decision/backoff smoke tests;
-- Scheduler → Repo Actor → isolated Worker → Evidence process smoke;
-- HTTP Gateway `/health`, `/ready` and repository-health smoke;
-- package and source-manifest verification.
-
-Release readiness requires Bun-native tests, TypeScript checking, MCP surface checks, public-document validation, tracked-file hygiene, and package export verification in the release environment.

package/docs/architecture/current/job-and-run-lifecycle.md

@@ -1,413 +0,0 @@
-# Job and Run Lifecycle
-
-> Status: **Runtime Authority**
-
-## 1. Purpose
-
-This document defines asynchronous execution semantics. It prevents request lifetime, process lifetime, Job lifetime, Run lifetime, and Task lifetime from being treated as the same state machine.
-
-## 2. Lifecycle Ownership
-
-| Lifecycle | Owner | Answers |
-| --- | --- | --- |
-| Request | Thin Gateway | Was the command accepted and what ID should the client query? |
-| Job | Repo Actor / Controller | What asynchronous system operation is pending or complete? |
-| Run | Agent execution subsystem | What happened during one Agent attempt? |
-| Task | Workflow Plane | Is the objective ready, under review, verified, accepted, or terminal? |
-| Worker | Execution Plane | Which process currently holds execution ownership? |
-| Lease | Resource subsystem | May this Worker still mutate the protected resource? |
-
-No lifecycle may substitute for another.
-
-## 3. Job State Machine
-
-### Target States
-
-```text
-accepted
-  -> queued
-  -> waiting_for_resource
-  -> dispatched
-  -> running
-  -> succeeded
-
-accepted/queued/waiting_for_resource/dispatched/running
-  -> failed
-  -> timed_out
-  -> cancelled
-  -> orphaned
-  -> stale
-```
-
-Optional review-oriented Jobs may include:
-
-```text
-running -> waiting_for_user -> running
-```
-
-### State Meanings
-
-- `accepted` — durable record exists and idempotency identity is reserved.
-- `queued` — eligible for scheduling but no Worker assigned.
-- `waiting_for_resource` — blocked by a dependency, claim, quota, or barrier.
-- `dispatched` — a Worker or external provider was assigned; execution may not have started.
-- `running` — valid Lease and execution heartbeat exist.
-- `waiting_for_user` — execution cannot progress without human input.
-- `succeeded` — the Job-owned operation completed successfully and result evidence is durable.
-- `failed` — operation completed unsuccessfully with durable error evidence.
-- `timed_out` — persisted deadline was exceeded and termination/reconciliation was recorded.
-- `cancelled` — an authorized cancellation ended this Job's ownership.
-- `orphaned` — ownership disappeared and success/failure cannot be proven.
-- `stale` — the operation's required revision or precondition changed before valid completion.
-
-### Current Implementation
-
-Local Bridge currently uses compatibility states such as `approved`, `running`, and `dispatched`. These remain readable. `approved` maps to accepted/queued semantics rather than a human approval queue.
-
-### Migration Rule
-
-New Job types should use the target meanings even if stored names remain temporarily compatible. A compatibility adapter must not mark a Job succeeded merely because a linked Run was created or dispatched.
-
-## 4. Admission Protocol
-
-Every long operation follows:
-
-```text
-1. validate repository, checkout, schema, policy and authorization
-2. derive requestId and semanticKey
-3. check idempotency index
-4. evaluate Task/dependency and resource policy
-5. atomically persist Job + accepted event + index entries
-6. return Job ID to caller
-7. schedule asynchronously
-```
-
-If step 5 fails, no execution may start.
-
-If the client disconnects after step 5, the Job remains accepted.
-
-## 5. Idempotency Protocol
-
-### Identity
-
-```text
-idempotencyKey = hash(requestId, repoId, operationType, semanticKey)
-```
-
-### Behavior
-
-- The first accepted command owns the key.
-- Repeated calls return the original Job summary.
-- A caller may explicitly request a new attempt only through retry semantics, producing a new attempt identity linked to the prior Job.
-- A terminal failure is not silently rerun because the client repeated the original request.
-
-### Semantic Keys
-
-Examples:
-
-```text
-dispatch-task: issueId + taskId + retryFromRunId
-run-check: checkId + revision + environmentFingerprint
-verify-edit: sessionId + editRevision + checkSet
-repository-command: approvalToken + checkoutSnapshot
-integration: runId + targetCheckoutId + reviewedDiffHash
-schedule-occurrence: scheduleId + occurrenceWindow + repoId
-```
-
-## 6. Scheduling and Claims
-
-After admission, the Repo Actor computes required Claims.
-
-Possible results:
-
-- all Claims granted: assign Worker and Lease;
-- compatible shared execution already active: subscribe to it;
-- temporary conflict: enter `waiting_for_resource`;
-- dependency incomplete: enter `waiting_for_dependency` detail;
-- release freeze or policy block: wait or fail according to explicit policy;
-- invalid scope or forbidden action: fail before Worker dispatch.
-
-A waiting Job remains observable and retains its deadline and queue metadata.
-
-## 7. Worker Start Protocol
-
-A Worker starts only after:
-
-1. Job is durable;
-2. resource Claims are granted;
-3. Lease with fencing token is persisted;
-4. execution configuration and artifact paths are durable.
-
-The Worker then records:
-
-```text
-workerAssigned
-workerStarted
-heartbeat
-progress events
-output references
-terminal result
-```
-
-A PID is diagnostic evidence. Lease identity is the authority to write lifecycle state.
-
-## 8. Heartbeat and Deadline
-
-A running Job or Run records:
-
-```text
-startedAt
-deadlineAt
-heartbeatAt
-leaseExpiresAt
-worker identity
-```
-
-The Controller distinguishes:
-
-- missing heartbeat but live process;
-- dead process but unexpired Lease;
-- expired Lease;
-- completed result with missing terminal transition;
-- process tree still alive after parent exit.
-
-Timeout handling must attempt process-tree termination, record the signal path, wait for terminal confirmation or mark unresolved descendants, and persist the resulting state.
-
-## 9. Run State Machine
-
-### Current and Target Core States
-
-```text
-queued
-  -> starting
-  -> running
-  -> waiting_for_user
-  -> succeeded
-
-queued/starting/running/waiting_for_user
-  -> failed
-  -> cancelled
-  -> unknown
-```
-
-A timeout is represented by terminal failure/unknown metadata plus a structured termination reason until a dedicated Run `timed_out` status is introduced.
-
-### Run Success Contract
-
-For Workspace execution, Run success requires:
-
-- Agent process exited successfully;
-- result record is durable;
-- declared process tree is closed;
-- final diff/evidence can be read.
-
-For isolated Worktree execution with automatic integration, Task-visible success requires either:
-
-- integration completed, `integratedSessionId` exists, and cleanup is recorded; or
-- Run execution succeeded but integration is explicitly pending/failed, in which case the Task remains review/integration pending and must not appear fully completed.
-
-For GitHub execution, provider success and collaboration artifacts are recorded, but merge and acceptance remain separate.
-
-## 10. Job-to-Run Relationship
-
-A Dispatch Task Job may proceed:
-
-```text
-Job accepted
-  -> Run accepted
-  -> Run dispatched
-  -> Job dispatched
-  -> Run running
-  -> Job running
-  -> Run terminal
-  -> continuation / integration / verification
-  -> Job terminal
-```
-
-The Job may remain non-terminal after Run success while integration or required continuation remains part of the Job contract.
-
-A Run terminal failure normally makes its owning dispatch Job fail, but Task retry semantics still require an explicit new Run.
-
-## 11. Shared Execution
-
-Identical check or deterministic execution requests may share one physical Worker execution.
-
-The model is:
-
-```text
-SharedExecution
-  -> Subscriber Job A
-  -> Subscriber Job B
-  -> Subscriber Job C
-```
-
-Rules:
-
-- each subscriber has independent cancellation, timeout, stale, and result-link state;
-- cancelling one subscriber does not kill the shared process while another subscriber remains active;
-- the physical execution terminates only after the last subscriber leaves or the shared contract itself fails;
-- every subscriber receives the shared result or its own scoped terminal outcome;
-- shared identity includes Revision and execution environment.
-
-In-memory subscriber sets may optimize delivery but must be reconstructable from durable Job relationships.
-
-## 12. Cancellation
-
-Cancellation targets an entity and authority boundary.
-
-### Job cancellation
-
-- marks that Job cancelled;
-- releases or withdraws its Claims;
-- removes its subscription from shared work;
-- terminates a dedicated Worker only if the Job is its sole owner.
-
-### Run cancellation
-
-- attempts to stop the Agent process tree or provider session;
-- records terminal evidence;
-- does not delete Task or prior evidence.
-
-### Request cancellation
-
-A disconnected or abandoned MCP request after acknowledgement does not cancel the Job.
-
-## 13. Timeout
-
-Timeout is evaluated from a persisted deadline, not an in-memory timer alone.
-
-On timeout:
-
-1. confirm the Job is still owned by the same fencing token;
-2. mark timeout intent;
-3. signal the complete process tree or external provider;
-4. persist termination events;
-5. close or orphan the Lease;
-6. record `timed_out` or `unknown` according to available evidence;
-7. release Claims;
-8. expose explicit retry semantics.
-
-## 14. Orphan Reconciliation
-
-A Job or Run may be orphaned when:
-
-- Controller or Worker exits unexpectedly;
-- persisted owner PID is dead;
-- Lease expires without terminal result;
-- external provider state is unavailable;
-- result exists but lifecycle transition was interrupted.
-
-Reconciliation order:
-
-```text
-1. read durable result/evidence
-2. inspect Lease and fencing token
-3. inspect process/provider liveness
-4. inspect process tree and artifact completeness
-5. recover terminal state when provable
-6. otherwise mark orphaned/unknown
-7. require explicit retry where duplicate execution is unsafe
-```
-
-Reconciliation must be idempotent.
-
-## 15. Stale State
-
-A Job becomes stale when a required precondition changes, including:
-
-- repository Revision changed while a queued or running check required the old Revision;
-- approval token no longer matches checkout snapshot;
-- source Run diff no longer applies to target Checkout;
-- Schedule Occurrence window was superseded;
-- resource mapping or repository identity changed incompatibly.
-
-Stale work must not produce reusable success evidence.
-
-## 16. Retry
-
-Retry creates a new attempt linked to the terminal entity:
-
-```text
-priorJobId
-priorRunId
-attemptNumber
-retryReason
-new requestId or retry identity
-```
-
-Before retry, the Repo Actor determines whether:
-
-- the original operation is safe to repeat;
-- a result may already exist;
-- cleanup is complete;
-- the repository Revision changed;
-- scope or acceptance criteria must be revised;
-- a different Agent is justified.
-
-Infrastructure failure does not automatically imply implementation failure, and Agent failure does not automatically justify switching Agents.
-
-## 17. Continuation After Successful Run
-
-Successful Run continuation is deterministic:
-
-```text
-Run success
-  -> inspect execution mode
-  -> integrate when required
-  -> run declared checks when policy applies
-  -> persist Verification
-  -> auto-complete eligible low/medium-risk Task
-  -> wait for human acceptance for high/destructive Task
-  -> unlock dependent Tasks
-```
-
-Every continuation step is either a durable Job or an atomic state transaction. A Controller restart can resume from the last durable boundary.
-
-## 18. Terminal-State Rules
-
-- `succeeded` requires durable result evidence.
-- `failed` requires durable error evidence.
-- `cancelled` requires cancellation authority and event.
-- `timed_out` requires persisted deadline evidence.
-- `orphaned` or `unknown` means the system cannot prove success or failure.
-- `stale` means result cannot satisfy the original semantic contract.
-- terminal entities do not return to running;
-- retry creates a new entity or attempt relationship.
-
-## 19. Projection Rules
-
-Active indexes include only non-terminal Jobs/Runs. Terminal history is queried separately and bounded by requested limits.
-
-A list endpoint may reconcile active entities but must not scan full terminal history. An entity detail endpoint may reconcile that entity specifically.
-
-## 20. Audit Requirements
-
-Every lifecycle transition records:
-
-```text
-entityId
-previousStatus
-nextStatus
-actor
-requestId
-correlationId
-causationId
-fencingToken when applicable
-reason
-evidence references
-occurredAt
-```
-
-Lifecycle transitions without an audit event are recovery anomalies and must be detectable by governance checks.
-
-## 21. Controller Ownership Fencing
-
-Repository controller ownership is a stable lease identity, not a per-Task token. Heartbeat or sibling dispatch renews/reuses the live owner and does not rotate its epoch. The epoch changes only on a proven takeover after the previous owner is dead or its record is malformed. Epoch writes are serialized and atomic.
-
-A child Worker receives the current controller PID and epoch as a derived execution capability. It may publish heartbeats or terminal state only while that capability still matches the durable owner record. Parallel sibling Runs therefore cannot invalidate each other by reacquiring repository ownership.
-
-## 22. Local Job Projection
-
-Local Bridge states are compatibility projections of Agent Runs or durable Execution Jobs. `starting` is active and maps to `running`; it is never interpreted as terminal failure. A projected Local Job synchronizes its durable Job before applying action-specific orphan or timeout rules, preventing a compatibility projection from masking a terminal durable result.
-
-Runtime storage is bound before the first Local Job is persisted. This prevents the Job from blocking migration of the directory that contains its own state.