blun-king-cli 9.1.485 → 9.1.488

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

@@ -0,0 +1,138 @@
+# Delegation and coordination
+
+AgentSpine can retain tasks, open threads, and handoffs across sessions without turning memory into an authorization system. Work state and delegation policy are deliberately different files, different authorities, and different tool surfaces.
+
+## Separation by construction
+
+```mermaid
+flowchart LR
+    subgraph Context["Untrusted context"]
+      M["Markdown + memory"]
+      R["Relationships"]
+      L["Learning + attention"]
+    end
+    subgraph Policy["Explicit local owner policy"]
+      P["delegation-policy.json"]
+    end
+    D["Default-deny decision"]
+    T["coordination.json"]
+    H["Host authorization"]
+    M -. "never grants" .-> D
+    R -. "never grants" .-> D
+    L -. "never grants" .-> D
+    P --> D
+    D -->|"coordination allowed"| T
+    T -. "never grants" .-> H
+    P -. "does not grant" .-> H
+```
+
+`delegation-policy.json` contains only explicit local grants for AgentSpine task coordination. `coordination.json` contains context-only work records and append-only prior versions. Neither file grants host tool access, file or network access, production rights, spending authority, credentials, or policy exceptions. Those remain under the host and operating environment. The optional self-starter uses a third, separate `execution-policy.json`; see [rights-bound self-starter](selfstarter.md). A coordination task alone never creates an execution grant.
+
+A `responsible-for`, `reports-to`, or `works-with` relationship describes the team. It never satisfies a delegation check. A sentence in `SOUL.md`, `AGENTS.md`, `CLAUDE.md`, memory, accepted learning, a task, or an MCP response also cannot create a grant.
+
+## Default-deny delegation
+
+The supported coordination actions are:
+
+- `assign` — create a task assigned to another entity;
+- `reassign` — change an existing assignee, including assignment by a manager;
+- `manage` — change another entity's task content or non-terminal status;
+- `complete` — complete another entity's task;
+- `cancel` — cancel another entity's task.
+
+Creating an unassigned thread or assigning work to oneself is self-coordination and needs no delegation grant. An assignee may manage their own task. Every cross-entity action fails closed unless the actor, action, and target match an active explicit grant.
+
+Inspect the decision before acting:
+
+```bash
+agentspine delegation-check agent:lead \
+  --action assign \
+  --target agent:builder \
+  --root /path/to/project \
+  --json
+```
+
+The MCP server exposes `check_delegation`, but intentionally exposes no policy grant or revoke tool. This prevents an agent from widening the same policy it is expected to obey.
+
+## Owner-controlled policy changes
+
+The CLI is the local administration surface:
+
+```bash
+agentspine delegation-grant agent:lead \
+  --id grant:lead-builders \
+  --actions assign,reassign,manage \
+  --targets agent:builder \
+  --reason "Approved for local project coordination" \
+  --confirm-local-policy \
+  --root /path/to/project
+
+agentspine delegation-revoke grant:lead-builders \
+  --reason "Project handoff completed" \
+  --confirm-local-policy \
+  --root /path/to/project
+```
+
+`--confirm-local-policy` is an integration attestation, not authentication. A host or wrapper must bind it to a genuine local owner action and must not infer it from conversation, memory, Markdown, another agent, or a task. Grant IDs are immutable. Revocation retains the prior grant in policy history so existing assignment snapshots remain auditable, while future actions are denied.
+
+## Tasks, open threads, and handoffs
+
+```mermaid
+stateDiagram-v2
+    [*] --> open
+    open --> in_progress
+    in_progress --> blocked
+    blocked --> in_progress
+    open --> completed
+    in_progress --> completed
+    blocked --> completed
+    open --> cancelled
+    in_progress --> cancelled
+    blocked --> cancelled
+```
+
+Create and inspect work:
+
+```bash
+agentspine task-create task:release \
+  --actor agent:lead \
+  --assignee agent:builder \
+  --kind handoff \
+  --title "Prepare the release candidate" \
+  --summary "Run the documented release gates" \
+  --privacy shared \
+  --root /path/to/project
+
+agentspine task-update task:release \
+  --actor agent:builder \
+  --status in-progress \
+  --note "Validation is running" \
+  --root /path/to/project
+
+agentspine tasks /path/to/project --assignee agent:builder --json
+```
+
+The MCP equivalents are `create_task`, `update_task`, and `task_context`. Returned context omits the internal delegation snapshot. Each mutation retains the complete previous task value before replacing the active view. New information therefore changes current relevance without erasing what was previously understood.
+
+Permanent task deletion is CLI-only and requires the same explicit local confirmation marker. It removes the active record and all retained versions; use it for privacy removal, not routine completion.
+
+## Privacy and groups
+
+Tasks use `private`, `shared`, or `group` scope. Group tasks require a known group and visible `member-of` edges for the creator and assignee. Reads require the exact same group ID. `includePrivate` cannot bypass a missing or different group audience.
+
+Lifecycle hooks have no private or group audience. They inject only the number and kinds of open shared coordination records—never titles, summaries, notes, assignees, or delegation policy. The agent must explicitly request relevant context.
+
+## Integrity and concurrency
+
+Both state files are private external project state, capped at 5 MiB, written with restrictive file mode and atomic replacement. Cross-process locks serialize policy changes and task mutations. A task mutation holds the policy read lock until its coordination write completes, so revocation cannot race an assignment into existence.
+
+All decision and mutation paths validate current state before use. Unknown entities, secrets, forged provenance, invalid assignment snapshots, malformed JSON, or inconsistent policy cause a fail-closed error. Damaged files are reported by `agentspine audit` and are never overwritten automatically.
+
+## Deliberate limits
+
+- AgentSpine coordinates records without execution authority. The optional self-starter is the sole narrow exception and requires a separate current exact execution grant for every lifecycle effect.
+- It does not send Telegram, email, chat, or notification messages.
+- It does not authenticate the human operating a shell.
+- It does not synchronize policy or tasks across machines.
+- It does not treat organizational relationships as an access-control list.
+- It does not replace host approvals, operating-system permissions, or an external policy engine.

package/agent-spine-plugin/docs/feed-transport.md

@@ -0,0 +1,99 @@
+# Signed mutable feed transport
+
+AgentSpine can discover successive immutable HTTPS snapshots through one signed, compare-and-swap feed. The feed is provider-neutral and deliberately narrow: it is a bounded hash-chain window of snapshot references, not a remote database, command queue, permission source, or replacement for local review.
+
+```mermaid
+sequenceDiagram
+    participant P as Local publisher
+    participant O as Immutable objects
+    participant F as Mutable feed
+    participant R as Local receiver
+    P->>O: Create snapshot object<br/>If-None-Match: *
+    P->>F: GET signed chain + strong ETag
+    P->>P: Append entry and sign entire window
+    P->>F: PUT new chain<br/>If-Match: previous ETag
+    F-->>P: 200/204 or 412 conflict
+    P->>F: Verify exact read-back
+    R->>F: GET signed chain + strong ETag
+    R->>R: Verify trusted key, chain and local receipt
+    R->>O: GET content-addressed snapshot
+    R->>R: Verify snapshot and import to quarantine
+    R->>R: Persist new receipt with prior receipt in history
+```
+
+## Publish
+
+The directory adapter must already be authenticated, and the named signer must remain stable for the lifetime of one feed:
+
+```bash
+export AGENTSPINE_FEED_TOKEN='deployment-supplied-value'
+
+agentspine share-feed-publish /srv/agent-memory/team-alpha \
+  --root /path/to/publisher-project \
+  --base https://memory.example.org/agentspine/team-alpha \
+  --feed feed:team-alpha \
+  --signer signer:team-alpha \
+  --id snapshot:team-alpha-2026-08-28-01 \
+  --token-env AGENTSPINE_FEED_TOKEN \
+  --confirm-local-share
+```
+
+Publication first creates and verifies the immutable object. It then reads the current feed, appends one entry, signs the entire retained window, updates using the previous strong ETag, and verifies an exact read-back. A `412` is a normal concurrency conflict: no retry is hidden, and the caller must fetch the winning feed before deciding whether to publish another snapshot.
+
+The stable feed URL is derived from the SHA-256 digest of `feedId`:
+
+```text
+https://memory.example.org/agentspine/team-alpha/feeds/{sha256(feedId)}.json
+```
+
+## Pull
+
+The receiver explicitly trusts the publisher's exported Ed25519 identity before pulling:
+
+```bash
+agentspine share-feed-pull \
+  --root /path/to/receiver-project \
+  --base https://memory.example.org/agentspine/team-alpha \
+  --feed feed:team-alpha \
+  --token-env AGENTSPINE_FEED_TOKEN
+```
+
+The first observation may join an established feed at its current tip. Every later pull must prove continuity from the locally stored receipt. A lower sequence is a rollback. A different entry at an observed sequence is equivocation. A newer feed whose bounded window no longer contains the observed tip is a continuity gap and fails closed instead of silently skipping history.
+
+The feed retains at most 256 references. Receivers that may remain offline for more than 255 publications should poll less sparsely or begin a new explicitly trusted feed after operator review. Feed signer rotation also requires a new `feedId`; this avoids treating a same-name key as the old identity.
+
+`share-feed-state` shows local receipts and retained prior receipts. There is intentionally no automatic reset command. Removing or replacing rollback protection is an operator decision outside the agent-controlled CLI workflow.
+
+## Server contract
+
+For a new feed, the service must atomically create the resource:
+
+```http
+PUT /agentspine/team-alpha/feeds/{feed-id-sha256}.json
+Content-Type: application/vnd.agentspine.feed+json
+If-None-Match: *
+```
+
+It returns `201` or `204`, then serves the exact document with a strong ETag. Updates require:
+
+```http
+PUT /agentspine/team-alpha/feeds/{feed-id-sha256}.json
+Content-Type: application/vnd.agentspine.feed+json
+If-Match: "the-etag-returned-by-the-last-get"
+```
+
+The service returns `200` or `204` only when that exact ETag still matches. It returns `412` without changing the feed after a competing update. Weak ETags are rejected because they cannot protect byte-exact compare-and-swap semantics. Responses are uncompressed JSON, no larger than 256 KiB, and redirects are never followed.
+
+The object endpoints continue to implement the create-only contract in [immutable HTTPS objects](object-transport.md). A production service should independently authenticate writers, verify request sizes and preconditions atomically, rate-limit access, and avoid logging bearer values or feed bodies.
+
+## Security and authority boundary
+
+- TLS, vetted and pinned DNS, SSRF protection, strict timeouts, no redirects, exact limits, and environment-only bearer tokens apply to both feed reads and writes.
+- Every network write requires explicit local owner confirmation. Private-network access requires the same confirmation plus an explicit opt-in.
+- The signed feed authenticates one configured origin and detects history changes. It does not approve any referenced claim.
+- The referenced snapshot is independently digest-checked and signature-checked, then imported through the existing quarantine. A second local user review remains mandatory before context use.
+- Feed receipts and their history live outside the scanned project and are checked by the ten-gate audit. Corrupt state is never overwritten automatically.
+- Feed payloads, receipts, snapshots, bearer authentication, signatures, and remote service responses always remain `context-only`. They cannot grant permissions, delegation, production access, spending rights, or policy exceptions.
+- Feed publication, pulling, endpoint selection, tokens, and receipt mutation are absent from MCP and hooks.
+
+Existing `AGENTS.md`, `CLAUDE.md`, `SOUL.md`, `MEMORY.md`, and other discovered Markdown files are never transported or modified by this layer.

package/agent-spine-plugin/docs/gateway-runtime.md

@@ -0,0 +1,109 @@
+# Durable gateway worker
+
+AgentSpine `0.8.0` includes an optional long-running worker that closes the gap between a channel message and an actual Claude Code or Codex run. While the worker is running, it polls configured Telegram accounts, authenticates every accepted update against an exact local channel binding, starts one leased agent lane, and delivers one idempotent reply to the original chat, topic, and message.
+
+The worker is not exposed through MCP and is never started by remembered text. Its policy defaults to disabled; the owner enables it once with `agentspine gateway-control /path/to/project --enabled true --confirm-local-gateway`. An operating-system service manager may then supervise it after the owner configures its environment and command line.
+
+## Automatic persona roster
+
+Set `AGENTSPINE_PERSONA_ROSTER_FILE` or pass `--persona-roster` to the worker. The path must be absolute, point to a regular non-symlink JSON file outside the agent project, and remain below 1 MiB. The file uses this envelope:
+
+```json
+{
+  "schema": "agentspine.persona-roster/v1",
+  "revision": 1,
+  "observedAt": "2032-01-01T00:00:00.000Z",
+  "bindings": [
+    {
+      "id": "persona-binding:franz",
+      "authenticator": "host-manifest",
+      "issuer": "host:local",
+      "tenantId": "tenant:blun",
+      "host": "codex",
+      "profileId": "profile:franz",
+      "subjectId": "subject:franz",
+      "kind": "agent",
+      "displayName": "Franz",
+      "sourceBinding": ".codex/agents/franz.md",
+      "groupId": "group:engineering"
+    }
+  ]
+}
+```
+
+Every tick synchronizes authenticated identities before any work is reconciled. New bindings append `join` events; renames retain the stable persona ID; omitted members in the same explicit roster scope become `left`; `"deactivated": true` records a distinct deactivation; reappearance appends `rejoin`. Names, Markdown, memory, and chat text cannot create identity or rights. Existing source files are never changed.
+
+The same approved envelope may contain `nativeDiscovery` scopes. AgentSpine then checks only the officially documented direct agent-manifest directories: Claude Code `~/.claude/agents/` or `<project>/.claude/agents/`, and Codex `~/.codex/agents/` or `<project>/.codex/agents/`. `CLAUDE_CONFIG_DIR` and `CODEX_HOME` replace only their matching user scope. Each scope fixes issuer, tenant, profile, agent/bot kind, and optional group; those authenticated scope fields plus the exact source binding form the stable identity. The manifest contributes only its declared display name and an exact source descriptor; its instructions remain host-native context. Direct regular `.md` or `.toml` files are bounded to 128 entries and 256 KiB each; symlinks and files exchanged during a read fail closed. No other home or project directory is enumerated. See the official [Claude Code custom subagent locations](https://code.claude.com/docs/en/sub-agents) and [Codex custom agent locations](https://developers.openai.com/codex/agent-configuration/subagents).
+
+```json
+{
+  "nativeDiscovery": [
+    {
+      "id": "native:claude:user",
+      "host": "claude",
+      "scope": "user",
+      "issuer": "host:local",
+      "tenantId": "tenant:blun",
+      "profileId": "profile:franz",
+      "kind": "agent",
+      "groupId": "group:engineering"
+    }
+  ]
+}
+```
+
+A one-shot manual validation is available through:
+
+```bash
+agentspine persona-sync /path/to/project \
+  --roster /absolute/path/to/roster.json \
+  --confirm-local-persona
+```
+
+## Telegram and host runner
+
+An active Telegram channel binding needs `receive` and `reply`, an ingress HMAC environment variable, and an outbound Bot API token environment variable. The worker polls only accounts present in current bindings. Unknown chats, topics, senders, and non-text updates do not enter the queue.
+
+`AGENTSPINE_HOST_RUNNER` must be an absolute locally approved executable path. AgentSpine invokes it with no shell and a minimized environment. One bounded JSON request arrives on stdin. For channel work it contains the exact host, profile, project root, agent scope, session key, and `agent_spine_channel_event` reference needed to start the native lifecycle hook. The message text itself is loaded by that hook from the authenticated channel state.
+
+When the runner starts the selected stock CLI, it maps that request to the child process environment: `AGENTSPINE_GATEWAY_CONTEXT=agentspine.gateway-start/v1`, `AGENTSPINE_ENTITY_ID`, `AGENTSPINE_PROJECT_ID`, optional `AGENTSPINE_GROUP_ID`, plus `AGENTSPINE_CHANNEL_EVENT_ID` and `AGENTSPINE_CHANNEL_PROVIDER`. The native `SessionStart` payload does not need proprietary fields; the trusted AgentSpine hook reads this exact environment bridge and then leases the referenced event. The runner must not pass provider tokens or the ingress HMAC secret to the host process.
+
+The runner returns one bounded JSON result:
+
+```json
+{
+  "text": "Die geprüfte Antwort.",
+  "checkpoint": { "step": "verified" },
+  "completed": true
+}
+```
+
+Start one diagnostic tick:
+
+```bash
+agentspine gateway-control /path/to/project \
+  --enabled true --confirm-local-gateway
+
+AGENTSPINE_TELEGRAM_TOKEN='…' \
+AGENTSPINE_TELEGRAM_INGRESS_SECRET='at-least-32-bytes…' \
+AGENTSPINE_HOST_RUNNER='/absolute/path/to/approved-runner' \
+agentspine-worker --root /path/to/project \
+  --persona-roster /absolute/path/to/roster.json --once
+```
+
+Remove `--once` under a service manager for continuous operation. AgentSpine does not silently install a daemon, persist provider tokens, or approve Codex/Claude executable hooks. Codex still requires the current hook definition to be visible and trusted in `/hooks`.
+
+## Goals, attention, and recovery
+
+An agent without a queued message or an owner-assigned goal reports `idle/needs-goal`. `goal-assign` creates one exact focused goal for an active authenticated agent. Promise, resolved-blocker, deadline, assignment, follow-up, and direct-message wakes share bounded per-agent lanes. Each effect rechecks current policy, identity, group, route, and kill-switch state.
+
+Queue leases expire safely, retries are bounded, and the worker wakes on relevant desired-state files or a capped timer without watching its own runtime writes. Prepared and demonstrably effect-free failed deliveries resume after restart. A revoked reply capability or exhausted no-effect retry budget becomes `dead-letter`; ambiguous sends become `delivery-unknown` and are never automatically replayed. Already delivered outbox entries are never sent twice. Checkpoints reject secrets and authority-shaped content. The ten-gate audit replays persona events, gateway history, receipts, lanes, queue IDs, delivery IDs, independent health heartbeats, and current authority markers.
+
+The worker can be stopped locally at any time:
+
+```bash
+agentspine gateway-control /path/to/project \
+  --kill-switch true --confirm-local-gateway
+```
+
+Memory, learning, relationships, persona files, goals, and model output cannot grant channel, tool, process, or execution permission.

package/agent-spine-plugin/docs/harness-reference.md

@@ -0,0 +1,45 @@
+# Harness reference study
+
+This architecture input was reviewed on 2026-08-29 against primary sources only. No upstream code, brand material, or persona text is included in AgentSpine.
+
+## Reviewed snapshots
+
+- OpenClaw `2026.8.1`, commit [`fb7822e1`](https://github.com/openclaw/openclaw/commit/fb7822e1d3333c9417131fa3514000a6a17e6dbd): [multi-agent routing](https://docs.openclaw.ai/concepts/multi-agent), [Gateway protocol](https://docs.openclaw.ai/gateway/protocol), and [cron jobs](https://docs.openclaw.ai/automation/cron-jobs).
+- NousResearch Hermes Agent `0.20.6`, commit [`1c5ee581`](https://github.com/NousResearch/hermes-agent/commit/1c5ee5815fe5a3913530ba9d803b5b60bc633766): [cron guide](https://hermes-agent.nousresearch.com/docs/user-guide/features/cron), [messaging overview](https://hermes-agent.nousresearch.com/docs/user-guide/messaging), and [Telegram guide](https://hermes-agent.nousresearch.com/docs/user-guide/messaging/telegram).
+
+## Architecture comparison
+
+| Pattern | Übernehmen | An AgentSpine anpassen | Bewusst nicht übernehmen |
+|---|---|---|---|
+| Long-lived local gateway | Durable event ownership, health, wake-up, and recovery outside conversational turns | Optional provider-neutral worker; it does not replace the model host or tool registry | No silent network listener, hidden installation, or MCP administration |
+| Agent isolation | Per-agent lane, state, session key, and exact channel-account binding | Separate tenant, profile, project, group, chat, and thread in every route | No fallback from one agent's private session, credentials, or memory into another |
+| Scheduler | Persistent desired state, startup reconciliation, targeted event wake, and independent ticker health | Goals and obligations enter one bounded priority queue; timer is capped and has no busy loop | No prompt-created cron authority and no model-controlled scheduler policy |
+| Isolated scheduled run | Fresh bounded host run with a terminal result and durable checkpoint | Return only the safe result/checkpoint to the responsible main context | No global transcript import and no private cross-session history mixing |
+| Telegram | Stable numeric identities, explicit binding, origin-preserving replies, allowlist-style ingress | HMAC-normalized `agentspine.channel-event/v1`, exact tenant/account/chat/thread/sender/agent scope | No name-based identity, inferred recipient, broad bot token access, or send capability from text |
+| Persona and voice | Per-agent persona source and stable named-bot separation | Authenticated roster metadata plus a bounded context-only `voiceBrief` | No persona file copying, invented feelings, dependency language, or authority from `SOUL.md` |
+| Delivery | Idempotent outbox, receipts, retry, and terminal failure | Ambiguous sends become `delivery-unknown` and require reconciliation rather than replay | No claim of mathematical exactly-once transport; the guarantee is at-most-one automatic external effect |
+
+## AgentSpine contracts derived from the study
+
+1. `agentspine.channel-event/v1` is immutable and binds provider, tenant, account, chat, thread, sender, agent, project, group, privacy, reply target, and observed time.
+2. The optional worker owns typed inbound, run, lifecycle, health, scheduler, and delivery transitions in external private state.
+3. Per-agent lanes serialize work; another agent, tenant, profile, project, group, chat, or thread cannot claim the lease.
+4. Reconciliation expires abandoned leases, detects ambiguous delivery, re-enqueues only demonstrably effect-free failures, and preserves terminal receipts.
+5. Gateway, adapter, scheduler, queue, worker lease, and host runtime have separate health fields. A live process alone is not healthy.
+6. Goals require an authenticated local owner assignment and contain one success criterion, next safe step, deadline, checkpoint, heartbeat, blocker, and history.
+7. Memory, Markdown, persona, relationship, task text, prior output, and MCP never satisfy identity, execution, route, or send policy.
+
+## Regression classes
+
+The local tests cover the public failure classes as contracts rather than copying their implementations:
+
+- A scheduled result that is delivered but never checkpointed cannot become terminal; run completion persists before delivery preparation.
+- A stopped scheduler cannot hide behind a running gateway because health gates are independent and audited.
+- Restart reconciliation converts an in-flight ambiguous send to `delivery-unknown`; it never floods Telegram by replaying it.
+- Every run has a bounded host timeout and one of the terminal or retryable queue states; no final-tool-call ghost remains leased forever.
+- Lease expiry and startup reconciliation close ghost lane rows and allow only safe work to resume.
+- Duplicate provider updates, parallel workers, and repeated delivery calls converge on one event, one lane, one outbox key, and at most one automatic external send.
+
+## Stronger boundaries retained
+
+AgentSpine keeps no global full transcript, exposes no channel, goal, wake, worker, kill-switch, secret, or send administration through MCP, and does not broaden tools from persona or team membership. Host and local policy stores remain physically separate from context state. Explicit host trust and local owner confirmation remain unavoidable security decisions.

package/agent-spine-plugin/docs/host-integration.md

@@ -0,0 +1,129 @@
+# Host integration
+
+AgentSpine uses native plugin surfaces instead of asking users to paste a large system prompt into every project.
+
+## Claude Code
+
+| Component | Path | Purpose |
+|---|---|---|
+| Manifest | `.claude-plugin/plugin.json` | Package identity and version |
+| Marketplace | `.claude-plugin/marketplace.json` | GitHub installation and updates |
+| Skill | `skills/agent-spine/SKILL.md` | Context rules and preservation invariants |
+| MCP | `.mcp.json` | Read-only source tools plus external overlay workflows |
+| Hooks | `hooks/hooks.json` | Automatic briefing, attention, protected-source guard, and rights-bound checkpoints |
+
+Install from GitHub:
+
+```bash
+claude plugin marketplace add Maykbiletti/AgentSpine
+claude plugin install agent-spine@agent-spine
+```
+
+Use `claude plugin validate .` in a checkout to validate the manifest and marketplace. Claude Code asks the user to approve executable plugin components according to its trust model.
+
+The Claude manifest explicitly references `./.mcp.json`. The hook bundle remains at Claude Code's native auto-discovery path `hooks/hooks.json`; it is deliberately not registered a second time through the manifest. Version `0.8.0` replaces the `0.7.0` plugin cache identity. The hook definition contains only portable documented hook fields; `hooks/version.json` carries the separately validated bundle release and lifecycle contract. The repository checks resolve installed-root variables, perform a real MCP `initialize` handshake, validate exactly one native hook command per event, and exercise staged clean install, previous-version cache rejection, upgrade, host-native source resolution, indexed and lazy Claude memory, automatic multilingual briefing, attention, exact job start, tool checkpoint, new-session resume, purge, and uninstall preservation:
+
+```bash
+npm run host:check
+npm run host:install-check
+npm run acceptance
+```
+
+### Claude MCP troubleshooting
+
+If the plugin is listed but `agent-spine` is missing from `/mcp`, update the marketplace cache and reinstall before starting a new session:
+
+```bash
+claude plugin marketplace update agent-spine
+claude plugin uninstall agent-spine@agent-spine
+claude plugin install agent-spine@agent-spine
+claude plugin list
+claude mcp list
+```
+
+Open `/mcp` in the new interactive session and approve or reconnect `agent-spine`. `Pending approval` means discovery succeeded but Claude Code still needs the user's trust decision. A missing entry after reinstall should be diagnosed from `claude plugin validate .`, `npm run host:check`, and Claude Code's plugin diagnostics; AgentSpine does not write to Claude's user configuration or silently approve itself.
+
+## Codex
+
+| Component | Path | Purpose |
+|---|---|---|
+| Manifest | `.codex-plugin/plugin.json` | Package identity plus explicit skill and MCP registration |
+| Skill | `skills/agent-spine/SKILL.md` | Context rules and preservation invariants |
+| MCP | Manifest `mcpServers` | Read-only source tools plus external overlay workflows |
+| Hooks | `hooks/hooks.json` | Auto-discovered lifecycle guardrails |
+
+Open `/plugins` in Codex CLI after configuring a marketplace that contains AgentSpine, then start a new session. Codex presents a startup review when a new or changed hook definition needs trust; there is no `/hooks` slash command. Codex records trust against the exact hook-definition hash, so an installed, updated, or previously untrusted bundle is skipped until that current definition is reviewed and trusted. This follows the official [Codex hooks trust and plugin discovery contract](https://developers.openai.com/codex/hooks).
+
+Codex discovers the hook at the standard `hooks/hooks.json` path. The file deliberately contains only the documented top-level `description` and `hooks` fields; earlier AgentSpine builds added private `version` and `contract` metadata there, which a strict Codex parser could reject before presenting a trust decision. Cache identity remains in `.codex-plugin/plugin.json`, while Codex records hook trust against the current definition hash. Codex sets `CLAUDE_PLUGIN_ROOT` for hook compatibility, so the same hook bundle can execute in both hosts. The MCP registration uses Codex's `PLUGIN_ROOT` expansion.
+
+Verify the live host in a newly started Codex CLI session:
+
+```text
+/plugins
+Trust all and continue
+```
+
+`npm run host:check` proves manifest shape, package containment, and a real MCP handshake. `npm run host:install-check` stages the installed bundle and executes its hook entrypoint with native event JSON. Neither command can manufacture Codex's user-controlled trust receipt; only the startup review in the actual host proves that final boundary.
+
+## BLUN King
+
+| Component | Path | Purpose |
+|---|---|---|
+| Manifest | `blun.plugin.json` | Native BLUN plugin identity plus skill, MCP, and lifecycle-hook registration |
+| Skill | `skills/agent-spine/SKILL.md` | Context rules and preservation invariants |
+| MCP | Manifest `mcpServers` | Read-only source tools plus external overlay workflows |
+| Hooks | Manifest `hooks` | Automatic briefing, attention, protected-source guard, and checkpoints |
+
+Install the local checkout from Fredrik's TUI:
+
+```text
+/plugins install C:\path\to\AgentSpine
+```
+
+BLUN asks the user to trust a third-party plugin before installation because its MCP server and hooks execute local code. Accept that visible install decision, then use `/reload` or `/new`; BLUN has no separate `/hooks` command. The BLUN adapter maps its isolated `BLUN_HOME` to AgentSpine's Codex-compatible `AGENTS.md` source hierarchy, so user state remains under the BLUN app home instead of leaking into `.codex` or a scanned project.
+
+## Direct MCP use
+
+Any MCP client that supports stdio can launch:
+
+```json
+{
+  "mcpServers": {
+    "agent-spine": {
+      "command": "agentspine-mcp"
+    }
+  }
+}
+```
+
+The server implements `initialize`, `ping`, `tools/list`, and `tools/call`. It has no network dependency and exposes no source-file, delegation-policy, signer, trust, or shared-adapter administration tool. Overlay tools write only private AgentSpine context state outside the scanned project. Explicit delegation grants, key generation and rotation, trust changes, adapter connections, publication, HTTPS snapshot export, object upload or pulls, SQLite paths or operations, import review, and destructive sharing operations remain on the local CLI surface. MCP can only read already reviewed `shared_context`; its authentication summary contains no signature or public-key material. `session_briefing` is a read-only aggregator over these already constrained read paths and cannot widen them.
+
+Verify either installation against a synthetic or real project without changing its Markdown:
+
+```bash
+agentspine doctor --json
+npm run host:check
+agentspine audit /path/to/project --json
+```
+
+The audit exits non-zero when a required gate fails, making it suitable for installation smoke tests and CI.
+
+Use `agentspine doctor --host claude|codex --cwd /active/project --json` or `agentspine source-status --host claude|codex --cwd /active/project --json` to see the checked scope counts and a concrete empty/fail-closed reason. The lifecycle adapter never substitutes the installation directory for the active host hierarchy. Details and official host references are in [host-native source roots](source-roots.md).
+
+The provider-neutral lifecycle adapter covers `SessionStart` (including resume and compact starts), `UserPromptSubmit`, `PreToolUse`, `PostToolUse`, `PreCompact`, `PostCompact`, `Stop`, and `SubagentStop`. Start, prompt, and compaction boundaries scan and inject the actual byte-budgeted `session_briefing`; no model-side MCP selection is required. Prompt submission can additionally capture minimal safe learning and direct promise/blocker signals after the separate local continuity opt-in. `PostToolUse` writes an idempotent task heartbeat; `Stop` and `SubagentStop` close that heartbeat without emitting repeated chat text.
+
+When an exact locally registered job is waiting, `SessionStart` acquires its lease and injects its real checkpoint automatically. Subsequent tool and stop hooks resolve that job from the native host session; the model does not need to repeat a job envelope. `PreToolUse` first retains the protected-source guard, then rechecks the current execution grant, assignment, scope, capability, lease, and workspace. `PostToolUse` checkpoints exactly one matching result. A new session resumes only after the same checks. Grant and job administration remain local CLI operations and are absent from MCP. No hook creates permissions.
+
+Identity and audience come from explicit hook scope fields or the locally configured default direct-person/project scope. Group content requires an exact group ID and never enters automatic learning. Missing scope produces no inferred identity; corrupt state returns a visible `failedClosed` packet and must never be reported as successful recall.
+
+Hook stdin is JSON-only and limited to 64 KiB. State transitions use external atomic files and locks. Hook stdout contains only host protocol JSON; diagnostics are bounded to stderr by the host process. Hooks do not expose transport, key, trust, database, network, message, payment, production, delegation, or policy administration.
+
+The first executable-component trust approval remains mandatory. AgentSpine cannot approve itself. After approval and the one-time continuity opt-in, no per-session enablement or voluntary tool call is required.
+
+## Optional gateway worker
+
+The package also registers exactly one `agentspine-worker` entrypoint. It is separate from MCP and lifecycle hooks. When an owner runs it under a service manager, it synchronizes the configured authenticated persona roster, polls current Telegram bindings, prepares exact Claude/Codex start data, invokes only the absolute executable in `AGENTSPINE_HOST_RUNNER` without a shell, and returns one idempotent reply to the bound origin.
+
+The host runner is responsible for starting the selected host with the supplied scope and `agent_spine_channel_event` fields. Codex still refuses the injected context until the current hook hash has been reviewed in `/hooks`; the worker cannot bypass or manufacture that trust. Setup and the stdin/stdout contract are documented in [durable gateway worker](gateway-runtime.md).
+
+The visible acceptance runner invokes the same production lifecycle adapter with new synthetic people, separated groups, Swedish and Spanish prompts, restarts, compaction, correction, rollback, purge, current-rights checks, and durable checkpoints. It prints one reproducible receipt per gate and proves `mcpCalls: 0`. See [visible cross-host acceptance](acceptance.md).

package/agent-spine-plugin/docs/https-transport.md

@@ -0,0 +1,116 @@
+# HTTPS snapshot transport
+
+AgentSpine can carry a signed directory exchange across ordinary HTTPS without depending on a particular cloud, database, or agent vendor. The basic workflow is deliberately static: AgentSpine creates one immutable JSON snapshot, an operator publishes that file through existing infrastructure, and receivers pull it into the normal local quarantine. For direct create-only uploads, use the separate [immutable HTTPS object transport](object-transport.md).
+
+```mermaid
+sequenceDiagram
+    participant P as Publisher CLI
+    participant F as Signed directory adapter
+    participant H as Operator-controlled HTTPS
+    participant R as Receiver CLI
+    participant Q as Local quarantine
+    P->>F: validate signed manifest + every event
+    P->>P: create immutable snapshot outside project
+    P-->>H: operator publishes JSON file
+    R->>H: pinned-DNS HTTPS GET
+    H-->>R: bounded JSON, no redirect/compression
+    R->>R: validate snapshot digest + all Ed25519 envelopes
+    R->>Q: pending imports only
+    Q-->>R: second explicit local review still required
+```
+
+The web server never becomes an authority source. A TLS connection protects bytes in transit. The snapshot digest detects truncation or bundle mutation. The existing Ed25519 envelopes authenticate the configured manifest and event keys. The receiving project's trust store decides which keys are recognized. None of those checks approves a claim, grants a permission, or bypasses review.
+
+## Publish a snapshot
+
+Snapshots require a signed directory adapter. First create the signer, trust distribution, adapter, and events as described in [shared memory adapters](shared-memory.md). Then export:
+
+```bash
+agentspine share-snapshot-export /srv/agent-memory/team-alpha \
+  --root /path/to/publisher-project \
+  --out /srv/static/agent-memory/team-alpha-2026-08-28.json \
+  --id snapshot:team-alpha-2026-08-28 \
+  --confirm-local-share
+```
+
+The output must be outside the scanned project and must not already exist. AgentSpine writes it with owner-only mode on POSIX systems. Updating a feed means exporting a new file or atomically changing a server-side alias outside this static workflow. `share-https-publish` can create immutable remote objects, but AgentSpine still has no remote overwrite, delete, listing, or mutable alias command.
+
+Serve the exact file over HTTPS with:
+
+- a certificate accepted by the local Node.js trust store;
+- `Content-Type: application/json`;
+- no content compression;
+- no redirect at the configured URL;
+- access logs and retention appropriate for the snapshot's metadata sensitivity.
+
+Snapshots contain shared claims, group IDs, timestamps, public signing identities, and signatures. They contain no private learning, source Markdown, evidence text, tasks, delegation policy, credentials, attention state, or relationship profiles. TLS does not encrypt a snapshot stored on the server; secure storage and server access remain deployment responsibilities.
+
+## Pull a public endpoint
+
+Trust every expected event signer in the receiving project first, then run:
+
+```bash
+agentspine share-https-pull \
+  https://memory.example.org/team-alpha-2026-08-28.json \
+  --root /path/to/receiving-project
+
+agentspine share-inbox /path/to/receiving-project --status pending --json
+```
+
+The pull validates the entire response before writing local sharing state. All imports remain `pending` and invisible to `shared_context` until the receiving user accepts each item through `share-review --confirmed-by-user`.
+
+For an endpoint protected by a bearer token, provide only the environment variable name:
+
+```bash
+export AGENTSPINE_SNAPSHOT_TOKEN='deployment-supplied-value'
+agentspine share-https-pull \
+  https://memory.example.org/private/team-alpha.json \
+  --token-env AGENTSPINE_SNAPSHOT_TOKEN \
+  --root /path/to/receiving-project
+```
+
+Tokens are read at request time. They are not accepted in URLs, command arguments, snapshots, local sharing state, hook context, MCP results, or command output. Shell history, process environment access, and server logs are still operating-system concerns.
+
+## Private networks
+
+Public mode rejects loopback, private, link-local, carrier-grade NAT, multicast, reserved, and documentation address ranges. Every DNS answer is checked and the HTTPS connection is pinned to one vetted answer, preventing a second unvalidated lookup from rebinding the request. Mixed public/private answer sets fail closed.
+
+Self-hosted private endpoints require both flags:
+
+```bash
+agentspine share-https-pull \
+  https://memory.internal.example/team-alpha.json \
+  --allow-private-network \
+  --confirm-local-share \
+  --root /path/to/receiving-project
+```
+
+The confirmation is a local integration attestation, not permission derived from memory or an agent. TLS certificate verification remains enabled for private networks.
+
+## Network safety limits
+
+The reference client:
+
+- accepts one explicit `https://` JSON resource with no embedded credentials, query, or fragment;
+- performs one `GET`, disables connection pooling, pins validated DNS, and follows no redirects;
+- rejects non-JSON media types and compressed responses;
+- defaults to a 10-second timeout, configurable only from 1 to 30 seconds;
+- caps the response and validated snapshot at 21 MiB and the event set at 2,000;
+- rejects unknown fields, duplicate IDs, collisions, metadata mismatches, invalid bundle digests, unsigned documents, bad signatures, and untrusted keys before quarantine mutation;
+- deletes its temporary materialization after every success or failure;
+- exposes no HTTPS export or pull operation through MCP.
+
+The static client intentionally does not execute remote instructions, enumerate endpoints, accept remote redirects, refresh tokens, upload data, or implement a hosted control plane. Writable object, local SQLite, and peer transports are separate modules and preserve the same local validation and review boundary; hosted database adapters remain extension work.
+
+## Snapshot schema
+
+`agentspine.https-snapshot/v1` has exact top-level fields:
+
+- stable snapshot, scope, and adapter IDs;
+- generation timestamp;
+- one signed `agentspine.directory-adapter/v1` manifest envelope;
+- up to 2,000 signed `agentspine.shared-event/v1` event envelopes;
+- `authority: context-only`;
+- canonical SHA-256 digest over the complete snapshot body.
+
+Snapshot integrity is packaging evidence, not source identity. Manifest and event signatures are verified independently, and every event signer needs explicit local trust.