warpmetal 0.9.0 → 0.9.2

package/README.md

@@ -353,6 +353,47 @@ checkout requires the private WarpMetal owner token, so x402api authorizes and
 WarpMetal submits. WarpMetal keeps `--payment-signature-file` for another
 compatible external signer.
 
+## Retained Work and Insights
+
+The positional management commands use an existing server owner or SSH login:
+
+```sh
+warpmetal work list SERVER BOX --json
+warpmetal work show SERVER BOX WORK --json
+warpmetal work checkpoint SERVER BOX WORK --file checkpoint.json --json
+warpmetal work status SERVER BOX WORK --kind checkpoint --request REQUEST --json
+warpmetal insights list SERVER BOX --json
+warpmetal insights manager settings SERVER BOX --json
+warpmetal work open SERVER BOX WORK --connection-file sandbox.json --identity /path/to/sandbox-key
+warpmetal insights review SERVER BOX RUN --connection-file sandbox.json --identity /path/to/sandbox-key
+```
+
+Mutations require a closed JSON request with its request ID and exact revision
+fences. The private intent journal saves only opaque IDs, a body digest and
+progress before sending the mutation. Repeating the same intent uses GET-only
+reconciliation; a different body on the same route and request ID is refused.
+Pending operations exit 8, conflicts and terminal failures exit 5. A completed
+continuation or handoff receipt proves task admission; the task outcome remains
+pending.
+
+Metadata output excludes private Work content. `work content` deliberately
+returns that text, and `work create`/`update` accept it through the explicit
+input file. Redirects, oversized responses and malformed or foreign authority
+are refused before output. Account login does not authorize these endpoints;
+use `server login` or an existing scoped owner token.
+
+`open` and `review` fetch a fresh exact session descriptor. With `--json`, they
+return the descriptor without attaching. Interactive access requires a sandbox
+SSH grant, its pinned connection profile, matching sandbox identity, and local
+OpenCode 2.0.14. The fixed SSH bridge launches no initial prompt or new session.
+Manager review remains read-only; recommendation mode cannot automatically
+steer a worker. Protected takeover and Resume are explicit, revision-checked
+operations.
+
+See the complete [Work commands](docs/agent-work-cli.md),
+[Insights and manager commands](docs/agent-insights-cli.md), and
+[session transport](docs/session-handoff-transport.md).
+
 ## Security boundary
 
 - Order and access tokens are never printed; they are written to
@@ -366,8 +407,9 @@ compatible external signer.
 - The CLI writes x402api-compatible request envelopes and accepts validated
   x402api payment artifacts or a compatible external `PAYMENT-SIGNATURE` file.
   Wallet key management and signing remain outside this package.
-- Destructive or state-changing commands require explicit confirmations and
-  generate idempotency keys by default.
+- Destructive lifecycle commands require explicit confirmations and generate
+  idempotency keys by default. Work and Insights mutations require an explicit
+  closed request file with its request ID and revision fences.
 - Runtime bootstrap credentials remain memory-only. Manual installation asks
   for one only after the first host key has been pinned and strictly reverified;
   automatic reload bootstrap is rendered directly into provider-bound
@@ -383,6 +425,11 @@ compatible external signer.
   production image. It briefly disconnects active sessions but preserves the
   external workspace, lifetime, and start time. The wait completes only when
   the observed digest and generation both match the accepted target.
+- `sandbox action --action patch_image --confirm patch_image --image-digest <image@sha256:digest> --wait`
+  selects an approved immutable image for one sandbox while retaining its
+  incarnation generation. It briefly disconnects active sessions; the wait
+  requires the exact requested image digest even when the old container is
+  still running at that generation. Other actions refuse `--image-digest`.
 - Guarded reload powers the server off first. Runtime-enabled reload requires a
   second acknowledgment because all sandbox workspaces are erased. WarpMetal
   places the approved signed Runtime bootstrap in reload cloud-init

package/docs/agent-insights-cli.md

@@ -0,0 +1,123 @@
+# Agent Insights CLI contract
+
+Status: implemented in the reviewed CLI 0.9.1 candidate; publication and deployed qualification remain pending. Commands below use
+the closed, versioned owner contracts in `src/contracts/`; historical
+qualification evidence is retained separately from this source checkpoint.
+
+Agent Insights uses the existing server-owner token from `warpmetal server
+login`. It does not fall back to account login, create a sandbox grant, submit
+a prompt, start a provider call, or change manager/takeover state while reading
+or opening a session.
+
+## Commands
+
+All resource identifiers are positional. Mutations read a bounded, closed JSON
+object from `--file`; `--idempotency-key` defaults to that object's `requestId`.
+
+```text
+warpmetal insights summary SERVER [--limit N] [--cursor BOX]
+warpmetal insights status SERVER BOX
+warpmetal insights enable SERVER BOX --file FILE [--idempotency-key KEY]
+warpmetal insights disable SERVER BOX --file FILE [--idempotency-key KEY]
+warpmetal insights list SERVER BOX [--limit N] [--cursor FINDING]
+  [--state open|resolved] [--session SESSION] [--severity warning]
+  [--attention unacknowledged|acknowledged|snoozed|dismissed]
+  [--rule RULE] [--recent-hours 1|24|168|720]
+warpmetal insights show SERVER BOX FINDING
+warpmetal insights acknowledge SERVER BOX FINDING --file FILE [--idempotency-key KEY]
+warpmetal insights snooze SERVER BOX FINDING --file FILE [--idempotency-key KEY]
+warpmetal insights dismiss SERVER BOX FINDING --file FILE [--idempotency-key KEY]
+warpmetal insights open SERVER BOX FINDING [--takeover OPERATION]
+  [--connection-file FILE] [--identity PATH]
+
+warpmetal insights manager settings SERVER BOX [--file FILE] [--idempotency-key KEY]
+warpmetal insights manager activity SERVER BOX [--limit N] [--cursor RUN]
+  [--finding FINDING]
+warpmetal insights manager run SERVER BOX RUN
+warpmetal insights manager target SERVER BOX FINDING
+warpmetal insights manager recheck SERVER BOX FINDING --file FILE [--idempotency-key KEY]
+warpmetal insights manager status SERVER BOX FINDING --request REQUEST
+
+warpmetal insights takeover list SERVER BOX FINDING [--limit N] [--cursor OPERATION]
+warpmetal insights takeover SERVER BOX FINDING --file FILE [--idempotency-key KEY]
+warpmetal insights takeover status SERVER BOX FINDING --operation OPERATION
+warpmetal insights takeover resume SERVER BOX FINDING --operation OPERATION
+  --file FILE [--idempotency-key KEY]
+
+warpmetal insights review SERVER BOX RUN [--connection-file FILE] [--identity PATH]
+```
+
+The settings `enable` and `disable` verbs require the canonical Insights
+settings mutation and require `enabled` to match the verb. Finding action verbs
+likewise require the canonical action to match the verb. Manager settings with
+no file is a GET; with a file it is a PATCH. Manager status and takeover status
+are GET-only recovery lookups using the explicit `--request` or `--operation`.
+
+The `open --takeover OPERATION` option verifies an existing exact ready pause
+operation. It never creates one. The finding, source, member, policy and hold
+must still be current, and a superseding resume makes the proof stale. If the
+owner API cannot establish those facts, the CLI refuses the handoff. Ordinary
+`open` remains a read-only exact-session lookup.
+
+With `--json`, `open` and `review` print only the freshly validated canonical
+session-handoff descriptor and never claim that SSH or a native client opened.
+Without `--json`, they pass that descriptor to the separately owned fixed
+session-handoff launcher. Merely listing, showing, copying, opening or reviewing
+never acknowledges a finding, starts a review, pauses a member, resumes a hold,
+creates a session, or sends a prompt.
+
+## Transport and replay
+
+The handler exports:
+
+```text
+async handleInsights(positionals, options, services): number
+```
+
+`services` contains `client`, `store`, `context`, `requireServerToken`, `emit`,
+`readInput`, `runMutation`, and `openSessionHandoff`. Authentication calls
+`requireServerToken(store, serverId, options, context.env)`. HTTP uses
+`client.request(method, path, {token, body, idempotencyKey})`.
+
+Every mutation calls `runMutation` with the fixed exact API `path`, server and
+sandbox scope, mutation kind, validated request ID/body, and submit/reconcile
+callbacks. The journal is written before the first request. Repeating the same
+intent performs recovery with GET only; a changed body conflicts locally.
+Settings and finding actions reconcile through their read projections. Manager
+Recheck uses the request lookup route. Takeover and Resume use the exact
+operation lookup routes.
+
+Mutable-resource reconciliation succeeds only when the current GET still
+proves the saved request. Settings and attention require exactly the requested
+revision plus one and the requested state. Manager policy additionally requires
+the requested rules and limits; its public expiry and update timestamps must
+still prove the requested authorization duration. Runtime policy acknowledgement
+and manifest renewal can change those timestamps without changing the policy
+revision, so a later GET may conservatively return an unknown outcome even when
+the currently displayed policy is otherwise useful. `manager settings` without
+`--file` remains the way to inspect that current state without claiming recovery
+of an older mutation.
+
+A snooze deadline is derived from the backend clock and its public finding does
+not include the mutation timestamp. The initial POST receipt can prove the next
+attention revision, snoozed state and presence of the server-derived deadline;
+a GET-only retry cannot prove the originally requested duration and therefore
+fails closed. The CLI never retries the POST. Recheck, Takeover and Resume bind
+their public receipts to every request-carried revision, source, target and
+budget field that the backend projects. Resume also reads and verifies the exact
+predecessor policy and hold tuple before submission or recovery.
+
+The handler consumes unchanged owner projection modules:
+
+- `src/contracts/insights.js`: Insights query, mutation and response projectors;
+- `src/contracts/manager.js`: manager query, mutation and response projectors;
+- `src/contracts/session-handoff.js`: exact-session envelope projector.
+
+Unknown options, surplus positionals, malformed files, action/verb mismatch and
+invalid queries fail before any network request. Unknown or expanded server
+responses fail closed and are never printed. Input files are capped at the
+shared mutation limit and raw provider text, credentials, prompts and paths do
+not appear in output.
+
+Accepted/pending work exits 8. A terminal recommendation or `no_action` exits 0; `no_action` preserves its actual closed state and safe outcome instead of claiming a recommendation. Terminal failures exit 5. A completed review that requires owner attention retains `needs_owner`; opening its exact valid proposal-bearing session remains read-only. Authentication failures retain exit 4, request/transport/contract
+failures retain the shared CLI codes, and syntax/input errors exit 2.

package/docs/agent-work-cli.md

@@ -0,0 +1,72 @@
+# Retained Work CLI
+
+The Work commands use the existing server owner or short-lived owner SSH token.
+They never fall back to the account session and never accept a bearer token on
+the command line.
+
+## Command grammar
+
+Commands are positional:
+
+```text
+warpmetal work list SERVER BOX [--cursor CURSOR] [--limit N]
+warpmetal work show SERVER BOX WORK
+warpmetal work content SERVER BOX WORK [--revision N]
+warpmetal work sources SERVER BOX [--cursor CURSOR] [--limit N]
+warpmetal work policy SERVER BOX
+warpmetal work create SERVER BOX --file REQUEST.json [--idempotency-key KEY]
+warpmetal work update SERVER BOX WORK --file REQUEST.json [--idempotency-key KEY]
+warpmetal work enable SERVER BOX WORK --file REQUEST.json [--idempotency-key KEY]
+warpmetal work checkpoint SERVER BOX WORK --file REQUEST.json [--idempotency-key KEY]
+warpmetal work continue SERVER BOX WORK --file REQUEST.json [--idempotency-key KEY]
+warpmetal work restore SERVER BOX WORK --file REQUEST.json [--idempotency-key KEY]
+warpmetal work handoff SERVER BOX WORK --file REQUEST.json [--idempotency-key KEY]
+warpmetal work targets SERVER BOX WORK
+warpmetal work status SERVER BOX WORK --kind checkpoint|continue|restore|handoff
+  (--request REQUEST | --operation OPERATION)
+warpmetal work open SERVER BOX WORK [--connection-file FILE] [--identity FILE]
+```
+
+The common `--base-url`, `--state-dir`, `--token-file`, `--json`, and `--help`
+options retain their existing meanings. `open --json` fetches and prints a
+fresh validated handoff descriptor without starting SSH. Non-JSON `open`
+passes the same validated descriptor to the existing grant-bound session
+bridge; it cannot choose a path, shell command, native project, or session.
+
+## Closed input and output
+
+Every mutation reads one explicit JSON object from `--file`. Create and update
+permit at most 2 MiB of encoded JSON because those are the only deliberate
+private Work-content writes. Other mutation inputs are limited to 64 KiB. The
+canonical projectors reject unknown fields, invalid identifiers, stale or
+missing revision fences, invalid task pairs, unsupported target modes, and
+oversized content before a network request.
+
+The idempotency key defaults to the request body's exact `requestId`. An
+explicit `--idempotency-key` changes only the HTTP idempotency header. The
+private mutation journal binds origin, fixed API path, request ID, and body
+digest before the first POST. An ambiguous later invocation of the same intent
+uses only the command's fixed GET reconciliation route. It never resubmits the
+mutation or changes its body. A changed body under the same origin, fixed path,
+and saved request ID is a local conflict. A distinct fixed path has its own
+journal record.
+
+Metadata commands never print objective, constraints, context, credentials,
+host paths, native workspace directories, or raw Runtime evidence. `content`
+is the deliberate private-text read and `create`/`update` are the deliberate
+private-text writes. All server responses pass the reviewed closed Work,
+continuation, handoff, or session-handoff projector before output.
+
+## Operation outcomes
+
+A pending, reported, or outcome-unknown operation exits 8. Failed or
+superseded operations exit 5. A validated terminal `accepted` checkpoint exits
+0 only with its checkpoint receipt; restore exits 0 only with its materialized
+target; continuation and handoff exit 0 only with their admitted task/baseline
+receipt. Human output says `checkpoint saved`, `workspace restored`,
+`continuation admitted; task outcome pending`, or
+`handoff admitted; task outcome pending`; admission never claims the task
+finished.
+
+`status` is GET-only and requires exactly one saved request ID or operation ID.
+It cannot create or replay an operation.

package/docs/session-handoff-transport.md

@@ -0,0 +1,68 @@
+# Exact managed-session handoff transport
+
+Status: bounded transport implementation complete locally on 2026-09-27. Domain CLI dispatch and live native proof remain separate gates.
+
+The reusable Agent Kit boundary is:
+
+```js
+openSessionHandoff(descriptor, {
+  connectionFile,
+  identityPath,
+  context,
+  clientPath,
+}) -> Promise<number>
+```
+
+`descriptor` is the complete backend `AgentSessionHandoffEnvelope`. The function returns the local native client's numeric exit code. It throws a `CliError` with a closed `session_handoff_*` code when validation, SSH, framing, handshake, or relay setup fails. `connectionFile` and `identityPath` are explicit first-release prerequisites. `clientPath` defaults to `opencode`. `context` supplies bounded clock/environment/process seams for the real child-process journey; production defaults use the current clock, process environment, Node child processes, and cryptographic randomness.
+
+The domain CLI owns API lookup and command dispatch. Its JSON mode validates and prints the fresh backend descriptor without calling this function, starting SSH, or claiming a native attachment. A successful `HELLO_ACK` proves only that the bridge accepted the exact target. The connector does not claim that the native TUI rendered or attached to the conversation.
+
+## Validation and transport
+
+The connector accepts only the closed v1 envelope with `capability: exact_session`, `reason: null`, all three required access booleans true, `transport: wm-team-control/1`, and a non-null closed handoff target. The target must be fresh at the local clock and its issuance window must be no longer than 120 seconds. Its server and sandbox IDs must exactly match the version-1 sandbox connection profile. Unknown fields, raw path/URL/credential overrides, malformed IDs, invalid revisions, mixed task/Work shapes, expired descriptors, and profile mismatches fail before SSH starts.
+
+The sandbox identity must be an explicit regular private file. The connector never reads or exports its contents. It writes a private temporary `known_hosts` file from the validated connection profile and executes only:
+
+```text
+ssh -T -i <identity> \
+  -F <private empty config> \
+  -o BatchMode=yes -o PasswordAuthentication=no \
+  -o KbdInteractiveAuthentication=no \
+  -o IdentitiesOnly=yes \
+  -o StrictHostKeyChecking=yes \
+  -o UserKnownHostsFile=<private temporary file> \
+  -o ClearAllForwardings=yes -o ForwardAgent=no -o ForwardX11=no \
+  -o PermitLocalCommand=no -o RequestTTY=no \
+  -o ControlMaster=no -o ProxyCommand=none -o ProxyJump=none \
+  -p <profile port> warpmetal-sandbox@<profile host> \
+  warpmetal-team-control
+```
+
+There is no shell, arbitrary remote command, PTY fallback, management identity, agent forwarding, X11 forwarding, or SSH port forwarding.
+
+The first frame is the bounded `wm-team-control/1` `HELLO`:
+
+```json
+{"v":1,"protocol":"wm-team-control/1","handoff":"<exact descriptor.handoff>"}
+```
+
+No local native client starts until a bounded-time `HELLO_ACK` repeats the protocol and exact handoff receipt/target byte-equivalently as parsed JSON. The acknowledgement's box identity must also repeat the target server, sandbox, sandbox generation and instance; its host-key fingerprint must be one of the explicit profile pins. Runtime derives the private bridge grant ID as `"grt_" + sha256(profile.grantId + NUL + handoffId)[0:24 hex]`; the connector independently derives and requires that exact value, preserving the distinction between the public `grant_*` access-grant ID and the private `grt_*` bridge grant. The acknowledgement's engine fields are advisory and are never used to open a direct connection. A changed target, box, derived grant, host key, missing receipt, error, close, malformed frame, oversized frame, EOF, timeout, or SSH exit fails without launching OpenCode.
+
+## Local native client
+
+After the exact acknowledgement, the connector binds one ephemeral HTTP server to `127.0.0.1`. It generates a process-local password, requires HTTP Basic `opencode:<password>` on every request, removes that credential before framing, and passes it only to the owned native child as `OPENCODE_PASSWORD`. This is the pinned 2.0.14 client-side credential variable; `OPENCODE_SERVER_PASSWORD` is for the server and is removed from the local client environment. WarpMetal owner/access tokens and credential variables are also removed. It sets `OPENCODE_DISABLE_AUTOUPDATE=1` and launches exactly:
+
+```text
+opencode --server http://127.0.0.1:<ephemeral-port> \
+  --session <descriptor.handoff.source.nativeSessionId>
+```
+
+It adds no project path, prompt, continue, role, agent, provider, standalone, or model argument. The bridge owns native service authentication; neither native credentials nor the local relay password cross SSH.
+
+The relay supports bounded HTTP and SSE over request, response-head, data, end, cancel, ping/pong, error, and close frames. It rejects upgrades, non-loopback Host/Origin values, bodies over 1 MiB, more than 32 in-flight requests, response frames over 8 MiB, and unrecognized frames. Manager-review mutation remains denied by the trusted sandbox bridge; the connector preserves the bridge's `team_helper_manager_review_read_only` refusal as an HTTP 403. Ordinary worker owner input can pass only as an explicit request made by the native client and remains subject to the bridge's exact-session revalidation. Opening itself emits no prompt or session creation request.
+
+When the native client exits, the connector sends one close frame, closes its relay, ends the owned SSH process, removes temporary host pins, clears its local password reference, and returns the client exit code. SSH loss tears down only connector-owned processes. It never stops or restarts the managed service or worker.
+
+## Test boundary
+
+`test/session-handoff-e2e.test.js` uses the unchanged backend fixture at `test/fixtures/agent-session-handoff-v1.backend-wire.fixture.json` (SHA-256 `75934b615896344032bc50157756264030bae87be5de6ceafd299d95f703aa56`). It starts actual fake SSH and native-client child processes plus the connector's real loopback HTTP/SSE listener. The journey proves exact HELLO/ACK order, strict SSH arguments and host pins, local Basic authentication, credential stripping, exact native arguments, GET/SSE transport, zero open-time prompt/create requests, pre-SSH target refusals, changed protocol/target/box/derived-grant/host-key refusal before client launch, bridge-loss cleanup, and manager-review mutation refusal.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "warpmetal",
-  "version": "0.9.0",
+  "version": "0.9.2",
   "description": "Agent-safe CLI and skill for purchasing, renewing, and managing WarpMetal VPS servers",
   "type": "module",
   "bin": {
@@ -10,13 +10,15 @@
     "bin/",
     "src/",
     "skills/warpmetal/",
-    "README.md"
+    "README.md",
+    "docs/agent-*.md",
+    "docs/session-handoff-transport.md"
   ],
   "engines": {
     "node": ">=20.0.0"
   },
   "scripts": {
-    "check": "node --check bin/warpmetal.js && node --check src/account-gateway.js && node --check src/account-session.js && node --check src/api.js && node --check src/args.js && node --check src/cli.js && node --check src/connection.js && node --check src/customer-auth.js && node --check src/errors.js && node --check src/host-trust.js && node --check src/install-skill.js && node --check src/installer.js && node --check src/models.js && node --check src/payment.js && node --check src/runtime.js && node --check src/ssh-alias.js && node --check src/ssh.js && node --check src/state.js && node --check src/version.js",
+    "check": "node --check bin/warpmetal.js && node --check src/account-gateway.js && node --check src/account-session.js && node --check src/api.js && node --check src/args.js && node --check src/cli.js && node --check src/connection.js && node --check src/customer-auth.js && node --check src/errors.js && node --check src/host-trust.js && node --check src/install-skill.js && node --check src/installer.js && node --check src/models.js && node --check src/payment.js && node --check src/runtime.js && node --check src/ssh-alias.js && node --check src/ssh.js && node --check src/state.js && node --check src/version.js && node --check src/agent-management.js && node --check src/agent-work.js && node --check src/agent-insights.js && node --check src/session-handoff.js && node --check src/contracts/work.js && node --check src/contracts/work-handoff.js && node --check src/contracts/insights.js && node --check src/contracts/manager.js && node --check src/contracts/session-handoff.js",
     "plugin:check": "node --test test/plugin.test.js",
     "test": "node --test",
     "prepack": "npm run check && npm test"

package/skills/warpmetal/SKILL.md

@@ -356,3 +356,50 @@ If the installed CLI lacks a required runtime command, stop, explain the
 version limitation, and ask before upgrading the official npm package. Do not
 reconstruct runtime changes with raw HTTP, ad hoc SSH, Podman, Docker, or host
 configuration commands.
+
+## Retained Work and Insights
+
+The source candidate adds positional Work, Insights, manager and exact-session
+commands. Confirm their presence with `warpmetal --help` before use. They
+require an existing server owner or SSH login; the account login session does
+not authorize these routes. Keep `--json` for agent-driven metadata and status
+commands.
+
+```sh
+warpmetal work list SERVER BOX --json
+warpmetal work show SERVER BOX WORK --json
+warpmetal work status SERVER BOX WORK --kind checkpoint --request REQUEST --json
+warpmetal insights list SERVER BOX --json
+warpmetal insights manager settings SERVER BOX --json
+warpmetal insights manager status SERVER BOX FINDING --request REQUEST --json
+```
+
+Mutation requests use `--file` with a closed JSON object containing its saved
+request ID and exact revision fences. Persist the owner's intended request
+before invoking a mutation. The CLI journals only opaque IDs and a body digest
+before dispatch. Repeating the same origin, route and request ID performs
+GET-only reconciliation. Never replace the request ID to work around an
+ambiguous response, stale revision or conflict. Pending operations exit 8;
+conflicts or terminal failures exit 5. Accepted continuation/handoff proves
+admission, while the task outcome remains pending.
+
+Ordinary output is metadata. `work content` deliberately reads private owner
+text; `work create` and `work update` deliberately write it from the explicit
+request file. Do not copy private content into evidence, logs or unrelated
+commands.
+
+`work open SERVER BOX WORK --json`, `insights open SERVER BOX FINDING --json`
+and `insights review SERVER BOX RUN --json` return a fresh validated descriptor
+without attaching. Human interactive mode needs `--connection-file` plus
+`--identity` for the selected sandbox grant, and local OpenCode 2.0.14. It uses a
+fixed, pinned SSH bridge and exact session ID, creates no session and sends no
+initial prompt. Do not substitute the VPS owner identity, raw host paths or a
+fallback session. Manager review is read-only. Recommend mode has no automatic
+worker steering; protected takeover and explicit Resume require the current
+operation, policy and hold revisions.
+
+Complete schemas and grammar accompany the candidate package in
+`docs/agent-work-cli.md`, `docs/agent-insights-cli.md` and
+`docs/session-handoff-transport.md`. These commands require the matching
+candidate control plane, Runtime and Sandbox; CLI availability alone does not
+prove that the server supports them.

package/skills/warpmetal/references/cli-reference.md

@@ -10,6 +10,7 @@
 - Server management
 - Agent Runtime and sandboxes
 - Per-agent access
+- Retained Work and Insights (source candidate)
 - Skill installation and state
 - Exit codes
 
@@ -342,8 +343,8 @@ warpmetal sandbox list --server <serverId> --json
 warpmetal sandbox get --server <serverId> --sandbox <sandboxId> [--wait] --json
 warpmetal sandbox action \
   --server <serverId> --sandbox <sandboxId> \
-  --action <start|stop|restart|make_persistent|refresh_image> --confirm <same-action> \
-  [--wait] --json
+  --action <start|stop|restart|make_persistent|refresh_image|patch_image> --confirm <same-action> \
+  [--image-digest <image@sha256:digest>] [--wait] --json
 warpmetal sandbox delete \
   --server <serverId> --sandbox <sandboxId> --confirm DELETE [--wait] --json
 
@@ -411,6 +412,57 @@ Every selection must reference a sandbox name in the same file. Unknown fields,
 including URL, shell, command, argv, environment, or artifact overrides, are
 rejected before an API request.
 
+## Retained Work and Insights (source candidate)
+
+Discover command availability with `warpmetal --help`; these routes require
+the corresponding candidate control plane, Runtime and Sandbox.
+
+```sh
+warpmetal work list|sources|policy SERVER BOX --json
+warpmetal work show|content|targets SERVER BOX WORK --json
+warpmetal work create SERVER BOX --file request.json --json
+warpmetal work update|enable|checkpoint|continue|restore|handoff SERVER BOX WORK --file request.json --json
+warpmetal work status SERVER BOX WORK --kind checkpoint|continue|restore|handoff \
+  (--request REQUEST | --operation OPERATION) --json
+warpmetal work open SERVER BOX WORK --json
+warpmetal insights summary SERVER --json
+warpmetal insights status|list SERVER BOX --json
+warpmetal insights enable|disable SERVER BOX --file request.json --json
+warpmetal insights show SERVER BOX FINDING --json
+warpmetal insights acknowledge|snooze|dismiss SERVER BOX FINDING --file request.json --json
+warpmetal insights open SERVER BOX FINDING [--takeover OPERATION] --json
+warpmetal insights manager settings SERVER BOX [--file request.json] --json
+warpmetal insights manager activity SERVER BOX [--finding FINDING] --json
+warpmetal insights manager run SERVER BOX RUN --json
+warpmetal insights manager target SERVER BOX FINDING --json
+warpmetal insights manager recheck SERVER BOX FINDING --file request.json --json
+warpmetal insights manager status SERVER BOX FINDING --request REQUEST --json
+warpmetal insights takeover list SERVER BOX FINDING --json
+warpmetal insights takeover SERVER BOX FINDING --file request.json --json
+warpmetal insights takeover status SERVER BOX FINDING --operation OPERATION --json
+warpmetal insights takeover resume SERVER BOX FINDING --operation OPERATION --file request.json --json
+warpmetal insights review SERVER BOX RUN --json
+```
+
+Use the server's existing scoped owner/SSH credential. The account session is
+not a fallback. `--file` mutations validate a closed request with an explicit
+request ID and revision fences before HTTP. Saved same-intent retries are
+GET-only. Preserve the original request after a lost reply; never generate a
+new request to bypass an uncertain outcome. Pending operations exit 8, terminal
+failures/conflicts exit 5. Accepted Continue/handoff means task admission, not
+completion. Check task state separately.
+
+Only `work content` deliberately prints private content. Metadata and receipts
+are closed projections. Do not log private request files or content output.
+
+`open`/`review --json` returns a fresh descriptor without SSH. For deliberate
+human interactive access, omit `--json` and supply absolute
+`--connection-file` and `--identity` paths for the exact sandbox grant. Local
+OpenCode 2.0.14 connects through the fixed pinned bridge to the exact existing
+session. The command creates no session and sends no initial prompt. Manager
+review cannot mutate the worker. Takeover checks the current protected hold;
+Resume requires its saved operation, predecessor and revision tuple.
+
 ## Per-agent access
 
 ```sh

package/skills/warpmetal/references/runtime.md

@@ -183,6 +183,25 @@ workspace, sandbox lifetime, and original start time. `--wait` requires both
 the observed digest and generation to match the accepted target. A change to
 the global production image does not refresh existing sandboxes implicitly.
 
+To replace one sandbox's image while keeping its incarnation generation, use
+an explicitly approved digest-pinned image reference:
+
+```sh
+warpmetal sandbox action \
+  --server <serverId> \
+  --sandbox <sandboxId> \
+  --action patch_image \
+  --confirm patch_image \
+  --image-digest <registry/image@sha256:64-lowercase-hex-digest> \
+  --wait \
+  --json
+```
+
+This also briefly disconnects active sessions. The reference must contain an
+immutable SHA-256 digest; tags alone are refused. `--image-digest` is supported
+only for `patch_image`. Its wait requires the exact requested observed digest
+and the accepted generation, so a still-running old container is not completion.
+
 Manual deletion is irreversible:
 
 ```sh