@trydreamstate/cli 1.3.2 → 1.3.4

package/agent-plugin/skills/workflows/SKILL.md

@@ -3,7 +3,7 @@ name: workflows
 description: "Best practices for building and running automations that are not outreach sequences: frame the job, smallest graph, validate after every change, runtime inputs, safe recovery of failed runs."
 ---
 
-Run this through the Dreamstate MCP tools: `packs_get` for the pack's capabilities, `tools_get` for the exact input schema, then `tools_run` (`dry_run` first for anything that writes, spends credits or reaches a person). If the server asks you to sign in, approve it in the browser.
+Run this through the Dreamstate MCP tools: `packs_get` for the pack's capabilities, `tools_get` for the exact input schema, then `tools_run`. Anything that writes, spends credits or reaches a person: dry_run first, then live with the quote_hash the dry_run returned, a max_credits ceiling and an idempotency_key. max_credits 0 is valid only when that quote is 0. A larger paid run, or a live external send above the server's recipient threshold, also needs the user's yes before you send approved: true; never send it on your own. `max_rows` is a param of `tables.columns.run` and `tables.table_sources.run`, not of `tools_run`. `max_live_sends` is a param of the external-send sequence capabilities (`sequence.sequences.activate_audience`, `sequence.sequences.resume`, and the rest of that family), sent inside `params`, not a gating input of `tools_run`. The paid-run consent rule is one sentence in the MCP server instructions, rendered from consentRule.json and PAID_RUN_APPROVAL_THRESHOLDS: rows, dollars, credits, and the conversion. If the server asks you to sign in, approve it in the browser.
 
 # Workflows
 
@@ -19,7 +19,7 @@ Run this through the Dreamstate MCP tools: `packs_get` for the pack's capabiliti
 Best practices for building and running automations. The workflow pack lists the tools and their exact inputs; this skill is how to use them well. Outreach cadences to people are sequences, covered by the outreach skill. Everything else is a workflow.
 
 1. Build new unless asked. A new request gets a new automation built from scratch. When the user names an existing one to change, resolve that name among existing automations by listing workflows and sequences with that name as the search text, then change the match. A named thing that is not a workflow or sequence may be a task, a record or a worksheet; check those only after automations come back empty. A step inside a workflow, such as a task step, is edited in that workflow's graph, not in the task list.
-1a. "Enroll these in a workflow" is never a missing input. Use a workflow whose table trigger is the worksheet the user is looking at, or one they named; otherwise build a new draft for that worksheet (worksheet rows trigger plus fitting steps, a follow-up task per person by default), validate, and enroll. Never ask which workflow.
+1a. "Enroll these in a workflow" is never a missing input. Use a workflow whose table trigger is the worksheet the user is looking at, or one they named; otherwise build a new draft for that worksheet (worksheet rows trigger plus fitting steps, a follow-up task per person by default), validate, and enroll. Never ask which workflow. Filters on any worksheet column narrow who enrolls; with no filter every row enrolls. When the user said who should enroll, filter on the columns that hold it and report how many enrolled and how many were held back.
 2. Frame the job before building: what triggers it, who or what it acts on, what it changes, what it costs, when it stops and how often it runs.
 2a. Use a blueprint when one does exactly what you need; otherwise build your own. Workflow blueprints already cover common jobs: CRM syncs, list and do-not-contact syncs, routers, digests and signal monitors. List blueprints of the workflow kind, read what the closest one creates and what it still needs, install it, then adapt it to this request. Installing never needs answers or connections; the result names what is still to pick, so say that. Build from scratch only when no blueprint fits, and say which one came closest.
 3. Ask one clarifying question only when a required input is missing. Otherwise build with sensible defaults and say what you assumed.
@@ -31,7 +31,7 @@ Best practices for building and running automations. The workflow pack lists the
 8a. Building never waits on rows. A worksheet trigger on an empty or still-filling worksheet is still a valid enrollment: build, validate and turn it on, and rows enroll as they land. Say it is waiting for rows, never stop because the worksheet is empty.
 8b. Use the row-created trigger when each new worksheet row must enter once. It watches future row arrivals on one worksheet, carries that row identity through the graph, and does not reuse or freeze a saved selection. Use the table trigger only when user wants a selected saved-view audience.
 8c. To tag or mark a triggering row, add the worksheet-row update step. Choose its column and either replace its value or append a value to its existing list. Do not ask user to export, reimport, or manually tag rows when workflow already has triggering row identity.
-9. Decide by judgment whether to confirm before activating something that sends or spends. When the user already asked for it, do it. There is no system approval step.
+9. Activating something that sends or spends follows the paid-run consent rule.
 10. Draft, published, active, running and finished are separate facts. Report only what the last result proves.
 
 ## Delete and archive

package/agent-plugin/skills/workflows/lifecycle-and-enrollment.md

@@ -6,6 +6,6 @@ Missing connections never block building, editing, saving a draft or validating.
 
 Enrollment, activation and delivery are different events. Read the result after each one. After an unclear result, check current state before retrying, and never enroll twice or replay an effect that already happened.
 
-Preview first. Activation needs `params.max_credits` on `workflow.workflows.activate`: read exact `required_caps.max_credits` from preview, then resend that value unchanged. Live enrollment takes no send cap: every eligible selected row is enrolled. The activation ceiling is a caller input, not user approval. Never guess it or ask the user to approve it.
+Preview first. Activation stores `params.max_credits` on `workflow.workflows.activate`: read exact `required_caps.max_credits` from preview, then resend that value unchanged. This persisted per-delivery ceiling is a declared domain input, not run `max_credits`; put run gating fields at door. Live enrollment takes no send cap: every eligible selected row is enrolled. Never guess it or ask user to approve it.
 
 An active worksheet trigger snapshots its saved view on periodic ticks and idempotently enrolls rows that arrive later; draft, paused, and inactive workflows never refill.

package/agent-plugin/skills/worksheet-tidy/SKILL.md

@@ -3,7 +3,7 @@ name: worksheet-tidy
 description: "Review a workbook worksheet's structure and values, including duplicate or overlapping columns, column order, types and formatting, columns to hide, criteria and run conditions that never vary, and suspicious values, then apply reversible fixes. Use it when a worksheet has grown messy, before sharing it, or before enrolling it into a sequence. It does not merge CRM records across the workspace, rebuild the list's source (list-building does) or explain failed runs (diagnostics does)."
 ---
 
-Run this through the Dreamstate MCP tools: `packs_get` for the pack's capabilities, `tools_get` for the exact input schema, then `tools_run` (`dry_run` first for anything that writes, spends credits or reaches a person). If the server asks you to sign in, approve it in the browser.
+Run this through the Dreamstate MCP tools: `packs_get` for the pack's capabilities, `tools_get` for the exact input schema, then `tools_run`. Anything that writes, spends credits or reaches a person: dry_run first, then live with the quote_hash the dry_run returned, a max_credits ceiling and an idempotency_key. max_credits 0 is valid only when that quote is 0. A larger paid run, or a live external send above the server's recipient threshold, also needs the user's yes before you send approved: true; never send it on your own. `max_rows` is a param of `tables.columns.run` and `tables.table_sources.run`, not of `tools_run`. `max_live_sends` is a param of the external-send sequence capabilities (`sequence.sequences.activate_audience`, `sequence.sequences.resume`, and the rest of that family), sent inside `params`, not a gating input of `tools_run`. The paid-run consent rule is one sentence in the MCP server instructions, rendered from consentRule.json and PAID_RUN_APPROVAL_THRESHOLDS: rows, dollars, credits, and the conversion. If the server asks you to sign in, approve it in the browser.
 
 # Worksheet Tidy
 
@@ -59,3 +59,5 @@ Search the workbook tool for each change. The search returns runnable schemas fo
 ## Check it works
 
 Done means checked, not built. Before you report, read back everything you made or changed, and run, test or preview it where that is offered; publish or send only when the user asked. An empty, failed or wrong result means an input or setting is wrong: find which from the error or the output, correct it and check again, until it is right or a real blocker stops it. Report what you checked and what it showed.
+
+Paid and outward runs follow the paid-run consent rule.

package/agent-plugin/skills/writing/SKILL.md

@@ -3,7 +3,7 @@ name: writing
 description: "Draft, revise and publish articles and landing copy grounded in workspace context and a target query."
 ---
 
-Run this through the Dreamstate MCP tools: `packs_get` for the pack's capabilities, `tools_get` for the exact input schema, then `tools_run` (`dry_run` first for anything that writes, spends credits or reaches a person). If the server asks you to sign in, approve it in the browser.
+Run this through the Dreamstate MCP tools: `packs_get` for the pack's capabilities, `tools_get` for the exact input schema, then `tools_run`. Anything that writes, spends credits or reaches a person: dry_run first, then live with the quote_hash the dry_run returned, a max_credits ceiling and an idempotency_key. max_credits 0 is valid only when that quote is 0. A larger paid run, or a live external send above the server's recipient threshold, also needs the user's yes before you send approved: true; never send it on your own. `max_rows` is a param of `tables.columns.run` and `tables.table_sources.run`, not of `tools_run`. `max_live_sends` is a param of the external-send sequence capabilities (`sequence.sequences.activate_audience`, `sequence.sequences.resume`, and the rest of that family), sent inside `params`, not a gating input of `tools_run`. The paid-run consent rule is one sentence in the MCP server instructions, rendered from consentRule.json and PAID_RUN_APPROVAL_THRESHOLDS: rows, dollars, credits, and the conversion. If the server asks you to sign in, approve it in the browser.
 
 # Writing
 
@@ -14,10 +14,6 @@ Run this through the Dreamstate MCP tools: `packs_get` for the pack's capabiliti
 - Short-form social posts: [`social`].
 - The `social` pack lists the tools and their exact inputs.
 
-<!-- architect-operation-contract
-{"required_capability_ids":[]}
--->
-
 Own the draft, review, revise, and publish lifecycle for long-form articles and landing copy. Every factual claim traces to a workspace-wiki fact, cited evidence, or a dated external source; the voice matches what the workspace has already published; and each lifecycle step is a deliberate, verifiable state change. Traditional keyword, ranking, and generative-citation evidence belongs to `visibility`; current external evidence and durable facts about the business belong to `knowledge`. Never re-derive those measurements or restate a business fact from memory.
 
 Authoring: prepare brief, evidence ledger, novelty decision, destination, and voice; compose internally; discover owner and hydrate schema; save complete artifact; read result before showing or advancing. Unsaved long-form copy in chat is not an article. Preserve exact user-named title. A rewrite is not persisted until live result says save succeeded.
@@ -82,3 +78,5 @@ Report the missing source, stale revision, failed destination, or missing publis
 ## Check it works
 
 Done means checked, not built. Before you report, read back everything you made or changed, and run, test or preview it where that is offered; publish or send only when the user asked. An empty, failed or wrong result means an input or setting is wrong: find which from the error or the output, correct it and check again, until it is right or a real blocker stops it. Report what you checked and what it showed.
+
+Paid and outward runs follow the paid-run consent rule.

package/agent-plugin/skills/x-posts/SKILL.md

@@ -3,7 +3,7 @@ name: x-posts
 description: "Write and revise X posts and threads: the first line, single post versus thread, weighted length and Premium limits, thread structure, post types, replies and links, and phrases to avoid. Use it for the copy of any post going to X. It does not cover scheduling, publishing or automations (social does)."
 ---
 
-Run this through the Dreamstate MCP tools: `packs_get` for the pack's capabilities, `tools_get` for the exact input schema, then `tools_run` (`dry_run` first for anything that writes, spends credits or reaches a person). If the server asks you to sign in, approve it in the browser.
+Run this through the Dreamstate MCP tools: `packs_get` for the pack's capabilities, `tools_get` for the exact input schema, then `tools_run`. Anything that writes, spends credits or reaches a person: dry_run first, then live with the quote_hash the dry_run returned, a max_credits ceiling and an idempotency_key. max_credits 0 is valid only when that quote is 0. A larger paid run, or a live external send above the server's recipient threshold, also needs the user's yes before you send approved: true; never send it on your own. `max_rows` is a param of `tables.columns.run` and `tables.table_sources.run`, not of `tools_run`. `max_live_sends` is a param of the external-send sequence capabilities (`sequence.sequences.activate_audience`, `sequence.sequences.resume`, and the rest of that family), sent inside `params`, not a gating input of `tools_run`. The paid-run consent rule is one sentence in the MCP server instructions, rendered from consentRule.json and PAID_RUN_APPROVAL_THRESHOLDS: rows, dollars, credits, and the conversion. If the server asks you to sign in, approve it in the browser.
 
 # X posts
 
@@ -71,3 +71,5 @@ Change what was asked and keep the rest verbatim. If a thread post runs long, sp
 ## Check it works
 
 Read the saved draft back: the hook alone justifies post two, each post is under the account's limit, each thread post stands alone, every number traces to something real, and nothing contains an em dash.
+
+Paid and outward runs follow the paid-run consent rule.

package/dist/agentGuidance.generated.json

@@ -0,0 +1,35 @@
+{
+    "generated_by": "packages/cli/scripts/build-agent-plugin.mjs from apps/backend/src/services/mcp/consentRule.json; do not edit by hand",
+    "consent": {
+        "summary": "Anything that writes, spends credits or reaches a person: dry_run first, then live with the quote_hash the dry_run returned, a max_credits ceiling and an idempotency_key. max_credits 0 is valid only when that quote is 0. A larger paid run, or a live external send above the server's recipient threshold, also needs the user's yes before you send approved: true; never send it on your own.",
+        "paid_run": "Anything that writes, spends credits or reaches a real person: run mode dry_run first, show the user the preview, the row count and the credit estimate, then run live with the quote_hash that dry_run returned, a max_credits ceiling and an idempotency_key. max_credits 0 is valid only when that quote is 0. A live paid run states max_rows; an external send states max_live_sends of at least the dry_run recipient_count. A quote returned by a refused live call is only a price, never a confirmation.",
+        "human_approval": "A paid run above the server's row or provider-spend limit, a live external send above the server's recipient threshold, or a run that turns on a recurring trigger, also needs the user's yes. Ask them, and only then send approved: true with the same quote_hash. You are asserting that you asked a person; never send it on your own."
+    },
+    "router_steps": [
+        {
+            "mcp": "whoami",
+            "cli": "dreamstate whoami --json",
+            "text": "names the user and the active workspace. If it lists several workspaces, confirm the right one before writing anything."
+        },
+        {
+            "mcp": "packs_route",
+            "cli": "dreamstate packs route --goal \"<goal>\" --json",
+            "text": "maps a goal to a domain; `packs_get` returns that domain's capabilities and skills."
+        },
+        {
+            "mcp": "tools_search",
+            "cli": "dreamstate tools search --goal \"<goal>\" --toolset <pack_id> --json",
+            "text": "finds the capability for the goal; `tools_get` returns its exact input schema. Read the schema every time, never guess params from memory."
+        },
+        {
+            "mcp": "tools_run",
+            "cli": "dreamstate tools run <capability_id> --params '{...}' --mode <dry_run|live> --json",
+            "text": "runs it with `capability_id` and `params`. The gating inputs (`mode`, `max_credits`, `idempotency_key`, `quote_hash`, `approved`) go on the run call itself, never inside `params`. `max_rows` is a param of `tables.columns.run` and `tables.table_sources.run`, not of `tools_run`. `max_live_sends` is a param of the external-send sequence capabilities (`sequence.sequences.activate_audience`, `sequence.sequences.resume`, and the rest of that family), sent inside `params`, not a gating input of `tools_run`."
+        },
+        {
+            "mcp": "runs_get",
+            "cli": "dreamstate runs get <run_id> --json",
+            "text": "follows long work; `runs_events` and `runs_list` read more of it and `runs_cancel` stops a run."
+        }
+    ]
+}

package/dist/capabilityPosture.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Inline-read and column-run hand-off, derived from the tools-get capability
+ * record. No capability id list: a free synchronous read omits the turn token,
+ * and a queued external test run (column runs and the same posture class)
+ * returns without waiting.
+ */
+export interface CapabilityPosture {
+    inlineRead: boolean;
+    returnsRunId: boolean;
+}
+export declare function postureFromContract(fetched: unknown): CapabilityPosture;
+//# sourceMappingURL=capabilityPosture.d.ts.map

package/dist/capabilityPosture.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"capabilityPosture.d.ts","sourceRoot":"","sources":["../src/capabilityPosture.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,MAAM,WAAW,iBAAiB;IAChC,UAAU,EAAE,OAAO,CAAC;IACpB,YAAY,EAAE,OAAO,CAAC;CACvB;AAaD,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,OAAO,GAAG,iBAAiB,CAkBvE"}

package/dist/capabilityPosture.js

@@ -0,0 +1,39 @@
+"use strict";
+/**
+ * Inline-read and column-run hand-off, derived from the tools-get capability
+ * record. No capability id list: a free synchronous read omits the turn token,
+ * and a queued external test run (column runs and the same posture class)
+ * returns without waiting.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.postureFromContract = postureFromContract;
+function record(value) {
+    return value && typeof value === 'object' && !Array.isArray(value) ? value : null;
+}
+function capabilityOf(fetched) {
+    const root = record(fetched);
+    if (!root)
+        return null;
+    const data = record(root.data);
+    return record(data?.capability) ?? record(root.capability);
+}
+function postureFromContract(fetched) {
+    const capability = capabilityOf(fetched);
+    if (!capability)
+        return { inlineRead: false, returnsRunId: false };
+    const asyncPolicy = record(capability.async_policy);
+    const asyncMode = typeof asyncPolicy?.mode === 'string' ? asyncPolicy.mode : undefined;
+    const credit = typeof capability.credit_class === 'string' ? capability.credit_class : undefined;
+    const consequence = typeof capability.consequence === 'string' ? capability.consequence : undefined;
+    const effect = typeof capability.effect_class === 'string' ? capability.effect_class : undefined;
+    // Missing async_policy is unknown. Do not guess sync, and do not treat it as a hand-off.
+    const inlineRead = capability.mutates !== true
+        && asyncMode === 'sync'
+        && (credit === 'free' || credit === undefined)
+        && (consequence === 'read_only' || consequence === 'test_run');
+    const returnsRunId = asyncMode === 'async'
+        && consequence === 'test_run'
+        && credit === 'dynamic'
+        && effect === 'external';
+    return { inlineRead, returnsRunId };
+}

package/dist/client.d.ts

@@ -1,4 +1,21 @@
 export declare const CLI_VERSION: string;
+/** Command that updates the CLI. One constant so every surface prints the same one. */
+export declare const CLI_UPDATE_COMMAND = "npm install -g @trydreamstate/cli@latest";
+/**
+ * Release identity the server stamps on every /api/v1 response (contract C2):
+ * meta.server_version, meta.minimum_cli_version, meta.release_sha and
+ * meta.registry_hash in the JSON envelope (whoami also puts registry_hash on
+ * data), and X-Dreamstate-Server-Version / -Minimum-Cli-Version / -Release-Sha
+ * / -Registry-Hash as response headers. The client reads both so a server that
+ * only sets one of them (a proxy that rewrites bodies, an error page with no
+ * envelope) still reports skew.
+ */
+export interface ServerReleaseInfo {
+    server_version: string | null;
+    minimum_cli_version: string | null;
+    release_sha: string | null;
+    registry_hash: string | null;
+}
 export interface DreamstateClientOptions {
     apiKey: string;
     baseUrl: string;
@@ -37,7 +54,6 @@ export interface WhoamiWorkspace {
 export interface CapabilityRunBody {
     params: Record<string, unknown>;
     mode?: 'smoke_test' | 'dry_run' | 'live';
-    agent_session_id?: string;
     approved?: boolean;
     max_credits?: number;
     [key: string]: unknown;
@@ -71,6 +87,8 @@ export declare class CliError extends Error {
     /** The server's retry decision and repair, forwarded unchanged so the CLI never re-derives them. */
     readonly retryable?: boolean;
     readonly repair?: unknown;
+    /** The server's own envelope meta (trace_id, server_version, ...), kept whole so a refusal prints what the server said. */
+    readonly meta?: Record<string, unknown>;
     constructor(message: string, code: string, status: number, options?: {
         details?: unknown;
         retryAfter?: string;
@@ -78,8 +96,18 @@ export declare class CliError extends Error {
         idempotencyKey?: string;
         retryable?: boolean;
         repair?: unknown;
+        meta?: Record<string, unknown>;
     });
 }
+/**
+ * Release identity from one response, preferring the JSON envelope and falling
+ * back to the X-Dreamstate-* headers. Success and error envelopes carry it
+ * alike (contract C2), so this runs on both.
+ */
+export declare function readServerReleaseInfo(payload: unknown, headers?: Headers): ServerReleaseInfo;
+/** How far this CLI is from the server it just talked to. */
+export type VersionSkew = 'compatible' | 'cli_behind_server' | 'cli_below_minimum' | 'unknown';
+export declare function describeVersionSkew(info: ServerReleaseInfo, cliVersion?: string): VersionSkew;
 export declare function readToolEnvelopeTraceId(value: unknown): string | undefined;
 export declare function requestDeviceAuthorization(baseUrl: string, body: {
     state: string;
@@ -96,6 +124,9 @@ export declare class DreamstateClient {
     private readonly workspace?;
     private readonly requestTimeoutMs?;
     private readonly onVersionWarning?;
+    private releaseInfo;
+    /** Release identity from the most recent response, success or error. */
+    get serverInfo(): ServerReleaseInfo;
     constructor(options: DreamstateClientOptions);
     getWhoami(): Promise<unknown>;
     /** Status reports server compatibility, including a requirement this CLI cannot satisfy. */
@@ -113,9 +144,9 @@ export declare class DreamstateClient {
     runCapability(capabilityId: string, body: CapabilityRunBody, idempotencyKey?: string | null): Promise<unknown>;
     getRun(id: string): Promise<unknown>;
     listRuns(query?: Record<string, unknown>): Promise<unknown>;
-    resumeRun(id: string, body: Record<string, unknown>, idempotencyKey?: string): Promise<unknown>;
     getRunEvents(id: string, query?: Record<string, unknown>): Promise<unknown>;
     cancelRun(id: string, body: Record<string, unknown>, idempotencyKey?: string): Promise<unknown>;
+    private noteServerInfo;
     private request;
 }
 //# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"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"}

package/dist/client.js

@@ -1,15 +1,26 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.DreamstateClient = exports.CliError = exports.TOOL_AND_RUN_REQUEST_TIMEOUT_MS = exports.DEFAULT_REQUEST_TIMEOUT_MS = exports.CLI_VERSION = void 0;
+exports.DreamstateClient = exports.CliError = exports.TOOL_AND_RUN_REQUEST_TIMEOUT_MS = exports.DEFAULT_REQUEST_TIMEOUT_MS = exports.CLI_UPDATE_COMMAND = exports.CLI_VERSION = void 0;
+exports.readServerReleaseInfo = readServerReleaseInfo;
+exports.describeVersionSkew = describeVersionSkew;
 exports.readToolEnvelopeTraceId = readToolEnvelopeTraceId;
 exports.requestDeviceAuthorization = requestDeviceAuthorization;
 exports.claimDeviceAuthorization = claimDeviceAuthorization;
-const node_crypto_1 = require("node:crypto");
+const idempotency_1 = require("./idempotency");
+const errors_1 = require("./errors");
+const registryManifest_1 = require("./registryManifest");
 exports.CLI_VERSION = require('../package.json').version;
+/** Command that updates the CLI. One constant so every surface prints the same one. */
+exports.CLI_UPDATE_COMMAND = 'npm install -g @trydreamstate/cli@latest';
 exports.DEFAULT_REQUEST_TIMEOUT_MS = 15_000;
 exports.TOOL_AND_RUN_REQUEST_TIMEOUT_MS = 60_000;
-/** Server workspace refusals rewritten so the message says what to run next. */
-const WORKSPACE_ERROR_MESSAGES = {
+/**
+ * Next steps for server workspace refusals. The server's message is forwarded
+ * unchanged; the CLI's own guidance travels beside it as details.cli_hint, so
+ * an agent reading either surface sees the same message and a script can tell
+ * what the server said from what the CLI added.
+ */
+const WORKSPACE_ERROR_HINTS = {
     workspace_required: 'No workspace is selected. Run dreamstate workspaces list, then dreamstate workspaces use <workspace> (or pass --workspace <id|slug>).',
     workspace_forbidden: 'You are not a member of that workspace. Run dreamstate workspaces list to see the workspaces you can use, then dreamstate workspaces use <workspace>.',
     workspace_scoped_credential: 'This key is bound to one workspace. Run dreamstate login for a user session that can switch, or remove --workspace and DREAMSTATE_WORKSPACE.',
@@ -24,6 +35,8 @@ class CliError extends Error {
     /** The server's retry decision and repair, forwarded unchanged so the CLI never re-derives them. */
     retryable;
     repair;
+    /** The server's own envelope meta (trace_id, server_version, ...), kept whole so a refusal prints what the server said. */
+    meta;
     constructor(message, code, status, options = {}) {
         super(message);
         this.name = 'CliError';
@@ -41,9 +54,52 @@ class CliError extends Error {
             this.retryable = options.retryable;
         if (options.repair !== undefined)
             this.repair = options.repair;
+        else if (code in errors_1.CLI_LOCAL_ERROR_REPAIRS)
+            this.repair = errors_1.CLI_LOCAL_ERROR_REPAIRS[code];
+        if (options.meta !== undefined)
+            this.meta = options.meta;
     }
 }
 exports.CliError = CliError;
+function objectRecord(value) {
+    return value && typeof value === 'object' && !Array.isArray(value) ? value : undefined;
+}
+function metaRecord(payload) {
+    return objectRecord(objectRecord(payload)?.meta);
+}
+function nonEmptyString(value) {
+    return typeof value === 'string' && value.trim() ? value.trim() : null;
+}
+/**
+ * Release identity from one response, preferring the JSON envelope and falling
+ * back to the X-Dreamstate-* headers. Success and error envelopes carry it
+ * alike (contract C2), so this runs on both.
+ */
+function readServerReleaseInfo(payload, headers) {
+    const meta = metaRecord(payload);
+    const header = (name) => nonEmptyString(typeof headers?.get === 'function' ? headers.get(name) : null);
+    const data = objectRecord(objectRecord(payload)?.data);
+    return {
+        server_version: nonEmptyString(meta?.server_version) ?? header('X-Dreamstate-Server-Version'),
+        minimum_cli_version: nonEmptyString(meta?.minimum_cli_version) ?? header('X-Dreamstate-Minimum-Cli-Version'),
+        release_sha: nonEmptyString(meta?.release_sha) ?? header('X-Dreamstate-Release-Sha'),
+        registry_hash: nonEmptyString(meta?.registry_hash) ?? nonEmptyString(data?.registry_hash) ?? header('X-Dreamstate-Registry-Hash'),
+    };
+}
+function describeVersionSkew(info, cliVersion = exports.CLI_VERSION) {
+    if (info.minimum_cli_version && isVersionGreater(info.minimum_cli_version, cliVersion))
+        return 'cli_below_minimum';
+    if (info.server_version && isVersionGreater(info.server_version, cliVersion))
+        return 'cli_behind_server';
+    return info.server_version || info.minimum_cli_version ? 'compatible' : 'unknown';
+}
+function updateRequiredError(minimum, cliVersion, status, details, meta) {
+    return new CliError(`CLI ${minimum} or newer is required (this is ${cliVersion}). Run: ${exports.CLI_UPDATE_COMMAND}`, 'cli_update_required', status, {
+        details: { ...details, minimum_cli_version: minimum, cli_version: cliVersion, update_command: exports.CLI_UPDATE_COMMAND },
+        retryable: false,
+        ...(meta ? { meta } : {}),
+    });
+}
 function isApiErrorBody(value) {
     const error = value && typeof value === 'object' ? value.error : null;
     if (!error || typeof error !== 'object')
@@ -110,24 +166,61 @@ function waitForRetryAfter(value) {
 function versionAtMost(current, target) {
     return !isVersionGreater(current, target);
 }
-function responseError(payload, status) {
-    if (isApiErrorBody(payload)) {
-        return new CliError(payload.error.message, payload.error.code, status, {
-            details: payload.error.details,
-            ...(typeof payload.error.retryable === 'boolean'
-                ? { retryable: payload.error.retryable }
-                : {}),
-            ...(payload.error.repair && typeof payload.error.repair === 'object'
-                ? { repair: payload.error.repair }
-                : {}),
+function errorEnvelope(payload) {
+    return isApiErrorBody(payload) ? payload : null;
+}
+/**
+ * The one parser for an error envelope. request() and the public login
+ * requests both use it, so rate-limit receipts, cli_update_required, repair,
+ * trace, meta and the idempotency key are not a second copy.
+ */
+function cliErrorFromEnvelope(payload, status, extras = {}) {
+    const meta = metaRecord(payload);
+    const envelope = errorEnvelope(payload);
+    if (envelope) {
+        const retryAfterValue = extras.response ? retryAfter(extras.response, envelope) : undefined;
+        const repair = envelope.error.repair && typeof envelope.error.repair === 'object' ? { repair: envelope.error.repair } : {};
+        if (envelope.error.code === 'cli_update_required') {
+            const minimum = extras.info?.minimum_cli_version ?? '';
+            const serverDetails = envelope.error.details;
+            return new CliError(envelope.error.message, 'cli_update_required', status, {
+                details: {
+                    ...(serverDetails && typeof serverDetails === 'object' && !Array.isArray(serverDetails) ? serverDetails : {}),
+                    ...(minimum ? { minimum_cli_version: minimum } : {}),
+                    cli_version: exports.CLI_VERSION,
+                    update_command: exports.CLI_UPDATE_COMMAND,
+                },
+                retryAfter: retryAfterValue,
+                traceId: readToolEnvelopeTraceId(payload),
+                idempotencyKey: extras.idempotencyKey,
+                retryable: false,
+                ...repair,
+                ...(meta ? { meta } : {}),
+            });
+        }
+        const hint = WORKSPACE_ERROR_HINTS[envelope.error.code];
+        const serverDetails = envelope.error.details;
+        return new CliError(envelope.error.message, envelope.error.code, status, {
+            ...(hint
+                ? { details: { ...(serverDetails && typeof serverDetails === 'object' && !Array.isArray(serverDetails) ? serverDetails : {}), cli_hint: hint } }
+                : { details: serverDetails }),
+            retryAfter: retryAfterValue,
+            traceId: readToolEnvelopeTraceId(payload),
+            idempotencyKey: extras.idempotencyKey,
+            ...(typeof envelope.error.retryable === 'boolean' ? { retryable: envelope.error.retryable } : {}),
+            ...repair,
+            ...(meta ? { meta } : {}),
         });
     }
     const error = payload && typeof payload === 'object' ? payload.error : null;
-    if (error &&
-        typeof error === 'object' &&
-        typeof error.code === 'string') {
+    if (error && typeof error === 'object' && typeof error.code === 'string') {
         const code = error.code;
-        return new CliError(code, code, status);
+        const message = typeof error.message === 'string' ? error.message : code;
+        return new CliError(message, code, status, {
+            idempotencyKey: extras.idempotencyKey,
+            traceId: readToolEnvelopeTraceId(payload),
+            ...(meta ? { meta } : {}),
+        });
     }
     return null;
 }
@@ -166,7 +259,7 @@ async function requestPublic(baseUrl, path, init) {
     catch {
         throw new CliError(`Dreamstate API returned invalid JSON (HTTP ${response.status})`, 'invalid_response', response.status);
     }
-    const apiError = responseError(payload, response.status);
+    const apiError = cliErrorFromEnvelope(payload, response.status, { response });
     if (apiError)
         throw apiError;
     if (!response.ok)
@@ -182,6 +275,11 @@ class DreamstateClient {
     workspace;
     requestTimeoutMs;
     onVersionWarning;
+    releaseInfo = { server_version: null, minimum_cli_version: null, release_sha: null, registry_hash: null };
+    /** Release identity from the most recent response, success or error. */
+    get serverInfo() {
+        return { ...this.releaseInfo };
+    }
     constructor(options) {
         this.apiKey = options.apiKey;
         this.baseUrl = options.baseUrl.replace(/\/+$/, '');
@@ -240,25 +338,28 @@ class DreamstateClient {
     listRuns(query = {}) {
         return this.request(`/runs${queryString(query)}`, {}, exports.TOOL_AND_RUN_REQUEST_TIMEOUT_MS);
     }
-    resumeRun(id, body, idempotencyKey) {
-        const key = idempotencyKey ?? (0, node_crypto_1.randomUUID)();
-        return this.request(`/runs/${encodeURIComponent(id)}/resume`, {
-            method: 'POST',
-            body: JSON.stringify(body),
-            headers: { 'Idempotency-Key': key },
-        }, exports.TOOL_AND_RUN_REQUEST_TIMEOUT_MS);
-    }
     getRunEvents(id, query = {}) {
         return this.request(`/runs/${encodeURIComponent(id)}/events${queryString(query)}`);
     }
     cancelRun(id, body, idempotencyKey) {
-        const key = idempotencyKey ?? (0, node_crypto_1.randomUUID)();
+        // A re-run of the same cancel presents the same key, so a cancel whose reply was
+        // lost replays instead of racing the run's own state version.
+        const key = idempotencyKey ?? (0, idempotency_1.deterministicIdempotencyKey)({ scope: 'runs.cancel', workspace: this.workspace, body: { run_id: id, ...body } });
         return this.request(`/runs/${encodeURIComponent(id)}/cancel`, {
             method: 'POST',
             body: JSON.stringify(body),
-            ...(key ? { headers: { 'Idempotency-Key': key } } : {}),
+            headers: { 'Idempotency-Key': key },
         });
     }
+    noteServerInfo(info) {
+        (0, registryManifest_1.noteRegistryHash)(info.registry_hash);
+        this.releaseInfo = {
+            server_version: info.server_version ?? this.releaseInfo.server_version,
+            minimum_cli_version: info.minimum_cli_version ?? this.releaseInfo.minimum_cli_version,
+            release_sha: info.release_sha ?? this.releaseInfo.release_sha,
+            registry_hash: info.registry_hash ?? this.releaseInfo.registry_hash,
+        };
+    }
     async request(path, init = {}, defaultTimeoutMs = exports.DEFAULT_REQUEST_TIMEOUT_MS, allowIncompatibleCli = false) {
         const requestTimeoutMs = this.requestTimeoutMs ?? defaultTimeoutMs;
         let response;
@@ -283,9 +384,9 @@ class DreamstateClient {
             }
             catch (error) {
                 if (controller.signal.aborted) {
-                    throw new CliError(`Request timed out after ${requestTimeoutMs}ms`, 'request_timeout', 0, { idempotencyKey });
+                    throw new CliError(errors_1.CLI_LOCAL_ERROR_CODES.request_timeout, 'request_timeout', 0, { idempotencyKey, repair: errors_1.CLI_LOCAL_ERROR_REPAIRS.request_timeout });
                 }
-                throw new CliError(`Request failed: ${error instanceof Error ? error.message : String(error)}`, 'network_error', 0);
+                throw new CliError(`Request failed: ${error instanceof Error ? error.message : String(error)}`, 'network_error', 0, { repair: errors_1.CLI_LOCAL_ERROR_REPAIRS.network_error });
             }
             finally {
                 clearTimeout(timeout);
@@ -295,48 +396,38 @@ class DreamstateClient {
                 payload = await response.json();
             }
             catch {
-                throw new CliError(`Dreamstate API returned invalid JSON (HTTP ${response.status})`, 'invalid_response', response.status);
+                this.noteServerInfo(readServerReleaseInfo(undefined, response.headers));
+                throw new CliError(`Dreamstate API returned invalid JSON (HTTP ${response.status})`, 'invalid_response', response.status, { idempotencyKey, repair: errors_1.CLI_LOCAL_ERROR_REPAIRS.invalid_response });
             }
-            if (isApiErrorBody(payload)) {
-                const retryAfterValue = retryAfter(response, payload);
-                if (!retriedRateLimit &&
-                    response.status === 429 &&
-                    retryAfterValue &&
-                    retryAfterDelayMs(retryAfterValue) !== null) {
+            const info = readServerReleaseInfo(payload, response.headers);
+            this.noteServerInfo(info);
+            const meta = metaRecord(payload);
+            const envelopeError = errorEnvelope(payload);
+            if (envelopeError && response.status === 429 && !retriedRateLimit) {
+                const retryAfterValue = retryAfter(response, envelopeError);
+                if (retryAfterValue && retryAfterDelayMs(retryAfterValue) !== null) {
                     retriedRateLimit = true;
                     await waitForRetryAfter(retryAfterValue);
                     continue;
                 }
-                throw new CliError(WORKSPACE_ERROR_MESSAGES[payload.error.code] ?? payload.error.message, payload.error.code, response.status, {
-                    details: payload.error.details,
-                    retryAfter: retryAfterValue,
-                    traceId: readToolEnvelopeTraceId(payload),
-                    idempotencyKey,
-                    ...(typeof payload.error.retryable === 'boolean'
-                        ? { retryable: payload.error.retryable }
-                        : {}),
-                    ...(payload.error.repair && typeof payload.error.repair === 'object'
-                        ? { repair: payload.error.repair }
-                        : {}),
-                });
             }
+            const parsed = cliErrorFromEnvelope(payload, response.status, { idempotencyKey, response, info });
+            if (parsed)
+                throw parsed;
             if (!response.ok)
-                throw new CliError(`Dreamstate API request failed (HTTP ${response.status})`, 'request_failed', response.status);
-            const minimum = payload && typeof payload === 'object'
-                ? payload.meta?.minimum_cli_version
-                : undefined;
-            if (!allowIncompatibleCli &&
-                typeof minimum === 'string' &&
-                isVersionGreater(minimum, exports.CLI_VERSION)) {
-                throw new CliError(`CLI ${minimum} or newer is required. Run: npm install -g @trydreamstate/cli@latest`, 'cli_update_required', 0);
+                throw new CliError(`Dreamstate API request failed (HTTP ${response.status})`, 'request_failed', response.status, { idempotencyKey, ...(meta ? { meta } : {}) });
+            const minimum = info.minimum_cli_version;
+            if (!allowIncompatibleCli && minimum && isVersionGreater(minimum, exports.CLI_VERSION)) {
+                // A conforming server refuses first (C3), so reaching here means the
+                // request may already have executed. The body is kept in the error so a
+                // write's receipt is not lost behind the update notice.
+                throw updateRequiredError(minimum, exports.CLI_VERSION, 0, init.method && init.method !== 'GET' ? { response: payload } : undefined, meta);
             }
-            const server = payload && typeof payload === 'object'
-                ? payload.meta?.server_version
-                : undefined;
-            if (typeof server === 'string' &&
+            const server = info.server_version;
+            if (server &&
                 isVersionGreater(server, exports.CLI_VERSION) &&
-                (typeof minimum !== 'string' || versionAtMost(minimum, exports.CLI_VERSION))) {
-                this.onVersionWarning?.(`Warning: CLI ${exports.CLI_VERSION} is behind server ${server}. Proceeding; server minimum is ${minimum ?? 'not declared'}.`);
+                (!minimum || versionAtMost(minimum, exports.CLI_VERSION))) {
+                this.onVersionWarning?.(`Warning: CLI ${exports.CLI_VERSION} is behind server ${server}. Proceeding; server minimum is ${minimum ?? 'not declared'}. Update: ${exports.CLI_UPDATE_COMMAND}`);
             }
             return payload;
         }