blun-king-cli 9.1.486 → 9.1.488

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.

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

@@ -0,0 +1,98 @@
+# Safe learning
+
+AgentSpine separates an observation from a fact that may enter future context. An agent can propose a candidate and append evidence, but the candidate remains invisible to `learning_context` until it passes an explicit review or the narrowly scoped, default-off automatic policy.
+
+```mermaid
+flowchart LR
+    O["Observation"] --> C["Candidate"]
+    C --> E["Append-only evidence"]
+    E --> R{"Review gate"}
+    R -->|"explicit user confirmation"| A["Accepted context"]
+    R -->|"reject"| X["Rejected history"]
+    R -->|"opt-in low-risk policy"| A
+    A --> S["Supersede without erasing"]
+    S --> B["Rollback restores prior fact"]
+```
+
+## Candidate kinds
+
+| Kind | Normal review path | Automatic eligibility |
+|---|---|---|
+| `preference` | Explicit confirmation | Never |
+| `no-go` | Explicit confirmation | Never |
+| `goal` | Explicit confirmation | Never |
+| `correction` | Explicit confirmation | Never |
+| `personal-fact` | Explicit confirmation | Never |
+| `project-fact` | Explicit confirmation | Opt-in, evidence-gated |
+| `reference` | Explicit confirmation | Opt-in, evidence-gated |
+
+Every candidate and evidence record carries `authority: context-only`. Accepted learning can improve relevance and consistency, but it cannot grant permissions, delegation, production access, spending rights, policy exceptions, or instructions to act.
+
+## Evidence and provenance
+
+Evidence is append-only while a candidate is awaiting review. Supported evidence types are `user-statement`, `document`, `interaction`, and `test`. Document evidence must reference a discovered Markdown source; AgentSpine records that source's SHA-256 at observation time without editing it.
+
+Adding evidence stores the previous candidate version in history before recalculating confidence. Distinct evidence IDs or source fingerprints are counted for automatic evaluation. Secret-shaped content is rejected before it reaches learning state.
+
+## Explicit review
+
+Acceptance requires the `confirmedByUser` marker and a review reason. The marker is an integration attestation, not identity proof: a host adapter should set it only after an actual user gesture or unambiguous user instruction. AgentSpine never infers confirmation from another memory, Markdown sentence, candidate, agent message, or relationship edge.
+
+```bash
+agentspine learn-propose learning:concise \
+  --kind preference \
+  --claim "The preferred output is concise." \
+  --evidence "The user explicitly requested concise output." \
+  --privacy private
+
+agentspine learn-review learning:concise \
+  --decision accept \
+  --reason "Explicitly confirmed by the user." \
+  --confirmed-by-user
+
+agentspine learn-context . --include-private --json
+```
+
+Candidates never appear in learned context before acceptance. Native lifecycle hooks inject only accepted, exactly scoped learning inside the byte-budgeted session briefing. They never inject unreviewed candidates.
+
+## Optional automatic promotion
+
+Automatic promotion is disabled by default. When deliberately enabled, it applies only to `project-fact` and `reference`, and only when both confidence and distinct-evidence thresholds pass.
+
+```bash
+agentspine learn-config . \
+  --auto-promote true \
+  --min-confidence 0.9 \
+  --min-evidence 2
+
+agentspine learn-evaluate . --json
+```
+
+The accepted record stores the policy thresholds, evidence count, and evaluation time used for that decision. The audit rejects an accepted record with no valid manual-review proof or automatic-promotion snapshot. Personal facts, preferences, goals, corrections, and no-gos are never automatically promoted by this general evaluator.
+
+This evaluator is separate from [automatic continuity](automatic-continuity.md). After its own local privacy opt-in, the lifecycle adapter may accept only direct, high-confidence style preferences, no-gos, corrections, project facts, and references with a recorded threshold proof. Personal facts, group conversation content, identity claims, secrets, authority, access, and operational permissions are never eligible. The continuity path is not exposed through MCP.
+
+## Supersession and rollback
+
+New information does not overwrite an accepted fact. Propose a new candidate with `--supersedes` and the same kind, subject, and privacy scope. Acceptance marks the prior record `superseded` and retains both versions. Rollback deactivates the replacement and restores the prior accepted record atomically.
+
+```bash
+agentspine learn-propose learning:new-goal \
+  --kind goal \
+  --claim "The current goal is the new synthetic milestone." \
+  --evidence "The user changed the goal." \
+  --supersedes learning:old-goal
+
+agentspine learn-rollback learning:new-goal \
+  --reason "The change was recorded incorrectly."
+```
+
+Permanent deletion removes one candidate and its learning history. An accepted superseding record must be rolled back before deletion so its predecessor is not stranded.
+
+## Privacy and groups
+
+Private learning requires an explicit `includePrivate` read. Group learning requires a known group entity, an exact `groupId`, and—when a subject is present—a visible `member-of` edge. `includePrivate` does not bypass a different or missing group audience. Session hooks have no group audience and therefore expose no group learning.
+
+## Storage and concurrency
+
+`learning.json` lives in the same external per-project state directory as the catalog, graph, and attention state. Mutations use a per-project lock and atomic replacement, so concurrent agents cannot silently discard evidence. State is capped at 5 MiB and original Markdown remains byte-for-byte unchanged.