@skrr-ai/cli 0.1.119 → 0.1.120

package/dist/lib/dedicated-service.d.ts

@@ -252,8 +252,9 @@ export interface DedicatedServiceSocketOptions {
 export type ServiceVerb = 'list' | 'get' | 'create' | 'update' | 'action' | 'logs' | 'logs:stop' | 'approve' | 'secret' | 'exec';
 /**
  * One admitted socket for a run of service verbs. `call` emits
- * `dedicated:service:<verb>` with a fresh requestId and resolves on the
- * matching `dedicated:service:ack`; push events (`state`, `log`,
+ * `dedicated:service:<verb>` with a requestId and resolves on the matching
+ * `dedicated:service:ack`; callers normally get a fresh id, while service
+ * exec may provide its durable idempotency key. Push events (`state`, `log`,
  * `log:closed`, `proposed`) are exposed via `on` for the follow loop.
  */
 export declare class DedicatedServiceChannel {

package/dist/lib/dedicated-service.js

@@ -122,6 +122,7 @@ exports.DedicatedServiceError = DedicatedServiceError;
 function isServiceUnsupportedCode(code) {
     const c = (code || '').toLowerCase();
     return (c === 'dedicated_runtime_services_unsupported' ||
+        c === 'dedicated_runtime_service_exec_receipts_unsupported' ||
         c === 'dedicated_runtime_terminal_unsupported' ||
         c === 'services_unsupported' ||
         c === 'unsupported' ||
@@ -432,8 +433,9 @@ function socketOptions(token, wsOrigin) {
 }
 /**
  * One admitted socket for a run of service verbs. `call` emits
- * `dedicated:service:<verb>` with a fresh requestId and resolves on the
- * matching `dedicated:service:ack`; push events (`state`, `log`,
+ * `dedicated:service:<verb>` with a requestId and resolves on the matching
+ * `dedicated:service:ack`; callers normally get a fresh id, while service
+ * exec may provide its durable idempotency key. Push events (`state`, `log`,
  * `log:closed`, `proposed`) are exposed via `on` for the follow loop.
  */
 class DedicatedServiceChannel {
@@ -539,7 +541,13 @@ class DedicatedServiceChannel {
     }
     /** The shared request/ack round-trip. */
     callEvent(event, ackEvent, payload, context, timeoutMs, describe = describeServiceRefusal) {
-        const requestId = `svc-${(0, node_crypto_1.randomUUID)()}`;
+        // `service exec` deliberately supplies its durable request id so a lost
+        // socket response can be inspected or replayed without a second effect.
+        // Other verbs retain their historical per-call id generation.
+        const supplied = payload.requestId;
+        const requestId = typeof supplied === 'string' && /^[A-Za-z0-9_.:-]{1,128}$/.test(supplied)
+            ? supplied
+            : `svc-${(0, node_crypto_1.randomUUID)()}`;
         return new Promise((resolve, reject) => {
             if (this.dead) {
                 reject(new DedicatedServiceError('The connection to skrr is closed.', 'disconnected'));

package/dist/lib/governed-store.d.ts

@@ -65,6 +65,14 @@ export declare function resolveGovernedStoreInstallPlan(body: {
 /** `POST /admin/releases` — publish one artifact release. Admin. */
 export declare function publishGovernedStoreRelease(body: Record<string, unknown>): Promise<{
     release: unknown;
+    releaseId?: string;
+    execution?: unknown;
+}>;
+/** Read the immutable governed-release receipt before retrying a lost response. */
+export declare function getGovernedStoreReleaseReceipt(releaseId: string): Promise<{
+    release: unknown;
+    releaseId: string;
+    execution: unknown;
 }>;
 /** `POST /admin/licenses` — mint a bundle license against an acquisition. Admin. */
 export declare function createGovernedStoreLicense(body: Record<string, unknown>): Promise<{

package/dist/lib/governed-store.js

@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.searchGovernedStoreArtifacts = searchGovernedStoreArtifacts;
 exports.resolveGovernedStoreInstallPlan = resolveGovernedStoreInstallPlan;
 exports.publishGovernedStoreRelease = publishGovernedStoreRelease;
+exports.getGovernedStoreReleaseReceipt = getGovernedStoreReleaseReceipt;
 exports.createGovernedStoreLicense = createGovernedStoreLicense;
 exports.updateOwnLicensePolicy = updateOwnLicensePolicy;
 exports.updateWorkspaceLicensePolicy = updateWorkspaceLicensePolicy;
@@ -46,6 +47,10 @@ async function publishGovernedStoreRelease(body) {
         body,
     });
 }
+/** Read the immutable governed-release receipt before retrying a lost response. */
+async function getGovernedStoreReleaseReceipt(releaseId) {
+    return (0, api_fetch_1.apiFetch)(`/api/store/governance/admin/releases/${encodeURIComponent(releaseId)}/receipt`);
+}
 /** `POST /admin/licenses` — mint a bundle license against an acquisition. Admin. */
 async function createGovernedStoreLicense(body) {
     return (0, api_fetch_1.apiFetch)('/api/store/governance/admin/licenses', {

package/dist/lib/hosted-machines.d.ts

@@ -44,6 +44,26 @@ export interface HostedMachineSession {
 }
 export interface HostedMachineResponse {
     session?: HostedMachineSession;
+    operation?: HostedMachineOperation;
+    replayed?: boolean;
+}
+/** A durable request receipt, deliberately separate from the machine state. */
+export interface HostedMachineOperation {
+    id: string;
+    action: 'start' | 'execute' | 'destroy';
+    state: 'accepted' | 'started' | 'completed' | 'failed' | 'unknown';
+    acceptedAt?: string | null;
+    startedAt?: string | null;
+    completedAt?: string | null;
+    sessionId?: string;
+    result?: Record<string, unknown>;
+    error?: {
+        code?: string;
+        message?: string;
+    };
+}
+export interface HostedMachineOperationResponse {
+    operation: HostedMachineOperation;
 }
 export interface HostedMachineListResponse {
     data?: HostedMachineSession[];
@@ -77,6 +97,8 @@ export interface HostedMachineExecResponse {
     executionTime?: number;
     previewUrl?: string | null;
     session?: HostedMachineSession;
+    operation?: HostedMachineOperation;
+    replayed?: boolean;
 }
 /**
  * The curated `machines hosted exec --json` shape (OSK-4870).
@@ -98,6 +120,9 @@ export interface HostedMachineExecJson {
         id: string;
         status: string;
     };
+    /** Additive durable receipt metadata for safely recovering a lost response. */
+    operation?: HostedMachineOperation;
+    replayed?: boolean;
 }
 export declare function curateHostedMachineExecResult(response: HostedMachineExecResponse): HostedMachineExecJson;
 export interface HostedMachineScope {
@@ -155,8 +180,14 @@ export declare function getHostedMachine(id: string, scope?: HostedMachineScope)
 export declare function attachHostedMachineRepo(id: string, input: AttachHostedMachineRepoInput, scope?: HostedMachineScope): Promise<HostedMachineResponse>;
 export declare function pauseHostedMachine(id: string, scope?: HostedMachineScope): Promise<HostedMachineResponse>;
 export declare function resumeHostedMachine(id: string, scope?: HostedMachineScope): Promise<HostedMachineResponse>;
-export declare function destroyHostedMachine(id: string, scope?: HostedMachineScope): Promise<HostedMachineResponse>;
-export declare function execHostedMachine(id: string, input: HostedMachineExecInput, scope?: HostedMachineScope): Promise<HostedMachineExecResponse>;
+export declare function destroyHostedMachine(id: string, scope?: HostedMachineScope & {
+    requestId?: string;
+}): Promise<HostedMachineResponse>;
+export declare function execHostedMachine(id: string, input: HostedMachineExecInput, scope?: HostedMachineScope & {
+    requestId?: string;
+}): Promise<HostedMachineExecResponse>;
+/** Read a durable operation receipt without touching the machine or provider. */
+export declare function getHostedMachineOperation(operationId: string, scope?: HostedMachineScope): Promise<HostedMachineOperationResponse>;
 /**
  * The CLI gave up watching. The RUNTIME did not give up.
  *

package/dist/lib/hosted-machines.js

@@ -23,6 +23,7 @@ exports.pauseHostedMachine = pauseHostedMachine;
 exports.resumeHostedMachine = resumeHostedMachine;
 exports.destroyHostedMachine = destroyHostedMachine;
 exports.execHostedMachine = execHostedMachine;
+exports.getHostedMachineOperation = getHostedMachineOperation;
 exports.waitForHostedMachineReady = waitForHostedMachineReady;
 exports.offlineForLabel = offlineForLabel;
 const api_fetch_1 = require("./api-fetch");
@@ -77,6 +78,10 @@ function curateHostedMachineExecResult(response) {
             status: hostedMachineStatus(response.session),
         };
     }
+    if (response.operation)
+        out.operation = response.operation;
+    if (response.replayed)
+        out.replayed = true;
     return out;
 }
 function hostedMachineId(session) {
@@ -201,6 +206,10 @@ async function startHostedMachine(input) {
     return (0, api_fetch_1.apiFetch)('/api/agentic/sandbox-sessions', {
         method: 'POST',
         body: input,
+        // apiFetch normally creates a fresh key for each invocation. The key
+        // generated (or supplied) by `machines hosted start` instead names this
+        // exact operation across a process restart and a lost response.
+        headers: { 'Idempotency-Key': input.clientRequestId },
     });
 }
 async function listHostedMachines(scope = {}) {
@@ -228,14 +237,23 @@ async function resumeHostedMachine(id, scope = {}) {
 async function destroyHostedMachine(id, scope = {}) {
     return (0, api_fetch_1.apiFetch)(hostedMachinePath(`/${encodeURIComponent(id)}`, scope), {
         method: 'DELETE',
+        ...(scope.requestId ? { headers: { 'Idempotency-Key': scope.requestId } } : {}),
     });
 }
 async function execHostedMachine(id, input, scope = {}) {
     return (0, api_fetch_1.apiFetch)(hostedMachinePath(`/${encodeURIComponent(id)}/execute`, scope), {
         method: 'POST',
-        body: input,
+        body: {
+            ...input,
+            ...(scope.requestId ? { clientRequestId: scope.requestId } : {}),
+        },
+        ...(scope.requestId ? { headers: { 'Idempotency-Key': scope.requestId } } : {}),
     });
 }
+/** Read a durable operation receipt without touching the machine or provider. */
+async function getHostedMachineOperation(operationId, scope = {}) {
+    return (0, api_fetch_1.apiFetch)(`/api/agentic/sandbox-sessions/operations/${encodeURIComponent(operationId)}${scope.workspaceId ? `?workspaceId=${encodeURIComponent(scope.workspaceId)}` : ''}`);
+}
 /**
  * The CLI gave up watching. The RUNTIME did not give up.
  *

package/dist/lib/json-output.d.ts

@@ -53,7 +53,7 @@ export declare function stripStorageFieldsFromText(text: string): string;
 export declare function withOk<T>(value: T, ok?: boolean): T | ({
     ok: boolean;
 } & Record<string, unknown>);
-export type CliOperationMode = 'execute' | 'dry_run' | 'verify';
+export type CliOperationMode = 'execute' | 'dry_run' | 'read' | 'verify';
 export type CliWriteState = 'confirmed' | 'not_attempted' | 'unknown';
 export type CliResourceIdentity = {
     kind: string;

package/dist/lib/machines.d.ts

@@ -1,4 +1,4 @@
-import type { DaemonContactState } from '@skrr-ai/data-provider';
+import type { DaemonContactState, DaemonMaintenanceSummary } from '@skrr-ai/data-provider';
 /**
  * machines.ts — request client for `/api/machines`.
  *
@@ -220,6 +220,14 @@ export interface MachineDaemonSummary {
     supersededCount: number;
     /** The profile this CLI is running as. */
     activeProfile: boolean;
+    /**
+     * The key a maintenance hold addresses this daemon by (`skrr daemon maintenance`),
+     * read from the server's own `daemons` list (D25). Absent on a server older than that
+     * list, on a managed machine, and on a daemon with no stable identity.
+     */
+    runtimeKey?: string;
+    /** Present only while this daemon is held. See `DaemonMaintenanceSummary`. */
+    maintenance?: DaemonMaintenanceSummary;
 }
 export declare function parseDaemonId(daemonId: string): {
     source: string;

package/dist/lib/machines.js

@@ -207,10 +207,24 @@ function machineListView(machine, options) {
         ? daemons
         : daemons.filter((daemon) => daemon.harnessCount > daemon.supersededCount);
     const hidden = rows.length - visibleRows.length;
+    // The server's own `daemons` (one per runtimeKey, D25) carries the key a hold is
+    // addressed by, and this view REPLACES that list with one per daemon id, so it
+    // would drop the key. Carried over by daemon id, and only when the server sent one.
+    const serverDaemons = machine.daemons ?? [];
+    const keyedDaemons = visibleDaemons.map((daemon) => {
+        const named = serverDaemons.find((candidate) => candidate.daemonId === daemon.daemonId);
+        if (!named?.runtimeKey)
+            return daemon;
+        return {
+            ...daemon,
+            runtimeKey: named.runtimeKey,
+            ...(named.maintenance ? { maintenance: named.maintenance } : {}),
+        };
+    });
     return {
         ...machine,
         thisComputer: isThisComputer(machine, options.hardwareMachineUuid),
-        daemons: visibleDaemons,
+        daemons: keyedDaemons,
         harnesses: visibleRows,
         ...(hidden > 0 ? { hiddenHarnessCount: hidden } : {}),
     };

package/dist/lib/node-adapter.js

@@ -98,10 +98,23 @@ function createNodeAdapter(opts = {}) {
         // the exact attempt session before stamping Commitment provenance.
         const autonomousRunId = process.env.OVERSKY_AUTONOMOUS_RUN_ID?.trim();
         const sessionId = process.env.OVERSKY_SESSION_ID?.trim();
+        // The same pair for a Task run the AgentWorker executes (OSK-18132). It has
+        // no AutonomousRun, so the server names its TaskExecutionRun instead, and
+        // the wiki verifies that Run against this session before crediting the
+        // agent. A separate header pair, and only when there is no autonomous one:
+        // routes that read the session header above treat it as the
+        // AutonomousRun's attempt session and refuse it without a Run id beside
+        // it. Brand-free like the rest of the public contract (OSK-18267); the
+        // server names the pair once, in TaskExecutionRun/sessionRunBinding.js.
+        const taskRunId = process.env.OVERSKY_SESSION_TASK_RUN_ID?.trim();
         if (autonomousRunId && sessionId) {
             headers['X-Oversky-Autonomous-Run-Id'] = autonomousRunId;
             headers['X-Oversky-Session-Id'] = sessionId;
         }
+        else if (taskRunId && sessionId) {
+            headers['X-Task-Run-Id'] = taskRunId;
+            headers['X-Task-Run-Session-Id'] = sessionId;
+        }
         // Which agent this process is running AS, for attribution only — it is
         // what lets a task record `createdByAgentId` instead of overloading the
         // assignee list to remember that an agent filed it. Same contract as the

package/dist/lib/record-output.d.ts

@@ -0,0 +1,22 @@
+export declare const COMPACT_RECORD_FIELDS: {
+    readonly task: readonly ["id", "identifier", "ref", "title", "status", "statusType", "priority", "parentId", "spaceId", "projectId", "goalId", "assigneeAgentIds", "assigneeUserIds", "dri", "executionMode", "actionability", "execution", "completion", "currentResultId", "createdAt", "updatedAt", "completedAt", "url"];
+};
+export type RecordResource = keyof typeof COMPACT_RECORD_FIELDS;
+/** JSON-only projection flags for detail reads. */
+export declare const recordOutputFlags: {
+    fields: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+    compact: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+};
+export type RecordOutputFlags = {
+    fields?: string;
+    compact?: boolean;
+};
+/**
+ * Shape an already-normalized record. `--fields` is an explicit caller
+ * selection and therefore wins over `--compact`; no envelope is introduced.
+ */
+export declare function shapeRecordResponse(response: unknown, { resource, fields, compact }: RecordOutputFlags & {
+    resource: RecordResource;
+}): unknown;
+/** Explain that projection flags are intentionally JSON-only on a detail read. */
+export declare function textModeRecordProjectionNotes(flags: RecordOutputFlags): string[];

package/dist/lib/record-output.js

@@ -0,0 +1,78 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.recordOutputFlags = exports.COMPACT_RECORD_FIELDS = void 0;
+exports.shapeRecordResponse = shapeRecordResponse;
+exports.textModeRecordProjectionNotes = textModeRecordProjectionNotes;
+/**
+ * JSON projection for one record, deliberately separate from list output.
+ *
+ * A list has paging and an envelope; a detail read is one canonical document.
+ * Sharing the field selector is useful, but wrapping a detail in `{data:[...]}`
+ * merely to reuse list mechanics would give callers two incompatible meanings
+ * for the same command. This module owns the record-shaped contract instead.
+ */
+const core_1 = require("@oclif/core");
+const list_output_1 = require("./list-output");
+exports.COMPACT_RECORD_FIELDS = {
+    task: [
+        'id',
+        'identifier',
+        'ref',
+        'title',
+        'status',
+        'statusType',
+        'priority',
+        'parentId',
+        'spaceId',
+        'projectId',
+        'goalId',
+        'assigneeAgentIds',
+        'assigneeUserIds',
+        'dri',
+        'executionMode',
+        'actionability',
+        'execution',
+        'completion',
+        'currentResultId',
+        'createdAt',
+        'updatedAt',
+        'completedAt',
+        'url',
+    ],
+};
+/** JSON-only projection flags for detail reads. */
+exports.recordOutputFlags = {
+    fields: core_1.Flags.string({
+        description: 'JSON only: comma-separated fields to keep on this record (dotted paths allowed, e.g. id,title,actionability.reason). Wins over --compact.',
+    }),
+    compact: core_1.Flags.boolean({
+        description: 'JSON only: keep the task detail navigation and state fields, omitting description, activity, lifecycle, and other bulk. See docs/cli/SKRR_TASKS.md (Task detail output for agents).',
+    }),
+};
+/**
+ * Shape an already-normalized record. `--fields` is an explicit caller
+ * selection and therefore wins over `--compact`; no envelope is introduced.
+ */
+function shapeRecordResponse(response, { resource, fields, compact }) {
+    if (!response || typeof response !== 'object' || Array.isArray(response))
+        return response;
+    const record = response;
+    const selected = (0, list_output_1.parseFields)(fields);
+    if (selected)
+        return (0, list_output_1.projectRow)(record, selected);
+    if (!compact)
+        return record;
+    const compacted = (0, list_output_1.projectRow)(record, exports.COMPACT_RECORD_FIELDS[resource]);
+    // Do not turn a future/unknown detail response into an empty object: preserving
+    // it is safer than hiding the only information a caller received.
+    return Object.keys(compacted).length > 0 ? compacted : record;
+}
+/** Explain that projection flags are intentionally JSON-only on a detail read. */
+function textModeRecordProjectionNotes(flags) {
+    const given = [flags.fields ? '--fields' : null, flags.compact ? '--compact' : null].filter(Boolean);
+    if (given.length === 0)
+        return [];
+    return [
+        `Note: ${given.join(' and ')} ${given.length > 1 ? 'shape' : 'shapes'} JSON output only; the detail view is unchanged. Add --json to apply ${given.length > 1 ? 'them' : 'it'}.`,
+    ];
+}

package/dist/lib/roles.d.ts

@@ -53,7 +53,7 @@ export declare const roleApi: {
                 config?: Record<string, unknown> | undefined;
             }[];
             sources: {
-                source: "space" | "tasks" | "memory" | "email" | "goal" | "files" | "local" | "daemon" | "browser" | "conversations" | "slack" | "github" | "messages" | "calendar" | "docs" | "metrics" | "agent_run" | "agent_initiatives" | "documents" | "product_metrics" | "business_metrics" | "state_monitor" | "monitor";
+                source: "space" | "tasks" | "memory" | "daemon" | "email" | "goal" | "files" | "local" | "browser" | "conversations" | "slack" | "github" | "messages" | "calendar" | "agent_run" | "docs" | "metrics" | "agent_initiatives" | "documents" | "product_metrics" | "business_metrics" | "state_monitor" | "monitor";
                 enabled: boolean;
                 config?: Record<string, unknown> | undefined;
             }[];
@@ -135,7 +135,7 @@ export declare const roleApi: {
             text: string;
             effect: "append";
             id: string;
-            status: "active" | "proposed" | "retired";
+            status: "active" | "retired" | "proposed";
             reason?: string | undefined;
             source?: {
                 kind: "owner" | "role_spec" | "correction";
@@ -151,7 +151,7 @@ export declare const roleApi: {
             phrases: string[];
             effect: "refuse" | "require_approval";
             id: string;
-            status: "active" | "proposed" | "retired";
+            status: "active" | "retired" | "proposed";
             reason?: string | undefined;
             source?: {
                 kind: "owner" | "role_spec" | "correction";

package/dist/lib/scoped-memory-command.d.ts

@@ -12,6 +12,24 @@ export type MemoryStoreResolution = {
 };
 export declare function parseMemoryStoreResolutions(value: unknown): MemoryStoreResolution[] | undefined;
 export declare function memoryStoreResolutionLines(resolutions?: MemoryStoreResolution[]): string[];
+/**
+ * A Space on a command is context for the request; it is not evidence that
+ * this session mounted the Space's Memory Store.  Keeping that distinction in
+ * one diagnostic prevents every Memory verb from inventing a different (and
+ * often unsafe) recovery path.
+ *
+ * `stores` has already passed the server's mount visibility check.  We expose
+ * only those scopes, never a guessed Store or an inaccessible Space.
+ */
+export declare function memoryNotMountedDiagnostic({ requestedScope, agentId, spaceId, stores, }: {
+    requestedScope: string;
+    agentId: string;
+    spaceId?: string;
+    stores: MemoryStore[];
+}): {
+    message: string;
+    details: Record<string, unknown>;
+};
 export declare function parseMemoryMount(value: unknown): MemoryMount;
 export declare function parseMountedMemoryStore(value: unknown): MemoryStore;
 export declare const scopedMemoryFlags: {

package/dist/lib/scoped-memory-command.js

@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.ScopedMemoryCommand = exports.versionedMutationFlags = exports.mutationFlags = exports.scopedMemoryFlags = void 0;
 exports.parseMemoryStoreResolutions = parseMemoryStoreResolutions;
 exports.memoryStoreResolutionLines = memoryStoreResolutionLines;
+exports.memoryNotMountedDiagnostic = memoryNotMountedDiagnostic;
 exports.parseMemoryMount = parseMemoryMount;
 exports.parseMountedMemoryStore = parseMountedMemoryStore;
 exports.parseMemoryApiError = parseMemoryApiError;
@@ -45,6 +46,43 @@ function memoryStoreResolutionLines(resolutions) {
     };
     return resolutions.map((resolution) => `${labels[resolution.outcome]}: ${resolution.storeId}`);
 }
+/**
+ * A Space on a command is context for the request; it is not evidence that
+ * this session mounted the Space's Memory Store.  Keeping that distinction in
+ * one diagnostic prevents every Memory verb from inventing a different (and
+ * often unsafe) recovery path.
+ *
+ * `stores` has already passed the server's mount visibility check.  We expose
+ * only those scopes, never a guessed Store or an inaccessible Space.
+ */
+function memoryNotMountedDiagnostic({ requestedScope, agentId, spaceId, stores, }) {
+    const availableScopes = [...new Set(stores.map((store) => `${store.owner.kind}:${store.owner.id}`))].sort();
+    const agentScope = `agent:${agentId}`;
+    const writableAgentStore = stores.some((store) => store.owner.kind === 'agent' &&
+        store.owner.id === agentId &&
+        store.mount.access === 'read_write');
+    const requestedSpaceId = requestedScope.startsWith('space:')
+        ? requestedScope.slice('space:'.length)
+        : undefined;
+    const resolve = `skrr memory mounts resolve --agent ${agentId}${spaceId ? ` --space ${spaceId}` : requestedSpaceId ? ` --space ${requestedSpaceId}` : ''} --json`;
+    const remedy = [
+        `Run \`${resolve}\` and select a writable mounted Store.`,
+        writableAgentStore
+            ? `To file Agent-owned Memory, retry with \`--scope ${agentScope}\`; Task or Space placement does not change that ownership.`
+            : 'A Space Store can be selected only after the session has mounted it; do not infer a mount from `--space` alone.',
+    ].join(' ');
+    return {
+        message: `MEMORY_NOT_MOUNTED: ${requestedScope} is not mounted for this session. ` +
+            '`--space` selects request context; it does not mount Space Memory. ' +
+            `→ ${remedy}`,
+        details: {
+            requestedScope,
+            ...(spaceId ? { spaceContext: spaceId } : {}),
+            availableScopes,
+            remedy,
+        },
+    };
+}
 // The public CLI must not load the private data-schemas package at runtime.
 // The API validates the full wire contract; check the fields used by CLI commands
 // before treating a response as a mounted Store or mount.
@@ -236,8 +274,21 @@ class ScopedMemoryCommand extends base_command_1.BaseCommand {
         const response = await this.memoryApi(flags.agent, `/stores${this.query(flags)}`);
         const stores = response.stores.map(parseMountedMemoryStore);
         const store = stores.find((candidate) => candidate.owner.kind === kind && candidate.owner.id === id);
-        if (!store)
-            this.error(`MEMORY_NOT_MOUNTED: ${flags.scope}`, { exit: 5 });
+        if (!store) {
+            const diagnostic = memoryNotMountedDiagnostic({
+                requestedScope: flags.scope,
+                agentId: flags.agent,
+                spaceId: flags.space,
+                stores,
+            });
+            this.failWithCliError({
+                message: diagnostic.message,
+                code: 'MEMORY_NOT_MOUNTED',
+                exit: 5,
+                retryable: false,
+                details: diagnostic.details,
+            });
+        }
         if (write && store.mount?.access !== 'read_write') {
             this.error('MEMORY_STORE_READ_ONLY: selected Store is read-only', { exit: 5 });
         }

package/dist/lib/space-charter.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Shared helpers for `skrr spaces charter …` and the wiki commands that can
+ * meet the one-charter rule (OSK-17985).
+ *
+ * A Space's charter is its one live `kind: 'charter'` wiki page. Its LEAD
+ * SECTION — everything before the first `##` heading — is what every agent
+ * turn in the Space receives; the rest is read on demand. The server computes
+ * the lead (`leadSection` on the charter read) with the same function the
+ * Space context builder uses, so these helpers print it rather than
+ * re-deriving it.
+ */
+import type { WikiCharterPage } from '@skrr-ai/data-provider';
+export type CharterConflictHint = {
+    message: string;
+    details: {
+        pageId?: string;
+        path?: string;
+    };
+};
+/**
+ * A `409 WIKI_CHARTER_EXISTS` turned into a message that names the charter
+ * already there and the command that frees the slot. `undefined` for anything
+ * else, so the caller falls through to its ordinary error handling.
+ */
+export declare function charterConflictHint(err: unknown, { binName, spaceId }: {
+    binName: string;
+    spaceId: string;
+}): CharterConflictHint | undefined;
+/**
+ * The lines `charter show` prints: where the charter is, then its lead section
+ * marked as what every agent reads, then either the whole page (`full`) or the
+ * command that reads it.
+ *
+ * An EMPTY lead is said in words, because it is the one charter state that
+ * changes what agents see without anything looking wrong: a page that opens
+ * with a `##` heading gives them no charter lead at all.
+ */
+export declare function charterLines(charter: WikiCharterPage & {
+    url?: string | null;
+}, { binName, spaceId, full }: {
+    binName: string;
+    spaceId: string;
+    full?: boolean;
+}): string[];
+/** What `charter show` prints for a Space that has no charter page yet. */
+export declare function noCharterLines({ binName, spaceId, }: {
+    binName: string;
+    spaceId: string;
+}): string[];

package/dist/lib/space-charter.js

@@ -0,0 +1,78 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.charterConflictHint = charterConflictHint;
+exports.charterLines = charterLines;
+exports.noCharterLines = noCharterLines;
+const http_error_1 = require("./http-error");
+/**
+ * A `409 WIKI_CHARTER_EXISTS` turned into a message that names the charter
+ * already there and the command that frees the slot. `undefined` for anything
+ * else, so the caller falls through to its ordinary error handling.
+ */
+function charterConflictHint(err, { binName, spaceId }) {
+    if (!(0, http_error_1.hasHttpStatus)(err, 409))
+        return undefined;
+    const body = (0, http_error_1.httpBodyOf)(err);
+    if (body?.code !== 'WIKI_CHARTER_EXISTS')
+        return undefined;
+    const pageId = typeof body.pageId === 'string' && body.pageId ? body.pageId : undefined;
+    const path = typeof body.path === 'string' && body.path ? body.path : undefined;
+    let where = 'another page';
+    if (path)
+        where = `'${path}'`;
+    else if (pageId)
+        where = `page ${pageId}`;
+    return {
+        message: `This Space already has a charter page: ${where}. A Space holds at most one live charter. ` +
+            `Change that page to another kind first (\`${binName} wiki update ${spaceId} ${path ?? '<path>'} ` +
+            `--kind doc\`) or archive it, then try again. Show it with \`${binName} spaces charter show ${spaceId}\`.`,
+        details: { ...(pageId ? { pageId } : {}), ...(path ? { path } : {}) },
+    };
+}
+/**
+ * The lines `charter show` prints: where the charter is, then its lead section
+ * marked as what every agent reads, then either the whole page (`full`) or the
+ * command that reads it.
+ *
+ * An EMPTY lead is said in words, because it is the one charter state that
+ * changes what agents see without anything looking wrong: a page that opens
+ * with a `##` heading gives them no charter lead at all.
+ */
+function charterLines(charter, { binName, spaceId, full = false }) {
+    const path = charter.path ?? charter.slug;
+    const lines = [`Charter: ${path} (${charter.pageId})`];
+    if (charter.title && charter.title !== path)
+        lines.push(`Title: ${charter.title}`);
+    if (charter.url)
+        lines.push(`URL: ${charter.url}`);
+    lines.push('');
+    lines.push('Lead section (everything before the first ## heading; read by every agent in this Space):');
+    const lead = typeof charter.leadSection === 'string' ? charter.leadSection : '';
+    if (lead) {
+        for (const line of lead.split('\n'))
+            lines.push(`  ${line}`);
+    }
+    else {
+        lines.push('  (empty: the page opens with a ## heading, so agents receive no charter lead. ' +
+            'Put the essentials before the first ## heading.)');
+    }
+    lines.push('');
+    if (full) {
+        lines.push('Full page:');
+        for (const line of String(charter.content ?? '').split('\n'))
+            lines.push(`  ${line}`);
+    }
+    else {
+        lines.push(`The rest of the page is read on demand: \`${binName} spaces charter show ${spaceId} --full\` ` +
+            `or \`${binName} wiki cat ${spaceId} ${path}\`.`);
+    }
+    return lines;
+}
+/** What `charter show` prints for a Space that has no charter page yet. */
+function noCharterLines({ binName, spaceId, }) {
+    return [
+        'This Space has no charter page yet.',
+        `Create one from the Space description: \`${binName} spaces charter create-from-description ${spaceId}\``,
+        `Or make an existing page the charter: \`${binName} wiki update ${spaceId} <path> --kind charter\``,
+    ];
+}