blun-king-cli 9.1.567 → 9.1.569

package/agent-spine-plugin/docs/releasing.md

@@ -0,0 +1,85 @@
+# Release process
+
+AgentSpine releases are intentionally tag-authorized while the package is pre-1.0. A maintainer decides when to tag; the repository then builds, verifies, attests, and publishes one traceable release bundle from that exact commit. Pull requests and ordinary branch pushes can never enter the release workflow.
+
+## Local release gate
+
+Update every release version surface: `package.json`, both version fields in `package-lock.json`, the BLUN, Claude and Codex host manifests, the Claude marketplace entry, `hooks/version.json`, and `src/version.js`. Move the relevant changelog entries from **Unreleased** into a dated SemVer section, then run:
+
+```bash
+npm ci
+npm run check
+npm run release:check -- --tag vX.Y.Z
+python3 /path/to/plugin-creator/scripts/validate_plugin.py .
+python3 /path/to/skill-creator/scripts/quick_validate.py skills/agent-spine
+npm pack --dry-run
+```
+
+The plugin validator must implement the current [Codex plugin-bundled hooks contract](https://developers.openai.com/codex/hooks#plugin-bundled-hooks), including the documented `hooks` override. A validator snapshot that rejects this field is stale and cannot certify this release; do not remove the override, because Codex would otherwise load the Claude-specific default hook bundle.
+
+`release:check` fails unless:
+
+- all release version surfaces agree and the tag is exactly `v{package.version}`;
+- the changelog has a dated section for that version;
+- the Git worktree is clean;
+- npm reports SHA-512 integrity and a correctly versioned tarball;
+- every required Claude Code, Codex, MCP, CLI, source, skill, documentation, license, and changelog file is packaged;
+- no `.env`, key material, Git metadata, tests, workflow files, generated AgentSpine state, or user-owned `AGENTS.md`, `CLAUDE.md`, `SOUL.md`, or `MEMORY.md` enters the tarball;
+- the package remains within explicit file-count and unpacked-size ceilings.
+
+## Tag and automated release
+
+Only after the release commit is on a fully green `main`, create a signed or annotated tag and push it:
+
+```bash
+git tag -s vX.Y.Z -m "AgentSpine vX.Y.Z"
+git push origin vX.Y.Z
+```
+
+The tag workflow then:
+
+1. checks out the immutable tag with full history;
+2. proves the tagged commit is contained in `main`;
+3. installs only the lockfile dependency graph;
+4. repeats the complete test, audit, host, metadata, changelog, and package-boundary gates;
+5. creates the `.tgz`, a CycloneDX SBOM, and SHA-256 checksums;
+6. creates GitHub build-provenance and SBOM attestations through short-lived OIDC credentials;
+7. transfers the bundle through a named workflow artifact;
+8. gives only the final isolated job `contents: write` and creates the GitHub Release from the existing tag.
+
+Every external action is pinned to a full commit SHA. Dependabot watches those pins. The normal CI workflow has only `contents: read`; the build/attestation release job has `contents: read`, `id-token: write`, and `attestations: write`; only the asset-publication job has `contents: write`. No release job receives AgentSpine memory, signing keys, bearer values, npm tokens, or user source files.
+
+Protect the GitHub `release` environment with required reviewers if the repository plan supports it. Enable immutable releases and tag protection in repository settings where available. Workflow checks are defense in depth and do not replace repository rulesets.
+
+## Verify a downloaded release
+
+After downloading the tarball, SBOM, and `SHA256SUMS` from GitHub Releases:
+
+```bash
+sha256sum --check SHA256SUMS
+gh attestation verify agent-spine-X.Y.Z.tgz \
+  --repo Maykbiletti/AgentSpine
+```
+
+Inspect the package without installation:
+
+```bash
+npm pack --dry-run ./agent-spine-X.Y.Z.tgz
+```
+
+Then install the exact tarball in fresh Claude Code and Codex environments and repeat `agentspine doctor`, the MCP handshake, source scan, verification, and audit.
+
+## Optional npm publication
+
+The GitHub workflow deliberately does not publish to npm until ownership of the package name and the registry-side trust relationship are configured. When enabled, use npm Trusted Publishing bound to this repository, the exact release workflow filename, a GitHub-hosted runner, and a protected release environment. Keep OIDC provenance enabled and do not introduce a long-lived `NPM_TOKEN`.
+
+Authoritative references:
+
+- [GitHub artifact attestations](https://docs.github.com/actions/security-for-github-actions/using-artifact-attestations/using-artifact-attestations-to-establish-provenance-for-builds)
+- [GitHub secure use reference](https://docs.github.com/actions/reference/security/secure-use)
+- [npm Trusted Publishing](https://docs.npmjs.com/trusted-publishers/)
+- [npm provenance statements](https://docs.npmjs.com/generating-provenance-statements/)
+
+## Rollback
+
+Never move, reuse, or delete an existing public version tag to hide a bad release. Publish a patch release that reverts the faulty behavior, retain the original checksums and attestations, and explain the affected versions. Uninstalling AgentSpine or deleting its external state must still leave every scanned project file untouched.

package/agent-spine-plugin/docs/session-timeline.md

@@ -0,0 +1,251 @@
+# Bounded session timeline and evidence recall
+
+Long-lived hosts already persist a session transcript. AgentSpine leaves that
+host-owned file in place: it never copies, archives, rewrites, places it in
+`MEMORY.md`, or injects it into a briefing. The timeline sidecar stores only a
+small, restart-safe index of redacted objective evidence, not a second
+transcript.
+
+## Enrollment contract
+
+The Claude, Codex, and King adapters are deny-by-default. A regular `UserPromptSubmit` hook first
+creates a short-lived opaque receipt only after its exact host preflight has
+been verified. The receipt binds one regular, non-symlinked transcript below a
+verified host `projects` (Claude) or `sessions` (Codex and King) root to the exact host, session, entity, user, tenant,
+project, task, and optional goal step. It is not exposed in hook context or to
+the model.
+
+The local owner may then activate that one snapshot explicitly:
+
+```text
+agentspine timeline-receipt --root /path/to/project
+agentspine timeline-enroll --root /path/to/project --receipt asthr_… --confirm-local-timeline
+```
+
+The receipt is one-use, expires quickly, and needs the same protected local
+host transport that created it. Normal CLI flags cannot substitute a path,
+host, session, or scope. Enrollment initializes only sidecar metadata from the
+signed record and may revalidate fixed source metadata plus a ≤4 KiB prefix; it
+never scans or indexes historic transcript content. It is context-only and
+creates no identity, permission, delegation, tool access, approval, or policy
+exception.
+
+Every capture and retrieval checks the exact binding again. The profile and
+provider-specific transcript root must be real non-symlinked directories; the source must be a
+single-link regular non-symlinked file below that root. `groupId` must be
+exactly `null`; groups and unknown visibility are excluded from enrollment,
+capture, and recall. Another provider needs its own equivalent verified host
+evidence and does not inherit Claude enrollment by name, transcript text, or
+path convention.
+
+If the enrolled transcript changes or grows, the old snapshot is unavailable.
+There is deliberately no append or full-history fallback. A fresh host receipt
+and a new local confirmation renew the immutable snapshot. If a torn local
+enrollment state cannot be repaired, a local owner can discard only that
+sidecar state:
+
+```text
+agentspine timeline-enrollment-recover --root /path/to/project --confirm-local-timeline-recovery
+```
+
+Recovery retains no old source, receipt, or evidence and requires a fresh host
+receipt before another enrollment.
+
+## Bounded retrieval
+
+Hooks do not scan, backfill, or search historic transcripts. They can expose a
+small freshness/status hint and a continuation capsule only. A matching
+`PreToolUse` guard may revalidate source metadata and a fixed ≤4 KiB prefix to
+reject a changed snapshot; it never extracts history. The only historic reader
+is a bound, on-demand MCP call:
+
+```text
+session_timeline_index(maxBytes)
+session_timeline_search(at | terms)
+session_timeline_search(at | terms, includePriorSessions: true)
+```
+
+Indexing is serialized and bounded to 64 KiB–16 MiB per call. A search needs
+either one exact UTC instant such as `2026-09-04T12:40:00.000Z`, or at least two
+concrete terms such as `Suite PASS`. An instant is exact unless the caller
+explicitly requests a valid window. There is no broad-text fallback and no
+whole-transcript MCP tool. Timestamp seeking reads only bounded byte probes and
+a selected bounded range; term search uses only already indexed cards.
+
+After a restart, the lifecycle hint may report only the number of already
+indexed prior sessions and objective events for the exact same private task.
+It does not contain transcript text. When a concrete question is relevant,
+`includePriorSessions: true` restricts candidate sources to the same host,
+entity, user, tenant, project, task and compatible goal. It ranks their signed
+sidecar cards before opening a source, selects at most one prior immutable
+snapshot, and verifies only matching original lines. A missing match does not
+fall back to scanning old transcripts.
+
+A matching host guard replaces all MCP-provided binding fields with its exact
+one-use invocation. Raw stdio, a reused invocation, a changed argument,
+foreign host/session/scope, a group claim, an expired receipt, a changed source,
+or an unsafe sidecar returns no cards. Plain stdio is not a cross-process
+identity channel: the feature remains unavailable without the protected local
+host transport capability. None of these records is a permission or approval.
+
+At most eight cards return. Each carries a timestamp, bounded redacted excerpt,
+stable opaque session and message references, source digest, deterministic room ID, and the
+`untrusted-session-history` trust marker. No public event digest or raw
+transcript byte is returned. Secret-shaped values and instruction-like archive
+text are redacted or discarded before state is written or a card is returned.
+Historic text remains untrusted context: it can support a check or a question,
+never an identity, permission, tool, delegation, access, payment, credential,
+policy exception, or external effect.
+
+## Memory-palace structure
+
+A room ID is deterministic for the enrolled source digest and a fixed one MiB
+byte-offset segment. A
+`agentspine.session-continuation-capsule/v1` contains only current task, goal,
+step, selected-lesson digest, outcome status, and room IDs. It contains no
+transcript text and does not make a room visible by itself.
+
+The authenticated sidecar holds source metadata, bounded redacted cards, and a
+state signature. A separate signed head detects state-only and mixed sidecar
+rollback while the protected integrity anchor remains intact. An exact
+one-generation torn write can be repaired under the owned lock; malformed,
+gapped, missing, altered, symlinked, hard-linked, re-rooted, racing, or
+signature-invalid state yields no cards. Restoring a complete matching local
+integrity directory is not distinguishable without an independent monotonic
+anchor, so AgentSpine makes no stronger rollback claim. It never preserves
+transcript bytes.
+
+## Measured boundary
+
+The synthetic acceptance sources contain 2,500 memory links, four old
+CSS-archive error lessons, and a multi-megabyte prior-session JSONL transcript.
+Before explicit prior-session selection, the restarted session finds no matching
+current result. After selection, the concrete `12:40` query retrieves only the
+matching verified objective result and stable source references; it does not
+load unrelated links or full history. The probes cover source-byte preservation, exact scope
+and group denial, expired and reused records, source/state tampering, profile
+changes, crashes, concurrency, final JSONL records, redaction, and bounded
+results.
+
+## Research inputs
+
+On 2026-09-04, AgentSpine reviewed two public repositories as untrusted
+architectural context only:
+
+- [Claude-Mem](https://github.com/thedotmack/claude-mem), `v13.24.0` at
+  `1df66c2`, Apache-2.0: the search → timeline → observation split informed
+  bounded retrieval.
+- [MemPalace](https://github.com/MemPalace/mempalace), `v3.9.0` at `d5250c7`,
+  MIT: raw-source ownership plus indexed time anchors informed the sidecar
+  boundary.
+
+No external code or script was copied or executed. License, architecture, and
+the current AgentSpine contracts were reviewed before independently implemented
+synthetic tests.
+
+
+## Codex native rollout contract
+
+The `codex-rollout-jsonl/v1` adapter accepts only an explicitly enrolled,
+uncompressed native rollout below the verified Codex profile's `sessions`
+directory. It never lists that directory or discovers neighboring sessions.
+Before enrollment, a bounded first-line read (at most 64 KiB) validates the
+`session_meta` record: native session identity, canonical project `cwd`, CLI
+version syntax, and absent/legacy history mode. The per-session transport,
+owner-confirmed enrollment and one-use PreToolUse invocation remain required.
+A Codex lookup leaves native permission decisions to Codex; the lookup adds no
+prompt or permission grant. King/BLUN cannot reuse this adapter through its
+Codex-compatible instruction hierarchy.
+
+Only native `response_item` tool outputs (`function_call_output`,
+`custom_tool_call_output`, `mcp_tool_call_output`) become historical result
+candidates. User and assistant messages do not. Results include timestamp,
+content digest, stable session/message references, native `call_id`, and a
+bounded original excerpt. They remain **untrusted historical context**, never
+current test verification, completion evidence or a learning authorization.
+Structured facts and corrections remain in the separate structured knowledge
+view; raw transcripts are not copied there. Conflicting historical outcomes
+are retained rather than combined into a new claim.
+
+The search ranks the existing bounded index before opening one selected source.
+Sources must match the same host, project, tenant, user and task; groups,
+unregistered private files, symlink escapes and modified snapshots are excluded.
+A source change makes the snapshot unavailable, including after restart. No
+automatic enrollment refresh, receipt reset or retry follows. Missing history
+must be stated honestly while ordinary authorized work remains possible.
+
+Unsupported: compressed, paginated or inherited/forked history; unknown record
+or explicit schema versions; automatic import of a real user's sessions.
+`cli_version` is header provenance, not proof that every version of a
+Codex installation is compatible. The supported structural contract is pinned
+below. A changed host format requires a reviewed adapter and fresh synthetic
+acceptance, not unchecked migration. No Otto/Fredrik live acceptance is implied.
+
+### Primary source provenance
+
+Inspected 2026-09-06: official [Codex hooks documentation](https://learn.chatgpt.com/docs/hooks)
+provides `session_id` and optional `transcript_path`, and explicitly states that
+the transcript format is not a stable interface. The adapter was independently
+implemented against [openai/codex commit 6af345407d9c2a568da9d01b6c4b81a9e61495c0](https://github.com/openai/codex/tree/6af345407d9c2a568da9d01b6c4b81a9e61495c0),
+Apache-2.0: `codex-rs/rollout/src/lib.rs`,
+`codex-rs/history/src/rollout_payload.rs`, and the protocol definitions
+`protocol.rs` / `models.rs`. That source workspace reports `0.0.0`; it is not an
+installed release-version claim. External sources supplied format evidence
+only; no implementation was copied or executed.
+
+Synthetic acceptance exercises native hooks and restarted MCP processes:
+session A stores a measured failure, session B retrieves its exact source after
+compaction, replay/races admit only one invocation, and foreign scope, changed
+sources, model claims, secret-bearing outputs and unknown formats yield no
+verified historical result. Fixtures create their own profiles and sessions.
+
+## King native agent-wire contract
+
+The `king-agent-wire-jsonl/v1` adapter is separate from both Claude and Codex.
+King may use the Codex-compatible `AGENTS.md` hierarchy for project rules, but
+that does not turn its history into a Codex rollout. The verified King lifecycle
+keeps the runtime host identity as `codex` while binding timeline records to the
+distinct `king` provider.
+
+King history is never discovered automatically. The trusted local launcher must
+provide both `AGENTSPINE_KING_TIMELINE_SOURCE`, pointing to the current
+`sessions/.../session_<id>/agents/main/wire.jsonl`, and
+`AGENTSPINE_KING_WIRE_PROTOCOL_VERSION`, matching that file's metadata header.
+The source must remain below the canonical non-symlinked `BLUN_HOME/sessions`
+root. A prompt, model response, MCP argument, remembered fact, or filename alone
+cannot create this mapping. Missing mappings leave history unavailable without
+blocking ordinary host-authorized work.
+
+Enrollment reads only the bounded first record. It requires the exact metadata
+shape and configured `protocol_version`, a positive integer creation time, and
+the current session directory. Indexing accepts only the reviewed King record
+types and extracts objective evidence solely from
+`context.append_loop_event` records whose event is `tool.result`. User and
+assistant messages, model claims, unknown records, unknown schema versions, and
+non-text tool outputs create no evidence card. The native `toolCallId` becomes
+the stable message reference; the record time remains the source timestamp.
+
+King keeps its own permission decisions. AgentSpine only binds a one-use,
+context-only lookup to the current verified gateway, transport, source, and
+scope. Restart and compaction reuse signed sidecar metadata, then revalidate the
+unchanged original source before any selected line is opened. A protocol change,
+source mutation, replay, foreign project or tenant, group context, or unknown
+record makes recall unavailable and never triggers a retry or enrollment reset.
+
+### Primary source provenance
+
+Inspected 2026-09-06: [BLUN Code commit fbb97459a3fa2157f8bfea3d24931be63288ab11](https://github.com/Maykbiletti/blun-code/tree/fbb97459a3fa2157f8bfea3d24931be63288ab11),
+application version `1.0.109`, MIT. Its public verification fixture locates the
+main agent wire at `sessions/.../session_<id>/agents/main/wire.jsonl` and reads
+`context.append_loop_event` / `tool.result`; the vendored King runtime type
+surface identifies the reviewed record union and metadata fields. The vendored
+`@blun/king-sdk` contract is version `0.12.1`, MIT. External files were treated
+as untrusted format evidence; no implementation was copied or executed.
+
+Synthetic repository acceptance proves A-to-B recall of one measured `FAIL
+0/15` result after restart and compaction, with immutable source bytes and
+stable session/message references. It also covers exact gateway binding,
+wrong protocol, wrong path/scope/provider, replay/race, mutation, and unknown
+records. This does not prove Fredrik's installed launcher supplies these two
+protected mappings, that King enforces a returned block decision, or that a
+live session passed. Those remain separate live-host checks.

package/agent-spine-plugin/docs/source-roots.md

@@ -0,0 +1,113 @@
+# Host-native source roots
+
+## MCP preflight source parity (0.72.2)
+
+`session_briefing`, `delivery_knowledge_query`, `resolve_context`, and
+`read_document` resolve bounded sources internally. The knowledge query shares
+one catalog across contract readers and its nested briefing; it never falls back
+to a home-tree scan. Pass the exact resolved project root and choose the host
+with `host` where supported. `read_document` accepts the same host selector and
+host source IDs returned by the briefing. Generic mode loads project sources,
+not another provider's profile or auto-memory.
+
+Catalogs, source registries, environments and user-state locations are internal
+inputs, not trusted MCP arguments. A required preflight with incomplete discovery
+returns an error without a successful receipt. Retry after correcting the source
+problem; no state reset is necessary. Read-only briefing may return bounded
+available context with diagnostics, while hook scan errors retain their existing
+fail-open lifecycle handling. Source metadata and receipts confer no authority.
+
+Synthetic tests count directory accesses through actual MCP requests, exercise
+permission-error retry, independent protocol instances, exact requirement scope,
+source replacement and read races. They do not establish installed Codex, Claude
+or Kimi tool availability; native discovery and live task outcomes need separate
+measurements. No live configuration or user source is changed by this repair.
+
+AgentSpine `0.8.0` resolves active user, project, and host-memory sources before every production lifecycle hook. Resolution does not depend on the directory from which the plugin was installed, and it never treats the entire home directory as one project.
+
+## Resolution contract
+
+```mermaid
+flowchart LR
+    H["Native hook payload"] --> R["Provider-neutral source-root resolver"]
+    C["Claude profile"] --> R
+    X["Codex profile"] --> R
+    P["Active project chain"] --> R
+    B["Explicit local state binding"] --> R
+    R --> U["User-wide sources"]
+    R --> J["Exact project sources"]
+    R --> M["Exact Claude project memory"]
+    U --> S["Byte-budgeted session_briefing"]
+    J --> S
+    M --> S
+```
+
+Claude resolution follows the documented user and project hierarchy: `CLAUDE_CONFIG_DIR` or `~/.claude`, user `CLAUDE.md` and rules, the active project chain, and the exact project-memory directory evidenced by `autoMemoryDirectory`, `CLAUDE_CODE_PROJECT_DIR_NAME`, or the native hook `transcript_path`. Inside that directory, `MEMORY.md` is the only index. The live path never enumerates that directory and never follows links found inside a fact file. AgentSpine does not guess Claude's private project-directory encoding. See Anthropic's [memory hierarchy and storage-location documentation](https://code.claude.com/docs/en/memory) and [Claude configuration directory documentation](https://code.claude.com/docs/en/claude-directory).
+
+## Indexed and lazy memory
+
+Every direct index link is counted as indexed, but its target is opened only when a marker proves relevance:
+
+```markdown
+- [Communication style](style.md) <!-- agentspine:always -->
+- [BLUN project](projects/blun.md) <!-- agentspine:project=project:blun -->
+- [Alpha team](groups/alpha.md) <!-- agentspine:group=group:alpha -->
+- [Owner preference](people/owner.md) <!-- agentspine:entity=person:owner -->
+- [Current handoff](tasks/handoff.md) <!-- agentspine:task=task:handoff -->
+- [Carbonara preference](food/pasta.md) <!-- agentspine:keywords=carbonara,pasta -->
+```
+
+An exact person, project, group, or task ID must match the current hook scope. Prompt relevance requires a normalized keyword match against the link label, filename, or explicit `keywords` marker. If relevance is uncertain, the target remains unopened. The index itself is always loaded so the host retains its native memory overview.
+
+The persistent cache lives under AgentSpine's platform state directory, outside ordinary agent projects. If the active project root is exactly a recognized user home, the configured AgentSpine state subtree may be below that root but is explicitly pruned before source enumeration; it is never context. The exception does not apply to nested project roots. The cache stores integrity-checked snapshots keyed by an opaque root digest and relative path. A cache hit still opens and validates the original path and file identity, but does not reread or rehash unchanged source bytes. Corrections, deletion, link removal, source-binding rollback, purge, restart, and compaction invalidate or prune the affected cache record immediately. Cache contents and relevance markers are context-only.
+
+Indexed targets use no-follow open semantics. Parent components, canonical scope, regular-file status, size, identity, modification metadata, and the pathname-to-handle identity are checked around the same read. A changing target is retried a bounded number of times and then rejected as a race; mixed snapshots are never injected.
+
+The live resolver processes at most 4,096 direct index links, selects at most eight relevant targets, and opens them one at a time under the host resolver's two-second work budget. `MEMORY.md` and each target are limited to 4 MiB, while the complete external cache is capped at 16 MiB. Exceeding a bound fails closed instead of widening discovery.
+
+Codex resolution uses `CODEX_HOME` or `~/.codex`, selects `AGENTS.override.md` before `AGENTS.md` at user scope, and walks from the configured project root to `cwd`. Per directory it selects override, regular, then the configured `project_doc_fallback_filenames`; `project_root_markers` and `project_doc_max_bytes` are read from the active profile's `config.toml`. Without a root marker, only `cwd` is the project root. See OpenAI's [AGENTS.md discovery order](https://developers.openai.com/codex/agent-configuration/agents-md) and [configuration reference](https://developers.openai.com/codex/config-reference).
+
+Only regular files under these evidenced roots are read. Symlinks are skipped. The resolver caps source count, per-file bytes, aggregate bytes, and recursive host-rule files. Required native instructions are collected first. Optional project-wide Markdown then uses only the remaining aggregate budget, at most 240 files, 8,192 directory entries and the shared two-second resolution budget. Reaching one of those optional discovery bounds keeps the deterministic partial context, skips the remainder and emits an audited `bounded-truncated` warning instead of blocking tools. Mandatory-source, aggregate-byte and safety failures are unchanged.
+
+A project-root scan is never run when the resolved root is the user's home directory or the exact configured Claude, Codex, or BLUN profile root. The self-starter applies the same exact-root exclusion before catalog construction or fingerprinting. A project nested inside a profile is not excluded and remains bounded and fully enforced. Foreign repositories and arbitrary hidden directories are not traversed.
+
+An inaccessible or concurrently removed entry is omitted from a bounded scan and reported in its skipped-path diagnostics. If a deeper scanner still reports a raw `EPERM` or `EACCES` directory-enumeration error, or a scanner-tagged incomplete traversal, every native hook event returns successfully and appends the actual event, phase, code, and affected path to the local scan audit. This availability rule does not convert policy, identity, permission, protected-source, or execution-grant failures into allows.
+
+## Portable user continuity
+
+Accepted preferences, no-gos, corrections, and references can be attached once to the local user through an explicit state binding. The binding references the existing external AgentSpine state; it does not copy records between project hashes.
+
+```bash
+agentspine source-bind /path/where/continuity-was-configured \
+  --host all \
+  --scope state-user \
+  --project /current/project \
+  --host-home /current/profile \
+  --confirm-local-binding
+```
+
+Only portable low-risk learning and the known person relationship context are read from this binding. Project facts, tasks, attention events, group/private project content, delegation policy, execution grants, jobs, secrets, and trust material remain in the exact project state. The registry is append-audited and supports explicit rollback and purge:
+
+```bash
+agentspine source-status --host claude --cwd /current/project --json
+agentspine source-rollback binding:ID --confirm-local-binding
+agentspine source-purge binding:ID --confirm-local-binding
+```
+
+Bindings and their provenance are context-only. They cannot create identity equivalence, roles, permissions, delegation, host trust, or self-starter rights.
+
+## Empty and damaged state
+
+Hook context includes a bounded `sourceResolution` report with checked scopes, counts, profile digest, project root, and the concrete empty or fail-closed reason. Indexed-memory diagnostics add counts for indexed, relevant, loaded, cache hits, cache misses, missing targets, scope omissions, path escapes, symlinks, size rejection, races, and live directory enumeration. They never include fact contents or fact paths. `agentspine doctor --host claude|codex --cwd … --json`, `agentspine source-status`, and `agentspine audit … --host … --json` expose the same report.
+
+Live hooks never enumerate orphaned files. An operator can request the separate bounded offline diagnostic explicitly:
+
+```bash
+agentspine doctor --host claude --cwd /current/project --offline-memory-orphans --json
+```
+
+It reports counts only, reads no orphan content, follows no symlinks, and grants no cleanup or deletion authority.
+
+The installed-bundle check reproduces the original zero-source failure from an AgentSpine checkout and a foreign `cwd`, repeats restart and compaction, exercises custom Claude and Codex homes, Codex fallback and nested override precedence, and proves no broad home scan, no foreign-project visibility, zero model-side MCP calls, exactly one hook set, and unchanged source bytes.
+
+The scale acceptance creates 50,000 real unindexed files beside six indexed entries. For the fully matching scope it records five loaded facts, seven safe opens (`MEMORY.md` twice plus five targets), zero directory enumerations, and no opens, reads, hashes, or counts for the 50,000 files. The same instrumentation result is independent of the unindexed file count; wall-clock thresholds are deliberately not used as a correctness oracle.

package/agent-spine-plugin/docs/structured-completion.md

@@ -0,0 +1,67 @@
+# Structured delivery completion
+
+Process assistance is advisory. Missing, consumed, late or unverified delivery
+receipts do not prevent authorized programming, analysis or ordinary replies.
+Do not reset evidence or repeat tests solely to dismiss a warning. The hook
+records mutation intent before allowing work and emits a bounded, deduplicated
+warning. An unverified Stop does not close a job or record successful learning.
+Access, protected-source, scope and effect-authorization checks remain enforced.
+`complete_delivery` still rejects invalid evidence; permitting a reply does not
+certify a successful delivery or grant publication authority.
+
+AgentSpine 0.72.4 adds `complete_delivery` for ordinary assignment-bound writing deliveries. Version 0.72.5 requires the actual test process result: structured exit code zero or the existing command-bound final marker. Transport success, a still-running process and prose output are not test evidence. An agent can store its three completed premortem checks through MCP and then give the user a normal summary. The operation does not execute a test, create host identity, authorize a write, consume the assignment or bypass Stop.
+
+## Call sequence
+
+1. Obtain the hook-issued assignment and requirement. Call `session_briefing`, `delivery_knowledge_query` and `record_delivery_premortem` before the first write.
+2. Make the changes through the host. Run a recognized test after the latest write. AgentSpine must have observed successful execution through the tool hook; a model-provided success flag is not evidence.
+3. Call `complete_delivery` with the exact root, requirement ID, complete binding, registered artifact digest, latest write digest and three checks. Use the returned identifiers, never identifiers copied from another delivery.
+4. Report the result normally. Stop independently rechecks observed tests, pending writes, scope, mandatory calls, closure integrity and the existing safety gates.
+
+The arguments have this shape; replace placeholders with actual bound values:
+
+```json
+{
+  "root": "/synthetic/project",
+  "requirementId": "<hook-issued requirement ID>",
+  "binding": {
+    "host": "codex",
+    "sessionId": "session:synthetic",
+    "projectId": "project:synthetic",
+    "assignmentId": "<hook-issued assignment ID>"
+  },
+  "artifactDigest": "<registered SHA-256>",
+  "lastWriteDigest": "<latest write SHA-256>",
+  "checks": [
+    { "category": "baseline-environment", "checkId": "<registered check ID>", "status": "PASS", "result": "Source comparison passed." },
+    { "category": "contract-tests", "checkId": "<registered check ID>", "status": "PASS", "result": "Observed artifact test passed." },
+    { "category": "delivery-path", "checkId": "<registered check ID>", "status": "PASS", "result": "Delivered tree matches the tested tree." }
+  ]
+}
+```
+
+Include established entity, group and task fields exactly. Results must be nonempty single-line text, at most 1,024 characters, without secret-shaped content. There must be one check per registered category. These descriptions are the agent's auditable account, not an independent measurement; the server separately requires observed successful post-write tests. Extra arguments such as `success` or a caller-supplied `testStateDigest` are rejected.
+
+## Preservation and concurrency
+
+The existing closure and event journal gain sealed `completionSource: "mcp"` and `testStateDigest` metadata capturing the observed verification state. Existing registrations, rejection receipts and previous-version records are not migrated or rewritten. Stop checks current evidence rather than trusting an old success forever.
+
+Identical retries return the stored closure. Changes to test evidence during the call cannot return successful completion. A later write invalidates the closure and requires fresh tests and its new write digest. A later failed or unverified test invalidates earlier successful verification. Changed check results conflict with an existing closure instead of overwriting history. Foreign bindings and consumed receipts cannot complete another assignment.
+
+The existing atomic replacement and owned lock protect storage. A regression terminates the real MCP process immediately before replacement, verifies unchanged state bytes, waits for the actual lock lease and retries through MCP. It never edits state or lock timestamps to recover.
+
+## Boundaries and measured evidence
+
+Goal- or queue-bound deliveries must use their existing checkpoint and outcome route. `complete_delivery` explicitly rejects them; goal protections are unchanged. The legacy five-line closure remains supported. Skill text does not register tools, and an isolated server test does not establish native Codex, Claude or Kimi compatibility.
+
+Run `node --test test/delivery-completion.test.js test/assignment-continuation.test.js test/delivery-verification.test.js test/mcp.test.js`.
+
+Before the MCP call, a normal Stop summary is allowed with unverified completion and an advisory. Afterwards the same summary can carry verified completion, including after a separate MCP process restart. Negative probes cover absent tests, later failed tests, new writes, foreign bindings, replay, malformed checks, secret-shaped values, concurrent calls and manipulated closure metadata: these never become valid evidence merely because the host can reply. Synthetic source bytes remain unchanged.
+
+Child tests clear inherited `NODE_TEST_CONTEXT` and require TAP evidence of one executed test and zero failures. An actual wrong artifact expectation must produce one failed test and exit 1. This corrects a 0.72.3 test-harness weakness: a recursive child test runner could skip its test while returning exit 0. Earlier positive exit status alone is not counted as proof that the artifact assertion ran.
+
+Version 0.72.5 exercises the official Codex `PostToolUse` fields (`Bash`, `tool_input.command`, `tool_response`), the measured Work `exec_command` result and PowerShell `exitCode`. This establishes the parser contract but not a live Otto restart or installed-reader migration. Native installation/update registration, loaded-reader compatibility, external recovery-event semantics and the live F79 task remain unverified. CodexLink and live session configuration are outside this change.
+
+CI 147's Windows aggregate audit failure was not reproduced by the diagnostic branch's ten passing matrix jobs. The assertion now reports failed gates without relaxing it or changing deadlines. Passing a later run does not establish that intermittent failure's cause.
+
+The first completion candidate exceeded the unchanged mandatory hook-context budget on long macOS and Windows paths. CI 150's diagnostic traced the apparent style rejection to that earlier preflight block. A synthetic 138-byte temporary-root probe reproduces the failure locally. Compact guidance retains every mandatory call, binding, check and legacy closure field, while the long-path Acceptance probe now passes without raising the injection limit or shortening user sources.

package/agent-spine-plugin/docs/world-model.md

@@ -0,0 +1,94 @@
+# Provenance-bound world model
+
+AgentSpine's world model keeps durable assertions about synthetic or real-world subjects outside user-owned source files. It is designed for continuity across turns, restarts, and compaction without turning remembered text or model output into truth or authority.
+
+## Evidence classes
+
+Every assertion has one immutable `evidenceKind`:
+
+- `objective-measurement` records an externally checkable observation;
+- `explicit-user-feedback` records an explicit correction or confirmation;
+- `model-suggestion` records a hypothesis that must remain a proposal.
+
+All three require a stable evidence ID, an evidence SHA-256, an exact observation timestamp, a subject, a predicate, a privacy scope, and the stored value. A model suggestion can never supersede established context. It stays in `proposals` even when its value happens to match an established fact.
+
+`record_world_assertion` is append-only. Repeating the same ID and material is idempotent; reusing an ID for different material fails closed. A newer measured or explicitly user-confirmed assertion can list older same-subject, same-predicate assertions in `supersedes`. Their history remains stored while the new assertion becomes the active view.
+
+## Truth and uncertainty rules
+
+`world_context` returns four separate collections:
+
+- `facts`: unexpired measured or explicitly user-confirmed assertions with one non-conflicting value;
+- `conflicts`: active established values that disagree for the same subject and predicate;
+- `proposals`: active model suggestions;
+- `stale`: assertions whose explicit expiry has passed.
+
+A conflict removes that subject/predicate from `facts` and sets `uncertainty.requiresResolution`. No confidence average can hide it. Expired evidence is never silently reused. Resolving a conflict requires a new established assertion that explicitly supersedes the conflicting assertion IDs.
+
+Session briefing reads this same model. It can expose conflicts, proposals, and stale items as uncertainty, but only the `facts` collection is established world context.
+
+## Structured knowledge and correction history
+
+An assertion may opt into one of five explicit knowledge kinds: `fact`, `user-preference`, `decision`, `task-state`, or `error-lesson`. This is a typed view over the same immutable evidence record, not a second memory store. Each typed item retains its evidence source and digest, observation and recording times, exact project/group/privacy scope, and optional stable session/message references. Decisions additionally require a bounded rationale.
+
+`world_context` derives one of four evidence-based statuses:
+
+- `confirmed` for current objective measurements or explicit user feedback;
+- `assumption` for model suggestions, including repeated matching suggestions;
+- `contradictory` for unresolved established values that disagree;
+- `superseded` for explicitly replaced or expired entries.
+
+Contradictory entries never enter `facts`. A newer explicit correction names every replaced assertion in `supersedes`; the current view then contains the correction while `includeKnowledgeHistory: true` exposes the traceable predecessors. Legacy assertions remain readable but are never retroactively assigned a knowledge kind.
+
+The session briefing carries only the bounded current structured view. Detailed correction history remains opt-in through `world_context`, preventing restarts from loading an ever-growing record. Secret-shaped structured values or rationales are rejected both at ingestion and state validation. A source reference is provenance only: it cannot confirm a model suggestion or create authority.
+
+## Normal-task continuation capsule
+
+A `task-state` assertion may use predicate `task.continuation` and value schema
+`agentspine.task-continuation/v1`. Its task ID must equal the assertion subject.
+The bounded value records the current objective, `active`, `blocked`, `paused`,
+or `completed` state, the last verified step and measurement ID/digest, at most eight
+open questions, and one next step. Both the checkpoint and its last verified
+step carry stable session/message provenance. A completed checkpoint requires a
+passed last step, objective-measurement evidence, and no open questions or next step.
+
+`world_context` derives `knowledge.continuation` only from current, confirmed,
+conflict-free checkpoints. Repeated model suggestions remain assumptions and
+never appear as resumable work. Competing established checkpoints are withheld
+until an explicit supersession resolves them. A newer correction preserves all
+predecessors in opt-in history. The selected checkpoint survives process restart
+and enters `SessionStart`/`PostCompact` briefing without rereading a transcript.
+Terminal checkpoints remain visible separately so completed work is not started
+again. At most eight capsules are returned, and `continuationTaskId` narrows the
+view to one exact task.
+
+This capsule is a working-memory aid, not a job lease or permission. It cannot
+start a tool, authorize a file change, publish, delegate, or replace the existing
+coordination, goal-plan, timeline, host, and safety contracts.
+
+## Task-relevant knowledge
+
+When `continuationTaskId` selects one current resumable capsule, `world_context`
+derives `knowledge.taskContext` from the loaded structured index. A deterministic
+query over its objective, questions, and next step selects at most six confirmed
+facts, preferences, decisions, or error lessons and keeps their source references.
+Uncertain, stale, superseded, private, foreign, and terminal state is excluded.
+No transcript or source is opened, and the view grants no authority.
+
+## Privacy and authority
+
+Assertions use `private`, `shared`, or exact `group` privacy. A group read rejects private inclusion, sees only its exact group records plus shared records, and cannot observe another group's values. Project-scoped records are visible only in that exact project; unscoped records may follow the same installation across project turns when intentionally read from that root.
+
+Every record and result is `context-only`. Predicate and nested-value keys that resemble permissions, authorization, credentials, secrets, tokens, tool access, delegation, production access, payment, or spending are rejected. World context is never consulted by host authorization, delegation, execution, signing, or trust code.
+
+State is written atomically under an owned, heartbeat-protected lock with a 5 MiB bound and mode `0600`. Corrupt JSON, altered value digests, invalid schemas, or authority-shaped persisted data fail closed. The state lives at `world-model.json` under the external per-project AgentSpine state directory; Markdown and other user sources are never changed.
+
+## Research provenance
+
+The design review on 2026-09-04 inspected repository `main` at commit `26b181e95dde34d2fea62cdb8f37258e2bb3f082`, current tests, project instructions, history, open pull requests, and the following public primary sources as untrusted context:
+
+- [W3C PROV-DM](https://www.w3.org/TR/prov-dm/), W3C Recommendation dated 2013-04-30, W3C Document License. Relevant principle: represent provenance through distinct entities, activities, agents, and relations rather than an ungrounded truth label.
+- [NIST AI Risk Management Framework 1.0](https://www.nist.gov/itl/ai-risk-management-framework), released 2023-01-26, official NIST publication. Relevant principle: trustworthy behavior needs explicit measurement, evaluation, and risk handling; the NIST page reported an AI RMF revision in progress when checked.
+- [NIST AI RMF Playbook — Measure](https://airc.nist.gov/airmf-resources/playbook/measure/), checked 2026-09-04, official NIST guidance. Relevant principles: record provenance, repeat measurements, expose measurable and unmeasurable risks, and compare user/community feedback separately from internal measurements.
+
+No external code, data, executable, credential, policy, or permission was imported. The standards influenced only AgentSpine's local schema boundaries and synthetic evaluation cases; AgentSpine remains Apache-2.0.

package/agent-spine-plugin/hooks/codex.json

@@ -4,7 +4,7 @@
     "SessionStart": [
       {
         "matcher": "startup|resume|clear|compact",
-        "hooks": [{ "type": "command", "command": "node \"${PLUGIN_ROOT}/src/hook.js\"", "timeout": 180 }]
+        "hooks": [{ "type": "command", "command": "node \"${PLUGIN_ROOT}/src/hook.js\"", "timeout": 15 }]
       }
     ],
     "UserPromptSubmit": [
@@ -14,7 +14,7 @@
     ],
     "PreToolUse": [
       {
-        "matcher": "Edit|Write|apply_patch|Bash",
+        "matcher": "^(?:Edit|Write|apply_patch|Bash|PowerShell|mcp__(?:plugin_agent-spine_agent-spine|agent-spine)__session_timeline_(?:index|search))$",
         "hooks": [{ "type": "command", "command": "node \"${PLUGIN_ROOT}/src/hook.js\"", "timeout": 15 }]
       }
     ],