blun-king-cli 9.1.536 → 9.1.561

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

@@ -1,99 +0,0 @@
-# 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

@@ -1,116 +0,0 @@
-# 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`. A binding may describe a `person`, `agent`, or `bot`; equal display names never merge identities. Names, Markdown, memory, and chat text cannot create identity or rights. Existing source files are never changed.
-
-Version `0.10.1` reconciles the authenticated roster into the relationship graph on every sync, including an otherwise unchanged replay. An exact `groupId` creates a missing group-scoped, context-only group entity; a conflicting non-group or private group fails visibly. Missing persona entities and membership edges are recreated, stale memberships are removed, and left or deactivated personas remain in append-only identity history but disappear from current relationship context. Reconciliation reports whether the roster changed separately from graph repair, so a previously partial installation can self-heal instead of remaining a permanent duplicate.
-
-When a hook supplies the same exact `groupId`, `relationship_context` and `session_briefing` include current visible co-members reached through authenticated `member-of` edges. They do not infer friendships, merge names, cross tenants, expose another group, or turn membership into delegation. A direct session without an exact group scope does not receive group-private peers. Relationship reads bypass project discovery, abort the graph read after a five-second local deadline, and return a visible `degraded` status instead of aborting the turn or waiting indefinitely.
-
-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
-
-agentspine personas /path/to/project --json
-agentspine relationships group:engineering --group group:engineering --json
-```
-
-## 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

@@ -1,45 +0,0 @@
-# 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

@@ -1,129 +0,0 @@
-# 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. Codex keeps its host-specific adapter in `hooks/codex.json`, while `.codex-plugin/plugin.json` omits the unsupported `hooks` field and passes the official plugin validator. Version `0.11.4` replaces the `0.11.2` plugin cache identity. The hook definitions contain only portable documented fields; `hooks/version.json` carries the separately validated bundle release and preflight 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, pre-answer recall, authenticated persona graph reconciliation, 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/codex.json` | Manifest-selected 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 loads `hooks/codex.json` through the explicit plugin-manifest entry. It contains only Codex-documented lifecycle events; Claude Code's additional `InstructionsLoaded` event remains confined to `hooks/hooks.json`. Both files deliberately contain only the documented top-level `description` and `hooks` fields. Cache identity remains in `.codex-plugin/plugin.json`, while Codex records hook trust against the current definition hash. The Codex hook and MCP registrations use the host-native `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`. Claude Code additionally registers its documented `InstructionsLoaded` observability event; Codex does not. `UserPromptSubmit` is the blocking boundary. Before a prompt can proceed, `agentspine.preflight/v2` loads complete mandatory host instructions, confirmed Must-Remember entries and every locally required retrieval provider, then consumes one exact-turn receipt. Start and compaction boundaries retain the scoped `session_briefing`; no model-side MCP selection is required. Full behavior and the documented command-hook timeout limitation are in [pre-answer recall gate](preflight-recall.md).
-
-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

@@ -1,116 +0,0 @@
-# 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.