@trydreamstate/cli 1.3.2 → 1.3.3

package/dist/index.js

@@ -1,15 +1,13 @@
 #!/usr/bin/env node
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.CliUsageError = exports.CLI_EXIT = void 0;
+exports.toolTurnToken = exports.omitsToolTurnForInlineTableRead = exports.capabilityIdempotencyKey = exports.CliUsageError = exports.CLI_EXIT = void 0;
 exports.parseCliArgs = parseCliArgs;
-exports.toolTurnToken = toolTurnToken;
-exports.omitsToolTurnForInlineTableRead = omitsToolTurnForInlineTableRead;
-exports.capabilityIdempotencyKey = capabilityIdempotencyKey;
 exports.refusalEnvelope = refusalEnvelope;
 exports.openWebUrl = openWebUrl;
 exports.exitCodeForError = exitCodeForError;
 exports.extractWorkspaceFlag = extractWorkspaceFlag;
+exports.statusData = statusData;
 exports.runCli = runCli;
 const node_child_process_1 = require("node:child_process");
 const node_crypto_1 = require("node:crypto");
@@ -21,11 +19,21 @@ const node_util_1 = require("node:util");
 const config_1 = require("./config");
 const pluginInstaller_1 = require("./pluginInstaller");
 const turnCache_1 = require("./turnCache");
+const idempotency_1 = require("./idempotency");
 const runWait_1 = require("./runWait");
 const client_1 = require("./client");
+const errors_1 = require("./errors");
+Object.defineProperty(exports, "CLI_EXIT", { enumerable: true, get: function () { return errors_1.CLI_EXIT; } });
+Object.defineProperty(exports, "CliUsageError", { enumerable: true, get: function () { return errors_1.CliUsageError; } });
+const gatedRun_1 = require("./gatedRun");
+Object.defineProperty(exports, "capabilityIdempotencyKey", { enumerable: true, get: function () { return gatedRun_1.capabilityIdempotencyKey; } });
+Object.defineProperty(exports, "omitsToolTurnForInlineTableRead", { enumerable: true, get: function () { return gatedRun_1.omitsToolTurnForInlineTableRead; } });
+Object.defineProperty(exports, "toolTurnToken", { enumerable: true, get: function () { return gatedRun_1.toolTurnToken; } });
+const tablesImport_1 = require("./tablesImport");
+const commandTable_1 = require("./commandTable");
 const skillInstaller_1 = require("./skillInstaller");
-exports.CLI_EXIT = { SUCCESS: 0, UNCLASSIFIED: 1, USAGE: 2, AUTH: 3, NOT_FOUND: 4, SERVER: 5, RATE_LIMITED: 6, APPROVAL: 7, TIMEOUT: 8, REFUSED: 9, TRANSPORT: 10 };
 const TOOLS_RUN_MODES = ['smoke_test', 'dry_run', 'live'];
+const UUID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
 const USAGE = `Dreamstate CLI
 
 Usage:
@@ -53,26 +61,22 @@ Usage:
   dreamstate commands search <term> [--json-output|--json]
   dreamstate tools search --goal <goal> [--terms <csv>] [--limit <n>] [--toolset <pack_id>] [--json-output|--json]
   dreamstate tools get <capability_id> [--json-output|--json]
-  dreamstate tools run <capability_id> [--params <object>|--json <body>] [--turn-token <token>] (--live | --dry-run | --mode <smoke_test|dry_run|live>) [--agent-session-id <uuid>] [--approved] [--approved-effect-unknown] [--max-credits <n>] [--idempotency-key <key>] [--wait-timeout <seconds>] [--no-wait] [--open] [--json-output|--json]
+  dreamstate tools run <capability_id> [--params <object>|--json <body>] [--turn-token <token>] (--live | --dry-run | --mode <smoke_test|dry_run|live>) [--approved] [--approval-id <uuid>] [--approved-effect-unknown] [--max-credits <n>] [--quote-hash <sha256:...>] [--idempotency-key <key>] [--wait-timeout <seconds>] [--no-wait] [--open] [--json-output|--json]
   dreamstate sequences <verb> [args] [flags]
   dreamstate workflows <verb> [args] [flags]
-  dreamstate tables import --table-id <uuid> --file <path> [--format <csv|json|jsonl|xlsx>] [--preview] [--upsert-key <header>] [--background] [--json-output|--json]
+  dreamstate tables import --table-id <uuid> --file <path> [--format <csv|json|jsonl|xlsx>] [--preview] [--upsert-key <header>] [--row-kind <person|company>] [--keep-unmapped-columns <true|false>] [--json-output|--json]
   dreamstate runs list [--limit <n>] [--cursor <cursor>] [--json <query>] [--json-output|--json]
   dreamstate runs get <run_id> [--json-output|--json]
-  dreamstate runs resume <run_id> --state-version <n> [--reason <text>] [--idempotency-key <key>] [--open] [--json-output|--json]
   dreamstate runs events <run_id> [--json-output|--json]
   dreamstate runs cancel <run_id> [--state-version <n>] [--reason <text>] [--json <body>] [--idempotency-key <key>] [--json-output|--json]
 
 All catalog discovery reads live API records. Set DREAMSTATE_API_URL and DREAMSTATE_API_KEY.
 Run responses wait for terminal run status by default, timeout default is 120 seconds, --no-wait returns immediate response. Timeout prints latest run envelope and exits ${runWait_1.RUN_WAIT_TIMEOUT_EXIT_CODE}.
+A write you re-run unchanged presents the same Idempotency-Key (printed as meta.idempotency_key), so the server replays instead of running it twice; --idempotency-key sets one yourself. Exit codes: 0 ok, 2 usage, 3 auth, 4 not found, 5 server failure, 6 rate limited, 7 approval/consent/spend gate required, 8 CLI update required, 9 refused, 10 transport, 11 timeout.
 login opens browser approval and installs Dreamstate skills for detected agents; --no-skills skips installation. login --token stores a ds_user_ session or ds_live_ key (for SSH or remote machines) after verifying it with whoami.
 Global flag --workspace <id|slug> (any command) or DREAMSTATE_WORKSPACE picks the workspace for one call; workspaces use stores a default. Flag beats env beats stored. A ds_live_ key is bound to one workspace and cannot switch.
 logout deletes the stored credentials file. --agents takes space-separated, comma-separated or repeated values.
 `;
-class CliUsageError extends Error {
-    constructor(message) { super(message); this.name = 'CliUsageError'; }
-}
-exports.CliUsageError = CliUsageError;
 function outputOption(values) {
     return values['json-output'] ? { jsonOutput: true } : {};
 }
@@ -84,35 +88,35 @@ function parseJsonObject(raw, flag = '--json') {
         return value;
     }
     catch (error) {
-        throw new CliUsageError(`${flag} ${error instanceof Error ? error.message : 'is invalid'}`);
+        throw new errors_1.CliUsageError(`${flag} ${error instanceof Error ? error.message : 'is invalid'}`);
     }
 }
 function requireOne(positionals, usage) {
     if (positionals.length !== 2 || !positionals[1])
-        throw new CliUsageError(`Usage: ${usage}`);
+        throw new errors_1.CliUsageError(`Usage: ${usage}`);
     return positionals[1];
 }
 function csv(raw, flag = '--terms') {
     const values = raw.split(',').map((value) => value.trim()).filter(Boolean);
     if (!values.length)
-        throw new CliUsageError(`${flag} must contain at least one value`);
+        throw new errors_1.CliUsageError(`${flag} must contain at least one value`);
     return [...new Set(values)];
 }
 function requireToolsRunMode(body) {
     if (TOOLS_RUN_MODES.includes(body.mode))
         return;
-    throw new CliUsageError('mode must be one of: smoke_test, dry_run, live.');
+    throw new errors_1.CliUsageError('mode must be one of: smoke_test, dry_run, live.');
 }
 function nonNegativeNumber(raw, flag) {
     const value = Number(raw);
     if (!Number.isFinite(value) || value < 0)
-        throw new CliUsageError(`${flag} must be a non-negative number`);
+        throw new errors_1.CliUsageError(`${flag} must be a non-negative number`);
     return value;
 }
 function nonNegativeInteger(raw, flag) {
     const value = Number(raw);
     if (!Number.isSafeInteger(value) || value < 0)
-        throw new CliUsageError(`${flag} must be a non-negative integer`);
+        throw new errors_1.CliUsageError(`${flag} must be a non-negative integer`);
     return value;
 }
 // runs.get returns { data: { run: { state_version } } }. Cancel posts
@@ -141,7 +145,7 @@ function parsePacks(argv) {
         return { command: 'packs_get', packId: requireOne(positionals, 'dreamstate packs get <pack_id>'), ...outputOption(values) };
     if (positionals.length === 1 && positionals[0] === 'route' && values.goal?.trim())
         return { command: 'packs_route', goal: values.goal.trim(), ...outputOption(values) };
-    throw new CliUsageError('Usage: dreamstate packs <list|get|route>');
+    throw new errors_1.CliUsageError('Usage: dreamstate packs <list|get|route>');
 }
 /** Rewrites `--agents a b c` into `--agents=a --agents=b --agents=c` so parseArgs sees every value. */
 function spaceSeparatedAgents(argv) {
@@ -172,7 +176,7 @@ function parseSkills(argv) {
         const requested = [...new Set(values.agents.flatMap((raw) => csv(raw, '--agents')))];
         const invalid = requested.filter((agent) => !skillInstaller_1.SKILL_INSTALL_AGENTS.includes(agent));
         if (invalid.length)
-            throw new CliUsageError(`--agents values must be one of: ${skillInstaller_1.SKILL_INSTALL_AGENTS.join(', ')} (got: ${invalid.join(', ')})`);
+            throw new errors_1.CliUsageError(`--agents values must be one of: ${skillInstaller_1.SKILL_INSTALL_AGENTS.join(', ')} (got: ${invalid.join(', ')})`);
         return requested;
     };
     if (positionals.length === 1 && positionals[0] === 'list') {
@@ -195,14 +199,14 @@ function parseSkills(argv) {
         return { command: 'skills_install', skillId: values.skill?.trim() || '*', agents: agents(), ...(values.project ? { project: true } : {}), ...(values.copy ? { copy: true } : {}), ...outputOption(values) };
     if (positionals.length === 1 && positionals[0] === 'doctor')
         return { command: 'skills_doctor', agents: agents(), ...(values.project ? { project: true } : {}), ...outputOption(values) };
-    throw new CliUsageError('Usage: dreamstate skills <list|get|search|install|doctor>');
+    throw new errors_1.CliUsageError('Usage: dreamstate skills <list|get|search|install|doctor>');
 }
 function parseCommands(argv) {
     const { values, positionals } = (0, node_util_1.parseArgs)({ args: argv, options: { 'json-output': { type: 'boolean' }, help: { type: 'boolean', short: 'h' } }, allowPositionals: true, strict: true });
     if (values.help)
         return { command: 'help' };
     if (positionals[0] !== 'search' || positionals.length < 2)
-        throw new CliUsageError('Usage: dreamstate commands search <term>');
+        throw new errors_1.CliUsageError('Usage: dreamstate commands search <term>');
     return { command: 'commands_search', term: positionals.slice(1).join(' '), ...outputOption(values) };
 }
 /**
@@ -210,10 +214,8 @@ function parseCommands(argv) {
  * are mutually exclusive ways of saying the same thing, and disagreeing ones are a
  * usage error rather than a silent winner.
  *
- * --approved is deliberately NOT here. It is a retained no-op: the run body schema
- * is strict and has no `approved` key, so sending it failed the entire call rather
- * than authorizing anything. Spend authority is max_credits and a human grant
- * arrives as approval_id.
+ * --approved is deliberately NOT here: it is not a mode. It rides on a live run
+ * as the caller's assertion that it asked a person (see parseTools).
  */
 function toolsRunMode(values) {
     const chosen = new Set();
@@ -224,12 +226,12 @@ function toolsRunMode(values) {
     if (values.mode !== undefined) {
         const mode = values.mode.trim();
         if (!TOOLS_RUN_MODES.includes(mode)) {
-            throw new CliUsageError(`--mode must be one of: ${TOOLS_RUN_MODES.join(', ')}`);
+            throw new errors_1.CliUsageError(`--mode must be one of: ${TOOLS_RUN_MODES.join(', ')}`);
         }
         chosen.add(mode);
     }
     if (chosen.size > 1) {
-        throw new CliUsageError(`Conflicting execution modes requested: ${[...chosen].sort().join(', ')}. Pass exactly one of --live, --dry-run, --mode.`);
+        throw new errors_1.CliUsageError(`Conflicting execution modes requested: ${[...chosen].sort().join(', ')}. Pass exactly one of --live, --dry-run, --mode.`);
     }
     return [...chosen][0];
 }
@@ -239,7 +241,8 @@ function parseTools(argv) {
             limit: { type: 'string' }, toolset: { type: 'string' },
             'idempotency-key': { type: 'string' }, 'json-output': { type: 'boolean' }, open: { type: 'boolean' },
             'dry-run': { type: 'boolean' }, live: { type: 'boolean' }, mode: { type: 'string' },
-            'agent-session-id': { type: 'string' }, approved: { type: 'boolean' }, 'approved-effect-unknown': { type: 'boolean' },
+            approved: { type: 'boolean' }, 'approved-effect-unknown': { type: 'boolean' },
+            'quote-hash': { type: 'string' }, 'approval-id': { type: 'string' },
             'max-credits': { type: 'string' }, 'turn-token': { type: 'string' }, 'wait-timeout': { type: 'string' }, 'no-wait': { type: 'boolean' }, help: { type: 'boolean', short: 'h' },
         }, allowPositionals: true, strict: true });
     if (values.help)
@@ -256,7 +259,7 @@ function parseTools(argv) {
         if (values.toolset !== undefined)
             query.toolset = values.toolset;
         if (typeof query.goal !== 'string' && !Array.isArray(query.query_terms))
-            throw new CliUsageError('tools search requires --goal, --terms, or --json query fields');
+            throw new errors_1.CliUsageError('tools search requires --goal, --terms, or --json query fields');
         return { command: 'tools_search', query, ...output };
     }
     if (positionals[0] === 'get')
@@ -264,11 +267,11 @@ function parseTools(argv) {
     if (positionals[0] === 'run') {
         const capabilityId = requireOne(positionals, 'dreamstate tools run <capability_id> [--params <object>|--json <body>]');
         if (values.json && values.params)
-            throw new CliUsageError('Use either --params for tool parameters or --json for the complete request, not both.');
+            throw new errors_1.CliUsageError('Use either --params for tool parameters or --json for the complete request, not both.');
         if (!values.json && !values.params)
-            throw new CliUsageError('tools run requires --params <object> or --json <body>; fetch live schema first with tools get');
+            throw new errors_1.CliUsageError('tools run requires --params <object> or --json <body>; fetch live schema first with tools get');
         const json = values.json ? parseJsonObject(values.json) : undefined;
-        const body = json && ('params' in json || 'mode' in json || 'agent_session_id' in json || 'approved_effect_unknown' in json || 'max_credits' in json)
+        const body = json && ('params' in json || 'mode' in json || 'agent_session_id' in json || 'approved_effect_unknown' in json || 'max_credits' in json || 'quote_hash' in json || 'approved' in json || 'approval_id' in json)
             ? json
             : {};
         if (values.params)
@@ -277,17 +280,37 @@ function parseTools(argv) {
             body.params = json;
         // The server never defaults a mode, so a mutating run with none is refused
         // mode_required; --live and --mode exist so a caller can actually ask for one.
-        // `approved` is no longer sent: the run body schema is strict and has no such
-        // key, so passing it failed the whole call instead of authorizing anything.
         const chosenMode = toolsRunMode(values);
         if (chosenMode)
             body.mode = chosenMode;
-        if (values['agent-session-id'])
-            body.agent_session_id = values['agent-session-id'];
+        // agent_session_id selects the in-app Architect surface and the server refuses it for every
+        // other caller (an API key may name a session only while an Architect turn is running on it,
+        // which a CLI user never has). There is no flag for it, and a full --json body must not smuggle it.
+        if (body.agent_session_id !== undefined) {
+            throw new errors_1.CliUsageError('agent_session_id is not accepted by the CLI: only the in-app Architect may name an Architect session, and the server refuses it for every other caller. Remove it from the request.');
+        }
         if (values['approved-effect-unknown'])
             body.approved_effect_unknown = true;
         if (values['max-credits'] !== undefined)
             body.max_credits = nonNegativeNumber(values['max-credits'], '--max-credits');
+        if (values['quote-hash'] !== undefined) {
+            if (!/^sha256:[a-f0-9]{64}$/.test(values['quote-hash']))
+                throw new errors_1.CliUsageError('--quote-hash must be the sha256:<64 hex> quote_hash a dry run returned');
+            body.quote_hash = values['quote-hash'];
+        }
+        // --approved is the caller's assertion that it showed a person the dry run's
+        // rows and cost and they agreed. A paid run above the size or dollar
+        // threshold is refused without it. It only means something on a live run,
+        // so any other mode never sends it.
+        if (values.approved && body.mode === 'live')
+            body.approved = true;
+        // --approval-id names a recorded approval (a uuid the approvals capabilities returned)
+        // the door should honour for this run. It is a door input, never a param.
+        if (values['approval-id'] !== undefined) {
+            if (!UUID_PATTERN.test(values['approval-id']))
+                throw new errors_1.CliUsageError('--approval-id must be the uuid of a recorded approval');
+            body.approval_id = values['approval-id'];
+        }
         // No client-side mode requirement: the server owns that refusal and answers
         // mode_required with a repair, and the parse grammar is expected to accept a
         // run without one. What was missing was any way to ASK for live.
@@ -296,18 +319,24 @@ function parseTools(argv) {
         const waitTimeout = values['wait-timeout'] === undefined ? 120 : nonNegativeNumber(values['wait-timeout'], '--wait-timeout');
         return { command: 'tools_run', capabilityId, body, waitTimeout, ...(values['no-wait'] ? { noWait: true } : {}), ...(values['turn-token'] ? { turnToken: values['turn-token'] } : {}), ...(values['idempotency-key'] ? { idempotencyKey: values['idempotency-key'] } : {}), ...(values.open ? { open: true } : {}), ...output };
     }
-    throw new CliUsageError('Usage: dreamstate tools <search|get|run>');
+    throw new errors_1.CliUsageError('Usage: dreamstate tools <search|get|run>');
 }
 function parseTables(argv) {
+    // Servers before this release put --background on the import command they hand out. It
+    // never did anything (the import always ran to completion in this process), so 1.3.3
+    // dropped it; say so plainly instead of the generic "unknown option" error.
+    if (argv.includes('--background')) {
+        throw new errors_1.CliUsageError('--background was removed in 1.3.3: dreamstate tables import always runs to completion in this process. Run the same command without it.');
+    }
     const { values, positionals } = (0, node_util_1.parseArgs)({ args: argv, options: {
-            'table-id': { type: 'string' }, file: { type: 'string' }, format: { type: 'string' }, background: { type: 'boolean' },
+            'table-id': { type: 'string' }, file: { type: 'string' }, format: { type: 'string' },
             preview: { type: 'boolean' }, 'upsert-key': { type: 'string' }, 'row-kind': { type: 'string' }, 'keep-unmapped-columns': { type: 'string' },
             'json-output': { type: 'boolean' }, help: { type: 'boolean', short: 'h' },
         }, allowPositionals: true, strict: true });
     if (values.help)
         return { command: 'help' };
     if (positionals.length !== 1 || positionals[0] !== 'import' || !values['table-id'] || !values.file) {
-        throw new CliUsageError('Usage: dreamstate tables import --table-id <uuid> --file <path> [--format <csv|json|jsonl|xlsx>] [--preview] [--upsert-key <header>] [--row-kind <person|company>] [--keep-unmapped-columns <true|false>] [--background]');
+        throw new errors_1.CliUsageError('Usage: dreamstate tables import --table-id <uuid> --file <path> [--format <csv|json|jsonl|xlsx>] [--preview] [--upsert-key <header>] [--row-kind <person|company>] [--keep-unmapped-columns <true|false>]');
     }
     // --format is an override, not a requirement. Requiring it made the caller restate
     // what the file path already says, and an omitted flag produced a usage error rather
@@ -315,16 +344,16 @@ function parseTables(argv) {
     // the kind from the file it receives.
     const format = values.format;
     if (format !== undefined && !['csv', 'json', 'jsonl', 'xlsx'].includes(format)) {
-        throw new CliUsageError('--format must be one of csv, json, jsonl, xlsx');
+        throw new errors_1.CliUsageError('--format must be one of csv, json, jsonl, xlsx');
     }
     const upsertKey = values['upsert-key']?.trim();
     const rowKind = values['row-kind'];
     if (rowKind !== undefined && rowKind !== 'person' && rowKind !== 'company') {
-        throw new CliUsageError('--row-kind must be person or company');
+        throw new errors_1.CliUsageError('--row-kind must be person or company');
     }
     const keepUnmappedColumns = values['keep-unmapped-columns'];
     if (keepUnmappedColumns !== undefined && keepUnmappedColumns !== 'true' && keepUnmappedColumns !== 'false') {
-        throw new CliUsageError('--keep-unmapped-columns must be true or false');
+        throw new errors_1.CliUsageError('--keep-unmapped-columns must be true or false');
     }
     return {
         command: 'tables_import',
@@ -335,14 +364,13 @@ function parseTables(argv) {
         ...(upsertKey ? { upsertKey } : {}),
         ...(rowKind ? { rowKind } : {}),
         ...(keepUnmappedColumns === 'false' ? { keepUnmappedColumns: false } : {}),
-        background: Boolean(values.background),
         ...outputOption(values),
     };
 }
 function runsListLimit(raw) {
     const value = nonNegativeInteger(raw, '--limit');
     if (value < 1 || value > 500)
-        throw new CliUsageError('--limit must be an integer from 1 to 500');
+        throw new errors_1.CliUsageError('--limit must be an integer from 1 to 500');
     return value;
 }
 function parseRuns(argv) {
@@ -357,30 +385,28 @@ function parseRuns(argv) {
         if (values.cursor !== undefined) {
             const cursor = values.cursor.trim();
             if (!cursor)
-                throw new CliUsageError('--cursor must be a non-empty string');
+                throw new errors_1.CliUsageError('--cursor must be a non-empty string');
             query.cursor = cursor;
         }
         return { command: 'runs_list', query, ...output };
     }
     if (values.limit !== undefined || values.cursor !== undefined) {
-        throw new CliUsageError('--limit and --cursor are only valid on runs list');
+        throw new errors_1.CliUsageError('--limit and --cursor are only valid on runs list');
+    }
+    if (positionals[0] === 'resume') {
+        // The server retired generic run resume (verifyExecutionDoorCollapse.ts blocks the
+        // route), so there is nothing to call. Say where the replacement is.
+        throw new errors_1.CliUsageError('runs resume was retired: the server has no generic run resume. A table run checkpoint resumes with: dreamstate tools run tables.table_runs.resume --params \'{...}\' --live. Start a new run for anything else.');
     }
     const runId = requireOne(positionals, `dreamstate runs ${positionals[0] ?? '<get|events|cancel>'} <run_id>`);
     if (positionals[0] === 'get')
         return { command: 'runs_get', runId, ...output };
     if (positionals[0] === 'events')
         return { command: 'runs_events', runId, ...output };
-    if (positionals[0] === 'resume') {
-        if (values.json)
-            throw new CliUsageError('Use --state-version and --reason with runs resume, not --json.');
-        if (values['state-version'] === undefined)
-            throw new CliUsageError('--state-version is required for runs resume.');
-        return { command: 'runs_resume', runId, stateVersion: nonNegativeInteger(values['state-version'], '--state-version'), ...(values.reason ? { reason: values.reason } : {}), ...(values['idempotency-key'] ? { idempotencyKey: values['idempotency-key'] } : {}), ...(values.open ? { open: true } : {}), ...output };
-    }
     if (positionals[0] === 'cancel') {
         const idempotency = values['idempotency-key'] ? { idempotencyKey: values['idempotency-key'] } : {};
         if (values.json && (values['state-version'] !== undefined || values.reason)) {
-            throw new CliUsageError('Use either --json <body> or --state-version and --reason with runs cancel, not both.');
+            throw new errors_1.CliUsageError('Use either --json <body> or --state-version and --reason with runs cancel, not both.');
         }
         if (values.json)
             return { command: 'runs_cancel', runId, body: parseJsonObject(values.json), ...idempotency, ...output };
@@ -393,7 +419,7 @@ function parseRuns(argv) {
             ...output,
         };
     }
-    throw new CliUsageError('Usage: dreamstate runs <get|events|cancel> <run_id>');
+    throw new errors_1.CliUsageError('Usage: dreamstate runs <list|get|events|cancel> <run_id>');
 }
 function normalizeJsonOutputAlias(argv) {
     return argv.map((argument, index) => argument === '--json' && (index === argv.length - 1 || argv[index + 1]?.startsWith('-'))
@@ -412,9 +438,9 @@ function parseCliArgs(argv) {
         if (values.help)
             return { command: 'help' };
         if (positionals.length)
-            throw new CliUsageError('Usage: dreamstate login [--token <ds_user_...|ds_live_...>]');
+            throw new errors_1.CliUsageError('Usage: dreamstate login [--token <ds_user_...|ds_live_...>]');
         if (values.token !== undefined && values['api-key-file'])
-            throw new CliUsageError('Use either --token or --api-key-file, not both.');
+            throw new errors_1.CliUsageError('Use either --token or --api-key-file, not both.');
         return { command: 'login', ...(values.token !== undefined ? { token: values.token } : {}), ...(values['api-key-file'] ? { apiKeyFile: values['api-key-file'] } : {}), ...(values.profile ? { profile: (0, config_1.validateProfileName)(values.profile) } : {}), ...(values['no-skills'] ? { noSkills: true } : {}), ...outputOption(values) };
     }
     if (group === 'install') {
@@ -422,11 +448,11 @@ function parseCliArgs(argv) {
         if (values.help)
             return { command: 'help' };
         if (positionals.length)
-            throw new CliUsageError('Usage: dreamstate install [--agents <claude codex grok>]');
+            throw new errors_1.CliUsageError('Usage: dreamstate install [--agents <claude codex grok>]');
         const requested = values.agents ? [...new Set(values.agents.flatMap((raw) => csv(raw, '--agents')))] : [...pluginInstaller_1.PLUGIN_AGENTS];
         const invalid = requested.filter((agent) => !pluginInstaller_1.PLUGIN_AGENTS.includes(agent));
         if (invalid.length)
-            throw new CliUsageError(`--agents values must be one of: ${pluginInstaller_1.PLUGIN_AGENTS.join(', ')} (got: ${invalid.join(', ')})`);
+            throw new errors_1.CliUsageError(`--agents values must be one of: ${pluginInstaller_1.PLUGIN_AGENTS.join(', ')} (got: ${invalid.join(', ')})`);
         return { command: 'install', agents: requested, ...outputOption(values) };
     }
     if (group === 'logout') {
@@ -434,14 +460,14 @@ function parseCliArgs(argv) {
         if (values.help)
             return { command: 'help' };
         if (positionals.length)
-            throw new CliUsageError('Usage: dreamstate logout');
+            throw new errors_1.CliUsageError('Usage: dreamstate logout');
         return { command: 'logout', ...outputOption(values) };
     }
     if (group === 'status') {
         const { values, positionals } = (0, node_util_1.parseArgs)({ args: rest, options: { 'json-output': { type: 'boolean' } }, allowPositionals: true, strict: true });
         if (!positionals.length)
             return { command: 'status', ...outputOption(values) };
-        throw new CliUsageError('Usage: dreamstate status [--json-output]');
+        throw new errors_1.CliUsageError('Usage: dreamstate status [--json-output]');
     }
     if (group === 'profiles') {
         const { values, positionals } = (0, node_util_1.parseArgs)({ args: rest, options: { 'json-output': { type: 'boolean' } }, allowPositionals: true, strict: true });
@@ -456,13 +482,13 @@ function parseCliArgs(argv) {
             return { command: 'profiles_remove', name: (0, config_1.validateProfileName)(positionals[1]), ...output };
         if (positionals.length === 2 && positionals[0] === 'env')
             return { command: 'profiles_env', name: (0, config_1.validateProfileName)(positionals[1]), ...output };
-        throw new CliUsageError('Usage: dreamstate profiles <list|use <name>|current|remove <name>|env <name>>');
+        throw new errors_1.CliUsageError('Usage: dreamstate profiles <list|use <name>|current|remove <name>|env <name>>');
     }
     if (group === 'whoami') {
         const { values, positionals } = (0, node_util_1.parseArgs)({ args: rest, options: { 'json-output': { type: 'boolean' } }, allowPositionals: true, strict: true });
         if (positionals.length === 0)
             return { command: 'whoami', ...outputOption(values) };
-        throw new CliUsageError('Usage: dreamstate whoami [--json-output]');
+        throw new errors_1.CliUsageError('Usage: dreamstate whoami [--json-output]');
     }
     if (group === 'workspaces') {
         const { values, positionals } = (0, node_util_1.parseArgs)({ args: rest, options: { 'json-output': { type: 'boolean' }, help: { type: 'boolean', short: 'h' } }, allowPositionals: true, strict: true });
@@ -472,7 +498,7 @@ function parseCliArgs(argv) {
             return { command: 'workspaces_list', ...outputOption(values) };
         if (positionals.length === 2 && positionals[0] === 'use' && positionals[1])
             return { command: 'workspaces_use', workspace: positionals[1], ...outputOption(values) };
-        throw new CliUsageError('Usage: dreamstate workspaces <list|use <id|slug>>');
+        throw new errors_1.CliUsageError('Usage: dreamstate workspaces <list|use <id|slug>>');
     }
     if (group === 'auth') {
         const { values, positionals } = (0, node_util_1.parseArgs)({ args: rest, options: { 'api-key-file': { type: 'string' }, 'no-skills': { type: 'boolean' }, 'json-output': { type: 'boolean' } }, allowPositionals: true, strict: true });
@@ -480,7 +506,7 @@ function parseCliArgs(argv) {
             return { command: 'login', ...(values['api-key-file'] ? { apiKeyFile: values['api-key-file'] } : {}), ...(values['no-skills'] ? { noSkills: true } : {}), ...outputOption(values) };
         if (positionals.length === 1 && positionals[0] === 'whoami')
             return { command: 'whoami', ...outputOption(values) };
-        throw new CliUsageError('Usage: dreamstate auth <login|whoami>');
+        throw new errors_1.CliUsageError('Usage: dreamstate auth <login|whoami>');
     }
     if (group === 'packs')
         return parsePacks(rest);
@@ -498,10 +524,14 @@ function parseCliArgs(argv) {
         return require('./commands/sequences').parseSequencesCommand(rest);
     if (group === 'workflows')
         return require('./commands/workflows').parseWorkflowsCommand(rest);
-    throw new CliUsageError(`Unknown command: ${group}`);
+    throw new errors_1.CliUsageError(`Unknown command: ${group}`);
 }
 function print(value, stdout, compact) {
-    stdout.write(`${JSON.stringify(value, (key, nested) => key === 'tool_turn_token' ? undefined : nested, compact ? 0 : 2)}\n`);
+    // Printed exactly as the server returned it. tool_turn_token used to be stripped
+    // here, which made --turn-token impossible to use: a caller could never read the
+    // token from `tools get` to pass back. The token is a short-lived fetch fence tied
+    // to the caller's own session, not a credential, and MCP and REST return it too.
+    stdout.write(`${JSON.stringify(value, null, compact ? 0 : 2)}\n`);
 }
 function printPackRoute(value, stdout) {
     const data = value && typeof value === 'object' && !Array.isArray(value)
@@ -530,103 +560,32 @@ function printPackRoute(value, stdout) {
             stdout.write(`${packId}${typeof reason === 'string' ? `: ${reason}` : ''}\n`);
     }
 }
-function toolTurnToken(value) {
-    const root = value && typeof value === 'object' ? value : {};
-    const data = root.data && typeof root.data === 'object' ? root.data : {};
-    if (typeof data.tool_turn_token === 'string' && data.tool_turn_token.trim())
-        return data.tool_turn_token;
-    throw new client_1.CliError('tools get did not return a tool_turn_token.', 'invalid_tool_turn_token', 0);
-}
-/**
- * Free sync reads. The server runs these on the inline read path when
- * the body has no tool_turn_token and the request has no Idempotency-Key
- * (isInlineReadEligible). A tools get before the run is a second HTTP the
- * read does not need. Measured 2026-10-04: tables.workbooks.get full live CLI
- * 0.726s against whoami 0.455s, about 0.27s of tools get per harness read-back.
- * knowledge.brain.context.get is the same class (catalog: credit_class free,
- * async_policy.mode sync, mutates not set). Live 2026-10-05 a standalone
- * tools get of that id was 0.400s including node startup, next to whoami
- * 0.422s, so the same-process skip is one HTTP, not a second process.
- * The set name is historical. Writes are not in this set: they stay fetch-first.
- */
-const INLINE_READ_CAPABILITIES = new Set([
-    'tables.workbooks.get',
-    'tables.workbooks.overview',
-    'tables.workbooks.list',
-    'tables.columns.list',
-    'tables.columns.stats',
-    'tables.rows.query',
-    'tables.rows.get',
-    'tables.rows.count',
-    'knowledge.brain.context.get',
-    // Both are stored, free, synchronous inbox reads. Keeping either behind a
-    // tools_get turns one list or thread open into two HTTP requests, while the
-    // canonical inline-read gate already validates their read-only contract.
-    'unibox.inbox.unified_list',
-    'unibox.inbox.conversation_get',
-]);
-function omitsToolTurnForInlineTableRead(capabilityId) {
-    return INLINE_READ_CAPABILITIES.has(capabilityId);
-}
-function readIdempotencyContract(fetched) {
-    if (!fetched || typeof fetched !== 'object' || Array.isArray(fetched))
-        return null;
-    const root = fetched;
-    const data = root.data && typeof root.data === 'object' && !Array.isArray(root.data)
-        ? root.data
-        : null;
-    const candidates = [data?.capability, root.capability, data, root];
-    for (const candidate of candidates) {
-        if (!candidate || typeof candidate !== 'object' || Array.isArray(candidate))
-            continue;
-        if ('mutates' in candidate || 'idempotency_required' in candidate) {
-            return candidate;
-        }
-    }
-    return null;
-}
 /**
- * Header value, or null when the request must not carry Idempotency-Key.
- * Any key forces a read onto the durable run path (isInlineReadEligible).
- * Send one only for an explicit key, or when the tools get contract says
- * mutates or idempotency_required. Missing flags omit the key: a read whose
- * contract does not set mutates must not be treated as a write.
+ * The refusal envelope, in the shared shape { ok:false, error, meta }. The server's
+ * own message, retry decision, repair, details and meta (trace_id, server_version,
+ * minimum_cli_version, release_sha) are forwarded unchanged; retry_after and
+ * idempotency_key are request receipts, so they stay in meta. Process exit status
+ * remains process-level state: ToolEnvelopeMeta intentionally has no exit_code.
  */
-function capabilityIdempotencyKey(fetched, explicit) {
-    if (typeof explicit === 'string' && explicit.length > 0)
-        return explicit;
-    const contract = readIdempotencyContract(fetched);
-    if (contract?.mutates === true || contract?.idempotency_required === true)
-        return (0, node_crypto_1.randomUUID)();
-    return null;
-}
-function parameterIdempotencyKey(body) {
-    const params = body.params;
-    if (!params || typeof params !== 'object' || Array.isArray(params))
-        return undefined;
-    const key = params.idempotency_key;
-    return typeof key === 'string' && key.length > 0 ? key : undefined;
-}
-function code(error) {
-    return error && typeof error === 'object' && typeof error.code === 'string'
-        ? error.code
-        : undefined;
-}
 function refusalEnvelope(error, exitCode) {
     const cliError = error instanceof client_1.CliError ? error : null;
     return {
         ok: false,
-        executed: false,
         error: {
-            code: code(error) ?? 'invalid_request',
+            code: (0, gatedRun_1.code)(error) ?? 'invalid_request',
             message: error instanceof Error ? error.message : String(error),
-            ...(cliError?.details === undefined ? {} : { details: cliError.details }),
+            ...(cliError?.retryable === undefined ? {} : { retryable: cliError.retryable }),
             // The client keeps the server's retry decision and repair; dropping them
             // here left CLI automation without the recovery Architect and MCP get.
-            ...(cliError?.retryable === undefined ? {} : { retryable: cliError.retryable }),
             ...(cliError?.repair === undefined ? {} : { repair: cliError.repair }),
+            ...(cliError?.details === undefined ? {} : { details: cliError.details }),
+        },
+        meta: {
+            ...(cliError?.meta ?? {}),
+            ...(cliError?.traceId !== undefined && cliError.meta?.trace_id === undefined ? { trace_id: cliError.traceId } : {}),
+            ...(cliError?.retryAfter !== undefined ? { retry_after: cliError.retryAfter } : {}),
+            ...(cliError?.idempotencyKey !== undefined ? { idempotency_key: cliError.idempotencyKey } : {}),
         },
-        meta: { exit_code: exitCode },
     };
 }
 function openWebUrl(rawUrl, launch = node_child_process_1.spawn) {
@@ -687,7 +646,7 @@ function discoveredCapabilityId(value) {
         .filter((candidate) => typeof candidate === 'string' && candidate.length > 0);
     const ids = [...new Set(candidates)];
     if (ids.length !== 1)
-        throw new CliUsageError('Local file import discovery must return exactly one capability.');
+        throw new errors_1.CliUsageError('Local file import discovery must return exactly one capability.');
     return ids[0];
 }
 function hostedSkill(value) {
@@ -705,31 +664,83 @@ function hostedSkill(value) {
     const documents = Array.isArray(entry.documents)
         ? entry.documents.filter((document) => Boolean(document) && typeof document === 'object' && typeof document.name === 'string' && typeof document.content === 'string')
         : undefined;
-    return { id: entry.id, name: entry.name, description: entry.description, body: entry.body, frontmatter, documents };
+    // The server lists a skill's supporting pages beside the skill (data.files), each read
+    // with `skills get <id> --file <path>`; they are not inline in the skill record.
+    const files = Array.isArray(data.files)
+        ? data.files
+            .filter((file) => Boolean(file) && typeof file === 'object' && typeof file.path === 'string')
+            .map((file) => ({ path: file.path, ...(typeof file.revision_number === 'number' ? { revision_number: file.revision_number } : {}) }))
+        : undefined;
+    return {
+        id: entry.id, name: entry.name, description: entry.description, body: entry.body, frontmatter, documents,
+        ...(typeof entry.revision_number === 'number' ? { revision_number: entry.revision_number } : {}),
+        ...(files ? { files } : {}),
+    };
+}
+const SAFE_SKILL_ID = /^[a-z0-9][a-z0-9_-]*$/i;
+/**
+ * One hosted skill with its supporting pages read in. Reads are one at a time because
+ * the workspace's private vault admits two reads at once, and fifteen parallel reads
+ * failed in production.
+ */
+async function loadHostedSkill(client, id, withPages) {
+    if (!SAFE_SKILL_ID.test(id))
+        throw new errors_1.CliUsageError('Dreamstate API returned an invalid skill id.');
+    const skill = hostedSkill(await client.getSkill(id));
+    if (!SAFE_SKILL_ID.test(skill.id))
+        throw new errors_1.CliUsageError('Dreamstate API returned an invalid skill id.');
+    if (skill.id !== id)
+        throw new client_1.CliError('Dreamstate API returned a mismatched skill id.', 'invalid_response', 200);
+    if (!withPages || !skill.files?.length)
+        return skill;
+    const documents = [];
+    for (const file of skill.files) {
+        const page = hostedSkill(await client.getSkill(id, { file: file.path }));
+        documents.push({ name: file.path, content: page.body });
+    }
+    return { ...skill, documents };
+}
+/** Ids of every skill the server lists. */
+async function listedSkillIds(client) {
+    const listed = await client.listAllSkills();
+    const entries = listed && typeof listed === 'object' && listed.data?.skills;
+    const ids = Array.isArray(entries) ? entries.map((skill) => skill && typeof skill === 'object' ? skill.id : undefined).filter((id) => typeof id === 'string') : [];
+    if (ids.some((id) => !SAFE_SKILL_ID.test(id)))
+        throw new errors_1.CliUsageError('Dreamstate API returned an invalid skill id.');
+    return ids;
 }
 function exitCodeForError(error) {
-    if (code(error)?.startsWith('ERR_PARSE_ARGS'))
-        return exports.CLI_EXIT.USAGE;
-    if (error instanceof CliUsageError || error instanceof config_1.ApiKeyFileError || error instanceof config_1.ApiBaseUrlError || error instanceof config_1.MissingApiUrlError)
-        return exports.CLI_EXIT.USAGE;
+    const errorCode = (0, gatedRun_1.code)(error);
+    if (errorCode?.startsWith('ERR_PARSE_ARGS'))
+        return errors_1.CLI_EXIT.USAGE;
+    if (error instanceof errors_1.CliUsageError || error instanceof config_1.ApiKeyFileError || error instanceof config_1.ApiBaseUrlError || error instanceof config_1.MissingApiUrlError)
+        return errors_1.CLI_EXIT.USAGE;
     if (error instanceof config_1.MissingApiKeyError)
-        return exports.CLI_EXIT.AUTH;
-    if (code(error) === 'request_timeout')
-        return exports.CLI_EXIT.TIMEOUT;
+        return errors_1.CLI_EXIT.AUTH;
+    // By code before by status: a gate refusal arrives as 403 or 409 and must still read as
+    // "a person has to decide", and an update-required refusal is 426.
+    if (errorCode === 'cli_update_required')
+        return errors_1.CLI_EXIT.UPDATE_REQUIRED;
+    if ((0, errors_1.isApprovalGateCode)(errorCode))
+        return errors_1.CLI_EXIT.APPROVAL;
+    if (errorCode === 'request_timeout')
+        return errors_1.CLI_EXIT.TIMEOUT;
+    if ((0, errors_1.isLocalRefusalCode)(errorCode))
+        return errors_1.CLI_EXIT.REFUSED;
     const status = error instanceof client_1.CliError ? error.status : 0;
     if (status === 401 || status === 403)
-        return exports.CLI_EXIT.AUTH;
+        return errors_1.CLI_EXIT.AUTH;
     if (status === 404)
-        return exports.CLI_EXIT.NOT_FOUND;
+        return errors_1.CLI_EXIT.NOT_FOUND;
     if (status === 429)
-        return exports.CLI_EXIT.RATE_LIMITED;
-    if (code(error) === 'network_error')
-        return exports.CLI_EXIT.TRANSPORT;
-    if (status >= 500 || code(error) === 'invalid_response')
-        return exports.CLI_EXIT.SERVER;
+        return errors_1.CLI_EXIT.RATE_LIMITED;
+    if (errorCode === 'network_error')
+        return errors_1.CLI_EXIT.TRANSPORT;
+    if (status >= 500 || errorCode === 'invalid_response')
+        return errors_1.CLI_EXIT.SERVER;
     if (status >= 400)
-        return exports.CLI_EXIT.REFUSED;
-    return exports.CLI_EXIT.UNCLASSIFIED;
+        return errors_1.CLI_EXIT.REFUSED;
+    return errors_1.CLI_EXIT.UNCLASSIFIED;
 }
 async function readLoginKey(command, runtime) {
     if (command.apiKeyFile)
@@ -747,7 +758,7 @@ async function readLoginKey(command, runtime) {
     }
     if (runtime.promptHidden)
         return runtime.promptHidden('API key (input hidden): ');
-    throw new CliUsageError('No API key provided. Pipe it on stdin, set DREAMSTATE_API_KEY, or pass --api-key-file.');
+    throw new errors_1.CliUsageError('No API key provided. Pipe it on stdin, set DREAMSTATE_API_KEY, or pass --api-key-file.');
 }
 function deviceState() {
     return (0, node_crypto_1.randomBytes)(32).toString('base64url');
@@ -767,14 +778,14 @@ function extractWorkspaceFlag(argv) {
         if (argument === '--workspace') {
             const value = argv[index + 1];
             if (value === undefined || value.startsWith('-') || !value.trim())
-                throw new CliUsageError('--workspace requires a workspace id or slug.');
+                throw new errors_1.CliUsageError('--workspace requires a workspace id or slug.');
             workspace = value.trim();
             index += 1;
         }
         else if (argument.startsWith('--workspace=')) {
             workspace = argument.slice('--workspace='.length).trim();
             if (!workspace)
-                throw new CliUsageError('--workspace requires a workspace id or slug.');
+                throw new errors_1.CliUsageError('--workspace requires a workspace id or slug.');
         }
         else {
             rest.push(argument);
@@ -786,25 +797,29 @@ function whoamiData(value) {
     const data = value && typeof value === 'object' ? value.data : undefined;
     return data && typeof data === 'object' ? data : {};
 }
-function statusData(whoami, health) {
-    const meta = whoami && typeof whoami === 'object' ? whoami.meta : null;
-    const serverVersion = meta && typeof meta === 'object' ? meta.server_version : null;
-    const minimumCliVersion = meta && typeof meta === 'object' ? meta.minimum_cli_version : null;
+/**
+ * What `dreamstate status` reports. The release identity comes from the server's
+ * own answers (envelope meta and X-Dreamstate-* headers on every response), so
+ * skew is measured, not assumed: with a server that publishes nothing the skew is
+ * "unknown", never "compatible".
+ */
+function statusData(whoami, health, info) {
     const healthData = health && typeof health === 'object' ? health.data : null;
     const healthVersion = healthData && typeof healthData === 'object' ? healthData.version : null;
-    const version = typeof serverVersion === 'string' ? serverVersion : typeof healthVersion === 'string' ? healthVersion : null;
-    const minimum = typeof minimumCliVersion === 'string' ? minimumCliVersion : null;
-    const parts = (value) => value.replace(/^v/, '').split('-')[0].split('.').map((part) => Number(part));
-    const [minimumMajor = 0, minimumMinor = 0, minimumPatch = 0] = minimum ? parts(minimum) : [];
-    const [cliMajor = 0, cliMinor = 0, cliPatch = 0] = parts(client_1.CLI_VERSION);
-    const compatible = !minimum || minimumMajor < cliMajor || (minimumMajor === cliMajor && (minimumMinor < cliMinor || (minimumMinor === cliMinor && minimumPatch <= cliPatch)));
+    const serverVersion = info.server_version ?? (typeof healthVersion === 'string' ? healthVersion : null);
+    const resolved = { ...info, server_version: serverVersion };
+    const skew = (0, client_1.describeVersionSkew)(resolved);
+    const compatible = skew !== 'cli_below_minimum';
     return {
         cli_version: client_1.CLI_VERSION,
-        api_version: version,
-        minimum_cli_version: minimum,
-        minimum_cli_version_published: minimum !== null,
+        api_version: serverVersion,
+        server_version: serverVersion,
+        release_sha: info.release_sha,
+        minimum_cli_version: info.minimum_cli_version,
+        minimum_cli_version_published: info.minimum_cli_version !== null,
+        skew,
         compatible,
-        upgrade_hint: compatible ? null : 'Run: npm install -g @trydreamstate/cli@latest',
+        upgrade_hint: skew === 'cli_below_minimum' || skew === 'cli_behind_server' ? `Run: ${client_1.CLI_UPDATE_COMMAND}` : null,
         health,
         whoami: whoamiData(whoami),
     };
@@ -816,36 +831,31 @@ function activeWorkspace(data) {
 function wait(milliseconds) {
     return new Promise((resolve) => setTimeout(resolve, milliseconds));
 }
+/**
+ * The one way the CLI installs skills: every skill from the hosted catalog (the same
+ * records MCP skills_get and `skills get` read), with its supporting pages, plus the
+ * router. `skills install`, `login` and the single-skill form all come through here, so
+ * there is no second source of skill text on this machine.
+ */
 async function installHostedSkills(client, agents, runtime, options = {}) {
-    const listed = await client.listAllSkills();
-    const entries = listed && typeof listed === 'object' && listed.data?.skills;
-    const ids = Array.isArray(entries) ? entries.map((skill) => skill && typeof skill === 'object' ? skill.id : undefined).filter((id) => typeof id === 'string') : [];
+    const ids = options.only ?? await listedSkillIds(client);
     if (!ids.length)
         throw new client_1.CliError('Dreamstate API returned no installable skills.', 'invalid_response', 200);
-    if (ids.some((id) => !/^[a-z0-9][a-z0-9_-]*$/i.test(id)))
-        throw new CliUsageError('Dreamstate API returned an invalid skill id.');
     const skills = [];
-    for (const id of ids) {
-        const skill = hostedSkill(await client.getSkill(id));
-        if (!/^[a-z0-9][a-z0-9_-]*$/i.test(skill.id))
-            throw new CliUsageError('Dreamstate API returned an invalid skill id.');
-        if (skill.id !== id)
-            throw new client_1.CliError('Dreamstate API returned a mismatched skill id.', 'invalid_response', 200);
-        skills.push(skill);
-    }
+    for (const id of ids)
+        skills.push(await loadHostedSkill(client, id, true));
     const packs = await client.listPacks();
     const whoami = await client.getWhoami();
     const workspaceId = typeof whoami?.data?.workspace_id === 'string' ? whoami.data.workspace_id : 'unknown';
-    const indexVersion = (0, node_crypto_1.createHash)('sha256')
-        .update(JSON.stringify(skills.map((skill) => [skill.id, skill.description, skill.body, skill.frontmatter ?? {}])))
-        .digest('hex').slice(0, 16);
-    const installed = await (0, skillInstaller_1.installSkills)([...skills, (0, skillInstaller_1.routerSkill)(packs)], {
+    const all = [...skills, (0, skillInstaller_1.routerSkill)(packs)];
+    // Stamped into every file so a stale install is visible against the live skills.
+    const installed = await (0, skillInstaller_1.installSkills)(all, {
         agents,
         homeDirectory: runtime.homeDirectory,
         project: Boolean(options.project),
         copy: Boolean(options.copy) || process.platform === 'win32',
         workspaceId,
-        indexVersion,
+        indexVersion: (0, skillInstaller_1.skillIndexVersion)(all),
     });
     return { files: installed.files, skillIds: [...ids, 'router'] };
 }
@@ -930,12 +940,12 @@ async function runCli(argv = process.argv.slice(2), runtime = {}) {
         if (command.command === 'help' || command.command === 'pack_help') {
             const packHelp = command.command === 'pack_help' ? command : undefined;
             print({ ok: true, data: { usage: packHelp?.usage ?? USAGE }, meta: {} }, stdout, Boolean(packHelp?.jsonOutput));
-            process.exitCode = exports.CLI_EXIT.SUCCESS;
+            process.exitCode = errors_1.CLI_EXIT.SUCCESS;
             return;
         }
         if (command.command === 'version') {
             print({ ok: true, data: { version: client_1.CLI_VERSION }, meta: {} }, stdout, false);
-            process.exitCode = exports.CLI_EXIT.SUCCESS;
+            process.exitCode = errors_1.CLI_EXIT.SUCCESS;
             return;
         }
         if (command.command === 'install') {
@@ -948,7 +958,7 @@ async function runCli(argv = process.argv.slice(2), runtime = {}) {
             const removedSkills = done.includes('claude') ? await (0, pluginInstaller_1.removeClaudeSkillCopies)(runtime.homeDirectory) : [];
             stderr.write(`Dreamstate plugin installed for ${done.join(', ')}. Start a new session; the first Dreamstate tool call asks you to sign in.\n`);
             print({ ok: true, data: { ...installed, removed_skill_copies: removedSkills }, meta: {} }, stdout, Boolean(command.jsonOutput));
-            process.exitCode = exports.CLI_EXIT.SUCCESS;
+            process.exitCode = errors_1.CLI_EXIT.SUCCESS;
             return;
         }
         if (command.command === 'logout') {
@@ -967,7 +977,7 @@ async function runCli(argv = process.argv.slice(2), runtime = {}) {
             const message = removed ? `Removed ${path}` : `Already logged out: no credentials at ${path}`;
             stderr.write(`${message}\n`);
             print({ ok: true, data: { credentials_path: path, removed }, meta: {} }, stdout, Boolean(command.jsonOutput));
-            process.exitCode = exports.CLI_EXIT.SUCCESS;
+            process.exitCode = errors_1.CLI_EXIT.SUCCESS;
             return;
         }
         if (command.command === 'profiles_list' || command.command === 'profiles_current' || command.command === 'profiles_use' || command.command === 'profiles_remove' || command.command === 'profiles_env') {
@@ -992,20 +1002,20 @@ async function runCli(argv = process.argv.slice(2), runtime = {}) {
             else {
                 const profiles = await (0, config_1.listCredentialProfiles)(path);
                 if (!profiles.some((profile) => profile.name === command.name))
-                    throw new CliUsageError(`Profile not found: ${command.name}.`);
+                    throw new errors_1.CliUsageError(`Profile not found: ${command.name}.`);
                 const result = { ok: true, data: { profile: command.name, exports: [`DREAMSTATE_PROFILE=${command.name}`] }, meta: {} };
                 if (command.jsonOutput)
                     print(result, stdout, true);
                 else
                     stdout.write(`export DREAMSTATE_PROFILE=${command.name}\n`);
             }
-            process.exitCode = exports.CLI_EXIT.SUCCESS;
+            process.exitCode = errors_1.CLI_EXIT.SUCCESS;
             return;
         }
         if (command.command === 'login' && command.token !== undefined) {
             const token = command.token.trim();
             if (!(0, config_1.isDreamstateToken)(token))
-                throw new CliUsageError('--token must be a Dreamstate session or API key starting with ds_user_ or ds_live_.');
+                throw new errors_1.CliUsageError('--token must be a Dreamstate session or API key starting with ds_user_ or ds_live_.');
             const environment = runtime.env ?? process.env;
             const baseUrl = (0, config_1.resolveApiBaseUrl)(environment);
             // Only an explicit flag or env picks the workspace here: a stored default belongs to the previous login.
@@ -1024,7 +1034,7 @@ async function runCli(argv = process.argv.slice(2), runtime = {}) {
                 await (0, config_1.storeApiKey)(token, runtimeCredentialsPath(runtime));
             const skills = await installLoginSkills(client, runtime, Boolean(command.noSkills), stderr);
             print(loginResult(whoami, skills), stdout, Boolean(command.jsonOutput));
-            process.exitCode = exports.CLI_EXIT.SUCCESS;
+            process.exitCode = errors_1.CLI_EXIT.SUCCESS;
             return;
         }
         if (command.command === 'status') {
@@ -1033,27 +1043,47 @@ async function runCli(argv = process.argv.slice(2), runtime = {}) {
             const apiKey = await (0, config_1.resolveApiKey)(environment, credentialFilePath);
             const workspace = await (0, config_1.resolveWorkspace)(extracted.workspace, environment, credentialFilePath);
             const client = new client_1.DreamstateClient({ baseUrl: (0, config_1.resolveApiBaseUrl)(environment), apiKey, ...(workspace ? { workspace } : {}), requestTimeoutMs: runtime.requestTimeoutMs });
-            const [whoami, health] = await Promise.all([client.getStatusWhoami(), client.getHealth()]);
-            print({ ok: true, data: statusData(whoami, health), meta: {} }, stdout, Boolean(command.jsonOutput));
-            process.exitCode = exports.CLI_EXIT.SUCCESS;
+            let whoami = null;
+            let health = null;
+            let refusedAsTooOld = null;
+            try {
+                [whoami, health] = await Promise.all([client.getStatusWhoami(), client.getHealth()]);
+            }
+            catch (error) {
+                // A server that refuses this CLI as too old (426) is the clearest skew report there is:
+                // print it as a status, with the update command, instead of only an error.
+                if (!(error instanceof client_1.CliError) || error.code !== 'cli_update_required')
+                    throw error;
+                refusedAsTooOld = error;
+            }
+            const info = client.serverInfo;
+            const refusal = refusedAsTooOld?.details && typeof refusedAsTooOld.details === 'object' ? refusedAsTooOld.details : {};
+            const data = statusData(whoami, health, {
+                ...info,
+                minimum_cli_version: info.minimum_cli_version ?? (typeof refusal.minimum_cli_version === 'string' ? refusal.minimum_cli_version : null),
+            });
+            print({ ok: true, data, meta: {} }, stdout, Boolean(command.jsonOutput));
+            process.exitCode = data.skew === 'cli_below_minimum' ? errors_1.CLI_EXIT.UPDATE_REQUIRED : errors_1.CLI_EXIT.SUCCESS;
+            if (process.exitCode === errors_1.CLI_EXIT.UPDATE_REQUIRED)
+                stderr.write(`This CLI (${client_1.CLI_VERSION}) is below the server minimum${data.minimum_cli_version ? ` ${String(data.minimum_cli_version)}` : ''}. ${String(data.upgrade_hint)}\n`);
             return;
         }
         if (command.command === 'login') {
             if (command.apiKeyFile || (runtime.env ?? process.env).DREAMSTATE_API_KEY || runtime.promptHidden) {
                 const key = await readLoginKey(command, runtime);
                 if (!(0, config_1.isDreamstateToken)(key))
-                    throw new CliUsageError('Dreamstate API keys must start with ds_user_ or ds_live_.');
+                    throw new errors_1.CliUsageError('Dreamstate API keys must start with ds_user_ or ds_live_.');
                 const path = command.profile
                     ? await (0, config_1.storeCredentialProfile)(command.profile, key, runtimeCredentialsPath(runtime))
                     : await (0, config_1.storeApiKey)(key, runtimeCredentialsPath(runtime));
                 const client = new client_1.DreamstateClient({ baseUrl: (0, config_1.resolveApiBaseUrl)(runtime.env ?? process.env), apiKey: key, requestTimeoutMs: runtime.requestTimeoutMs, onVersionWarning: (message) => stderr.write(`${message}\n`) });
                 const skills = await installLoginSkills(client, runtime, Boolean(command.noSkills), stderr);
                 print({ ok: true, data: { credentials_path: path, skills }, meta: {} }, stdout, Boolean(command.jsonOutput));
-                process.exitCode = exports.CLI_EXIT.SUCCESS;
+                process.exitCode = errors_1.CLI_EXIT.SUCCESS;
                 return;
             }
             await loginWithDeviceAuthorization(runtime, stdout, stderr, command.profile, Boolean(command.noSkills), Boolean(command.jsonOutput));
-            process.exitCode = exports.CLI_EXIT.SUCCESS;
+            process.exitCode = errors_1.CLI_EXIT.SUCCESS;
             return;
         }
         if (command.command === 'skills_doctor') {
@@ -1065,8 +1095,56 @@ async function runCli(argv = process.argv.slice(2), runtime = {}) {
             const client = new client_1.DreamstateClient({ baseUrl, apiKey, ...(workspace ? { workspace } : {}), requestTimeoutMs: runtime.requestTimeoutMs });
             await client.listSkills({ limit: 1 });
             const installers = await (0, skillInstaller_1.inspectSkillInstallers)(command.agents, runtime.homeDirectory, Boolean(command.project));
-            print({ ok: true, data: { index_reachable: true, installers }, meta: {} }, stdout, Boolean(command.jsonOutput));
-            process.exitCode = exports.CLI_EXIT.SUCCESS;
+            // Age says nothing about whether the install matches the server. Compare the content
+            // stamp of every installed skill with the live skill's, the way install computes it.
+            const ids = await listedSkillIds(client);
+            const live = [];
+            for (const id of ids)
+                live.push(await loadHostedSkill(client, id, false));
+            live.push((0, skillInstaller_1.routerSkill)(await client.listPacks()));
+            const drift = await (0, skillInstaller_1.compareInstalledSkills)(live, runtime.homeDirectory, Boolean(command.project));
+            const pluginAgents = await (0, pluginInstaller_1.agentsWithDreamstatePlugin)(runtime.homeDirectory);
+            const duplicateSources = pluginAgents.filter((agent) => command.agents.includes(agent) && drift.installed_skill_ids.length > 0);
+            print({ ok: true, data: { index_reachable: true, installers, content: drift, plugin_agents: pluginAgents, ...(duplicateSources.length ? { duplicate_skill_sources: duplicateSources } : {}) }, meta: {} }, stdout, Boolean(command.jsonOutput));
+            process.exitCode = errors_1.CLI_EXIT.SUCCESS;
+            return;
+        }
+        // The CLI's own commands answer from its parser tables, so they need no key;
+        // matching capabilities are added when a key is available.
+        if (command.command === 'commands_search') {
+            const commands = (0, commandTable_1.searchCliCommands)(command.term, USAGE);
+            let capabilities = null;
+            let capabilitiesError = null;
+            try {
+                const environment = runtime.env ?? process.env;
+                const credentialFilePath = runtimeCredentialsPath(runtime);
+                const apiKey = await (0, config_1.resolveApiKey)(environment, credentialFilePath);
+                const workspace = await (0, config_1.resolveWorkspace)(extracted.workspace, environment, credentialFilePath);
+                const client = new client_1.DreamstateClient({
+                    baseUrl: (0, config_1.resolveApiBaseUrl)(environment),
+                    apiKey,
+                    ...(workspace ? { workspace } : {}),
+                    requestTimeoutMs: runtime.requestTimeoutMs,
+                    onVersionWarning: (message) => stderr.write(`${message}\n`),
+                });
+                capabilities = await client.listTools({ goal: command.term });
+            }
+            catch (error) {
+                if (!commands.length || (error instanceof client_1.CliError && error.code === 'cli_update_required'))
+                    throw error;
+                capabilitiesError = { code: (0, gatedRun_1.code)(error) ?? 'request_failed', message: error instanceof Error ? error.message : String(error) };
+            }
+            print({
+                ok: true,
+                data: {
+                    commands,
+                    // Catalog capabilities that match the same words; run one with `dreamstate tools run <capability_id>`.
+                    capabilities: capabilities?.data ?? null,
+                    ...(capabilitiesError ? { capabilities_error: capabilitiesError } : {}),
+                },
+                meta: capabilities?.meta && typeof capabilities.meta === 'object' ? capabilities.meta : {},
+            }, stdout, Boolean(command.jsonOutput));
+            process.exitCode = errors_1.CLI_EXIT.SUCCESS;
             return;
         }
         // Preview parses the local file and writes nothing, so it must not require a key.
@@ -1081,9 +1159,9 @@ async function runCli(argv = process.argv.slice(2), runtime = {}) {
                 }, stdout, Boolean(command.jsonOutput));
             }
             catch (error) {
-                throw new CliUsageError(error instanceof CliUsageError ? error.message : error instanceof Error ? error.message : String(error));
+                throw new errors_1.CliUsageError(error instanceof errors_1.CliUsageError ? error.message : error instanceof Error ? error.message : String(error));
             }
-            process.exitCode = exports.CLI_EXIT.SUCCESS;
+            process.exitCode = errors_1.CLI_EXIT.SUCCESS;
             return;
         }
         // init writes a local scaffold and calls no API, so it must not require a key.
@@ -1097,7 +1175,7 @@ async function runCli(argv = process.argv.slice(2), runtime = {}) {
                 await require('./commands/workflows')
                     .runWorkflowsCommand(undefined, command, stdout);
             }
-            process.exitCode = exports.CLI_EXIT.SUCCESS;
+            process.exitCode = errors_1.CLI_EXIT.SUCCESS;
             return;
         }
         const environment = runtime.env ?? process.env;
@@ -1117,7 +1195,7 @@ async function runCli(argv = process.argv.slice(2), runtime = {}) {
         }
         if (command.command === 'workspaces_use' && apiKey.startsWith('ds_live_')) {
             // Decided locally: a workspace key can never switch, so no request is worth making.
-            throw new CliUsageError('This key is bound to one workspace. Run dreamstate login for a user session that can switch.');
+            throw new errors_1.CliUsageError('This key is bound to one workspace. Run dreamstate login for a user session that can switch.');
         }
         const workspace = command.command === 'workspaces_use'
             ? command.workspace
@@ -1129,6 +1207,19 @@ async function runCli(argv = process.argv.slice(2), runtime = {}) {
             requestTimeoutMs: runtime.requestTimeoutMs,
             onVersionWarning: (message) => (runtime.stderr ?? process.stderr).write(`${message}\n`),
         });
+        const turnsPath = (0, turnCache_1.turnCachePath)(credentialFilePath);
+        const idempotencyPath = (0, idempotency_1.pendingIdempotencyPath)(credentialFilePath);
+        // A turn belongs to one workspace, so the workspace is part of the cache identity.
+        const gatedContext = () => ({
+            client,
+            baseUrl,
+            turnKey: workspace ? `${apiKey}\n${workspace}` : apiKey,
+            turnsPath,
+            idempotencyPath,
+            ...(workspace ? { workspace } : {}),
+            stderr,
+            sleep: runtime.sleep ?? wait,
+        });
         let result;
         switch (command.command) {
             case 'whoami': {
@@ -1149,7 +1240,7 @@ async function runCli(argv = process.argv.slice(2), runtime = {}) {
                     stdout.write(rows.length
                         ? `${rows.map((row) => `${row.id === activeId ? '*' : ' '} ${row.slug ?? '-'}  ${row.name}  ${row.role ?? '-'}  ${row.id}`).join('\n')}\n`
                         : 'No workspaces. Ask a workspace owner to invite you.\n');
-                    process.exitCode = exports.CLI_EXIT.SUCCESS;
+                    process.exitCode = errors_1.CLI_EXIT.SUCCESS;
                     return;
                 }
                 break;
@@ -1160,10 +1251,10 @@ async function runCli(argv = process.argv.slice(2), runtime = {}) {
                 const wanted = command.workspace.toLowerCase();
                 const match = data.workspaces?.find((row) => row.id.toLowerCase() === wanted || row.slug?.toLowerCase() === wanted);
                 if (!match)
-                    throw new CliUsageError(`You are not a member of workspace "${command.workspace}". Run dreamstate workspaces list to see the workspaces you can use.`);
+                    throw new errors_1.CliUsageError(`You are not a member of workspace "${command.workspace}". Run dreamstate workspaces list to see the workspaces you can use.`);
                 const stored = await (0, config_1.readStoredCredentials)(await (0, config_1.selectedCredentialsPath)(credentialFilePath, environment));
                 if (!stored)
-                    throw new CliUsageError('workspaces use saves the default next to a stored login. Run dreamstate login or dreamstate login --token first.');
+                    throw new errors_1.CliUsageError('workspaces use saves the default next to a stored login. Run dreamstate login or dreamstate login --token first.');
                 await (0, config_1.storeApiKey)(stored.token, await (0, config_1.selectedCredentialsPath)(credentialFilePath, environment), match.id);
                 stderr.write(`Default workspace: ${match.name} (${match.slug})\n`);
                 result = { ok: true, data: { workspace: { id: match.id, name: match.name, slug: match.slug }, credentials_path: credentialFilePath }, meta: {} };
@@ -1188,47 +1279,26 @@ async function runCli(argv = process.argv.slice(2), runtime = {}) {
                 result = await client.searchSkillDocuments(command.query);
                 break;
             case 'skills_install': {
-                if (command.skillId === '*') {
-                    const installed = await installHostedSkills(client, command.agents, runtime, { project: command.project, copy: command.copy });
-                    result = { ok: true, data: { installed_files: installed.files, skill_ids: installed.skillIds, agents: command.agents, ...(command.project ? { lock_file: 'skills-lock.json' } : {}) }, meta: {} };
+                // An agent that already loads Dreamstate skills from the plugin gets them from there:
+                // installing hosted copies too would load the same skill twice under two names, from
+                // two sources that drift apart. login skips such agents the same way.
+                const withPlugin = await (0, pluginInstaller_1.agentsWithDreamstatePlugin)(runtime.homeDirectory);
+                const targets = command.agents.filter((agent) => !withPlugin.includes(agent));
+                const skipped = command.agents.filter((agent) => !targets.includes(agent)).map((agent) => ({ agent, reason: 'plugin_installed' }));
+                if (skipped.length)
+                    stderr.write(`Skipped ${skipped.map((entry) => entry.agent).join(', ')}: the Dreamstate plugin already provides skills there. Update it with dreamstate install.\n`);
+                if (!targets.length) {
+                    result = { ok: true, data: { installed_files: [], skill_ids: [], agents: [], skipped_agents: skipped }, meta: {} };
                     break;
                 }
-                const ids = [command.skillId];
-                // A remote id becomes a directory name; refuse traversal before any request or write.
-                if (ids.some((id) => !/^[a-z0-9][a-z0-9_-]*$/i.test(id)))
-                    throw new CliUsageError('Dreamstate API returned an invalid skill id.');
-                // Read each skill one at a time because the workspace's private vault
-                // admits two reads at once, and fifteen parallel reads failed in production.
-                const skills = [];
-                for (const id of ids) {
-                    const skill = hostedSkill(await client.getSkill(id));
-                    if (!/^[a-z0-9][a-z0-9_-]*$/i.test(skill.id))
-                        throw new CliUsageError('Dreamstate API returned an invalid skill id.');
-                    if (skill.id !== id)
-                        throw new client_1.CliError('Dreamstate API returned a mismatched skill id.', 'invalid_response', 200);
-                    skills.push(skill);
-                }
-                const packs = await client.listPacks();
-                const whoami = await client.getWhoami();
-                const workspaceId = typeof whoami?.data?.workspace_id === 'string' ? whoami.data.workspace_id : 'unknown';
-                // Stamped into every file so a stale install is visible against the live skills.
-                const indexVersion = (0, node_crypto_1.createHash)('sha256')
-                    .update(JSON.stringify(skills.map((skill) => [skill.id, skill.description, skill.body, skill.frontmatter ?? {}])))
-                    .digest('hex').slice(0, 16);
-                const installed = await (0, skillInstaller_1.installSkills)([...skills, (0, skillInstaller_1.routerSkill)(packs)], {
-                    agents: command.agents,
-                    homeDirectory: runtime.homeDirectory,
-                    project: Boolean(command.project),
-                    copy: Boolean(command.copy) || process.platform === 'win32',
-                    workspaceId,
-                    indexVersion,
+                const installed = await installHostedSkills(client, targets, runtime, {
+                    project: command.project,
+                    copy: command.copy,
+                    ...(command.skillId === '*' ? {} : { only: [command.skillId] }),
                 });
-                result = { ok: true, data: { installed_files: installed.files, skill_ids: [...ids, 'router'], agents: command.agents, ...(command.project ? { lock_file: 'skills-lock.json' } : {}) }, meta: {} };
+                result = { ok: true, data: { installed_files: installed.files, skill_ids: installed.skillIds, agents: targets, ...(skipped.length ? { skipped_agents: skipped } : {}), ...(command.project ? { lock_file: 'skills-lock.json' } : {}) }, meta: {} };
                 break;
             }
-            case 'commands_search':
-                result = await client.listTools({ goal: command.term });
-                break;
             case 'tools_search':
                 result = await client.listTools(command.query);
                 break;
@@ -1239,100 +1309,30 @@ async function runCli(argv = process.argv.slice(2), runtime = {}) {
                 result = await client.getTool(command.capabilityId);
                 break;
             case 'tools_run': {
-                // A quote binds to the turn that asked for it. Reuse a turn only while
-                // a quote is pending (after a dry run or a quote_required refusal), and
-                // forget it once the paid run is admitted, so every other call keeps
-                // fetching a fresh turn exactly as before.
-                const turns = (0, turnCache_1.turnCachePath)(credentialFilePath);
-                // A turn belongs to one workspace, so the workspace is part of the cache identity.
-                const turnKey = workspace ? `${apiKey}\n${workspace}` : apiKey;
-                let warnedAboutTurnCache = false;
-                const warnTurnCache = () => {
-                    if (warnedAboutTurnCache)
-                        return;
-                    warnedAboutTurnCache = true;
-                    stderr.write('Warning: Dreamstate turn cache unavailable; continuing without turn reuse.\n');
-                };
-                const pending = command.turnToken
-                    ? null
-                    : await (0, turnCache_1.reusableTurnToken)(turns, baseUrl, turnKey, command.capabilityId, Date.now(), warnTurnCache);
-                const inlineRead = !command.turnToken && !pending && !command.idempotencyKey && omitsToolTurnForInlineTableRead(command.capabilityId);
-                const fetchedForRun = command.turnToken || pending || inlineRead ? null : await client.getTool(command.capabilityId);
-                let turnToken = command.turnToken ?? pending ?? (inlineRead ? undefined : toolTurnToken(fetchedForRun));
-                const callerParameterKey = parameterIdempotencyKey(command.body);
-                let idempotencyKey = capabilityIdempotencyKey(fetchedForRun, callerParameterKey ?? command.idempotencyKey);
-                let recoveredInlineRead = false;
-                const run = () => client.runCapability(command.capabilityId, {
-                    ...command.body,
-                    ...(turnToken ? { tool_turn_token: turnToken } : {}),
-                }, idempotencyKey);
-                try {
-                    try {
-                        result = await run();
-                    }
-                    catch (error) {
-                        // The inline skip is only valid while the server still treats this
-                        // capability as a free sync read. capability_not_fetched means the
-                        // fetch-first fence is on, so retry once on the old get-then-run path.
-                        if (inlineRead && !recoveredInlineRead && code(error) === 'capability_not_fetched') {
-                            recoveredInlineRead = true;
-                            const fetched = await client.getTool(command.capabilityId);
-                            turnToken = toolTurnToken(fetched);
-                            idempotencyKey = capabilityIdempotencyKey(fetched, callerParameterKey ?? command.idempotencyKey);
-                            result = await run();
-                        }
-                        else if (command.body.mode !== 'live' || code(error) !== 'quote_required') {
-                            // A quote_required refusal binds a fresh quote to this turn, so the
-                            // identical call admits on the next try. Retry once here instead of
-                            // making the caller rerun the same command by hand.
-                            throw error;
-                        }
-                        else {
-                            result = await run();
-                        }
-                    }
-                }
-                catch (error) {
-                    if (!command.turnToken && turnToken && code(error) === 'quote_required') {
-                        await (0, turnCache_1.rememberTurnToken)(turns, baseUrl, turnKey, command.capabilityId, turnToken, Date.now(), warnTurnCache);
-                    }
-                    throw error;
-                }
-                if (!command.turnToken) {
-                    if (command.body.mode === 'dry_run' && turnToken)
-                        await (0, turnCache_1.rememberTurnToken)(turns, baseUrl, turnKey, command.capabilityId, turnToken, Date.now(), warnTurnCache);
-                    else if (pending)
-                        await (0, turnCache_1.forgetTurnToken)(turns, baseUrl, turnKey, command.capabilityId, warnTurnCache);
-                }
-                if (!command.noWait && !(0, runWait_1.columnRunReturnsRunId)(command.capabilityId)) {
-                    const waited = await (0, runWait_1.waitForRun)(client, result, command.waitTimeout, runtime.sleep ?? wait);
-                    result = waited.value;
-                    if (waited.timedOut)
-                        process.exitCode = runWait_1.RUN_WAIT_TIMEOUT_EXIT_CODE;
-                }
+                const outcome = await (0, gatedRun_1.runGated)(gatedContext(), {
+                    capabilityId: command.capabilityId,
+                    body: command.body,
+                    ...(command.turnToken ? { turnToken: command.turnToken } : {}),
+                    ...(command.idempotencyKey ? { idempotencyKey: command.idempotencyKey } : {}),
+                    waitTimeout: command.waitTimeout,
+                    ...(command.noWait ? { noWait: true } : {}),
+                });
+                result = outcome.value;
+                if (outcome.timedOut)
+                    process.exitCode = runWait_1.RUN_WAIT_TIMEOUT_EXIT_CODE;
                 break;
             }
             case 'tables_import': {
                 await (0, promises_1.access)(command.file);
-                // Search ranking is not an import contract. This exact capability owns the
-                // prepare handoff for caller-local files, while nearby upload capabilities
-                // can also match these words and made a real import fail after local work.
-                const importCapabilityId = 'tables.table_sources.csv_import_prepare';
-                const importContract = await client.getTool(importCapabilityId);
-                result = await client.runCapability(importCapabilityId, {
-                    // A mutation run needs the turn token its own get minted; without it
-                    // an API-key import was refused after the local file work.
-                    tool_turn_token: toolTurnToken(importContract),
-                    mode: 'live',
-                    params: {
-                        table_id: command.tableId,
-                        file_path: command.file,
-                        ...(command.format ? { file_kind: command.format } : {}),
-                        ...(command.upsertKey ? { upsert_key: command.upsertKey } : {}),
-                        ...(command.rowKind ? { row_kind: command.rowKind } : {}),
-                        ...(command.keepUnmappedColumns === false ? { keep_unmapped_columns: false } : {}),
-                    },
-                }, capabilityIdempotencyKey(importContract));
+                const imported = await (0, tablesImport_1.importLocalTable)(gatedContext(), {
+                    tableId: command.tableId,
+                    file: command.file,
+                    ...(command.format ? { format: command.format } : {}),
+                    ...(command.upsertKey ? { upsertKey: command.upsertKey } : {}),
+                    ...(command.rowKind ? { rowKind: command.rowKind } : {}),
+                    ...(command.keepUnmappedColumns === false ? { keepUnmappedColumns: false } : {}),
+                });
+                result = { ok: true, data: { import: imported }, meta: {} };
                 break;
             }
             case 'runs_list':
@@ -1341,12 +1341,6 @@ async function runCli(argv = process.argv.slice(2), runtime = {}) {
             case 'runs_get':
                 result = await client.getRun(command.runId);
                 break;
-            case 'runs_resume':
-                result = await client.resumeRun(command.runId, {
-                    expected_state_version: command.stateVersion,
-                    ...(command.reason ? { reason: command.reason } : {}),
-                }, command.idempotencyKey);
-                break;
             case 'runs_events':
                 result = await client.getRunEvents(command.runId);
                 break;
@@ -1355,28 +1349,40 @@ async function runCli(argv = process.argv.slice(2), runtime = {}) {
                     expected_state_version: command.stateVersion ?? stateVersionFromRunRead(await client.getRun(command.runId)),
                     ...(command.reason ? { reason: command.reason } : {}),
                 };
-                result = await client.cancelRun(command.runId, body, command.idempotencyKey);
+                const identity = { scope: 'runs.cancel', workspace, body: { run_id: command.runId, ...body } };
+                const key = command.idempotencyKey ?? await (0, idempotency_1.pendingIdempotencyKey)(idempotencyPath, identity);
+                try {
+                    result = await client.cancelRun(command.runId, body, key);
+                    if (!command.idempotencyKey)
+                        await (0, idempotency_1.finishIdempotencyAttempt)(idempotencyPath, identity);
+                }
+                catch (error) {
+                    const transient = error instanceof client_1.CliError && (error.code === 'request_timeout' || error.code === 'network_error' || error.retryable === true || error.status >= 500);
+                    if (!command.idempotencyKey && !transient)
+                        await (0, idempotency_1.finishIdempotencyAttempt)(idempotencyPath, identity);
+                    throw error;
+                }
                 break;
             }
             case 'pack': {
                 if (command.pack === 'sequences') {
-                    await require('./commands/sequences').runSequencesCommand(client, command, stdout, runtime.sleep ?? wait);
+                    await require('./commands/sequences').runSequencesCommand(gatedContext(), command, stdout);
                 }
                 else {
-                    await require('./commands/workflows').runWorkflowsCommand(client, command, stdout, runtime.sleep ?? wait);
+                    await require('./commands/workflows').runWorkflowsCommand(gatedContext(), command, stdout);
                 }
                 return;
             }
             default: return;
         }
-        if ((command.command === 'tools_run' || command.command === 'runs_resume') && command.open)
+        if (command.command === 'tools_run' && command.open)
             openResult(result, runtime);
         if (command.command === 'packs_route' && !command.jsonOutput)
             printPackRoute(result, stdout);
         else
             print(result, stdout, Boolean(command.jsonOutput));
         if (process.exitCode !== runWait_1.RUN_WAIT_TIMEOUT_EXIT_CODE)
-            process.exitCode = exports.CLI_EXIT.SUCCESS;
+            process.exitCode = errors_1.CLI_EXIT.SUCCESS;
     }
     catch (error) {
         const exitCode = exitCodeForError(error);