audience: AI coding agents first.

# Incident resolution coordinator — request

**Goal:** build crash-safe independent protected-machinery incident execution, artifact verification, and original-run resumption.

**Execution authority:** trusted independent agent only. NEVER launch this request through factory; coordinator, policy enforcement, canaries, and signing judge incident repairs.

**Canonical design:** `docs/specs/2026-08-09-factory-supervision-and-resolution-design.md`.

## Prerequisites

- Factory producer contracts from `docs/plans/2026-08-09-factory-supervisor-producer.md` landed and live.
- Incident dispatch selector capability authority rebased and landed. Reuse it; no second model/account registry.

## Files

- Create `collector/src/incidents/incident-execution-ledger.ts` — SQLite execution/lease/checkpoint/outbox authority.
- Create `collector/src/incidents/incident-dispatch-coordinator.ts` — claim, stable-unit admission, heartbeat, escalation, takeover, result ingestion.
- Create `collector/src/incidents/factory-incident-ingress.ts` — authenticated local factory intent validation/idempotency.
- Create `collector/src/incidents/resolution-artifact.ts` — canonical artifact verification and Ed25519 signing boundary.
- Create `collector/src/incidents/protected-incident-policy.ts` — incident type scope, canary, auto-repair, recursion guard.
- Create `modules/workstation/claude/incidents/canaries/` fixtures for gate/factory/harness/auth/cluster/data-safety types.
- Create `modules/workstation/systemd/user/overdeck-incident-resolver@.service` — stable independent resolver unit.
- Modify `collector/src/incidents/incident-service.ts` — ledger-backed state, provisional resolution, Kanboard projection.
- Modify `collector/src/incidents/provider.ts` — execution evidence and projection seams only.
- Modify `collector/src/actions.ts` — require verified artifact before `incident.resolve`.
- Modify `collector/src/server.ts` — loopback/service-authenticated factory ingestion and coordinator controls; browser cannot set source.
- Modify `collector/src/paths.ts` and config types — ledger, artifact store, public verification keys, workspace root.
- Modify `modules/workstation/claude/incidents/taxonomy.json` — protected type policy references; coordinator/policy/canary/signing failures remain non-automatic.
- Modify `packaging/deploy-local.sh` — key generation/custody, unit install, canary deployment.
- Add focused collector and packaging tests beside each new module.

## Contract

Copy verbatim from canonical design:

- `IncidentExecutionV1`, `IncidentCheckpointV1`, `IncidentOutboxV1`.
- `ResolutionArtifactV1`.
- `ResolverSeat`, `ResolutionBudget`, `ResolutionPolicy`.
- Factory incident idempotency key: `sha256(adwId + resolutionEpoch + failureClass + normalizedFingerprint)`.

Kanboard remains incident/user record and eventually consistent projection. Local execution ledger is sole execution authority.

## Behavior

- Factory ingress accepts only service-authenticated loopback/local IPC, server-authors `source="factory-supervisor"`, validates trace reference, and files one idempotent incident.
- Claim dispatch with generation CAS. Persist launch intent before spawn and admission receipt before `running`.
- Stable identity includes unit, boot ID, PID/start ticks, argv digest, dispatch and generation.
- Expired resolver can continue only after higher-generation acknowledgment. Otherwise terminate verified identity and resume from validated `IncidentCheckpointV1`; missing/diverged checkpoint -> `needs-attention`.
- Outbox stores replayable payload artifact + digest + event key. Partial Kanboard writes reconcile idempotently.
- Resolver uses dedicated worktree and pinned Defaults policy. It may touch only incident-type-authorized protected paths, never coordinator/policy/canaries/signing/scope in same attempt.
- Automatic chains remain finite. No nested incidents. Coordinator/policy/canary/signing defect stops for owner.
- Run immutable canaries and touched-module gates. Local infra installs live and verifies installed bytes before landing.
- Coordinator verifies evidence, signs canonical `ResolutionArtifactV1` with deployment Ed25519 key, and records public key id.
- `incident.resolve` verifies schema, signature, incident/dispatch/generation, scope, deployed bytes, gates, and canaries.
- Resolution remains provisional until original run resumes from compatible checkpoint and crosses original failed gate. If still red, continue only within same incident epoch and progress/budget; otherwise `needs-attention`.
- Enable automatic non-destructive repair for gate/factory/harness/auth/cluster types after canaries ship. Data-safety destructive operations always require owner decision.

## Out of scope

- Ordinary Defaults settings CRUD and UI.
- Factory target-code resolution internals.
- Manual incident retry redesign.
- Destructive migration, deletion, restore, or irreversible auto-repair.

## Acceptance

- Run full collector suite from `collector/`: `bun test`.
- Run full factory suite: `python3 -m pytest modules/harness/factory/tests/ -q`.
- Expected clean PASS for launch crash windows, lease takeover, outbox replay, duplicate terminal result, invalid signature/scope/deployed digest, canary failure, original-gate still red, and recursion guard.
- Deploy with `bash packaging/deploy-local.sh`; verify private signing key permissions, public key loading, stable resolver unit, and provider-free protected incident canary end-to-end.