diff --git a/openspec/changes/process-ledger-and-orphan-detection/design.md b/openspec/changes/archive/2026-10-11-process-ledger-and-orphan-detection/design.md similarity index 100% rename from openspec/changes/process-ledger-and-orphan-detection/design.md rename to openspec/changes/archive/2026-10-11-process-ledger-and-orphan-detection/design.md diff --git a/openspec/changes/process-ledger-and-orphan-detection/proposal.md b/openspec/changes/archive/2026-10-11-process-ledger-and-orphan-detection/proposal.md similarity index 100% rename from openspec/changes/process-ledger-and-orphan-detection/proposal.md rename to openspec/changes/archive/2026-10-11-process-ledger-and-orphan-detection/proposal.md diff --git a/openspec/changes/process-ledger-and-orphan-detection/specs/process-ledger/spec.md b/openspec/changes/archive/2026-10-11-process-ledger-and-orphan-detection/specs/process-ledger/spec.md similarity index 100% rename from openspec/changes/process-ledger-and-orphan-detection/specs/process-ledger/spec.md rename to openspec/changes/archive/2026-10-11-process-ledger-and-orphan-detection/specs/process-ledger/spec.md diff --git a/openspec/changes/process-ledger-and-orphan-detection/tasks.md b/openspec/changes/archive/2026-10-11-process-ledger-and-orphan-detection/tasks.md similarity index 100% rename from openspec/changes/process-ledger-and-orphan-detection/tasks.md rename to openspec/changes/archive/2026-10-11-process-ledger-and-orphan-detection/tasks.md diff --git a/openspec/specs/process-ledger/spec.md b/openspec/specs/process-ledger/spec.md new file mode 100644 index 00000000..e9074ee8 --- /dev/null +++ b/openspec/specs/process-ledger/spec.md @@ -0,0 +1,80 @@ +# process-ledger Specification + +## Purpose +TBD - created by archiving change process-ledger-and-orphan-detection. Update Purpose after archive. + +## Requirements + +### Requirement: Every shared spawn is recorded with an OS identity + +Core SHALL write a synchronous ledger snapshot when a shared adapter spawns a +child. The snapshot SHALL include run id, pid, OS start time, executable path, +hostname, cwd, change name and a secret-free SHA-256 command-line hash. The raw +command line SHALL NOT be stored. A start-time read failure SHALL record that +the time is unavailable rather than inventing one. + +#### Scenario: A spawned agent is recorded + +- **WHEN** a shared adapter spawns an agent process with a PID +- **THEN** the ledger holds a snapshot naming run, pid, start time, executable, + hostname, cwd and, where known, change, with a command-line hash and no raw + arguments + +#### Scenario: Start time cannot be read + +- **WHEN** the OS start-time read fails at spawn +- **THEN** the snapshot is written with start time unavailable +- **AND** no guessed time is recorded + +### Requirement: Normal exit updates and bounds the ledger + +Core SHALL mark a snapshot `exitedAt` when its process closes. Ledger state +SHALL be stored outside the checkout keyed by canonical repository identity and +hostname, and SHALL be bounded by count and retention. + +#### Scenario: A process exits normally + +- **WHEN** a recorded process closes +- **THEN** its snapshot gains an exit time + +#### Scenario: Two machines run one repository + +- **WHEN** the same repository spawns processes on two hosts +- **THEN** their snapshots are keyed apart by hostname + +### Requirement: Kill is re-verified and explicit + +Termination SHALL be an explicit, confirmable action on the recovery surface. +Before terminating, core SHALL re-read the live OS start time for the PID and +SHALL confirm the executable and hostname match the snapshot. A mismatch SHALL +be reported as PID reuse and SHALL NOT be terminated. Termination SHALL use the +existing process-tree helper. + +#### Scenario: The live snapshot matches + +- **WHEN** a person confirms termination and the live PID start time and + hostname match the recorded snapshot +- **THEN** the process tree is terminated + +#### Scenario: PID reuse + +- **WHEN** the live start time differs from the recorded one +- **THEN** no kill is issued and the mismatch is reported + +### Requirement: Compliance observes processes without terminating them + +Compliance SHALL report overdue and orphaned process findings with snapshot +evidence and advice. Compliance SHALL NOT terminate a process, and the process +rules SHALL have no repair implementation. + +#### Scenario: A process exceeds its expected duration + +- **WHEN** a recorded process has run past its expected limit +- **THEN** Compliance reports a finding with the snapshot and advice +- **AND** no process is terminated + +#### Scenario: A process is orphaned after a restart + +- **WHEN** a record has no exit time and no live writer +- **THEN** Compliance reports it as orphaned and directs the person to the + recovery surface