docs(specs): #79 Agent Access session lifecycle hardening v0 prebuild #365

Merged

pdurlej merged 1 commit from claude/fork-A1-agent-access-session-lifecycle-hardening into main

2026-05-23 09:19:24 +02:00

claude commented

2026-05-18 08:17:08 +02:00

Collaborator

Summary

Slice (b)+(c) extension of Agent Access Plane v0 (PR #323, draft). Closes the remaining gap in issue #79 — 4 of 6 listed tasks already shipped via incremental PRs (--list, --prune, signal block, startup cleanup). Two tasks remain (runtime dir race, TTL evidence-driven reduction) plus adversarial test surface for AC-compliance.

What's in

Spec Kit (6 files, ~700 LOC)

docs/specs/agent-access-session-lifecycle-hardening-v0/:

README.md — overview, 4/6 done status, file map, refs
00-constitution.md — 8 principles (P1 inherit from #323, P2 atomic dir-creation, P3 evidence-informed TTL, P4 no key in observable state, P5 observability-first audit, P6 path-trust defense, P7 cross-cousin isolation future, P8 per-slice acceptance)
01-specify.md — machine-checkable AC blocks for e1/e2/f1/f2 + end-of-v0 (AC-v0.*) acceptance criteria with hostile-input enumeration
02-plan.md — design choices: Design A (atomic mkdir) vs Design B (flock) for race fix; adversarial test pattern; audit log JSONL shape per ADR-0004; TTL decision matrix
03-tasks.md — 4 slices (e1 race fix Full, e2 adversarial tests Full, f1 evidence Lite, f2 TTL decision Lite); per-task breakdown; sequencing diagram; realistic 10-14 day wall-clock
04-implement-notes.md — cite existing 655-LOC wrapper symbols by line; known gotchas (macOS vs Linux ssh-agent output diff, SSH_AUTH_SOCK race after kill, JSONL append concurrency); wiring with PR #323 and fork A2 (#56 identity split)

Companion codex execution prompt

prompts/codex-agent-access-session-lifecycle-hardening.md (per PR #326 convention):

Safety/production boundary explicit (no runtime mutation, no ~/.openclaw touch, no schema change beyond #323)
Per-slice instructions with branch names + tier per ADR-0007
8 stop conditions including ADR-0018 invariants (no "accept workaround" / no "keep 4h because nobody decided")

Status of issue #79 tasks

Task	Status	Reference
(a) `--list` sessions	✅ done	commit `eca015a`
(b) stale session dir pruning	✅ done	commit `f269673`
(c) signal handling Ctrl+C during startup	✅ partial	`_block_start_signals` present
(d) parse_agent_output / startup failure cleanup	✅ done	commit `a39c3af`
(e) runtime dir race + intended mode	⏳ this spec slice e1
(f) TTL reduction from evidence	⏳ this spec slice f1+f2

Worktree discipline

This PR built in dedicated worktree /Users/pd/Developer/iskra-platform-2026-04-30-fork-A1 per prompts/fork-dispatch-2026-05-18-retry-batch.md §1.1 — v0.1 fix to yesterday's shared-checkout collision (PR #356).

Tier

Trivial per ADR-0007 — docs-only, no code/schema/runtime/sacred-path mutation. Real implementation lands in 4 subsequent slice PRs (e1/e2 Full, f1/f2 Lite) via canary 3+3 + operator merge.

Refs #79, #76 (epic), #77 (prior wrapper), PR #323 (parent spec), PR #326 (execution prompt convention)

## Summary Slice (b)+(c) extension of Agent Access Plane v0 (PR #323, draft). Closes the remaining gap in issue #79 — 4 of 6 listed tasks already shipped via incremental PRs (--list, --prune, signal block, startup cleanup). Two tasks remain (runtime dir race, TTL evidence-driven reduction) plus adversarial test surface for AC-compliance. ## What's in ### Spec Kit (6 files, ~700 LOC) `docs/specs/agent-access-session-lifecycle-hardening-v0/`: - **README.md** — overview, 4/6 done status, file map, refs - **00-constitution.md** — 8 principles (P1 inherit from #323, P2 atomic dir-creation, P3 evidence-informed TTL, P4 no key in observable state, P5 observability-first audit, P6 path-trust defense, P7 cross-cousin isolation future, P8 per-slice acceptance) - **01-specify.md** — machine-checkable AC blocks for e1/e2/f1/f2 + end-of-v0 (AC-v0.*) acceptance criteria with hostile-input enumeration - **02-plan.md** — design choices: Design A (atomic mkdir) vs Design B (flock) for race fix; adversarial test pattern; audit log JSONL shape per ADR-0004; TTL decision matrix - **03-tasks.md** — 4 slices (e1 race fix Full, e2 adversarial tests Full, f1 evidence Lite, f2 TTL decision Lite); per-task breakdown; sequencing diagram; realistic 10-14 day wall-clock - **04-implement-notes.md** — cite existing 655-LOC wrapper symbols by line; known gotchas (macOS vs Linux ssh-agent output diff, SSH_AUTH_SOCK race after kill, JSONL append concurrency); wiring with PR #323 and fork A2 (#56 identity split) ### Companion codex execution prompt `prompts/codex-agent-access-session-lifecycle-hardening.md` (per PR #326 convention): - Safety/production boundary explicit (no runtime mutation, no `~/.openclaw` touch, no schema change beyond #323) - Per-slice instructions with branch names + tier per ADR-0007 - 8 stop conditions including ADR-0018 invariants (no "accept workaround" / no "keep 4h because nobody decided") ## Status of issue #79 tasks | Task | Status | Reference | |---|---|---| | (a) `--list` sessions | ✅ done | commit `eca015a` | | (b) stale session dir pruning | ✅ done | commit `f269673` | | (c) signal handling Ctrl+C during startup | ✅ partial | `_block_start_signals` present | | (d) parse_agent_output / startup failure cleanup | ✅ done | commit `a39c3af` | | (e) runtime dir race + intended mode | ⏳ this spec slice e1 | | (f) TTL reduction from evidence | ⏳ this spec slice f1+f2 | ## Worktree discipline This PR built in dedicated worktree `/Users/pd/Developer/iskra-platform-2026-04-30-fork-A1` per `prompts/fork-dispatch-2026-05-18-retry-batch.md` §1.1 — v0.1 fix to yesterday's shared-checkout collision (PR #356). ## Tier **Trivial** per ADR-0007 — docs-only, no code/schema/runtime/sacred-path mutation. Real implementation lands in 4 subsequent slice PRs (e1/e2 Full, f1/f2 Lite) via canary 3+3 + operator merge. Refs #79, #76 (epic), #77 (prior wrapper), PR #323 (parent spec), PR #326 (execution prompt convention)

claude added 1 commit

2026-05-18 08:17:08 +02:00

docs(specs): #79 Agent Access session lifecycle hardening v0 prebuild

base-is-main / guard (pull_request) Successful in 1s

Details

canary-required / collect-diff (pull_request) Successful in 4s

Details

patchwarden-pr-sanity / collect-diff (pull_request) Successful in 3s

Details

canary-required / canary (pull_request) Successful in 14s

Details

patchwarden-pr-sanity / sanity (pull_request) Successful in 19s

Details

c10c5377ed

Slice (b)+(c) extension of Agent Access Plane v0 (PR #323, draft).
Closes the remaining gap in issue #79 — 4 of 6 listed tasks already
shipped via incremental PRs (--list, --prune, signal block, startup
cleanup). Two tasks remain (runtime dir race, TTL evidence-driven
reduction) plus adversarial test surface for AC-compliance.

Spec Kit:
- README.md: overview, 4/6 done status, file map
- 00-constitution.md: 8 principles (P1 inherit from #323, P2 atomic
  dir-creation, P3 evidence-informed TTL, P4 no key in observable
  state, P5 observability-first audit, P6 path-trust defense, P7
  cross-cousin isolation future, P8 per-slice acceptance)
- 01-specify.md: machine-checkable AC for e1/e2/f1/f2 + end-of-v0
- 02-plan.md: design choices (Design A atomic mkdir vs B flock),
  adversarial test pattern, audit log JSONL shape, TTL decision matrix
- 03-tasks.md: 4 slices, per-task breakdown, sequencing diagram,
  realistic 10-14 day wall-clock
- 04-implement-notes.md: cite existing 655-LOC wrapper symbols by
  line, known gotchas (macOS/Linux ssh-agent output diff, SSH_AUTH_SOCK
  race after kill, JSONL append concurrency), wiring with PR #323
  and fork A2 (#56 identity split)

Companion codex execution prompt:
- prompts/codex-agent-access-session-lifecycle-hardening.md
- Safety/production boundary explicit (no runtime mutation, no
  ~/.openclaw touch, no schema change beyond #323)
- Per-slice instructions with branch names + tier per ADR-0007
- 8 stop conditions including ADR-0018 invariant: no
  "accept workaround as primary outcome", no "keep 4h because
  nobody decided" TTL outcome

Constraints honored:
- No code mutation in this PR (Spec Kit + execution prompt only)
- Each slice is its own PR per ADR-0017 (no stacked PRs)
- Each PR titled to match content (lesson from 2026-05-17 fork-anchor
  misalignments)
- Per Codex 2026-05-17 feedback: Safety boundary section + Next
  implementer instructions + bug/feature prebuild shape distinction

Worktree isolation: this PR built in dedicated
/Users/pd/Developer/iskra-platform-2026-04-30-fork-A1 per
prompts/fork-dispatch-2026-05-18-retry-batch.md §1.1 v0.1 fix to
yesterday's shared-checkout collision.

Tier: Trivial per ADR-0007 (docs-only, no code/schema/runtime/sacred).

Refs #79, #76 (epic), #77 (prior), PR #323 (parent spec)