@skrr-ai/cli 0.1.118 → 0.1.120

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;
@@ -10,6 +11,7 @@ const core_1 = require("@oclif/core");
 const node_crypto_1 = require("node:crypto");
 const base_command_1 = require("../base-command");
 const api_fetch_1 = require("./api-fetch");
+const memory_history_session_1 = require("./memory-history-session");
 function parseMemoryStoreResolutions(value) {
     if (value === undefined)
         return undefined;
@@ -44,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.
@@ -120,6 +159,9 @@ const ERROR_EXITS = {
     MEMORY_AUTHORIZATION_STALE: 8,
 };
 function parseMemoryApiError(error) {
+    if (error.code === 'MEMORY_HISTORY_API_UNSUPPORTED') {
+        return { code: error.code, message: error.message, retryable: false };
+    }
     try {
         const body = JSON.parse(error.body || '{}');
         const details = {
@@ -136,7 +178,7 @@ function parseMemoryApiError(error) {
         };
         return {
             code: String(body.code || body.error || error.code || 'MEMORY_API_ERROR').toUpperCase(),
-            message: [body.message || error.message, body.remedy].filter(Boolean).join(' '),
+            message: [body.message || error.message, body.remedy, error.recoveryHint].filter(Boolean).join(' '),
             retryable: body.retryable === true,
             ...(Object.keys(details).length ? { details } : {}),
         };
@@ -144,7 +186,7 @@ function parseMemoryApiError(error) {
     catch {
         return {
             code: error.code || 'MEMORY_API_ERROR',
-            message: error.message,
+            message: [error.message, error.recoveryHint].filter(Boolean).join(' '),
             retryable: false,
         };
     }
@@ -154,8 +196,35 @@ class ScopedMemoryCommand extends base_command_1.BaseCommand {
         return `/api/agents/${encodeURIComponent(agentId)}/memories/workspace${suffix}`;
     }
     async memoryApi(agentId, suffix, options = {}) {
+        return this.memoryRequest(this.endpoint(agentId, suffix), options);
+    }
+    async memoryHistoryApi(flags, options) {
+        const suffix = options.versionId ? `/${encodeURIComponent(options.versionId)}` : '';
+        const query = { memoryId: options.memoryId, limit: options.limit };
+        if (!(0, memory_history_session_1.hasMemoryHistoryRuntime)()) {
+            const store = await this.resolveStore(flags);
+            return this.memoryApi(flags.agent, `/stores/${store.id}/versions${suffix}${this.query(flags, query)}`);
+        }
+        const { sessionId } = (0, memory_history_session_1.memoryHistorySession)();
+        if (Boolean(flags.store) === Boolean(flags.scope)) {
+            this.error('Pass exactly one of --store <id> or --scope agent:<id>|space:<id>.', { exit: 2 });
+        }
+        if (flags.scope && !/^(agent|space):[^:]+$/.test(flags.scope)) {
+            this.error('--scope must be agent:<id> or space:<id>.', { exit: 2 });
+        }
+        if (flags.scope?.startsWith('space:') && !flags.space) {
+            this.error(`MEMORY_SPACE_CONTEXT_REQUIRED: --space ${flags.scope.slice(6)} is required when selecting ${flags.scope}.`, { exit: 2, code: 'MEMORY_SPACE_CONTEXT_REQUIRED' });
+        }
+        // Mount resolution belongs to the admitted session facade. A generic Store
+        // preflight would require an owner credential before the session-only read.
+        const path = `/api/agentic/sessions/${encodeURIComponent(sessionId)}/memory/agents/${encodeURIComponent(flags.agent)}/versions${suffix}`;
+        return this.memoryRequest(`${path}${this.query(flags, {
+            ...query, ...(flags.store ? { storeId: flags.store } : { scope: flags.scope }),
+        })}`, { sessionRead: 'memory-history-v1' });
+    }
+    async memoryRequest(path, options) {
         try {
-            return await (0, api_fetch_1.apiFetch)(this.endpoint(agentId, suffix), options);
+            return await (0, api_fetch_1.apiFetch)(path, options);
         }
         catch (error) {
             if (error instanceof api_fetch_1.ApiFetchError) {
@@ -205,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\``,
+    ];
+}

package/dist/lib/space-loop-migration.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Converting a Space's older periodic agent turns into Space loops on the CLI
+ * (OSK-18009, design §5.11): how `skrr spaces loops migrate` prints a plan and
+ * what applying it did.
+ *
+ * The vocabulary (dispositions, reasons, outcomes) and every sentence that
+ * explains a code are `@skrr-ai/data-provider`'s (`spaces/loopMigration.ts`),
+ * and the server sends each code's sentence beside it; this file only lays
+ * them out. A label, a prompt or a note was written by a person or an agent
+ * and is printed as data, on one line.
+ */
+import type { SpaceLoopMigrationApplyResponse, SpaceLoopMigrationPlan } from '@skrr-ai/data-provider';
+/** The plan, as a person reviews it before applying. */
+export declare function planLines(plan: SpaceLoopMigrationPlan, { binName }?: {
+    binName?: string;
+}): string[];
+/** What applying did, one line per entry. */
+export declare function applyLines(response: SpaceLoopMigrationApplyResponse): string[];

package/dist/lib/space-loop-migration.js

@@ -0,0 +1,128 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.planLines = planLines;
+exports.applyLines = applyLines;
+const space_notebook_1 = require("./space-notebook");
+const SHAPE_WORD = {
+    space_loop: "the Space's loop",
+    member_automation: "its owner's own Commitment, delivering into the Space",
+};
+const OUTCOME_WORD = {
+    handed_over: 'handed over',
+    awaiting_activation: 'loop made, not active yet',
+    already_handed_over: 'already handed over',
+    not_converted: 'not converted',
+    not_yours: 'not yours to convert',
+    abandoned: 'its loop ended before taking over',
+    failed: 'failed',
+};
+function perDay(value) {
+    if (value >= 1)
+        return `${Math.round(value * 100) / 100}/day`;
+    return `1 every ${Math.round(1 / value)} days`;
+}
+function entryHeading(entry) {
+    return `  ${entry.entryId}  ${(0, space_notebook_1.oneLine)(entry.label, 80)}`;
+}
+function convertLines(entry) {
+    const lines = [entryHeading(entry)];
+    const target = entry.target;
+    if (target) {
+        lines.push(`    becomes   ${SHAPE_WORD[target.shape] || target.shape}: owned by user ${target.ownerUserId}, held by agent ${target.agentId}`);
+    }
+    if (entry.pointer) {
+        lines.push(`    loop      ${entry.pointer.commitmentId} (${entry.pointer.loopStatus || 'unknown'}); the entry keeps firing until it is active`);
+    }
+    const cadence = entry.cadence;
+    if (cadence) {
+        lines.push(`    cadence   ${cadence.fidelity}: ${(0, space_notebook_1.oneLine)(cadence.before.summary, 80)}, ${perDay(cadence.before.turnsPerDay)} -> ${(0, space_notebook_1.oneLine)(cadence.after.summary, 100)}, ${perDay(cadence.after.turnsPerDay)}`);
+        for (const note of cadence.notes)
+            lines.push(`              ${(0, space_notebook_1.oneLine)(note.message, 200)}`);
+    }
+    for (const note of entry.notes)
+        lines.push(`    differs   ${(0, space_notebook_1.oneLine)(note.message, 200)}`);
+    if (entry.activation?.knownBlockers?.length) {
+        lines.push(`    activate  will stay a draft until fixed: ${entry.activation.knownBlockers.join(', ')} (the entry keeps firing meanwhile)`);
+    }
+    lines.push(entry.apply.allowed
+        ? '    apply     you can apply this'
+        : `    apply     not you: ${(0, space_notebook_1.oneLine)(entry.apply.message || entry.apply.reason, 200)}`);
+    return lines;
+}
+/** The plan, as a person reviews it before applying. */
+function planLines(plan, { binName = 'skrr' } = {}) {
+    const lines = [
+        `Converting ${plan.sourceLabel} entries of space ${plan.spaceId} into Space loops`,
+        plan.executionPrincipal
+            ? `Execution principal: user ${plan.executionPrincipal.userId} (version ${plan.executionPrincipal.version}). Their entries become the Space's loops; everyone else's become their own Commitments.`
+            : "This Space has no active execution principal, so every entry becomes its owner's own Commitment.",
+    ];
+    if (plan.entryScope === 'owner') {
+        lines.push(`A ${plan.sourceLabel} is private to its member: this plan lists only yours, and each member converts their own.`);
+    }
+    const groups = [
+        ['Will convert', plan.entries.filter((entry) => entry.disposition === 'convert')],
+        [
+            'Converted, loop not active yet',
+            plan.entries.filter((entry) => entry.disposition === 'resume'),
+        ],
+        ['Handed over', plan.entries.filter((entry) => entry.disposition === 'handed_over')],
+        ['Not converted', plan.entries.filter((entry) => entry.disposition === 'not_convertible')],
+    ];
+    for (const [title, entries] of groups) {
+        if (entries.length === 0)
+            continue;
+        lines.push('', `${title} (${entries.length}):`);
+        for (const entry of entries) {
+            if (entry.disposition === 'convert' || entry.disposition === 'resume') {
+                lines.push(...convertLines(entry));
+            }
+            else if (entry.disposition === 'handed_over') {
+                const status = entry.pointer?.loopStatus;
+                lines.push(`${entryHeading(entry)}: retired, replaced by loop ${entry.pointer?.commitmentId} (${status || 'unknown'})${status && status !== 'active' && status !== 'paused'
+                    ? '. A retired entry stays retired; make a new loop or heartbeat to bring the turn back.'
+                    : ''}`);
+            }
+            else {
+                // A short detail reads inline; a long one (which events and filters
+                // block a Space assistant, OSK-18010) gets its own line, never cut short.
+                const detail = entry.detail ? (0, space_notebook_1.oneLine)(entry.detail, 600) : '';
+                const inline = detail && detail.length <= 160;
+                lines.push(`${entryHeading(entry)}: ${(0, space_notebook_1.oneLine)(entry.message || entry.reason, 240)}${inline ? ` (${detail})` : ''}`);
+                if (detail && !inline)
+                    lines.push(`    why       ${detail}`);
+            }
+        }
+    }
+    if (plan.entries.length === 0) {
+        lines.push('', plan.entryScope === 'owner'
+            ? `You have no ${plan.sourceLabel} in this space.`
+            : `No ${plan.sourceLabel} entries in this space.`);
+    }
+    lines.push('', `Plan digest: ${plan.planDigest}`);
+    if (plan.counts.applicableByYou > 0) {
+        lines.push(`Apply the ${plan.counts.applicableByYou} you can: ${binName} spaces loops migrate ${plan.spaceId} --from ${plan.source} --apply --plan-digest ${plan.planDigest}`);
+    }
+    else {
+        lines.push('Nothing here is yours to apply.');
+    }
+    return lines;
+}
+/** What applying did, one line per entry. */
+function applyLines(response) {
+    const lines = response.results.map((result) => {
+        const word = OUTCOME_WORD[result.outcome] || result.outcome;
+        const loop = result.commitmentId ? ` -> loop ${result.commitmentId}` : '';
+        const code = result.code ? ` (${result.code})` : '';
+        const detail = result.detail ? `: ${(0, space_notebook_1.oneLine)(result.detail, 240)}` : '';
+        return `${result.entryId}  ${word}${loop}${code}${detail}`;
+    });
+    const counts = Object.entries(response.counts)
+        .map(([outcome, count]) => `${count} ${OUTCOME_WORD[outcome] || outcome}`)
+        .join(', ');
+    lines.push('', counts || 'Nothing to apply.');
+    if (response.results.some((result) => result.outcome === 'awaiting_activation')) {
+        lines.push('A loop that is not active yet leaves its entry firing. Fix what the code names, then activate the loop; its entry retires the moment it is active.');
+    }
+    return lines;
+}

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

@@ -0,0 +1,22 @@
+/**
+ * The Space Notebook on the CLI (OSK-17996): how `skrr spaces notebook` prints
+ * one page of a Space's timeline.
+ *
+ * The vocabulary, the link paths and the sentences that explain why a kind
+ * ends where it does are `@skrr-ai/data-provider`'s (`spaces/notebook.ts`);
+ * this file only lays them out, so the CLI cannot describe a window or a
+ * visibility rule differently from the web Notebook tab.
+ *
+ * A row's summary was written by a person, an Agent or the platform (its
+ * author says which) and is printed as data: on one line, control characters
+ * removed, so a summary cannot forge a row of its own.
+ */
+import { type SpaceNotebookAuthor, type SpaceNotebookResponse } from '@skrr-ai/data-provider';
+/** One printable line: no control or bidi characters, whitespace collapsed. */
+export declare function oneLine(value: unknown, max?: number): string;
+export declare function notebookAuthorLabel(author: SpaceNotebookAuthor | undefined): string;
+/** The lines `spaces notebook` prints for one page. */
+export declare function notebookLines(page: SpaceNotebookResponse, { webOrigin, binName }: {
+    webOrigin?: string;
+    binName: string;
+}): string[];

package/dist/lib/space-notebook.js

@@ -0,0 +1,140 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.oneLine = oneLine;
+exports.notebookAuthorLabel = notebookAuthorLabel;
+exports.notebookLines = notebookLines;
+/**
+ * The Space Notebook on the CLI (OSK-17996): how `skrr spaces notebook` prints
+ * one page of a Space's timeline.
+ *
+ * The vocabulary, the link paths and the sentences that explain why a kind
+ * ends where it does are `@skrr-ai/data-provider`'s (`spaces/notebook.ts`);
+ * this file only lays them out, so the CLI cannot describe a window or a
+ * visibility rule differently from the web Notebook tab.
+ *
+ * A row's summary was written by a person, an Agent or the platform (its
+ * author says which) and is printed as data: on one line, control characters
+ * removed, so a summary cannot forge a row of its own.
+ */
+const data_provider_1 = require("@skrr-ai/data-provider");
+const KIND_TAG = {
+    task_result: 'result',
+    loop_cycle: 'cycle',
+    hypothesis: 'hypothesis',
+    journal_entry: 'journal',
+    report: 'report',
+};
+const VERDICT_WORD = {
+    supported: 'supported',
+    refuted: 'ruled out',
+    inconclusive: 'inconclusive',
+    superseded: 'superseded',
+};
+/** One printable line: no control or bidi characters, whitespace collapsed. */
+function oneLine(value, max = 240) {
+    const text = String(value ?? '')
+        // eslint-disable-next-line no-control-regex
+        .replace(/[\u0000-\u001f\u007f-\u009f‎‏‪-‮⁦-⁩]/g, ' ')
+        .replace(/\s+/g, ' ')
+        .trim();
+    return text.length > max ? `${text.slice(0, max - 1).trimEnd()}…` : text;
+}
+function notebookAuthorLabel(author) {
+    if (!author)
+        return 'unknown';
+    if (author.kind === 'agent')
+        return author.agentId ? `agent ${author.agentId}` : 'agent';
+    if (author.kind === 'person')
+        return author.userId ? `person ${author.userId}` : 'person';
+    return author.label ? `system (${oneLine(author.label, 60)})` : 'system';
+}
+const LINK_WORD = {
+    home: 'loop of this Space',
+    watch: 'watching this Space',
+};
+const VISIBILITY_WORD = {
+    space_access: 'shared with the Space',
+    commitment_access: 'only for people who can open the Commitment',
+};
+/** Which Commitment a loop row came from, and who may see the row. */
+function loopLine(row) {
+    const link = LINK_WORD[row.loop.link] || row.loop.link;
+    const seen = VISIBILITY_WORD[row.visibility] || row.visibility;
+    return `${link} · ${seen}`;
+}
+function detailLines(row) {
+    switch (row.kind) {
+        case 'task_result': {
+            const task = row.task.identifier || row.task.id;
+            const conclusion = row.result.conclusionType ? `, ${row.result.conclusionType}` : '';
+            const current = row.result.current ? '' : ', superseded';
+            return [`task ${task}, result v${row.result.version}${conclusion}${current}`];
+        }
+        case 'loop_cycle': {
+            const stop = row.cycle.stop;
+            const lines = [
+                stop
+                    ? `stopped at ${stop.question}/${stop.gate}${stop.reason ? ` (${stop.reason})` : ''}`
+                    : 'an agent turn was dispatched',
+            ];
+            if (stop?.fix)
+                lines.push(`fix: ${oneLine(stop.fix)}`);
+            lines.push(loopLine(row));
+            return lines;
+        }
+        case 'hypothesis': {
+            const word = VERDICT_WORD[row.verdict.status] || row.verdict.status;
+            const by = row.verdict.authority === 'observation_backed' ? 'settled by readings' : 'agent-reported';
+            const lines = [`verdict: ${word} (${by})`];
+            if (row.verdict.reason)
+                lines.push(`because: ${oneLine(row.verdict.reason)}`);
+            lines.push(loopLine(row));
+            return lines;
+        }
+        default:
+            return [];
+    }
+}
+/** The lines `spaces notebook` prints for one page. */
+function notebookLines(page, { webOrigin, binName }) {
+    const lines = [];
+    if (!page.rows.length) {
+        lines.push(page.nextCursor
+            ? 'Nothing on this page.'
+            : `No available records in this listing (${page.kinds.map(data_provider_1.spaceNotebookKindLabel).join(', ')}).`);
+    }
+    for (const row of page.rows) {
+        const tag = (KIND_TAG[row.kind] || row.kind).padEnd(10);
+        lines.push(`${row.at}  ${tag}  ${oneLine(row.title, 80)}  · ${notebookAuthorLabel(row.author)}`);
+        if (row.summary) {
+            lines.push(`    ${oneLine(row.summary)}${row.summaryTruncated ? ' (cut; open it for the rest)' : ''}`);
+        }
+        for (const detail of detailLines(row))
+            lines.push(`    ${detail}`);
+        lines.push(`    ${webOrigin ? `${webOrigin}${row.link.path}` : row.link.path}`);
+    }
+    const notes = [];
+    for (const source of page.sources) {
+        if (source.state !== 'ended')
+            continue;
+        for (const window of source.windows || []) {
+            notes.push((0, data_provider_1.describeSpaceNotebookWindow)(source.kind, window));
+        }
+    }
+    // Who may see a loop row, once per rule the page shows.
+    for (const row of page.rows) {
+        if ('visibility' in row && row.visibility) {
+            notes.push((0, data_provider_1.describeSpaceNotebookVisibility)(row.visibility));
+        }
+    }
+    lines.push('', ...[...new Set(notes)], data_provider_1.SPACE_NOTEBOOK_COVERAGE_NOTE);
+    if (page.nextCursor) {
+        // A cursor is bound to the filter it was issued for; every kind is the
+        // default, so the flag is only repeated when the page was filtered.
+        const kinds = page.kinds.length && page.kinds.length < data_provider_1.SPACE_NOTEBOOK_KINDS.length
+            ? ` --kinds ${page.kinds.join(',')}`
+            : '';
+        lines.push('', `More: ${binName} spaces notebook ${page.spaceId}${kinds} --cursor ${page.nextCursor}`);
+    }
+    return lines;
+}

package/dist/lib/space-proposal-decision-command.d.ts

@@ -0,0 +1,36 @@
+import { BaseCommand } from '../base-command';
+import { type SpaceProposalDecision } from './space-proposals';
+/**
+ * The flags `keep` and `discard` share. Exported so each command spreads it
+ * into its own `flags`: the command-hygiene scan reads one file at a time and
+ * recognises a shared `...xFlags` spread, not a static inherited from a class.
+ */
+export declare const spaceProposalDecisionFlags: {
+    expected: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+    reason: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+    'reason-code': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+    json: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+};
+/**
+ * `skrr spaces proposals keep|discard <space> <KIND:ID>` (OSK-17993).
+ *
+ * Reads the item from the Space's inbox, then sends the decision to the
+ * endpoint the item names (`decisionRoute`): the owning object's own. The CLI
+ * decides nothing itself and adds no decision path. An Action Bundle is pinned
+ * to `--expected`, the revision the caller reviewed in `list`: deciding the
+ * bundle as it is NOW would approve writes the caller never saw.
+ */
+export declare abstract class SpaceProposalDecisionCommand extends BaseCommand {
+    static decision: SpaceProposalDecision;
+    static args: {
+        space: import("@oclif/core/interfaces").Arg<string, Record<string, unknown>>;
+        item: import("@oclif/core/interfaces").Arg<string, Record<string, unknown>>;
+    };
+    static flags: {
+        expected: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        reason: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        'reason-code': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        json: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+    };
+    run(): Promise<void>;
+}