Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
21 commits
Select commit Hold shift + click to select a range
6b79817
fix: reclaim delivered captures according to readability
Trecek Oct 25, 2026
84afa1e
fix: account for complete capture capacity envelope
Trecek Oct 25, 2026
8a3a018
test: correct capacity boundary and frame profile fixtures
Trecek Oct 25, 2026
51d5b8c
feat: report capture capacity headroom and refusal measurements
Trecek Oct 26, 2026
78a707b
refactor: extract capture setup failure transport
Trecek Oct 26, 2026
335f643
fix: run capacity-refused commands with bounded output
Trecek Oct 26, 2026
2dd9513
fix(review): Reuse the lifecycle test helpers
Trecek Oct 26, 2026
bb5268f
fix(review): report actual admission measurements and verify refusal …
Trecek Oct 26, 2026
e5e5282
fix(review): List violated envelope fields in the import-time assertion
Trecek Oct 26, 2026
32967cd
fix(review): Document the encoder measurement source and rounding for…
Trecek Oct 26, 2026
c00af5a
fix(review): Use the required predecessor directly in transition capa…
Trecek Oct 26, 2026
0b5e777
fix(review): expose degraded capture emitter
Trecek Oct 26, 2026
ce4b971
fix(review): Encapsulate capture-store projection stats
Trecek Oct 26, 2026
a5f5121
fix(review): Share capture-store capacity reporting
Trecek Oct 26, 2026
d71defb
fix(review): Move output-budget guidance beside its policy
Trecek Oct 26, 2026
68903e6
fix(review): Assert capture authority leaves a deleted record
Trecek Oct 26, 2026
854ae7a
fix(review): Assert fallback spawn receives the original command
Trecek Oct 26, 2026
0083c57
fix(review): Pin planned frame slack below eight bytes
Trecek Oct 26, 2026
9ade5d6
fix(review): keep admission measurement fixtures within valid capacit…
Trecek Oct 26, 2026
65c037a
fix(review): render envelope diagnostics without module singleton state
Trecek Oct 26, 2026
9620cd0
fix(review): profile finite timestamp widths in frame allowance test
Trecek Oct 26, 2026
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
22 changes: 13 additions & 9 deletions docs/decisions/0005-output-budget-protocol.md
Original file line number Diff line number Diff line change
Expand Up @@ -80,15 +80,19 @@ exact pull closure. It does not masquerade as the tool's normal operational fail
| `MAX_MCP_OUTPUT_TOKENS = 50_000` | Keep Claude's independently defined setting separate. It has no shared source of truth with Codex result or history limits and does not control Claude Code's observed disk-persistence gate. Claude's native Bash spill behavior covers shell output on that backend. |

The shell capture hook uses `shell_max_inline_bytes = 12_000` as the inline threshold:
commands whose combined output fits within that budget are inlined in full (artifact
retained for one hour after durable finalization); larger outputs are captured losslessly
to the same descriptor-owned artifact with a bounded head/tail slice and provenance
marker inlined. A per-artifact writer lease protects quiet live producers. Every valid
installed runner performs one bounded tail sweep after producer resources release, and
the cleanup-only `capture_lifecycle_hook.py` performs the same sweep at `SessionStart`
for interactive and headless sessions. Eligible artifacts are reclaimed on the next
enabled trusted trigger through identity-revalidated quarantine deletion. Cleanup
failure is fail-open and cannot replace the command's stdout, stderr, or exit status.
commands whose combined output fits within that budget are inlined in full; larger
outputs are captured losslessly to the descriptor-owned artifact with a bounded
head/tail slice and provenance marker inlined. Retention follows readability: after
delivery completes, captures with no outstanding bearer become eligible
immediately; a delivered capture with a
published reference remains readable until expiry; unsettled deliveries and failed
artifacts keep the one-hour hold. A per-artifact writer lease protects quiet live
producers. Every valid installed runner performs one bounded tail sweep after producer
resources release, and the cleanup-only `capture_lifecycle_hook.py` performs the same
sweep at `SessionStart` for interactive and headless sessions. Eligible artifacts are
reclaimed on the next enabled trusted trigger through identity-revalidated quarantine
deletion. Cleanup failure is fail-open and cannot replace the command's stdout,
stderr, or exit status.
`small_file_max_bytes` was removed — it existed solely for the classifier's
literal-small-JSONL exception, which is no longer needed.

Expand Down
97 changes: 87 additions & 10 deletions docs/decisions/0006-output-containment.md
Original file line number Diff line number Diff line change
Expand Up @@ -99,10 +99,24 @@ process-lifetime contract is defined against that host model in ADR-0008.
The lifecycle store records `RESERVED`, `STAGED`, `PUBLISHED_WRITING`,
`FINALIZED`, `FAILED`, `ABANDONED`, `DELETING`, `DELETED`, and `TAMPERED`.
The immutable FINAL, reference, delivery, and reader semantics belong to
ADR-0008. A finalized or failed artifact becomes eligible one hour after its
terminal transition; an abandoned producer becomes eligible one hour after its
durable creation time. Eligibility is reclaimed only on the next enabled,
trusted trigger, not by a wall-clock scheduler.
ADR-0008. Retention follows readability: after delivery completes, captures
with no outstanding bearer become eligible immediately; a delivered capture
with a published reference remains readable until expiry; unsettled deliveries
and failed artifacts keep the one-hour hold.

| FINALIZED record | Eligibility time | Why |
|---|---|---|
| Delivered with no outstanding bearer (`not_requested`, `unavailable`, `expired`, `revoked`) | Immediately after the delivered transition commits; its due timestamp is `manifest.finalized_at` | Inline bytes have already been delivered and no bearer can open the artifact |
| Delivered with a `published` reference | `manifest.reference_expiry` | The bearer remains readable until expiry |
| Any other FINALIZED state (undelivered, delivery `failed`/`unknown`, or reference `unknown`) | `manifest.retention_deadline` | Preserve the one-hour forensic hold |

`FAILED` artifacts, including pre-FINAL failures, remain eligible one hour after
their terminal transition; abandoned producers remain eligible one hour after
durable creation time. A FINALIZED record with no outstanding bearer is not due
until delivery completes, even though its due timestamp is `manifest.finalized_at`.

Eligibility is reclaimed only on the next enabled, trusted trigger, not by a
wall-clock scheduler.

Admission participates in that trigger-owned model. When store-wide due debt
reaches the assist threshold, the admitting runner performs one debt-scaled
Expand All @@ -122,6 +136,19 @@ at least one installed reclamation owner retains a positive directory-scan
budget. Removing either condition requires a new ownership decision; the
read-only doctor must not become a scheduler implicitly.

The producer's own runner tail tries its just-delivered inline capture first,
before the cursor-rotated backlog, within the existing `RUNNER_TAIL_BUDGET`;
this moves the same required deletion work earlier without increasing total
deletion work or adding an owner or scheduler.

Eligibility is distinct from access and deletion. Inline output has already
been delivered as in-memory bytes and grants no later artifact-opening
authority; `open_verified_capture()` requires a published bearer. A holder of a
delivered published reference may open it until expiry. Expiry prevents new
authorized opens but does not erase previously delivered bytes. An already-open
verified reader's shared lease prevents reclamation until it closes, after which
identity checks still have to pass before deletion.

Deletion is confined to the shared store's identity-revalidated quarantine
transaction. Only lifecycle-recorded `shell_[0-9a-f]{16}.log` artifacts are
eligible. Fresh records, live writers, nonmatching names, symlinks, FIFOs,
Expand Down Expand Up @@ -158,6 +185,9 @@ hook can be retired in favor of that mechanism.
rejected. Physical path strings are display hints, not filesystem authority.
5. General retrieval, publication/privacy policy, quota accounting, and upstream
live visibility remain downstream work identified by ADR-0008.
6. Undelivered and otherwise unsettled-delivery anomalies retain the one-hour
hold and sit outside the declared load; their encoded frames still count
against actual capacity.

## Resolved

Expand Down Expand Up @@ -196,13 +226,59 @@ bookkeeping failure discards or misreports a verified primary result outside
of what the import-time assertion alone can catch (e.g. a `PRESERVE_OUTPUT`
classification applied to a reason that should be `DISCARD_OUTPUT`).

Containment remains in force under setup-stage capacity degradation because
agent-visible output stays bounded by `shell_max_inline_bytes`.

The same enforcement surface bounds admission by measured reclamation debt:
assist and stall are admission-only capacity reasons, and import-time totality
requires their gate, failure, disposition, detail, and blocker classifications.
The production compaction floor is derived from the code-owned sustained
admission envelope, the canonical one-hour sweep grace, and the incident's
measured bytes per record. Runtime policy overrides below that derived floor
are rejected in favor of the safe production default.

The capacity model derives the production byte floor and the operational,
retained, and evidence record caps from one required record count.
`capacity_envelope_violations(spec)` supplies both the import-time check for the
production default and runtime override validation. The import-time assertion
checks only the static default; live admission and transition gates use actual
projected bytes. The success-path hold uses `REFERENCE_LIFETIME_SECONDS`: at the
declared peak of 0.5333 admissions per
second and a 1,800-second reference lifetime, `ceil(0.5333… * 1,800) + 16`
producers yields 976 held records. The floor adds the due debt that can accrue
before reclamation assist engages, `reclamation_debt_assist_records - 1`; this
produces 1,231 required records at the default 256-record assist threshold.
The same count is required by each record cap.

`PLANNED_RECORD_FRAME_BYTES` is 2,608 bytes: the largest measured encoding of
real `FINALIZED`, `DELETED`, and `FAILED` record shapes under the declared
numeric profile, rounded up to a multiple of eight. The measurement sets
non-schema counters and identities to `2**63 - 1`, uses the same compaction
epoch, valid finite timestamps, and bounded command outcomes. Adding the
default 256 tombstones gives `(1,231 + 256) * 2,608 = 3,878,096` bytes, below
the default `compaction_low_bytes` of 3,932,160. The declared allowance models
that load and profile; `CompactedFrameSizer` counts every encoded byte in the
retained projection, including opaque frames, for both admission and compaction.
A remeasured allowance above 2,644 bytes makes the default
import-time check fail and requires re-deriving the floor. Overrides that break
the byte or shared record-count envelope are rejected by the same function.

`compaction_low_bytes` is a soft limit for state-advancing work. Admission is
gated separately; transitions that advance a record through stage, publish,
and finalize may be refused above it. Same-state bookkeeping, including
delivery and reference updates, open-time normalization, and sweep expiry,
remains subject to the hard bound. Recovery transitions retain their reserved
headroom. `_with_capacity_rescue` first attempts the operation; for its existing
rescuable refusal reasons, it performs one bounded sweep and retries from a
fresh locked load before final refusal.

The retained-record envelope is a compacted projection of latest record
frames, allowed tombstones, and opaque bytes. Superseded transition frames
remain in the physical ledger until compaction, so they are temporary physical
amplification and are not multiplied into the retained-record floor.
`_append_locked` checks prospective physical size and compacts instead of
appending when the append trigger would be crossed. Compaction output may itself
exceed that trigger while remaining within the hard `MAX_LEDGER_BYTES` bound;
the trigger is not a universal ceiling. A projected-capacity refusal is a
`CaptureCapacityError`; an existing physical file above `MAX_LEDGER_BYTES` is
rejected on load as `CaptureLedgerError` and does not enter the capacity-only
degraded path.

## Consequences

Expand All @@ -215,5 +291,6 @@ are rejected in favor of the safe production default.
- Complete Codex shell output is captured to a descriptor-anchored carrier.
Oversized replay reports an opaque V2 reference or an unavailable status,
never an authoritative pathname.
- One-hour lifecycle reclamation is owned by the installed runner tail and the
cleanup-only `SessionStart` hook, with bounded retry and quarantine recovery.
- Readability-derived lifecycle reclamation is owned by the installed runner
tail and the cleanup-only `SessionStart` hook, with bounded retry and
quarantine recovery; unsettled artifacts retain the one-hour hold.
8 changes: 5 additions & 3 deletions docs/decisions/0008-shell-capture-snapshot-authority.md
Original file line number Diff line number Diff line change
Expand Up @@ -184,9 +184,11 @@ nonblocking exclusive lease and defers while the producer or any reader remains
live. The existing runner-tail and cleanup-only `SessionStart` owners remain the
only owners of the single `shell-captures` lifecycle resource.

References expire no later than the one-hour retention deadline. Expiry stops new
resolution, as does an explicit revoked state; cleanup removes an eligible carrier
only after leases release and descriptor-relative identity checks pass.
After the `delivered` transition commits, a capture with no outstanding bearer
becomes eligible for reclamation immediately. A published reference expires no
later than the one-hour retention deadline. Expiry stops new resolution, as does
an explicit revoked state; cleanup removes an eligible carrier only after producer
and reader leases release and descriptor-relative identity checks pass.

### Ledger, filesystem, and durability boundary

Expand Down
21 changes: 15 additions & 6 deletions docs/decisions/0009-verified-output-delivery-disposition.md
Original file line number Diff line number Diff line change
Expand Up @@ -67,11 +67,18 @@ delivery — the guard falls through to the ordinary fail-closed handler in
that case, matching the pre-existing behavior for every failure that occurs
before verification completes.

The reclamation-debt stall occurs before the child starts. Its
`PRESERVE_OUTPUT` classification therefore supplies no output or delivery
authority: the runner emits the ordinary structured setup failure and never
enters degraded delivery because neither a verified snapshot nor a completed
child exists.
When a capacity refusal occurs before the child starts, it supplies no
captured-output authority. Capacity is retention bookkeeping, not an output
integrity fault, so the runner executes the command uncaptured through the
existing spawn and drain path. Output remains bounded by `shell_max_inline_bytes`:
small output is inline, and oversized output is reduced to bounded head and tail
slices with a fixed elision line. No artifact or reference is issued. A
`capture_degraded` marker at stage `capture_setup` carries the capacity reason
and admission measurement. Other setup failures still fail closed.

The marker signals command-level degradation; lineage observations continue to
describe the launch's capture/direct routing. The marker is not an aggregate
degradation rate or alarm.

### 3. Exit-code parity under degraded delivery

Expand Down Expand Up @@ -129,10 +136,12 @@ reclaimability and gate-reachability trustworthy.
2. This ADR governs only the AutoSkillit Codex native-shell capture runner
established by ADR-0008. It does not extend disposition semantics to
Claude Code native shell, MCP `run_cmd`, or any other artifact contract.
3. Degraded delivery inherits ADR-0008's bounded-transport limits
3. Verified-snapshot degraded delivery inherits ADR-0008's bounded-transport limits
(`render_degraded_capture()` reuses the same inline-byte cap and V2
reference framing as the success path) — it does not add a new output
size allowance.
4. Setup-capacity degradation loses output beyond the inline budget and creates
no full-output artifact.

## Consequences

Expand Down
2 changes: 1 addition & 1 deletion docs/decisions/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@
- [0006-output-containment.md](0006-output-containment.md) — Retire pre-execution command-shape classification in favor of per-backend output-boundary bounding on measured bytes
- [0007-context-admission.md](0007-context-admission.md) — Freeze the versioned cumulative context-admission boundary, authority contract, producer coverage, and privacy rules
- [0008-shell-capture-snapshot-authority.md](0008-shell-capture-snapshot-authority.md) — Make verified pipe-EOF snapshots, opaque V2 references, and checked delivery the sole Codex shell-capture authority
- [0009-verified-output-delivery-disposition.md](0009-verified-output-delivery-disposition.md) — A checksum-verified capture is delivered or the failure explicitly says why not; a bookkeeping failure never discards it
- [0009-verified-output-delivery-disposition.md](0009-verified-output-delivery-disposition.md) — A checksum-verified capture is delivered or the failure explains why; eligible post-verification bookkeeping faults preserve it, while setup-stage capacity refusals may run uncaptured within the inline bound with a degradation marker; other setup failures fail closed
- [0010-systemd-scope-defense-in-depth.md](0010-systemd-scope-defense-in-depth.md) — systemd scope wrapping is a best-effort kernel backstop on top of the tether sweep, never the ceiling of record
- [0015-write-containment.md](0015-write-containment.md) — typed skill write scopes composed by union across interactive and headless sessions
- [0016-owner-scope.md](0016-owner-scope.md) — a fleet dispatch settles every funnel-spawned descendant of its L2, selected by owner-scope registration, before it persists or returns
Expand Down
Loading
Loading