@skrr-ai/cli 0.1.12 → 0.1.14

package/dist/commands/daemon/stop.js

@@ -1,14 +1,14 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 const core_1 = require("@oclif/core");
-const exec_oversky_1 = require("../../lib/exec-oversky");
+const exec_runtime_binary_1 = require("../../lib/exec-runtime-binary");
 class DaemonStop extends core_1.Command {
     // `skrr daemons <sub>` — the plural is advertised as an alias for the
     // whole topic, and without a per-command alias only the bare topic
     // resolved: every subcommand under it failed.
     static aliases = ['daemons:stop'];
     static summary = 'Stop the local skrr daemon';
-    static description = (0, exec_oversky_1.forwardedFlagsNote)('stop');
+    static description = (0, exec_runtime_binary_1.forwardedFlagsNote)('stop');
     static strict = false;
     async run() {
         // `this.argv`, NOT `this.parse()`. `strict = false` relaxes POSITIONAL
@@ -22,12 +22,12 @@ class DaemonStop extends core_1.Command {
         // mistake, one directory over.
         const argv = this.argv;
         try {
-            const code = await (0, exec_oversky_1.execOversky)(['stop', ...argv]);
+            const code = await (0, exec_runtime_binary_1.execRuntimeBinary)(['stop', ...argv]);
             this.exit(code);
         }
         catch (err) {
-            if (err.message === 'oversky-not-installed') {
-                this.log((0, exec_oversky_1.notInstalledMessage)());
+            if (err.message === 'runtime-binary-not-installed') {
+                this.log((0, exec_runtime_binary_1.notInstalledMessage)());
                 this.exit(127);
             }
             throw err;

package/dist/commands/daemon/uninstall.js

@@ -1,7 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 const core_1 = require("@oclif/core");
-const exec_oversky_1 = require("../../lib/exec-oversky");
+const exec_runtime_binary_1 = require("../../lib/exec-runtime-binary");
 /**
  * `skrr daemon uninstall` — uninstall the local runtime's OS service.
  *
@@ -20,7 +20,7 @@ class DaemonUninstall extends core_1.Command {
     // resolved: every subcommand under it failed.
     static aliases = ['daemons:uninstall'];
     static summary = "Remove the local skrr runtime's background service (local state is left alone)";
-    static description = (0, exec_oversky_1.forwardedFlagsNote)('uninstall');
+    static description = (0, exec_runtime_binary_1.forwardedFlagsNote)('uninstall');
     static strict = false; // forward all args verbatim — see run()
     async run() {
         // `this.argv`, NOT `this.parse()`. `strict = false` relaxes POSITIONAL
@@ -34,12 +34,12 @@ class DaemonUninstall extends core_1.Command {
         // mistake, one directory over.
         const argv = this.argv;
         try {
-            const code = await (0, exec_oversky_1.execOversky)(['uninstall', ...argv]);
+            const code = await (0, exec_runtime_binary_1.execRuntimeBinary)(['uninstall', ...argv]);
             this.exit(code);
         }
         catch (err) {
-            if (err.message === 'oversky-not-installed') {
-                this.log((0, exec_oversky_1.notInstalledMessage)());
+            if (err.message === 'runtime-binary-not-installed') {
+                this.log((0, exec_runtime_binary_1.notInstalledMessage)());
                 this.exit(127);
             }
             throw err;

package/dist/commands/daemon/unlock.js

@@ -1,14 +1,14 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 const core_1 = require("@oclif/core");
-const exec_oversky_1 = require("../../lib/exec-oversky");
+const exec_runtime_binary_1 = require("../../lib/exec-runtime-binary");
 class DaemonUnlock extends core_1.Command {
     // `skrr daemons <sub>` — the plural is advertised as an alias for the
     // whole topic, and without a per-command alias only the bare topic
     // resolved: every subcommand under it failed.
     static aliases = ['daemons:unlock'];
     static summary = 'Clear a stranded singleton lock (daemon.lock) left by a crashed skrr daemon';
-    static description = (0, exec_oversky_1.forwardedFlagsNote)('unlock');
+    static description = (0, exec_runtime_binary_1.forwardedFlagsNote)('unlock');
     static strict = false; // forward all args verbatim — see run()
     static examples = ['<%= config.bin %> daemon unlock'];
     async run() {
@@ -18,12 +18,12 @@ class DaemonUnlock extends core_1.Command {
         // the verb lives on a second binary you have to learn about first.
         const argv = this.argv;
         try {
-            const code = await (0, exec_oversky_1.execOversky)(['unlock', ...argv]);
+            const code = await (0, exec_runtime_binary_1.execRuntimeBinary)(['unlock', ...argv]);
             this.exit(code);
         }
         catch (err) {
-            if (err.message === 'oversky-not-installed') {
-                this.log((0, exec_oversky_1.notInstalledMessage)());
+            if (err.message === 'runtime-binary-not-installed') {
+                this.log((0, exec_runtime_binary_1.notInstalledMessage)());
                 this.exit(127);
             }
             throw err;

package/dist/commands/daemon/usage.js

@@ -6,7 +6,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.supportsDaemonUsage = supportsDaemonUsage;
 const core_1 = require("@oclif/core");
 const node_child_process_1 = require("node:child_process");
-const exec_oversky_1 = require("../../lib/exec-oversky");
+const exec_runtime_binary_1 = require("../../lib/exec-runtime-binary");
 const index_1 = __importDefault(require("./index"));
 /** Whether an `oversky --help` surface actually supports the usage command. */
 function supportsDaemonUsage(helpText) {
@@ -29,9 +29,9 @@ class DaemonUsage extends index_1.default {
     };
     async run() {
         const { flags } = await this.parse(DaemonUsage);
-        const binary = (0, exec_oversky_1.findOverskyBinary)();
+        const binary = (0, exec_runtime_binary_1.findRuntimeBinary)();
         if (!binary) {
-            this.log((0, exec_oversky_1.notInstalledMessage)());
+            this.log((0, exec_runtime_binary_1.notInstalledMessage)());
             this.exit(127);
         }
         // A stale PATH-first `oversky` (0.2.x is common on Homebrew installs) does
@@ -58,11 +58,11 @@ class DaemonUsage extends index_1.default {
         if (flags.json)
             args.push('--json');
         try {
-            this.exit(await (0, exec_oversky_1.execOversky)(args));
+            this.exit(await (0, exec_runtime_binary_1.execRuntimeBinary)(args));
         }
         catch (error) {
-            if (error.message === 'oversky-not-installed') {
-                this.log((0, exec_oversky_1.notInstalledMessage)());
+            if (error.message === 'runtime-binary-not-installed') {
+                this.log((0, exec_runtime_binary_1.notInstalledMessage)());
                 this.exit(127);
             }
             throw error;

package/dist/commands/login.js

@@ -38,7 +38,10 @@ const auth_storage_1 = require("../lib/auth-storage");
  * `cliLoginWithRefreshToken` for the full rationale.
  */
 class Login extends base_command_1.BaseCommand {
-    static description = 'Sign in to a skrr instance (PKCE localhost callback; device-code fallback)';
+    static description = 'Sign in to a skrr instance (PKCE localhost callback; device-code fallback). ' +
+        'On an interactive first login without a local runtime, skrr offers to install it as a ' +
+        'background service. Choose no, or set SKRR_SKIP_DAEMON_HANDOFF=1 before running this ' +
+        'command, to skip that optional setup.';
     static examples = [
         '<%= config.bin %> login',
         '<%= config.bin %> login --env prod',
@@ -186,7 +189,9 @@ class Login extends base_command_1.BaseCommand {
                 // profile, and until this login there was no session to take them from.
                 // Keyed off `reason` rather than the sentence in `detail`, which is
                 // written for a person and expected to be reworded.
-                if (handoff.reason === 'no-binary' || handoff.reason === 'no-service') {
+                if (handoff.reason === 'no-binary' ||
+                    handoff.reason === 'legacy-binary' ||
+                    handoff.reason === 'no-service') {
                     const setup = await (0, daemon_setup_1.offerDaemonSetup)({
                         binaryPresent: handoff.reason === 'no-service',
                         log: (line) => this.log(line),

package/dist/commands/spaces/list.d.ts

@@ -17,6 +17,19 @@ import { BaseCommand } from '../../base-command';
  * convention `describeResourceNotFound` follows in `base-command`.
  */
 export declare function noSpacesMatchedMessage(q: string, bin?: string): string;
+/**
+ * What the unfiltered zero-row case is allowed to say.
+ *
+ * A bare `No spaces.` on a fresh account is technically true and operationally
+ * useless: it names no next step, so the user reading `GETTING_STARTED.md`
+ * step 3 hits three of these in a row and concludes the product is inert.
+ * `commitments/list.ts` learned this the hard way and left the reasoning in a
+ * comment; the fix is to follow the same pattern here — one line naming the
+ * command that fixes it.
+ *
+ * Pure and exported so the wording is testable without an oclif runtime.
+ */
+export declare function noSpacesEmptyMessage(bin?: string): string;
 export default class SpacesList extends BaseCommand {
     static description: string;
     static examples: string[];

package/dist/commands/spaces/list.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.noSpacesMatchedMessage = noSpacesMatchedMessage;
+exports.noSpacesEmptyMessage = noSpacesEmptyMessage;
 const core_1 = require("@oclif/core");
 const data_provider_1 = require("@skrr-ai/data-provider");
 const base_command_1 = require("../../base-command");
@@ -29,6 +30,22 @@ function noSpacesMatchedMessage(q, bin = 'skrr') {
         'not a tokenized search, so word order matters.\n' +
         `  → retry with one distinctive word, or list them all with \`${bin} spaces list\`.`);
 }
+/**
+ * What the unfiltered zero-row case is allowed to say.
+ *
+ * A bare `No spaces.` on a fresh account is technically true and operationally
+ * useless: it names no next step, so the user reading `GETTING_STARTED.md`
+ * step 3 hits three of these in a row and concludes the product is inert.
+ * `commitments/list.ts` learned this the hard way and left the reasoning in a
+ * comment; the fix is to follow the same pattern here — one line naming the
+ * command that fixes it.
+ *
+ * Pure and exported so the wording is testable without an oclif runtime.
+ */
+function noSpacesEmptyMessage(bin = 'skrr') {
+    return ('No spaces yet.\n' +
+        `  → Create your first one: \`${bin} spaces create --title "My workspace"\``);
+}
 class SpacesList extends base_command_1.BaseCommand {
     static description = 'List spaces';
     static examples = [
@@ -95,7 +112,9 @@ class SpacesList extends base_command_1.BaseCommand {
         const r = response;
         const items = r?.data ?? [];
         if (items.length === 0) {
-            this.log(flags.q ? noSpacesMatchedMessage(flags.q, this.config.bin) : 'No spaces.');
+            this.log(flags.q
+                ? noSpacesMatchedMessage(flags.q, this.config.bin)
+                : noSpacesEmptyMessage(this.config.bin));
             return;
         }
         const rows = items.map((s) => ({

package/dist/commands/tasks/list.d.ts

@@ -1,6 +1,17 @@
 import type { TaskListParams } from '@skrr-ai/data-provider';
 import { BaseCommand } from '../../base-command';
 type ListFlags = Record<string, unknown>;
+/**
+ * What the zero-row case is allowed to say. The bare `No tasks.` was step 3
+ * of `GETTING_STARTED.md` and named no next step; a new user reading it hit
+ * three of these in a row and concluded the product was empty. Follow the
+ * `commitments/list.ts` pattern: name the command that fixes THIS empty state,
+ * with the specific `--status in_progress` hint kept because a reaped run
+ * genuinely hides here (a real bug, not a first-run scenario).
+ *
+ * Exported and pure so the wording is testable without an oclif runtime.
+ */
+export declare function emptyTasksMessage(flags: ListFlags, bin?: string): string;
 /**
  * The task-list request bag is shared with import/export so every CLI list
  * surface serializes the same server-side filters. Keep user-id resolution in

package/dist/commands/tasks/list.js

@@ -1,5 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.emptyTasksMessage = emptyTasksMessage;
 exports.buildListParams = buildListParams;
 const core_1 = require("@oclif/core");
 const data_provider_1 = require("@skrr-ai/data-provider");
@@ -7,6 +8,86 @@ const base_command_1 = require("../../base-command");
 const web_url_1 = require("../../lib/web-url");
 const format_1 = require("../../lib/format");
 const tasks_1 = require("../../lib/tasks");
+/**
+ * Names of `tasks list` flags that narrow the result set. Used to distinguish
+ * "no tasks anywhere" from "no tasks matching your filters" — the first case
+ * wants a create-command hint, the second wants a loosen-filters hint. Kept
+ * as a set so a new filter added to `buildListParams` shows up here at review
+ * time rather than silently changing the empty state.
+ */
+const FILTER_FLAGS = new Set([
+    'goal',
+    'project',
+    'cycle',
+    'parent',
+    'status',
+    'status-type',
+    'execution-state',
+    'actionable-by',
+    'actionable-for-agent',
+    'needs-me',
+    'actionability-state',
+    'actionability-reason',
+    'priority',
+    'estimate',
+    'min-estimate',
+    'assignee-agent',
+    'assignee-user',
+    'dri',
+    'dri-kind',
+    'mine',
+    'explicit-only',
+    'subscribed',
+    'include-snoozed',
+    'external-key',
+    'blocked-by',
+    'blocks',
+    'due-before',
+    'due-after',
+    'overdue',
+    'tag',
+    'label-id',
+    'q',
+]);
+/**
+ * What the zero-row case is allowed to say. The bare `No tasks.` was step 3
+ * of `GETTING_STARTED.md` and named no next step; a new user reading it hit
+ * three of these in a row and concluded the product was empty. Follow the
+ * `commitments/list.ts` pattern: name the command that fixes THIS empty state,
+ * with the specific `--status in_progress` hint kept because a reaped run
+ * genuinely hides here (a real bug, not a first-run scenario).
+ *
+ * Exported and pure so the wording is testable without an oclif runtime.
+ */
+function emptyTasksMessage(flags, bin = 'skrr') {
+    const activeFilters = Array.from(FILTER_FLAGS).filter((name) => {
+        const value = flags[name];
+        if (value === undefined || value === null || value === false)
+            return false;
+        if (typeof value === 'string' && value.length === 0)
+            return false;
+        if (Array.isArray(value) && value.length === 0)
+            return false;
+        return true;
+    });
+    const lines = ['No tasks.'];
+    if (activeFilters.length === 0) {
+        lines.push('');
+        lines.push(`  → Create your first one: \`${bin} tasks create --title "..." --space <space-id>\``);
+        lines.push(`  → List spaces to find one: \`${bin} spaces list\``);
+    }
+    else if (flags.status === 'in_progress' && !flags['execution-state']) {
+        // `--status in_progress` filters the board column only. A run that was
+        // reaped/reset (e.g. a stuck-task timeout) is moved OFF `in_progress` but
+        // keeps its execution markers, so it hides here. Point the operator at
+        // the execution-state views that still surface it.
+        lines.push('');
+        lines.push('Note: `--status in_progress` shows only the board column. A reaped or reset run');
+        lines.push('      no longer has that status. Try `--execution-state active` (running now) or');
+        lines.push(`      \`--execution-state recovered\` (reaped, startable), or \`${bin} tasks active\`.`);
+    }
+    return lines.join('\n');
+}
 /**
  * The task-list request bag is shared with import/export so every CLI list
  * surface serializes the same server-side filters. Keep user-id resolution in
@@ -303,17 +384,7 @@ class TasksList extends base_command_1.BaseCommand {
         const r = response;
         const items = r?.data ?? [];
         if (items.length === 0) {
-            this.log('No tasks.');
-            // `--status in_progress` filters the board column only. A run that was
-            // reaped/reset (e.g. a stuck-task timeout) is moved OFF `in_progress` but
-            // keeps its execution markers, so it hides here. Point the operator at the
-            // execution-state views that still surface it.
-            if (flags.status === 'in_progress' && !flags['execution-state']) {
-                this.log('');
-                this.log('Note: `--status in_progress` shows only the board column. A reaped or reset run');
-                this.log('      no longer has that status. Try `--execution-state active` (running now) or');
-                this.log('      `--execution-state recovered` (reaped, startable), or `skrr tasks active`.');
-            }
+            this.log(emptyTasksMessage(flags, this.config.bin));
             return;
         }
         const rows = items.map((t) => {

package/dist/commands/wiki/cat.js

@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 const core_1 = require("@oclif/core");
 const data_provider_1 = require("@skrr-ai/data-provider");
 const base_command_1 = require("../../base-command");
+const web_url_1 = require("../../lib/web-url");
 class WikiCat extends base_command_1.BaseCommand {
     static description = 'Print a wiki page (Markdown by default)';
     static examples = [
@@ -41,7 +42,7 @@ class WikiCat extends base_command_1.BaseCommand {
             this.handleApiError(err);
         }
         if (flags.json) {
-            this.log(JSON.stringify(page, null, 2));
+            this.log(JSON.stringify((0, web_url_1.withWikiPageUrl)(this.cliConfig.baseURL, page), null, 2));
             return;
         }
         // Body only — so `skrr wiki cat ... > page.md` produces a clean file and

package/dist/commands/wiki/mv.js

@@ -6,6 +6,7 @@ const core_1 = require("@oclif/core");
 const data_provider_1 = require("@skrr-ai/data-provider");
 const base_command_1 = require("../../base-command");
 const http_error_1 = require("../../lib/http-error");
+const web_url_1 = require("../../lib/web-url");
 const wiki_1 = require("../../lib/wiki");
 const write_1 = require("./write");
 /**
@@ -231,7 +232,10 @@ class WikiMv extends base_command_1.BaseCommand {
                 });
             }
             if (flags.json) {
-                this.log(JSON.stringify({ kind: 'page', ...moved }, null, 2));
+                this.log(JSON.stringify({
+                    kind: 'page',
+                    ...(0, web_url_1.withWikiPageUrl)(this.cliConfig.baseURL, moved),
+                }, null, 2));
                 return;
             }
             this.log(`Moved page ${source} → ${moved.path ?? args.destination}.`);

package/dist/commands/wiki/write.js

@@ -8,6 +8,7 @@ const core_1 = require("@oclif/core");
 const data_provider_1 = require("@skrr-ai/data-provider");
 const base_command_1 = require("../../base-command");
 const http_error_1 = require("../../lib/http-error");
+const web_url_1 = require("../../lib/web-url");
 const wiki_1 = require("../../lib/wiki");
 /**
  * The page lookup below goes through `dataService`, whose adapter throws a
@@ -248,8 +249,9 @@ class WikiWrite extends base_command_1.BaseCommand {
                 `it creates. Retitle it with \`${this.config.bin} wiki update ${args.space} ${page.path ?? args.path} ` +
                 `--title ${JSON.stringify(flags.title)}\` (the slug is kept, so stored paths stay valid).`);
         }
+        const withUrl = (0, web_url_1.withWikiPageUrl)(this.cliConfig.baseURL, page);
         if (flags.json) {
-            this.log(JSON.stringify(page, null, 2));
+            this.log(JSON.stringify(withUrl, null, 2));
             return;
         }
         // Report what actually happened, not what we set out to do — a write that
@@ -260,6 +262,8 @@ class WikiWrite extends base_command_1.BaseCommand {
             verb = flags.append ? 'Appended to' : 'Updated';
         }
         this.log(`${verb} ${page.path ?? args.path} (${page.pageId}).`);
+        if (withUrl.url)
+            this.log(`URL: ${withUrl.url}`);
     }
 }
 exports.default = WikiWrite;

package/dist/help.d.ts

@@ -20,8 +20,27 @@ import { Help } from '@oclif/core';
  * before running it. The audience most likely to need the good message was the
  * audience reliably denied it.
  *
- * Only the not-found path is overridden. Real help output is untouched.
+ * It also puts a GETTING STARTED block at the top of `skrr --help`.
+ *
+ * Dogfooding 0.1.12 found the root help teaching neither of the two commands
+ * the release exists to deliver: ~50 topics in alphabetical order, with `login`
+ * between `list-tokens` and `logout`, and nothing saying a runtime is needed or
+ * that `skrr` can fetch one. The shortest path to a working machine was
+ * undiscoverable from inside the tool that provides it — findable only by
+ * someone who read the docs, which is what the two-command flow exists to make
+ * unnecessary.
+ *
+ * Printed BEFORE the standard output rather than appended, because the thing it
+ * competes with is a fifty-line topic list. A signpost below that is a signpost
+ * for people who already knew.
  */
 export default class SkrrHelp extends Help {
+    /**
+     * The two commands, before the topic list rather than after it.
+     *
+     * Deliberately not a tutorial: two lines, both runnable, in the order a new
+     * machine needs them.
+     */
+    protected showRootHelp(): Promise<void>;
     showHelp(argv: string[]): Promise<void>;
 }

package/dist/help.js

@@ -23,9 +23,34 @@ const command_miss_1 = require("./lib/command-miss");
  * before running it. The audience most likely to need the good message was the
  * audience reliably denied it.
  *
- * Only the not-found path is overridden. Real help output is untouched.
+ * It also puts a GETTING STARTED block at the top of `skrr --help`.
+ *
+ * Dogfooding 0.1.12 found the root help teaching neither of the two commands
+ * the release exists to deliver: ~50 topics in alphabetical order, with `login`
+ * between `list-tokens` and `logout`, and nothing saying a runtime is needed or
+ * that `skrr` can fetch one. The shortest path to a working machine was
+ * undiscoverable from inside the tool that provides it — findable only by
+ * someone who read the docs, which is what the two-command flow exists to make
+ * unnecessary.
+ *
+ * Printed BEFORE the standard output rather than appended, because the thing it
+ * competes with is a fifty-line topic list. A signpost below that is a signpost
+ * for people who already knew.
  */
 class SkrrHelp extends core_1.Help {
+    /**
+     * The two commands, before the topic list rather than after it.
+     *
+     * Deliberately not a tutorial: two lines, both runnable, in the order a new
+     * machine needs them.
+     */
+    async showRootHelp() {
+        this.log('GETTING STARTED');
+        this.log('  skrr login             Sign in. Offers to set this machine up if it has no runtime.');
+        this.log('  skrr daemon install    Install the runtime by hand (fetches the signed release).');
+        this.log('');
+        return super.showRootHelp();
+    }
     async showHelp(argv) {
         // Mirror oclif's own id resolution: the topic separator is a space here, so
         // the id is the leading non-flag tokens joined with `:`.

package/dist/lib/api-fetch.d.ts

@@ -29,7 +29,8 @@ export declare class ApiFetchError extends Error {
     readonly status: number;
     readonly body?: string;
     readonly code?: string;
-    constructor(message: string, status: number, body?: string, code?: string);
+    readonly method?: string;
+    constructor(message: string, status: number, body?: string, code?: string, method?: string);
 }
 /**
  * Call a skrr API endpoint with the current credential. Throws

package/dist/lib/api-fetch.js

@@ -46,12 +46,19 @@ class ApiFetchError extends Error {
     status;
     body;
     code;
-    constructor(message, status, body, code) {
+    // The HTTP method of the failing request. The 403 branch of
+    // `handleApiError` needs to know whether the request even HAD a body before
+    // it can advise the user to "try again with less of the request body"
+    // (OSK-6765): `agents show` is a GET and had no body, and the advice was
+    // impossible to follow.
+    method;
+    constructor(message, status, body, code, method) {
         super(message);
         this.name = 'ApiFetchError';
         this.status = status;
         this.body = body;
         this.code = code;
+        this.method = method;
     }
 }
 exports.ApiFetchError = ApiFetchError;
@@ -189,7 +196,7 @@ async function apiFetch(pathOrUrl, opts = {}) {
         catch {
             /* ignore body read failures */
         }
-        throw new ApiFetchError(`HTTP ${res.status} ${res.statusText} — ${method} ${pathOrUrl}`, res.status, text, code);
+        throw new ApiFetchError(`HTTP ${res.status} ${res.statusText} — ${method} ${pathOrUrl}`, res.status, text, code, method);
     }
     // 204/205 carry no body by definition; an empty body has no content-type
     // worth judging. Neither is an error.

package/dist/lib/commitments.d.ts

@@ -362,6 +362,29 @@ export declare const COMMITMENT_CREATE_KEYS: readonly ["agentId", "kind", "compa
  */
 export declare function normalizeCreateBody(input: Record<string, unknown>): Record<string, unknown>;
 export declare function parseIntervalToMs(input: string): number;
+/**
+ * Assemble the `watchedSources` array from CLI flags — one place, so `create`
+ * and `update` agree on which flags carry what.
+ *
+ * The `space` and `monitor` sources need a scope id (`config.spaceId` /
+ * `config.monitorId`) that the flat `--watch` enum cannot carry. The API
+ * rejects the whole write when one is missing (`SPACE_SOURCE_SCOPE_REQUIRED` /
+ * `INVALID_MONITOR_REFERENCE`) — the same shape that made this a finding: the
+ * CLI advertised the source but had no way to satisfy it.
+ *
+ * The companion flags (`--watch-space`, `--watch-monitor`) fill that gap and
+ * implicitly opt the source in, so the enum and its config cannot disagree.
+ * Space refs must be RESOLVED to canonical ids by the caller — this helper
+ * does not do the network round trip, so it is unit-testable on its own.
+ */
+export type WatchFlagInputs = {
+    watch?: string[];
+    metricKey?: string[];
+    /** Already resolved to canonical space ids by the caller. */
+    spaceIds?: string[];
+    monitorIds?: string[];
+};
+export declare function buildWatchedSources(inputs: WatchFlagInputs): Array<Record<string, unknown>> | undefined;
 /** The evidence-health shape carried on a check's `inputs`. */
 export type EvidenceHealthView = {
     state?: string | null;
@@ -429,6 +452,27 @@ export declare function effectiveAutonomyMode(check?: {
         policyTrace?: Array<Record<string, unknown>>;
     } | null;
 } | null): string | undefined;
+/**
+ * A `commitment_standstill` policyTrace entry, extracted from the latest
+ * check's decision. The arbiter appends it whenever a quiet posture is the
+ * ANSWER to "why nothing is happening" (`CommitmentControl/index.js` around
+ * the `record_only`/empty-action-plan branch). Every field except `reason` is
+ * optional, and old checks lack the entry entirely — so a missing entry means
+ * "the loop had nothing standstill-worthy to say", not "we don't know".
+ *
+ * Exported for tests.
+ */
+export declare function extractStandstillFromCheck(check?: {
+    decision?: {
+        policyTrace?: Array<Record<string, unknown>>;
+    } | null;
+} | null): {
+    reason: string;
+    layer?: string;
+    owner?: string;
+    fix?: string;
+    alsoConstrained?: Array<Record<string, unknown>>;
+} | null;
 /**
  * The `Autonomy:` line — the stated mode, annotated when the latest check
  * actually ran at a STRICTER one (OSK-4881). Without the caveat, a commitment