@skrr-ai/cli 0.1.9 → 0.1.11

package/dist/base-command.d.ts

@@ -367,19 +367,7 @@ export declare function withSubject(subject: string | undefined, message: string
  * Exported for tests.
  */
 export declare function describeHarnessUnavailable(body: Record<string, unknown> | null, bin?: string): string;
-/**
- * Enrich the server's `ASSIGNEE_NOT_IN_SPACE` rejection with the same
- * copy-pasteable remedy the by-name resolution failure already gives (OSK-4864).
- *
- * When a caller names an assignee that is not a member of the space, the CLI's
- * own name-resolution path (`ASSIGNEE_NOT_FOUND`) says "add one with
- * `skrr spaces members add`". The server's id-based rejection reaches
- * `handleApiError` as a bare sentence that interpolates ids and offers no next
- * step, so the two paths for the same mistake read very differently. Append the
- * remedy unless the server already named it.
- *
- * Exported for tests.
- */
+export declare function describeResourceNotFound(serverMessage: string | undefined, bin?: string, baseURL?: string): string | null;
 export declare function describeAssigneeNotInSpace(serverMessage: string | undefined, bin?: string): string;
 /**
  * Whether an automated retry of the IDENTICAL request could plausibly succeed.

package/dist/base-command.js

@@ -5,6 +5,7 @@ exports.assigneePayloadNeedsResolution = assigneePayloadNeedsResolution;
 exports.parseGlobalFlags = parseGlobalFlags;
 exports.withSubject = withSubject;
 exports.describeHarnessUnavailable = describeHarnessUnavailable;
+exports.describeResourceNotFound = describeResourceNotFound;
 exports.describeAssigneeNotInSpace = describeAssigneeNotInSpace;
 exports.describeForbidden = describeForbidden;
 exports.isRetryableFailure = isRetryableFailure;
@@ -288,6 +289,16 @@ class BaseCommand extends core_1.Command {
                         kind: (0, auth_core_1.classifyTokenKind)(accessToken),
                     };
                 }
+                else if (autoResult.outcome.reason === 'rate_limited') {
+                    // Otherwise the only thing the user sees is "Not signed in", which is
+                    // true and points at the wrong repair: they are signed in, the local
+                    // broker is just being throttled, and the fix is to wait rather than
+                    // to log in again. Reachable in the ordinary way — a cold machine
+                    // running several skrr commands at once has every process brokering,
+                    // because none of them has a token yet.
+                    process.stderr.write('[skrr] The local skrr runtime is being rate-limited while brokering logins. ' +
+                        'This is transient — retry in a few minutes, or run `skrr login` to sign in directly.\n');
+                }
                 else if (autoResult.outcome.reason === 'base_url_mismatch' &&
                     autoResult.outcome.daemonServerUrl) {
                     // The user is about to see "Not signed in" — give them the
@@ -869,7 +880,15 @@ class BaseCommand extends core_1.Command {
             }
             else if (e.status === 404) {
                 this.failWithCliError({
-                    message: say(bodyMessage || 'Not found.'),
+                    // Give the by-id path the remedy the by-name path already carries.
+                    // The server answers a stale id with a bare `Space not found`, while
+                    // a typo'd NAME gets a message naming `spaces list` and `--q`. A
+                    // pasted stale id is the MORE common mistake and got the worse
+                    // message, because a UUID short-circuits the resolver and the
+                    // failure only surfaces here as a 404.
+                    message: say(describeResourceNotFound(bodyMessage, this.config.bin, this.cliConfig?.baseURL) ||
+                        bodyMessage ||
+                        'Not found.'),
                     code: bodyCode || 'NOT_FOUND',
                     status: e.status,
                     exit: 4,
@@ -1222,6 +1241,64 @@ function describeHarnessUnavailable(body, bin = 'skrr') {
  *
  * Exported for tests.
  */
+/**
+ * A bare `<Thing> not found` from the server, given the remedy the by-name
+ * path already carries.
+ *
+ * `skrr spaces show <stale-uuid>` answered `Space not found` / NOT_FOUND and
+ * stopped there, while a typo'd NAME got a genuinely good error naming
+ * `spaces list` and `spaces list --q`. The by-id path is the MORE common
+ * mistake — a stale or mistyped id pasted from somewhere — and it got the
+ * worse message, because a UUID short-circuits the resolver and the failure
+ * only surfaces later as a server 404.
+ *
+ * Same shape and same remedy as `describeAssigneeNotInSpace` above, whose own
+ * comment records the identical asymmetry for assignees (OSK-4864).
+ *
+ * Keyed on the server's exact sentence rather than the code, because
+ * `NOT_FOUND` is generic across resources and the sentence is what says which
+ * one. An unrecognised subject falls through unchanged — a wrong hint is worse
+ * than none.
+ */
+const NOT_FOUND_REMEDIES = {
+    'Space not found': 'spaces list',
+    'Task not found': 'tasks list',
+    'Goal not found': 'goals list',
+    'Agent not found': 'agents list',
+};
+/**
+ * Subjects whose ids are DEPLOYMENT-SCOPED, where "not found" most often means
+ * "not found HERE" rather than "does not exist".
+ *
+ * An agent id minted on one deployment cannot resolve on another, and the
+ * machine's own managed `CLAUDE.md` identity block prints agent ids without
+ * recording which deployment they belong to. So a machine whose CLI default
+ * moves between deployments keeps a platform-authored instruction telling its
+ * local coding agent to run `agent message send --agent <id>` with ids that
+ * cannot resolve — and the failure lands on the one sanctioned agent-to-user
+ * path, where it reads as "the agent silently stopped being able to reach its
+ * owner".
+ *
+ * Naming the server turns that into a diagnosable error. It does not FIX the
+ * stale block — the block should record its own deployment, which is a
+ * server-side change — but it stops the symptom being mute.
+ */
+const DEPLOYMENT_SCOPED_SUBJECTS = new Set(['Agent not found']);
+function describeResourceNotFound(serverMessage, bin = 'skrr', baseURL) {
+    const base = serverMessage?.trim();
+    if (!base)
+        return null;
+    const listCommand = NOT_FOUND_REMEDIES[base];
+    if (!listCommand)
+        return null;
+    const where = DEPLOYMENT_SCOPED_SUBJECTS.has(base) && baseURL ? ` on ${baseURL}` : '';
+    const scoped = DEPLOYMENT_SCOPED_SUBJECTS.has(base)
+        ? `\n  → ids are per-deployment, so one from another server (or from a stale managed ` +
+            `\`CLAUDE.md\` identity block) will not resolve here. \`${bin} context\` names this server.`
+        : '';
+    return (`${base}${where}\n  → list what you can see with \`${bin} ${listCommand}\`, ` +
+        `or search with \`${bin} ${listCommand} --q "<text>"\`.${scoped}`);
+}
 function describeAssigneeNotInSpace(serverMessage, bin = 'skrr') {
     const base = serverMessage?.trim() || 'That assignee is not a member of this space.';
     if (base.includes(`${bin} spaces members add`))

package/dist/commands/browser/skill/show.js

@@ -5,7 +5,13 @@ const browser_1 = require("../../browser");
 class BrowserSkillShow extends core_1.Command {
     static description = 'Print the version-matched skrr Browser agent skill';
     static args = {
-        name: core_1.Args.string({ description: 'Skill name (core)' }),
+        // `ignoreStdin` or oclif fills this positional from STDIN whenever stdin is
+        // not a TTY — so `echo x | skrr browser skill show` took the piped bytes as
+        // the skill name and failed with "Unknown skrr Browser skill: x", while the
+        // identical command with stdin closed printed the skill. `skrr commands
+        // --audit` names this rule (ARG_IMPLICIT_STDIN_ENABLED) and this was its
+        // only error.
+        name: core_1.Args.string({ description: 'Skill name (core)', ignoreStdin: true }),
     };
     async run() {
         const { args } = await this.parse(BrowserSkillShow);

package/dist/commands/code/index.d.ts

@@ -11,6 +11,7 @@ import { Command } from '@oclif/core';
  * that parses successfully and is then silently dropped.
  */
 export default class Code extends Command {
+    static summary: string;
     static description: string;
     static strict: boolean;
     static examples: string[];

package/dist/commands/code/index.js

@@ -17,7 +17,15 @@ const sky_code_managed_1 = require("../../lib/sky-code-managed");
  * that parses successfully and is then silently dropped.
  */
 class Code extends core_1.Command {
-    static description = 'Start the skrr Code interactive coding agent in this directory. Everything after ' +
+    // oclif renders `summary` in a command listing and `description` only in the
+    // command's own help. Without one, the forwarding note below — which has to
+    // be long, because it is explaining an absent FLAGS section — was printed in
+    // full inside `skrr --help`, twice (under TOPICS and again under COMMANDS),
+    // turning the top-level index into prose. Same trade the `skrr daemon`
+    // pass-throughs make: the note reaches whoever asks about this command, and
+    // nobody else.
+    static summary = 'Start the skrr Code interactive coding agent in this directory';
+    static description = 'Everything after ' +
         `\`code\` is forwarded to the engine unchanged, so engine flags are not listed here — ` +
         `run \`skrr code run --help\` for this wrapper, or the engine's own help for its ` +
         `flags. ${sky_code_managed_1.SKRR_AGENT_FLAG} is the one flag this wrapper consumes itself.`;

package/dist/commands/commitments/analytics/index.js

@@ -26,7 +26,9 @@ const REPORT_RUNNERS = {
         decision,
     }),
     distribution: ({ days, workspace }) => commitment_analytics_1.commitmentAnalyticsApi.distribution({ days, workspaceId: workspace }),
+    'distribution-tripwire': ({ limit, workspace }) => commitment_analytics_1.commitmentAnalyticsApi.distributionTripwire({ limit, workspaceId: workspace }),
     'attention-budget': ({ days, limit }) => commitment_analytics_1.commitmentAnalyticsApi.attentionBudget({ days, limit }),
+    'decision-inbox': () => commitment_analytics_1.commitmentAnalyticsApi.decisionInbox(),
     'action-adapters-audit': () => commitment_analytics_1.commitmentAnalyticsApi.actionAdapterAudit(),
     'recovery-metrics': ({ limit }) => commitment_analytics_1.commitmentAnalyticsApi.recoveryMetrics({ limit }),
     recovery: ({ limit }) => commitment_analytics_1.commitmentAnalyticsApi.recovery({ limit }),

package/dist/commands/daemon/byok.d.ts

@@ -6,6 +6,7 @@ import { Command } from '@oclif/core';
  */
 export default class DaemonByok extends Command {
     static aliases: string[];
+    static summary: string;
     static description: string;
     static strict: boolean;
     static examples: string[];

package/dist/commands/daemon/byok.js

@@ -12,7 +12,8 @@ class DaemonByok extends core_1.Command {
     // whole topic, and without a per-command alias only the bare topic
     // resolved: every subcommand under it failed.
     static aliases = ['daemons:byok'];
-    static description = 'Manage local BYOK provider credentials in the daemon profile Keychain';
+    static summary = 'Manage local BYOK provider credentials in the daemon profile Keychain';
+    static description = (0, exec_oversky_1.forwardedFlagsNote)('byok');
     static strict = false;
     static examples = [
         '<%= config.bin %> daemon byok status',

package/dist/commands/daemon/install.d.ts

@@ -13,6 +13,7 @@ import { Command } from '@oclif/core';
  */
 export default class DaemonInstall extends Command {
     static aliases: string[];
+    static summary: string;
     static description: string;
     static strict: boolean;
     run(): Promise<void>;

package/dist/commands/daemon/install.js

@@ -20,7 +20,8 @@ class DaemonInstall extends core_1.Command {
     // whole topic, and without a per-command alias only the bare topic
     // resolved: every subcommand under it failed.
     static aliases = ['daemons:install'];
-    static description = 'Install the local skrr runtime as a background service';
+    static summary = 'Install the local skrr runtime as a background service';
+    static description = (0, exec_oversky_1.forwardedFlagsNote)('install', { binds: true });
     static strict = false; // forward all args verbatim — see run()
     async run() {
         // `this.argv`, NOT `this.parse()`. `strict = false` relaxes POSITIONAL

package/dist/commands/daemon/login.d.ts

@@ -0,0 +1,31 @@
+import { Command } from '@oclif/core';
+/**
+ * `skrr daemon login` — authenticate the local runtime.
+ *
+ * Exists because the CLI and the daemon deliberately keep SEPARATE credentials
+ * (distinct keychain namespaces, distinct refresh families, independent
+ * revocation), and nothing made that legible. `skrr login` mints a cli-scope
+ * credential; the daemon reads a daemon-scope one. So the daemon would refuse to
+ * start, print `AUTH_BINDING_MISMATCH`, and the operator would run `skrr login`,
+ * complete a full browser flow, and get the identical error back — because the
+ * only command that could clear it lived on a second binary they had no reason to
+ * know existed (OSK-303).
+ *
+ * This does not merge the two credentials, and should not: daemon scope is
+ * deliberately LOWER-privileged than cli scope (`requireHumanScope` refuses it
+ * from billing, account management, password change and deletion), and separate
+ * revocation means losing a machine is not losing your session. What it removes
+ * is the user having to PERFORM that separation.
+ *
+ * `--env` / `--server` default to the deployment the CLI is on, for the same
+ * reason `install` does: a daemon authenticated against a different deployment
+ * than its CLI is the split OSK-279 exists to prevent, and picking it up from the
+ * session is how one command stops producing two answers.
+ */
+export default class DaemonLogin extends Command {
+    static aliases: string[];
+    static summary: string;
+    static description: string;
+    static strict: boolean;
+    run(): Promise<void>;
+}

package/dist/commands/daemon/login.js

@@ -0,0 +1,56 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const core_1 = require("@oclif/core");
+const daemon_binding_1 = require("../../lib/daemon-binding");
+const exec_oversky_1 = require("../../lib/exec-oversky");
+/**
+ * `skrr daemon login` — authenticate the local runtime.
+ *
+ * Exists because the CLI and the daemon deliberately keep SEPARATE credentials
+ * (distinct keychain namespaces, distinct refresh families, independent
+ * revocation), and nothing made that legible. `skrr login` mints a cli-scope
+ * credential; the daemon reads a daemon-scope one. So the daemon would refuse to
+ * start, print `AUTH_BINDING_MISMATCH`, and the operator would run `skrr login`,
+ * complete a full browser flow, and get the identical error back — because the
+ * only command that could clear it lived on a second binary they had no reason to
+ * know existed (OSK-303).
+ *
+ * This does not merge the two credentials, and should not: daemon scope is
+ * deliberately LOWER-privileged than cli scope (`requireHumanScope` refuses it
+ * from billing, account management, password change and deletion), and separate
+ * revocation means losing a machine is not losing your session. What it removes
+ * is the user having to PERFORM that separation.
+ *
+ * `--env` / `--server` default to the deployment the CLI is on, for the same
+ * reason `install` does: a daemon authenticated against a different deployment
+ * than its CLI is the split OSK-279 exists to prevent, and picking it up from the
+ * session is how one command stops producing two answers.
+ */
+class DaemonLogin extends core_1.Command {
+    static aliases = ['daemons:login'];
+    static summary = 'Authenticate the local skrr runtime (separate from `skrr login`)';
+    static description = (0, exec_oversky_1.forwardedFlagsNote)('login', { binds: true });
+    static strict = false; // forward all args verbatim — see run()
+    async run() {
+        // `this.argv`, NOT `this.parse()` — `strict = false` relaxes POSITIONAL
+        // arity and oclif still rejects any flag this command has not declared
+        // (OSK-296).
+        const argv = this.argv;
+        try {
+            // `--cwd` is deliberately NOT defaulted here. `skrrd login` resolves it
+            // from the installed service definition, which is the only authoritative
+            // answer; guessing it from the CLI's cwd is exactly the mistake that made
+            // the old default wrong.
+            const code = await (0, exec_oversky_1.execOversky)(['login', ...(0, daemon_binding_1.bindToCliSession)(argv)]);
+            this.exit(code);
+        }
+        catch (err) {
+            if (err.message === 'oversky-not-installed') {
+                this.log((0, exec_oversky_1.notInstalledMessage)());
+                this.exit(127);
+            }
+            throw err;
+        }
+    }
+}
+exports.default = DaemonLogin;

package/dist/commands/daemon/restart.d.ts

@@ -0,0 +1,9 @@
+import { Command } from '@oclif/core';
+export default class DaemonRestart extends Command {
+    static aliases: string[];
+    static summary: string;
+    static description: string;
+    static strict: boolean;
+    static examples: string[];
+    run(): Promise<void>;
+}

package/dist/commands/daemon/restart.js

@@ -0,0 +1,36 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const core_1 = require("@oclif/core");
+const exec_oversky_1 = require("../../lib/exec-oversky");
+class DaemonRestart 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:restart'];
+    static summary = 'Restart the local skrr daemon, preserving its current supervision mode';
+    static description = (0, exec_oversky_1.forwardedFlagsNote)('restart');
+    static strict = false; // forward all args verbatim — see run()
+    static examples = [
+        '<%= config.bin %> daemon restart',
+        '<%= config.bin %> daemon restart --profile work',
+    ];
+    async run() {
+        // `this.argv`, NOT `this.parse()`. `strict = false` relaxes POSITIONAL
+        // arity and oclif still rejects any flag this command has not declared —
+        // so every `skrrd` flag would be unreachable through the wrapper that
+        // exists to reach it (OSK-296).
+        const argv = this.argv;
+        try {
+            const code = await (0, exec_oversky_1.execOversky)(['restart', ...argv]);
+            this.exit(code);
+        }
+        catch (err) {
+            if (err.message === 'oversky-not-installed') {
+                this.log((0, exec_oversky_1.notInstalledMessage)());
+                this.exit(127);
+            }
+            throw err;
+        }
+    }
+}
+exports.default = DaemonRestart;

package/dist/commands/daemon/start.d.ts

@@ -1,6 +1,7 @@
 import { Command } from '@oclif/core';
 export default class DaemonStart extends Command {
     static aliases: string[];
+    static summary: string;
     static description: string;
     static strict: boolean;
     run(): Promise<void>;

package/dist/commands/daemon/start.js

@@ -7,7 +7,8 @@ class DaemonStart extends core_1.Command {
     // whole topic, and without a per-command alias only the bare topic
     // resolved: every subcommand under it failed.
     static aliases = ['daemons:start'];
-    static description = 'Start the local skrr daemon';
+    static summary = 'Start the local skrr daemon';
+    static description = (0, exec_oversky_1.forwardedFlagsNote)('start');
     static strict = false; // forward all args verbatim — see run()
     async run() {
         // `this.argv`, NOT `this.parse()`. `strict = false` relaxes POSITIONAL

package/dist/commands/daemon/status.d.ts

@@ -1,6 +1,7 @@
 import { Command } from '@oclif/core';
 export default class DaemonStatus extends Command {
     static aliases: string[];
+    static summary: string;
     static description: string;
     static strict: boolean;
     run(): Promise<void>;

package/dist/commands/daemon/status.js

@@ -7,7 +7,8 @@ class DaemonStatus extends core_1.Command {
     // whole topic, and without a per-command alias only the bare topic
     // resolved: every subcommand under it failed.
     static aliases = ['daemons:status'];
-    static description = 'Show skrr daemon status (config, connection, services)';
+    static summary = 'Show skrr daemon status (config, connection, services)';
+    static description = (0, exec_oversky_1.forwardedFlagsNote)('status');
     static strict = false;
     async run() {
         // `this.argv`, NOT `this.parse()`. `strict = false` relaxes POSITIONAL

package/dist/commands/daemon/stop.d.ts

@@ -1,6 +1,7 @@
 import { Command } from '@oclif/core';
 export default class DaemonStop extends Command {
     static aliases: string[];
+    static summary: string;
     static description: string;
     static strict: boolean;
     run(): Promise<void>;

package/dist/commands/daemon/stop.js

@@ -7,7 +7,8 @@ class DaemonStop extends core_1.Command {
     // whole topic, and without a per-command alias only the bare topic
     // resolved: every subcommand under it failed.
     static aliases = ['daemons:stop'];
-    static description = 'Stop the local skrr daemon';
+    static summary = 'Stop the local skrr daemon';
+    static description = (0, exec_oversky_1.forwardedFlagsNote)('stop');
     static strict = false;
     async run() {
         // `this.argv`, NOT `this.parse()`. `strict = false` relaxes POSITIONAL

package/dist/commands/daemon/uninstall.d.ts

@@ -13,6 +13,7 @@ import { Command } from '@oclif/core';
  */
 export default class DaemonUninstall extends Command {
     static aliases: string[];
+    static summary: string;
     static description: string;
     static strict: boolean;
     run(): Promise<void>;

package/dist/commands/daemon/uninstall.js

@@ -19,7 +19,8 @@ class DaemonUninstall extends core_1.Command {
     // whole topic, and without a per-command alias only the bare topic
     // resolved: every subcommand under it failed.
     static aliases = ['daemons:uninstall'];
-    static description = "Remove the local skrr runtime's background service (local state is left alone)";
+    static summary = "Remove the local skrr runtime's background service (local state is left alone)";
+    static description = (0, exec_oversky_1.forwardedFlagsNote)('uninstall');
     static strict = false; // forward all args verbatim — see run()
     async run() {
         // `this.argv`, NOT `this.parse()`. `strict = false` relaxes POSITIONAL

package/dist/commands/daemon/unlock.d.ts

@@ -0,0 +1,9 @@
+import { Command } from '@oclif/core';
+export default class DaemonUnlock extends Command {
+    static aliases: string[];
+    static summary: string;
+    static description: string;
+    static strict: boolean;
+    static examples: string[];
+    run(): Promise<void>;
+}

package/dist/commands/daemon/unlock.js

@@ -0,0 +1,33 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const core_1 = require("@oclif/core");
+const exec_oversky_1 = require("../../lib/exec-oversky");
+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 strict = false; // forward all args verbatim — see run()
+    static examples = ['<%= config.bin %> daemon unlock'];
+    async run() {
+        // Recovery verbs are the ones that most need to be reachable from the
+        // wrapper: you go looking for `unlock` exactly when the daemon is wedged,
+        // which is the worst moment to discover the CLI cannot reach it and that
+        // 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]);
+            this.exit(code);
+        }
+        catch (err) {
+            if (err.message === 'oversky-not-installed') {
+                this.log((0, exec_oversky_1.notInstalledMessage)());
+                this.exit(127);
+            }
+            throw err;
+        }
+    }
+}
+exports.default = DaemonUnlock;

package/dist/commands/goals/key-results/create.js

@@ -28,7 +28,16 @@ class GoalsKeyResultsCreate extends base_command_1.BaseCommand {
         }),
         title: core_1.Flags.string({ description: 'Key result title (required unless set via --from-json)' }),
         description: core_1.Flags.string({ description: 'Key result description' }),
-        progress: core_1.Flags.integer({ description: 'Progress 0–100 (used in manual mode)' }),
+        // The bound is declared, not just described. `--progress 150` and
+        // `--progress -5` both came back as a bare `Invalid request data /
+        // HTTP_400` from the server — byte-identical for two different mistakes,
+        // in a CLI that gives excellent field-level errors for enums. oclif
+        // refuses an out-of-range value naming the range, before the round trip.
+        progress: core_1.Flags.integer({
+            description: 'Progress 0–100 (used in manual mode)',
+            min: 0,
+            max: 100,
+        }),
         'progress-mode': core_1.Flags.string({
             description: 'How progress is tracked',
             options: [...data_provider_1.KEY_RESULT_PROGRESS_MODES],
@@ -78,6 +87,28 @@ class GoalsKeyResultsCreate extends base_command_1.BaseCommand {
         }
         const k = created;
         this.log(`Created key result ${k.id ?? '?'} on goal ${args.goalId} - ${k.title ?? '(no title)'}`);
+        if (k.progressMode === 'auto')
+            this.warn(AUTO_MODE_NOTE);
     }
 }
 exports.default = GoalsKeyResultsCreate;
+/**
+ * Why an `auto` key result reads as `-` from the CLI.
+ *
+ * Auto progress is computed from tasks linked to THIS key result
+ * (`Task.keyResultIds`), and the task↔key-result link is a DOCUMENTED
+ * omission from the CLI surface — it sits in `domain-api-parity.spec.ts`'s
+ * allowlist with a stated reason. So `--progress-mode auto` is offered by a
+ * surface that cannot make it move, and `resolveKeyResultProgress` renders
+ * `_computedProgress ?? null` for auto, i.e. `-`, while a `--progress` value
+ * you set is stored and returned by `update`.
+ *
+ * The result was one CLI reporting two different values for one field: the
+ * write echoed 40 and the list showed `-`. Saying so at the point of use is
+ * the honest fix; silently rendering the stored number instead would hide a
+ * real distinction (a manual value is not a computed one), and adding the
+ * link command would reverse a recorded decision.
+ */
+const AUTO_MODE_NOTE = 'Auto progress is computed from tasks linked to this key result, and linking a task to a key ' +
+    'result is deliberately not in the CLI — so this reads as "-" here until it is linked ' +
+    'elsewhere. Use --progress-mode manual to track a number from the CLI.';

package/dist/commands/goals/key-results/update.d.ts

@@ -25,3 +25,14 @@ export default class GoalsKeyResultsUpdate extends BaseCommand {
     };
     run(): Promise<void>;
 }
+/**
+ * The sentence to print when `done` and a sub-100 progress are made to
+ * disagree, or `null` when they do not. Exported for `update.spec.ts`.
+ *
+ * Returns a warning rather than reconciling the two: pulling progress to 100
+ * would be the CLI inventing a policy the server does not have, and it would
+ * destroy the recorded number on the way.
+ */
+export declare function describeDoneDisagreement(status: string | undefined, progress: number | null): string | null;
+/** How the server now holds one patched field, for the confirmation line. */
+export declare function describeField(kr: Record<string, unknown>, field: string): string;