@skrr-ai/cli 0.1.10 → 0.1.11

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

@@ -1,5 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.describeDoneDisagreement = describeDoneDisagreement;
+exports.describeField = describeField;
 const core_1 = require("@oclif/core");
 const data_provider_1 = require("@skrr-ai/data-provider");
 const base_command_1 = require("../../../base-command");
@@ -35,7 +37,16 @@ class GoalsKeyResultsUpdate extends base_command_1.BaseCommand {
             description: 'Clear the description (sends null)',
             exclusive: ['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],
@@ -86,7 +97,74 @@ class GoalsKeyResultsUpdate extends base_command_1.BaseCommand {
             return;
         }
         const k = updated;
-        this.log(`Updated key result ${k.id ?? args.krId} on goal ${args.goalId}`);
+        // `Updated key result <uuid> on goal <uuid>` echoed two ids the caller had
+        // just typed and said nothing about what changed — so a status-only update
+        // never confirmed that the value passed is the value that stuck, and the
+        // documented next move was to run it again "purely as insurance". Echo the
+        // patched fields as the SERVER now holds them, not as they were sent.
+        const echo = Object.keys(data)
+            .map((field) => `${field}=${describeField(k, field)}`)
+            .join(' ');
+        this.log(`Updated key result ${k.id ?? args.krId} on goal ${args.goalId}: ${echo}`);
+        // The write echoes the number back, so without this the caller has every
+        // reason to believe it took — and then `key-results list` shows `-`.
+        if (k.progressMode === 'auto' && flags.progress !== undefined) {
+            this.warn(`The value is stored. ${AUTO_MODE_NOTE}`);
+        }
+        // `done` beside `25%` on one row, with nothing reconciling them. The two
+        // ARE independent axes — a key result can be closed out incomplete, and
+        // pulling progress to 100 here would be the CLI inventing a policy the
+        // server does not have, destroying the recorded number in the process. So
+        // say which one is which instead, at the moment they are made to disagree,
+        // rather than leaving it to be discovered from a list days later.
+        const progress = (0, data_provider_1.resolveKeyResultProgress)(k);
+        const disagreement = describeDoneDisagreement(flags.status, progress);
+        if (disagreement)
+            this.warn(disagreement);
     }
 }
 exports.default = GoalsKeyResultsUpdate;
+/**
+ * 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.
+ */
+function describeDoneDisagreement(status, progress) {
+    if (status !== 'done' || typeof progress !== 'number' || progress >= 100)
+        return null;
+    return (`Status is 'done' but progress is ${progress}%. They are independent: status is the verdict, ` +
+        `progress is the measure, and a key result may legitimately be closed out incomplete. ` +
+        `If you meant it to read as finished, also pass --progress 100.`);
+}
+/** How the server now holds one patched field, for the confirmation line. */
+function describeField(kr, field) {
+    const value = kr[field];
+    if (value === null)
+        return 'cleared';
+    if (value === undefined)
+        return '(not returned)';
+    return typeof value === 'string' ? value : JSON.stringify(value);
+}
+/**
+ * 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/plan-now.d.ts

@@ -1,4 +1,50 @@
+import type { GoalPlanNowResponse } from '@skrr-ai/data-provider';
 import { BaseCommand } from '../../base-command';
+/**
+ * Turn the planner's internal `reason` enum into a sentence.
+ *
+ * These strings are produced by `GoalPlanner` and are not declared anywhere in
+ * `@skrr-ai/data-provider`, so this is a rendering table and deliberately NOT a
+ * second vocabulary: an unrecognised reason is returned verbatim rather than
+ * hidden, which is what keeps a new server reason visible instead of silently
+ * dropping to "the planner did something".
+ *
+ * Dogfooded: `plan-now` printed a bare `note: lock_held`, which reads as "the
+ * planner ran and found nothing", when in fact the planner never started.
+ */
+export declare function describePlannerReason(reason: string | null | undefined): string | null;
+/**
+ * Did the tick fail to run? `processed` is the server's own answer, and it is
+ * the field the old renderer ignored while printing three zeros and exiting 0.
+ *
+ * Only an EXPLICIT `false` counts, on either field. An absent `processed` is
+ * treated as "it ran", so a CLI pointed at a server that predates the field
+ * keeps working — the old renderer made the same assumption, just without
+ * saying so.
+ */
+export declare function plannerTickDidNotRun(result: GoalPlanNowResponse | undefined): boolean;
+/** Did the REQUEST give up, as opposed to the tick failing? */
+export declare function isPlannerRequestTimeout(err: unknown): boolean;
+/**
+ * What a gateway timeout on a planner tick actually licenses us to say.
+ *
+ * The shared error path maps every 502/503/504 to "this is a service outage …
+ * Nothing was changed", and for a planner tick both halves were wrong when
+ * dogfooded: the very next command against the same host answered instantly,
+ * and a retry two seconds later came back `lock_held` — proof the first request
+ * had been accepted and was still running. "Nothing was changed" is the
+ * dangerous half, because it invites a retry of a non-idempotent, task-creating,
+ * billable operation.
+ *
+ * A 504 is a gateway giving up. It carries no information about whether the
+ * origin finished the work, so this says exactly that and names the commands
+ * that CAN answer it.
+ */
+export declare function plannerTimeoutMessage(opts: {
+    goalId: string;
+    status: number;
+    bin: string;
+}): string;
 /**
  * `skrr goals plan-now <goal-id>` — run a single planner tick immediately,
  * independent of the configured cadence (or even when no cadence is set). The
@@ -8,8 +54,12 @@ import { BaseCommand } from '../../base-command';
  * response reports what the tick did: tasks created, existing tasks refined, and
  * how many created tasks were also scheduled for auto-execution (only when the
  * goal's `autoExecute` is on and an assignee resolves). `--space` scopes the
- * created tasks to a Mission Space and backfills spaceId on the goal's existing
- * tasks.
+ * created tasks to a space and backfills spaceId on the goal's existing tasks.
+ *
+ * The route answers HTTP 200 with `processed: false` when the tick was SKIPPED
+ * (a lock held by a running tick, a cadence that is not due, an archived goal).
+ * That is not a success, so this command does not report it as one — see the
+ * `processed` branch in `run()`.
  */
 export default class GoalsPlanNow extends BaseCommand {
     static description: string;
@@ -22,4 +72,6 @@ export default class GoalsPlanNow extends BaseCommand {
         space: import("@oclif/core/lib/interfaces").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
     };
     run(): Promise<void>;
+    /** A gateway timeout on THIS request, reported as what it is. */
+    private failIfRequestTimedOut;
 }

package/dist/commands/goals/plan-now.js

@@ -1,8 +1,119 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.describePlannerReason = describePlannerReason;
+exports.plannerTickDidNotRun = plannerTickDidNotRun;
+exports.isPlannerRequestTimeout = isPlannerRequestTimeout;
+exports.plannerTimeoutMessage = plannerTimeoutMessage;
 const core_1 = require("@oclif/core");
 const data_provider_1 = require("@skrr-ai/data-provider");
 const base_command_1 = require("../../base-command");
+/**
+ * Statuses that mean "this REQUEST gave up", not "the work failed".
+ *
+ * Same set `agents plan-day` uses, and for the same reason: a planner tick is a
+ * live agent turn that routinely outlives the edge's request budget, so the
+ * gateway answers while the server keeps running. A 4xx means the tick never
+ * started and a 500 means the route itself threw — neither is a timeout, and
+ * both are reported by the shared error path.
+ */
+const TIMEOUT_STATUSES = new Set([408, 504, 524]);
+/**
+ * Reasons whose no-op is CONTENTION or timing — the same call can be expected
+ * to run later. Everything else (`goal_archived`, `goal_planner_disabled`, …)
+ * needs the user to change something first, so a script retrying it would spin.
+ */
+const TRANSIENT_SKIP_REASONS = new Set(['lock_held', 'not_due', 'schedule_superseded']);
+/**
+ * Turn the planner's internal `reason` enum into a sentence.
+ *
+ * These strings are produced by `GoalPlanner` and are not declared anywhere in
+ * `@skrr-ai/data-provider`, so this is a rendering table and deliberately NOT a
+ * second vocabulary: an unrecognised reason is returned verbatim rather than
+ * hidden, which is what keeps a new server reason visible instead of silently
+ * dropping to "the planner did something".
+ *
+ * Dogfooded: `plan-now` printed a bare `note: lock_held`, which reads as "the
+ * planner ran and found nothing", when in fact the planner never started.
+ */
+function describePlannerReason(reason) {
+    if (!reason)
+        return null;
+    switch (reason) {
+        case 'lock_held':
+            return 'a planner tick for this goal is already running, so this one did not start';
+        case 'not_due':
+            return "the goal's next tick is not due yet";
+        case 'schedule_superseded':
+            return "the goal's cadence changed after this tick was scheduled, so it was dropped";
+        case 'goal_deleted':
+            return 'the goal no longer exists';
+        case 'goal_archived':
+            return 'the goal is archived';
+        case 'goal_planner_disabled':
+            return "the goal's auto-planner has no cadence set";
+        case 'missing_goal_id':
+            return 'the request carried no goal id';
+        case 'at_capacity':
+            return 'the goal is already at its maxActiveTasks cap, so no new tasks were created';
+        case 'at_capacity_refined':
+            return 'the goal is at its maxActiveTasks cap, so existing tasks were refined instead of new ones created';
+        case 'coordinator_suppressed':
+            return 'another proactive surface had just raised this goal, so no new tasks were created';
+        case 'all_creates_failed':
+            return 'the planner proposed tasks but none of them could be created';
+        case 'no_changes':
+            return 'the planner ran and found nothing to add or refine';
+        case 'one_voice_busy':
+            return 'another agent was already speaking for this owner, so the tick stayed quiet';
+        default:
+            // `one_voice_<something>` is a family the server composes at run time.
+            if (reason.startsWith('one_voice_')) {
+                return `the one-voice coordinator suppressed this tick (${reason.slice('one_voice_'.length)})`;
+            }
+            return reason;
+    }
+}
+/**
+ * Did the tick fail to run? `processed` is the server's own answer, and it is
+ * the field the old renderer ignored while printing three zeros and exiting 0.
+ *
+ * Only an EXPLICIT `false` counts, on either field. An absent `processed` is
+ * treated as "it ran", so a CLI pointed at a server that predates the field
+ * keeps working — the old renderer made the same assumption, just without
+ * saying so.
+ */
+function plannerTickDidNotRun(result) {
+    return result?.ok === false || result?.processed === false;
+}
+/** Did the REQUEST give up, as opposed to the tick failing? */
+function isPlannerRequestTimeout(err) {
+    const status = err?.status;
+    return typeof status === 'number' && TIMEOUT_STATUSES.has(status);
+}
+/**
+ * What a gateway timeout on a planner tick actually licenses us to say.
+ *
+ * The shared error path maps every 502/503/504 to "this is a service outage …
+ * Nothing was changed", and for a planner tick both halves were wrong when
+ * dogfooded: the very next command against the same host answered instantly,
+ * and a retry two seconds later came back `lock_held` — proof the first request
+ * had been accepted and was still running. "Nothing was changed" is the
+ * dangerous half, because it invites a retry of a non-idempotent, task-creating,
+ * billable operation.
+ *
+ * A 504 is a gateway giving up. It carries no information about whether the
+ * origin finished the work, so this says exactly that and names the commands
+ * that CAN answer it.
+ */
+function plannerTimeoutMessage(opts) {
+    const { goalId, status, bin } = opts;
+    return (`The planner tick for goal ${goalId} outlived this request (HTTP ${status}). ` +
+        'That is the gateway giving up, not a verdict on the tick: the run may still be ' +
+        'executing and may still create tasks. Nothing here observed whether it finished. ' +
+        `Check with \`${bin} goals plan-now ${goalId}\` — a "lock_held" answer means it is still ` +
+        `running — or \`${bin} goals tasks ${goalId}\` to see what it produced. ` +
+        'Do not retry blindly: a second tick is a second billable agent run.');
+}
 /**
  * `skrr goals plan-now <goal-id>` — run a single planner tick immediately,
  * independent of the configured cadence (or even when no cadence is set). The
@@ -12,11 +123,15 @@ const base_command_1 = require("../../base-command");
  * response reports what the tick did: tasks created, existing tasks refined, and
  * how many created tasks were also scheduled for auto-execution (only when the
  * goal's `autoExecute` is on and an assignee resolves). `--space` scopes the
- * created tasks to a Mission Space and backfills spaceId on the goal's existing
- * tasks.
+ * created tasks to a space and backfills spaceId on the goal's existing tasks.
+ *
+ * The route answers HTTP 200 with `processed: false` when the tick was SKIPPED
+ * (a lock held by a running tick, a cadence that is not due, an archived goal).
+ * That is not a success, so this command does not report it as one — see the
+ * `processed` branch in `run()`.
  */
 class GoalsPlanNow extends base_command_1.BaseCommand {
-    static description = 'Run one auto-planner tick for a goal right now';
+    static description = 'Run one auto-planner tick for a goal right now (a live agent turn that creates and refines tasks)';
     static examples = [
         '<%= config.bin %> goals plan-now <goal-id>',
         '<%= config.bin %> goals plan-now <goal-id> --space <space-id>',
@@ -28,41 +143,83 @@ class GoalsPlanNow extends base_command_1.BaseCommand {
     static flags = {
         json: core_1.Flags.boolean({ description: 'Output the planner result as JSON' }),
         space: core_1.Flags.string({
-            description: 'Scope created tasks to this Mission Space (backfills spaceId on existing tasks)',
+            description: "Scope created tasks to this space (also backfills spaceId on the goal's existing tasks)",
         }),
     };
     async run() {
         this.requireAuth();
         const { args, flags } = await this.parse(GoalsPlanNow);
+        // A tick is an LLM run; minutes of silence is normal and used to be
+        // indistinguishable from a hung command. stderr, so `--json` stdout stays a
+        // single parseable document.
+        this.logToStderr(`Running one planner tick for goal ${args.id}. This is a live agent turn and can take minutes.`);
         let result;
         try {
             result = await data_provider_1.dataService.planGoalNow(args.id, flags.space ? { spaceId: flags.space } : {});
         }
         catch (err) {
+            this.failIfRequestTimedOut(err, args.id);
             this.handleApiError(err);
         }
-        if (flags.json) {
-            this.log(JSON.stringify(result, null, 2));
-            return;
-        }
         const r = result;
-        if (!r?.ok) {
-            this.log(`Planner did not run${r?.reason ? `: ${r.reason}` : '.'}`);
+        const reasonText = describePlannerReason(r?.reason);
+        if (plannerTickDidNotRun(r)) {
+            // The backfill runs BEFORE planning and unconditionally, so a skipped
+            // tick can still have moved rows. Saying "nothing happened" would be the
+            // same class of lie this whole command is being fixed for.
+            const backfilled = r?.backfilledCount
+                ? ` ${r.backfilledCount} existing task(s) were still backfilled to the given space.`
+                : '';
+            const transient = TRANSIENT_SKIP_REASONS.has(r?.reason ?? '');
+            const retry = transient
+                ? ` Re-run \`${this.config.bin} goals plan-now ${args.id}\` to try again.`
+                : '';
+            this.failWithCliError({
+                message: `The planner did not run for goal ${args.id}` +
+                    (reasonText ? `: ${reasonText}.` : '.') +
+                    backfilled +
+                    retry,
+                code: 'PLANNER_TICK_NOT_RUN',
+                exit: 1,
+                retryable: transient,
+                details: r,
+            });
+        }
+        if (flags.json) {
+            this.log(JSON.stringify(r, null, 2));
             return;
         }
         this.log(`Planner tick for goal ${args.id}:`);
-        this.log(`  created:     ${r.createdCount ?? 0}`);
-        this.log(`  refined:     ${r.refinedCount ?? 0}`);
-        this.log(`  scheduled:   ${r.scheduledCount ?? 0}`);
-        if (r.backfilledCount) {
-            this.log(`  backfilled:  ${r.backfilledCount}`);
+        this.log(`  created:     ${r?.createdCount ?? 0}`);
+        this.log(`  refined:     ${r?.refinedCount ?? 0}`);
+        this.log(`  scheduled:   ${r?.scheduledCount ?? 0}`);
+        if (flags.space || r?.backfilledCount) {
+            this.log(`  backfilled:  ${r?.backfilledCount ?? 0}`);
         }
-        if (r.resolvedSpaceId) {
+        if (r?.resolvedSpaceId) {
             this.log(`  space:       ${r.resolvedSpaceId}`);
         }
-        if (r.reason) {
-            this.log(`  note:        ${r.reason}`);
+        if (reasonText) {
+            // The raw enum stays in parentheses: it is what the server logs and what
+            // an existing script may already grep for.
+            this.log(`  note:        ${reasonText} (${r?.reason}).`);
         }
     }
+    /** A gateway timeout on THIS request, reported as what it is. */
+    failIfRequestTimedOut(err, goalId) {
+        if (!isPlannerRequestTimeout(err))
+            return;
+        const status = err.status;
+        this.failWithCliError({
+            message: plannerTimeoutMessage({ goalId, status, bin: this.config.bin }),
+            code: 'PLANNER_TICK_TIMED_OUT',
+            status,
+            exit: 5,
+            // Deliberately false. The request may be repeated by a HUMAN who has
+            // checked, but `plan-now` is not idempotent, so a script must not treat
+            // this as "safe to send again".
+            retryable: false,
+        });
+    }
 }
 exports.default = GoalsPlanNow;

package/dist/commands/goals/planner-config.d.ts

@@ -1,16 +1,67 @@
 import { BaseCommand } from '../../base-command';
 /**
- * `skrr goals planner-config <goal-id>` — configure (or disable) the goal's
- * auto-planner: the scheduled tick that runs a planner agent to create and
- * refine tasks toward the goal.
+ * The goal's auto-planner state, as the CLI is willing to state it.
+ *
+ * Two fields are DERIVED rather than passed through, and both exist because the
+ * stored document can disagree with itself:
+ *
+ *   - `enabled` reads `tickIntervalMs`, the one field the server's own disable
+ *     path clears (`$unset tickIntervalMs` + `$unset nextTickAt`). It is the
+ *     single source of "is this armed".
+ *   - `nextTickAt` is forced to null whenever the planner is off. The stored
+ *     timestamp can SURVIVE a disable: `GoalPlanner.planForGoal` writes
+ *     `nextTickAt` unconditionally at claim time and again at completion, so a
+ *     tick that was already in flight when `--disable` ran re-creates the field
+ *     afterwards. Dogfooded — `goals show --json` reported a `nextTickAt` in the
+ *     past on a disabled planner while the plain view said `interval: disabled`,
+ *     i.e. the two renderings of one command disagreed about whether a tick was
+ *     scheduled. A disabled planner has no next tick; saying so is the only
+ *     reading that is true from either side.
+ *
+ * The raw server fields are never rewritten — `goals show --json` still carries
+ * `tickIntervalMs` / `nextTickAt` verbatim, and this view sits beside them.
+ */
+export type GoalPlannerView = {
+    enabled: boolean;
+    tickIntervalMs: number | null;
+    maxActiveTasks: number | null;
+    autoExecute: boolean | null;
+    nextTickAt: string | null;
+    lastTickedAt: string | null;
+    /**
+     * `tickLockedAt` — set when a tick claims the goal, unset when it finishes or
+     * fails. A value here means a claimed tick has not released the lock: it is
+     * either still running or it crashed. We report the timestamp and decline to
+     * choose between those two, because the CLI cannot tell them apart.
+     */
+    tickLockedAt: string | null;
+};
+/** Read the planner state off a Goal document (lean or typed). */
+export declare function goalPlannerView(goal: Record<string, unknown> | undefined | null): GoalPlannerView;
+/**
+ * The plain-text planner block, shared by `planner-config` and `goals show` so
+ * the two commands cannot drift into describing the same state differently.
+ */
+export declare function renderGoalPlannerLines(view: GoalPlannerView): string[];
+/**
+ * `skrr goals planner-config <goal-id>` — read, configure, or disable the
+ * goal's auto-planner: the scheduled tick that runs a planner agent to create
+ * and refine tasks toward the goal.
+ *
+ * With no flags this READS the config. It used to refuse, which made the only
+ * way to answer "is the planner on for this goal?" a write — and for `--disable`
+ * that meant turning the automation off to find out it was on. A recurring,
+ * task-creating, optionally agent-starting automation must be readable without
+ * changing it.
  *
  * Wraps `PATCH /api/goals/:goalId/planner-config` (data-provider
- * `updateGoalPlannerConfig`). Setting a cadence enables the planner; `--disable`
- * (which sends `tickIntervalMs: null`) turns it off. The interval flags mirror
- * the trigger-create convention elsewhere in this CLI: `--interval-minutes` for
- * the ergonomic path, `--interval-ms` for the raw value. The server owns the
- * bounds (interval 60s–30d, maxActiveTasks 1–50) and rejects out-of-range
- * values, surfaced here via the standard error path.
+ * `updateGoalPlannerConfig`) for writes and `GET /api/goals/:goalId` for the
+ * read. Setting a cadence enables the planner; `--disable` (which sends
+ * `tickIntervalMs: null`) turns it off. The interval flags mirror the
+ * trigger-create convention elsewhere in this CLI: `--interval-minutes` for the
+ * ergonomic path, `--interval-ms` for the raw value. The server owns the bounds
+ * (interval 60s–30d, maxActiveTasks 1–50) and rejects out-of-range values,
+ * surfaced here via the standard error path.
  */
 export default class GoalsPlannerConfig extends BaseCommand {
     static description: string;

package/dist/commands/goals/planner-config.js

@@ -1,24 +1,78 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.goalPlannerView = goalPlannerView;
+exports.renderGoalPlannerLines = renderGoalPlannerLines;
 const core_1 = require("@oclif/core");
 const data_provider_1 = require("@skrr-ai/data-provider");
 const base_command_1 = require("../../base-command");
+function str(value) {
+    return typeof value === 'string' && value ? value : null;
+}
+/** Read the planner state off a Goal document (lean or typed). */
+function goalPlannerView(goal) {
+    const g = (goal ?? {});
+    const tickIntervalMs = typeof g.tickIntervalMs === 'number' ? g.tickIntervalMs : null;
+    const enabled = tickIntervalMs != null;
+    return {
+        enabled,
+        tickIntervalMs,
+        maxActiveTasks: typeof g.maxActiveTasks === 'number' ? g.maxActiveTasks : null,
+        autoExecute: typeof g.autoExecute === 'boolean' ? g.autoExecute : null,
+        nextTickAt: enabled ? str(g.nextTickAt) : null,
+        lastTickedAt: str(g.lastTickedAt),
+        tickLockedAt: str(g.tickLockedAt),
+    };
+}
 /**
- * `skrr goals planner-config <goal-id>` — configure (or disable) the goal's
- * auto-planner: the scheduled tick that runs a planner agent to create and
- * refine tasks toward the goal.
+ * The plain-text planner block, shared by `planner-config` and `goals show` so
+ * the two commands cannot drift into describing the same state differently.
+ */
+function renderGoalPlannerLines(view) {
+    const interval = view.enabled
+        ? `${Math.round(view.tickIntervalMs / 60_000)}m (${view.tickIntervalMs}ms)`
+        : 'disabled';
+    let autoExecute = '-';
+    if (view.autoExecute !== null) {
+        autoExecute = view.autoExecute ? 'on' : 'off';
+    }
+    const lines = [
+        `  interval:        ${interval}`,
+        `  maxActiveTasks:  ${view.maxActiveTasks ?? '-'}`,
+        `  autoExecute:     ${autoExecute}`,
+    ];
+    if (view.nextTickAt)
+        lines.push(`  nextTickAt:      ${view.nextTickAt}`);
+    if (view.lastTickedAt)
+        lines.push(`  lastTickedAt:    ${view.lastTickedAt}`);
+    if (view.tickLockedAt) {
+        lines.push(`  tickLockedAt:    ${view.tickLockedAt} (a claimed tick has not released this lock)`);
+    }
+    return lines;
+}
+/**
+ * `skrr goals planner-config <goal-id>` — read, configure, or disable the
+ * goal's auto-planner: the scheduled tick that runs a planner agent to create
+ * and refine tasks toward the goal.
+ *
+ * With no flags this READS the config. It used to refuse, which made the only
+ * way to answer "is the planner on for this goal?" a write — and for `--disable`
+ * that meant turning the automation off to find out it was on. A recurring,
+ * task-creating, optionally agent-starting automation must be readable without
+ * changing it.
  *
  * Wraps `PATCH /api/goals/:goalId/planner-config` (data-provider
- * `updateGoalPlannerConfig`). Setting a cadence enables the planner; `--disable`
- * (which sends `tickIntervalMs: null`) turns it off. The interval flags mirror
- * the trigger-create convention elsewhere in this CLI: `--interval-minutes` for
- * the ergonomic path, `--interval-ms` for the raw value. The server owns the
- * bounds (interval 60s–30d, maxActiveTasks 1–50) and rejects out-of-range
- * values, surfaced here via the standard error path.
+ * `updateGoalPlannerConfig`) for writes and `GET /api/goals/:goalId` for the
+ * read. Setting a cadence enables the planner; `--disable` (which sends
+ * `tickIntervalMs: null`) turns it off. The interval flags mirror the
+ * trigger-create convention elsewhere in this CLI: `--interval-minutes` for the
+ * ergonomic path, `--interval-ms` for the raw value. The server owns the bounds
+ * (interval 60s–30d, maxActiveTasks 1–50) and rejects out-of-range values,
+ * surfaced here via the standard error path.
  */
 class GoalsPlannerConfig extends base_command_1.BaseCommand {
-    static description = "Configure or disable a goal's auto-planner";
+    static description = "Read, configure, or disable a goal's auto-planner (a recurring agent tick that CREATES and refines tasks under the goal)";
     static examples = [
+        '<%= config.bin %> goals planner-config <goal-id>',
         '<%= config.bin %> goals planner-config <goal-id> --interval-minutes 60',
         '<%= config.bin %> goals planner-config <goal-id> --interval-minutes 60 --max-active-tasks 5 --auto-execute',
         '<%= config.bin %> goals planner-config <goal-id> --no-auto-execute',
@@ -28,24 +82,24 @@ class GoalsPlannerConfig extends base_command_1.BaseCommand {
         id: core_1.Args.string({ description: 'Goal ID', required: true, ignoreStdin: true }),
     };
     static flags = {
-        json: core_1.Flags.boolean({ description: 'Output the updated goal as JSON' }),
+        json: core_1.Flags.boolean({ description: 'Output the goal as JSON' }),
         'interval-minutes': core_1.Flags.integer({
-            description: 'Planner tick cadence in minutes (enables the planner)',
+            description: 'How often the planner runs, in minutes. Setting it arms the planner: each tick creates and refines tasks under this goal',
             exclusive: ['interval-ms', 'disable'],
         }),
         'interval-ms': core_1.Flags.integer({
-            description: 'Planner tick cadence in milliseconds (enables the planner)',
+            description: 'Same cadence in milliseconds (raw value; arms the planner)',
             exclusive: ['interval-minutes', 'disable'],
         }),
         disable: core_1.Flags.boolean({
-            description: 'Disable the auto-planner (clears the tick cadence)',
+            description: 'Disarm the auto-planner — clears the cadence so no further ticks run',
             exclusive: ['interval-minutes', 'interval-ms'],
         }),
         'max-active-tasks': core_1.Flags.integer({
-            description: 'Cap on concurrently-active planner tasks (server bounds: 1–50)',
+            description: 'Stop creating new tasks once this many are active under the goal (server bounds: 1–50)',
         }),
         'auto-execute': core_1.Flags.boolean({
-            description: 'Auto-schedule planner-created tasks that have an assignee (use --no-auto-execute to turn off)',
+            description: 'Also START the agent on each planner-created task that has an assignee, without asking (use --no-auto-execute to turn off)',
             allowNo: true,
         }),
     };
@@ -68,34 +122,28 @@ class GoalsPlannerConfig extends base_command_1.BaseCommand {
         if (flags['auto-execute'] !== undefined) {
             data.autoExecute = flags['auto-execute'];
         }
-        if (Object.keys(data).length === 0) {
-            this.error('Nothing to update. Pass --interval-minutes/--interval-ms, --disable, --max-active-tasks, or --auto-execute/--no-auto-execute.', { exit: 1 });
-        }
+        const isWrite = Object.keys(data).length > 0;
         let result;
         try {
-            result = await data_provider_1.dataService.updateGoalPlannerConfig({ goalId: args.id, data });
+            result = isWrite
+                ? await data_provider_1.dataService.updateGoalPlannerConfig({ goalId: args.id, data })
+                : await data_provider_1.dataService.getGoal(args.id);
         }
         catch (err) {
             this.handleApiError(err);
         }
         if (flags.json) {
-            this.log(JSON.stringify(result, null, 2));
+            this.log(JSON.stringify({ ...result, planner: goalPlannerView(result) }, null, 2));
             return;
         }
-        const g = result;
-        const interval = g.tickIntervalMs == null
-            ? 'disabled'
-            : `${Math.round(g.tickIntervalMs / 60_000)}m (${g.tickIntervalMs}ms)`;
-        let autoExecute = '-';
-        if (g.autoExecute !== undefined) {
-            autoExecute = g.autoExecute ? 'on' : 'off';
-        }
         this.log(`Planner config for goal ${args.id}:`);
-        this.log(`  interval:        ${interval}`);
-        this.log(`  maxActiveTasks:  ${g.maxActiveTasks ?? '-'}`);
-        this.log(`  autoExecute:     ${autoExecute}`);
-        if (g.nextTickAt) {
-            this.log(`  nextTickAt:      ${g.nextTickAt}`);
+        for (const line of renderGoalPlannerLines(goalPlannerView(result))) {
+            this.log(line);
+        }
+        if (!isWrite) {
+            this.log('');
+            this.log(`Change it with \`${this.config.bin} goals planner-config ${args.id} --interval-minutes <n>\`, ` +
+                'or `--disable` to turn it off.');
         }
     }
 }