@skrr-ai/cli 0.1.129 → 0.1.130

package/dist/commands/tasks/self-schedule.js

@@ -1,5 +1,10 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.decisionClause = decisionClause;
+exports.describeSpentReturn = describeSpentReturn;
+exports.resolveRelativeRunAt = resolveRelativeRunAt;
+exports.resolveAbsoluteRunAt = resolveAbsoluteRunAt;
+exports.resolveRunAt = resolveRunAt;
 const core_1 = require("@oclif/core");
 const base_command_1 = require("../../base-command");
 const task_extras_1 = require("../../lib/task-extras");
@@ -20,6 +25,7 @@ class TasksSelfSchedule extends base_command_1.BaseCommand {
     static examples = [
         '<%= config.bin %> tasks self-schedule <task-id> --in 2h --note "check whether the deploy settled"',
         '<%= config.bin %> tasks self-schedule <task-id> --at 2026-09-09T14:00:00Z',
+        '<%= config.bin %> tasks self-schedule <task-id> --in 90m --re-enable',
         '<%= config.bin %> tasks self-schedule <task-id> --show',
         '<%= config.bin %> tasks self-schedule <task-id> --clear',
     ];
@@ -28,8 +34,14 @@ class TasksSelfSchedule extends base_command_1.BaseCommand {
     };
     static flags = {
         json: core_1.Flags.boolean({ description: 'Output as JSON' }),
-        at: core_1.Flags.string({ description: 'Absolute return time (ISO-8601 UTC)' }),
-        in: core_1.Flags.string({ description: 'Relative return time such as 90m, 2h, 3d' }),
+        at: core_1.Flags.string({
+            description: 'Absolute return time: ISO-8601 with a UTC offset, such as 2026-11-05T10:00:00Z or ' +
+                '2026-11-05T10:00:00-08:00',
+        }),
+        in: core_1.Flags.string({
+            description: 'Relative return time: a number with a unit (s, m, h, d), such as 90m, 1.5h or 3d. ' +
+                'A bare number means minutes. At least 60s, at most 14 days',
+        }),
         note: core_1.Flags.string({
             // This DOES reach the run now. It is read by `buildTaskExecutionPrompt`,
             // the one place every dispatch path assembles a task prompt, and rendered
@@ -40,7 +52,13 @@ class TasksSelfSchedule extends base_command_1.BaseCommand {
                 'prompt section, and readable any time with --show',
         }),
         'max-per-day': core_1.Flags.integer({
-            description: 'Cap on self-initiated returns per day (1-24, default 4)',
+            description: 'Cap on self-initiated returns per day (1-24). Omit to keep the cap this task ' +
+                'already has (4 for a task that never had one)',
+        }),
+        're-enable': core_1.Flags.boolean({
+            description: "Switch the task's return back on if it was turned off, then park it. Without this a " +
+                'switched-off return is left off and the park is refused. A person may; an agent only ' +
+                'where its initiative policy allows autonomous loops',
         }),
         show: core_1.Flags.boolean({ description: 'Print the pending return without changing it' }),
         clear: core_1.Flags.boolean({ description: 'Cancel the pending return' }),
@@ -61,20 +79,47 @@ class TasksSelfSchedule extends base_command_1.BaseCommand {
                 result = await task_extras_1.taskSelfScheduleApi.clear(taskRef);
             }
             else {
-                const runAt = resolveRunAt(flags.at, flags.in);
-                if (!runAt) {
+                const resolved = resolveRunAt(flags.at, flags.in);
+                if (!resolved) {
                     this.error('Pass --at <ISO-8601>, --in <duration>, or one of --show / --clear.', {
                         exit: 1,
                     });
                 }
+                if ('error' in resolved) {
+                    this.failWithCliError({
+                        message: resolved.error,
+                        code: 'INVALID_RETURN_TIME',
+                        exit: 1,
+                        retryable: false,
+                    });
+                }
+                // The server's field path, read back as the flag that wrote it.
+                this.requestFieldFlags = selfScheduleFieldFlags(Boolean(flags.at));
                 result = await task_extras_1.taskSelfScheduleApi.park(taskRef, {
-                    runAt,
+                    runAt: resolved.runAt,
                     ...(flags.note ? { note: flags.note } : {}),
-                    ...(flags['max-per-day'] ? { maxFiresPerDay: flags['max-per-day'] } : {}),
+                    // `!== undefined`, not truthiness: `--max-per-day 0` is a value the server
+                    // refuses (1-24), and dropping it here parked the task with the default
+                    // while printing a cap the person never asked for.
+                    ...(flags['max-per-day'] !== undefined ? { maxFiresPerDay: flags['max-per-day'] } : {}),
+                    ...(flags['re-enable'] ? { reEnable: true } : {}),
                 });
             }
         }
         catch (err) {
+            // A return someone switched off is left off. The server's sentence is the
+            // same for the web and the API; the CLI adds the flag that answers it.
+            if ((0, base_command_1.apiRefusal)(err).code === 'TASK_RETURN_DISABLED') {
+                this.failWithCliError({
+                    message: `Task ${taskRef}'s return is switched off, so it was not parked again.\n` +
+                        "→ Ask the task's owner to switch it back on in the task's Automations. A person " +
+                        'who means to turn it back on can run this command again with --re-enable.',
+                    code: 'TASK_RETURN_DISABLED',
+                    status: 409,
+                    exit: 1,
+                    retryable: false,
+                });
+            }
             this.handleApiError(err);
         }
         if (flags.json) {
@@ -82,15 +127,35 @@ class TasksSelfSchedule extends base_command_1.BaseCommand {
             return;
         }
         const runAt = result?.runAt;
+        const decision = result?.lastDecision;
         if (!runAt) {
             this.log(`Task ${taskRef} has no pending return.`);
+            // The interim tick clears the instant after a fire, so the decision may be
+            // all there is to say about the return that just went.
+            if (decision)
+                this.log(`Its last return ${decisionClause(decision)}.`);
             return;
         }
         // `pending` is derived server-side: a return that has already fired keeps
         // its instant on the row, and printing that verbatim would report a return
         // as upcoming an hour after it happened.
         const spent = result?.pending === false;
-        this.log(`Task ${taskRef} ${spent ? 'last returned at' : 'returns at'} ${runAt}`);
+        if (!spent) {
+            this.log(`Task ${taskRef} returns at ${runAt}`);
+        }
+        else {
+            // "Spent" only means the instant passed. Whether a run started is the
+            // decision's to say; "last returned at" was printed for returns that were
+            // skipped because the task was blocked, in review, done or archived.
+            const triggerId = result?.triggerId;
+            this.log(describeSpentReturn({
+                taskRef,
+                runAt,
+                decision,
+                triggerId: typeof triggerId === 'string' ? triggerId : undefined,
+                bin: this.config.bin,
+            }));
+        }
         if (result?.note)
             this.log(`Note: ${result.note}`);
         if (!spent && result?.maxFiresPerDay) {
@@ -99,20 +164,113 @@ class TasksSelfSchedule extends base_command_1.BaseCommand {
     }
 }
 exports.default = TasksSelfSchedule;
-/** `90m` / `2h` / `3d`, or an absolute instant. Absolute wins when both are given. */
-function resolveRunAt(at, relative) {
+/** The part after "the return came due and": what became of it, with the reason. */
+function decisionClause(decision) {
+    const why = decision.reasonText || decision.reason || decision.outcome || 'no reason was recorded';
+    switch (decision.verdict) {
+        case 'ran':
+            return 'started a run';
+        case 'failed':
+            return `could not be started: ${why}`;
+        case 'waiting':
+            return `has not started yet: ${why}`;
+        default:
+            return `was skipped: ${why}`;
+    }
+}
+/**
+ * The line `--show` prints for a return whose time has passed. "returned at" is
+ * said only when a run really started; a skipped, failed or unrecorded return
+ * says what it was.
+ */
+function describeSpentReturn({ taskRef, runAt, decision, triggerId, bin = 'skrr', }) {
+    if (decision?.verdict === 'ran')
+        return `Task ${taskRef} returned at ${runAt}`;
+    if (decision)
+        return `Task ${taskRef}: the return came due at ${runAt} and ${decisionClause(decision)}.`;
+    return (`Task ${taskRef}: the return came due at ${runAt}. Whether it ran is not recorded here; ` +
+        `\`${bin} triggers audit ${triggerId ?? `task-self-schedule:${taskRef}`}\` lists every fire.`);
+}
+/**
+ * Body paths the server may name in a refusal, and the flag that wrote each. `runAt`
+ * is written by whichever of --at / --in the person used, so a "runAt must be at
+ * least 60s in the future" for `--in 0m` is not read back as a flag they never typed.
+ */
+function selfScheduleFieldFlags(usedAt) {
+    return Object.freeze({
+        runAt: usedAt ? '--at' : '--in',
+        maxFiresPerDay: '--max-per-day',
+        note: '--note',
+    });
+}
+const MS_PER_UNIT = {
+    s: 1_000,
+    m: 60_000,
+    h: 3_600_000,
+    d: 86_400_000,
+};
+/**
+ * A number, optionally fractional, with an optional unit. The unit words
+ * collapse onto their first character (`sec`/`secs`, `min`/`mins`, `hr`/`hrs`,
+ * `day`/`days`), which is unambiguous across the four units this accepts.
+ */
+const RELATIVE_PATTERN = /^(\d+(?:\.\d+)?|\.\d+)\s*(s|secs?|seconds?|m|mins?|minutes?|h|hrs?|hours?|d|days?)?$/i;
+/** What a person is told when `--in` is not a duration, in the words they would retype. */
+const RELATIVE_HELP = 'use a number with a unit (s, m, h or d), such as 90m, 1.5h or 3d. A bare number means minutes.';
+/**
+ * `--in` as an instant. A value that does not parse says WHICH value, because
+ * the generic "pass --at or --in" this used to fall through to told a person who
+ * had passed `--in 1.5h` to pass `--in`.
+ *
+ * Seconds are accepted: the server owns the 60 s floor and answers
+ * `RETURN_TOO_SOON` with the bound, which is a better explanation than the CLI
+ * refusing the unit.
+ */
+function resolveRelativeRunAt(relative, now = Date.now()) {
+    const match = RELATIVE_PATTERN.exec(relative.trim());
+    if (!match)
+        return { error: `--in ${relative}: ${RELATIVE_HELP}` };
+    const unit = (match[2] ?? 'm').toLowerCase()[0];
+    const ms = Math.round(Number(match[1]) * MS_PER_UNIT[unit]);
+    const at = new Date(now + ms);
+    if (!Number.isFinite(at.getTime())) {
+        return { error: `--in ${relative}: too far away. A return is at most 14 days out.` };
+    }
+    return { runAt: at.toISOString() };
+}
+/** An ISO-8601 date and time that names its zone: `Z`, or an offset such as `-08:00`. */
+const ISO_WITH_ZONE = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}(?::\d{2}(?:\.\d+)?)?(?:Z|[+-]\d{2}(?::?\d{2})?)$/i;
+/** The same shape with no zone, which is a real ISO-8601 value and an ambiguous instant. */
+const ISO_WITHOUT_ZONE = /^\d{4}-\d{2}-\d{2}(?:T\d{2}:\d{2}(?::\d{2}(?:\.\d+)?)?)?$/i;
+const ABSOLUTE_HELP = 'use an ISO-8601 date and time with a UTC offset, such as 2026-11-05T10:00:00Z or ' +
+    '2026-11-05T10:00:00-08:00.';
+/**
+ * `--at` as a UTC instant. Any offset is accepted and normalised, so the server
+ * always receives `...Z`. A value with no zone is refused by saying so: it is a
+ * valid ISO-8601 string, and "Invalid ISO datetime" for it read as if the CLI
+ * could not parse a thing the help had just told the person to type.
+ */
+function resolveAbsoluteRunAt(absolute) {
+    const value = absolute.trim();
+    if (ISO_WITH_ZONE.test(value)) {
+        const at = new Date(value);
+        if (Number.isFinite(at.getTime()))
+            return { runAt: at.toISOString() };
+        return { error: `--at ${absolute}: that is not a real date and time. ${ABSOLUTE_HELP}` };
+    }
+    if (ISO_WITHOUT_ZONE.test(value)) {
+        return {
+            error: `--at ${absolute}: no time zone, so the instant is ambiguous. Add Z for UTC or an ` +
+                'offset, such as 2026-11-05T10:00:00Z or 2026-11-05T10:00:00-08:00.',
+        };
+    }
+    return { error: `--at ${absolute}: not recognised as a date and time. ${ABSOLUTE_HELP}` };
+}
+/** `--at`, or `--in`, or neither (undefined). Absolute wins when both are given. */
+function resolveRunAt(at, relative, now = Date.now()) {
     if (at)
-        return at;
+        return resolveAbsoluteRunAt(at);
     if (!relative)
         return undefined;
-    const match = /^(\d+)\s*(m|min|mins|h|hr|hrs|d)$/i.exec(relative.trim());
-    if (!match)
-        return undefined;
-    const value = Number(match[1]);
-    const unit = match[2].toLowerCase();
-    const MS_PER_UNIT = { m: 60_000, h: 3_600_000, d: 86_400_000 };
-    // `min`/`mins`/`hr`/`hrs` collapse onto their first character, which is
-    // unambiguous across the three units this accepts.
-    const ms = value * (MS_PER_UNIT[unit[0]] ?? MS_PER_UNIT.h);
-    return new Date(Date.now() + ms).toISOString();
+    return resolveRelativeRunAt(relative, now);
 }

package/dist/lib/northstars.d.ts

@@ -1,7 +1,8 @@
-import { NORTHSTAR_ANALYSIS_MODES, NORTHSTAR_APPROVAL_TRIGGERS, NORTHSTAR_EXECUTION_MODES, NORTHSTAR_INTENT_VERDICTS, NORTHSTAR_MANAGEMENT_INTENT_KINDS, NORTHSTAR_REVIEW_STATUSES } from '@skrr-ai/data-provider';
+import { NORTHSTAR_ANALYSIS_MODES, NORTHSTAR_APPROVAL_TRIGGERS, NORTHSTAR_EXECUTION_MODES, NORTHSTAR_INTENT_VERDICTS, NORTHSTAR_MANAGEMENT_INTENT_KINDS, NORTHSTAR_REASON_WORDS, NORTHSTAR_REVIEW_STATUSES, describeNorthstarReason } from '@skrr-ai/data-provider';
 import type { Northstar, NorthstarAnalysisMode, NorthstarExecutionMode, NorthstarGovernance, NorthstarGovernanceStatus, NorthstarGovernanceUpdateParams, NorthstarListResponse, NorthstarManagementIntent, NorthstarManagementIntentKind, NorthstarRecommendation, NorthstarReviewRecord, NorthstarStatusResponse } from '@skrr-ai/data-provider';
 import { withQuery } from './triggers';
 export { NORTHSTAR_ANALYSIS_MODES, NORTHSTAR_APPROVAL_TRIGGERS, NORTHSTAR_EXECUTION_MODES, NORTHSTAR_INTENT_VERDICTS, NORTHSTAR_MANAGEMENT_INTENT_KINDS, NORTHSTAR_REVIEW_STATUSES, };
+export { NORTHSTAR_REASON_WORDS, describeNorthstarReason };
 export type { Northstar, NorthstarAnalysisMode, NorthstarExecutionMode, NorthstarGovernance, NorthstarGovernanceStatus, NorthstarManagementIntent, NorthstarManagementIntentKind, NorthstarRecommendation, NorthstarReviewRecord, };
 /**
  * oclif's `options:` needs runtime arrays, and these two are LIFECYCLE
@@ -72,9 +73,6 @@ export declare function lookupReview(northstarId: string, typed: string): Promis
 /** ms → a short human duration, for a table cell that must stay narrow. */
 export declare function humanMs(ms?: number): string;
 export declare function shortDate(value?: string): string;
-export declare const NORTHSTAR_REASON_WORDS: Readonly<Record<string, string>>;
-/** A code in words; an unknown code comes back unchanged, an absent one says so. */
-export declare function describeNorthstarReason(code: string | null | undefined): string;
 export type NorthstarDecisionContext = {
     northstarId: string;
     intentId: string;
@@ -131,6 +129,48 @@ export declare function listFooter(input: {
     nextCursor?: string | null;
     cursor?: boolean;
 }): string;
+/** What a northstar with no workspace is called wherever a workspace is named. */
+export declare const PERSONAL_NORTHSTAR_WORKSPACE = "personal";
+/** Why a personal northstar can look missing on the web. The one sentence the others build on. */
+export declare const NORTHSTAR_WEB_SCOPE_SENTENCE: string;
+/** Help text shared by `list` and `show`: where a northstar's workspace is printed. */
+export declare const NORTHSTAR_WORKSPACE_READ_HELP: string;
+/** Help text for `create`: which workspace it lands in, and how to choose one. */
+export declare const NORTHSTAR_WORKSPACE_CREATE_HELP: string;
+/**
+ * Anything that may carry a `workspaceId`: a typed Northstar, or the raw record `create` prints (it
+ * is read through `Record<string, unknown>` so `--json` is the server's body plus the url).
+ */
+type WorkspaceBearing = {
+    workspaceId?: unknown;
+} | Record<string, unknown>;
+export declare function shortWorkspaceId(id: string): string;
+/** The workspace a northstar lives in, in one word or id: `personal` when it has none. */
+export declare function northstarWorkspaceLabel(northstar: WorkspaceBearing, options?: {
+    short?: boolean;
+}): string;
+/** The line `show` and `create` print: the full workspace id, or `personal`. */
+export declare function northstarWorkspaceLine(northstar: WorkspaceBearing): string;
+/** What the process that ran `create` asked for: the inputs to which note a personal northstar gets. */
+export type PersonalNorthstarContext = {
+    /** An Agent session: its workspace comes from the session, and `--workspace` is ignored. */
+    autonomous?: boolean;
+    /** The workspace the request carried (`--workspace`, or the one `workspaces use` chose). */
+    requestedWorkspaceId?: string;
+};
+/**
+ * What `create` adds when the northstar landed in no workspace. Three causes, three endings:
+ *
+ *   - an Agent session takes its workspace from the session and ignores `--workspace`, so telling
+ *     it to pass the flag would send it round in a circle;
+ *   - a workspace WAS requested but the person is not a member of it: the server does not refuse,
+ *     it creates the northstar personal (`resolveWorkspaceContext`), so "pass --workspace" would
+ *     be said to someone who just did;
+ *   - nothing was requested, and the way out is the flag.
+ */
+export declare function personalNorthstarNote(context?: PersonalNorthstarContext): string;
+/** The note for a northstar `create` just made: nothing when it is in a workspace. */
+export declare function createdNorthstarNote(northstar: WorkspaceBearing, context?: PersonalNorthstarContext): string | undefined;
 export declare function renderNorthstarList(rows: Northstar[], log: (line: string) => void): void;
 /**
  * The active-commitment cap, in words. `0` is accepted and stored, and a review

package/dist/lib/northstars.js

@@ -1,15 +1,19 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.northstarWideFlag = exports.CRITICAL_COMMITMENT_APPROVAL_NOTE = exports.ALLOCATION_INPUT_FLAGS = exports.NORTHSTAR_LIST_DEFAULT_LIMIT = exports.NORTHSTAR_REASON_WORDS = exports.northstarApi = exports.NORTHSTAR_RECOMMENDATION_STATUSES = exports.NORTHSTAR_PRIORITY_TIERS = exports.NORTHSTAR_STATUSES = exports.NORTHSTAR_REVIEW_STATUSES = exports.NORTHSTAR_MANAGEMENT_INTENT_KINDS = exports.NORTHSTAR_INTENT_VERDICTS = exports.NORTHSTAR_EXECUTION_MODES = exports.NORTHSTAR_APPROVAL_TRIGGERS = exports.NORTHSTAR_ANALYSIS_MODES = void 0;
+exports.northstarWideFlag = exports.CRITICAL_COMMITMENT_APPROVAL_NOTE = exports.ALLOCATION_INPUT_FLAGS = exports.NORTHSTAR_WORKSPACE_CREATE_HELP = exports.NORTHSTAR_WORKSPACE_READ_HELP = exports.NORTHSTAR_WEB_SCOPE_SENTENCE = exports.PERSONAL_NORTHSTAR_WORKSPACE = exports.NORTHSTAR_LIST_DEFAULT_LIMIT = exports.northstarApi = exports.NORTHSTAR_RECOMMENDATION_STATUSES = exports.NORTHSTAR_PRIORITY_TIERS = exports.NORTHSTAR_STATUSES = exports.describeNorthstarReason = exports.NORTHSTAR_REASON_WORDS = exports.NORTHSTAR_REVIEW_STATUSES = exports.NORTHSTAR_MANAGEMENT_INTENT_KINDS = exports.NORTHSTAR_INTENT_VERDICTS = exports.NORTHSTAR_EXECUTION_MODES = exports.NORTHSTAR_APPROVAL_TRIGGERS = exports.NORTHSTAR_ANALYSIS_MODES = void 0;
 exports.intentRisk = intentRisk;
 exports.shortReviewId = shortReviewId;
 exports.lookupReview = lookupReview;
 exports.humanMs = humanMs;
 exports.shortDate = shortDate;
-exports.describeNorthstarReason = describeNorthstarReason;
 exports.describeDecisionRefusal = describeDecisionRefusal;
 exports.describeDecisionOutcome = describeDecisionOutcome;
 exports.listFooter = listFooter;
+exports.shortWorkspaceId = shortWorkspaceId;
+exports.northstarWorkspaceLabel = northstarWorkspaceLabel;
+exports.northstarWorkspaceLine = northstarWorkspaceLine;
+exports.personalNorthstarNote = personalNorthstarNote;
+exports.createdNorthstarNote = createdNorthstarNote;
 exports.renderNorthstarList = renderNorthstarList;
 exports.describeMaxActive = describeMaxActive;
 exports.renderNorthstar = renderNorthstar;
@@ -55,7 +59,9 @@ Object.defineProperty(exports, "NORTHSTAR_APPROVAL_TRIGGERS", { enumerable: true
 Object.defineProperty(exports, "NORTHSTAR_EXECUTION_MODES", { enumerable: true, get: function () { return data_provider_1.NORTHSTAR_EXECUTION_MODES; } });
 Object.defineProperty(exports, "NORTHSTAR_INTENT_VERDICTS", { enumerable: true, get: function () { return data_provider_1.NORTHSTAR_INTENT_VERDICTS; } });
 Object.defineProperty(exports, "NORTHSTAR_MANAGEMENT_INTENT_KINDS", { enumerable: true, get: function () { return data_provider_1.NORTHSTAR_MANAGEMENT_INTENT_KINDS; } });
+Object.defineProperty(exports, "NORTHSTAR_REASON_WORDS", { enumerable: true, get: function () { return data_provider_1.NORTHSTAR_REASON_WORDS; } });
 Object.defineProperty(exports, "NORTHSTAR_REVIEW_STATUSES", { enumerable: true, get: function () { return data_provider_1.NORTHSTAR_REVIEW_STATUSES; } });
+Object.defineProperty(exports, "describeNorthstarReason", { enumerable: true, get: function () { return data_provider_1.describeNorthstarReason; } });
 const format_1 = require("./format");
 const triggers_1 = require("./triggers");
 /**
@@ -169,86 +175,6 @@ function shortDate(value) {
     const date = new Date(value);
     return Number.isNaN(date.getTime()) ? '—' : date.toISOString().replace('T', ' ').slice(0, 16);
 }
-/* --------------------------------------------------------------------------
- * Reason codes in words
- *
- * The server refuses, skips and decides with machine codes
- * (`reviewer_agent_not_always_on`, `northstar_version_drift`, ...). A code is
- * for a script; a person reading a table or an error needs the sentence. This
- * is the ONE place those sentences live, so a command never invents its own
- * wording (the old governance line guessed "offline" for a reviewer that was
- * simply not Always-On) and `--json` can carry the same text as `reasonText`.
- *
- * Entries are CLAUSES, lower-case with no trailing full stop, so a caller can
- * put them after "agent turn not started:" or inside a longer sentence. A code
- * with no entry is returned AS IT IS: an unknown code printed raw is honest,
- * a guessed explanation is not.
- * ------------------------------------------------------------------------ */
-exports.NORTHSTAR_REASON_WORDS = {
-    // An agent turn that was not reserved for an agent_assisted review.
-    no_reviewer_agent_configured: 'no reviewer agent is set on this northstar',
-    northstar_paused: 'the northstar is paused',
-    northstar_achieved: 'the northstar is marked achieved',
-    northstar_archived: 'the northstar is archived',
-    analysis_mode_not_agent_assisted: 'analysis mode is deterministic, so no agent is asked',
-    managed_agent_missing: 'the reviewer agent does not exist or is not visible to you',
-    always_on_control_unavailable: "the reviewer agent's Always-On state could not be read just now",
-    always_on_disabled: 'Always-On is turned off for the reviewer agent',
-    always_on_suspended: 'Always-On is suspended for the reviewer agent',
-    always_on_stale_generation: "the reviewer agent's Always-On state changed while this ran",
-    reviewer_agent_foreign_owner: "the reviewer agent belongs to someone other than this northstar's owner",
-    reviewer_agent_not_always_on: 'the reviewer agent is not Always-On (it is not offline; turn Always-On on for it)',
-    run_already_reserved: 'an agent run was already reserved for this review',
-    envelope_build_failed: 'the review could not be packaged for the agent',
-    governance_run_reservation_failed: 'reserving the agent turn failed unexpectedly',
-    run_not_reserved: 'the run queue declined to reserve the agent turn',
-    enqueue_failed: 'the agent turn could not be queued',
-    agent_run_reserved: 'an agent turn is reserved; its results land asynchronously',
-    // Why an intent was recorded, held or refused by policy.
-    execution_mode_advisory: 'execution mode is advisory: recorded for you to read, nothing is changed',
-    execution_mode_approval: 'execution mode is approval: it waits for a person',
-    proposal_only: 'a proposal: the governor never applies it, a person does',
-    commitment_protected: "the commitment is on this northstar's protected list",
-    intent_kind_not_allowed: "this kind of intent is not in the northstar's allowed list",
-    critical_commitment_lifecycle: 'it changes a critical commitment, which always needs a person',
-    resume_requires_approval: 'resuming always needs a person',
-    budget_telemetry_unavailable: 'the automatic-change budget could not be read, so it fell back to approval',
-    critical_demotion: 'it would demote a critical commitment',
-    tier_change_too_large: 'the tier change is larger than one step',
-    weight_change_too_large: 'the weight change exceeds the allowed relative change',
-    bounds_increase_compute: 'it would buy more compute',
-    bounds_change_exceeds_max_relative_change: 'the bounds change exceeds the allowed relative change',
-    auto_pause_evidence_incomplete: 'the evidence for an automatic pause is incomplete',
-    no_auto_rule_for_kind: 'no automatic rule covers this kind of change',
-    auto_mutation_review_cap_reached: 'this review already made its maximum automatic changes',
-    auto_mutation_daily_cap_reached: "today's automatic-change cap is used up",
-    mutation_cooldown_active: 'the commitment was changed automatically too recently (cooldown)',
-    commitment_not_linked_to_northstar: 'the commitment is no longer linked to this northstar',
-    commitment_not_found: 'the commitment no longer exists',
-    approved_by_user: 'approved by a person',
-    rejected_by_user: 'rejected by a person',
-    // Why a decision (approve / reject) was refused or did not take effect.
-    commitment_version_drift: 'the commitment changed after this was proposed',
-    northstar_version_drift: 'the northstar changed after this was proposed',
-    // Two ways to the same ending: a newer review asks the same question again, or a concurrent review
-    // is already making (or has made) this very change. Either way another review has it.
-    superseded: 'another review already proposed or made the same change',
-    recommendation_dismissed: 'its recommendation was dismissed',
-    intent_not_found: "no such intent in this northstar's 50 most recent reviews",
-    review_not_found: 'no such review on this northstar',
-    northstar_not_found: 'no such northstar',
-    owner_approval_required: "only the northstar's owner can approve a proposal",
-    transition_lost: 'another decision landed first',
-    claim_lost: 'another process is already applying it',
-    mutation_error: 'the change failed part-way and was left for the repair pass',
-    proposal_kind_requires_manual_action: 'this kind of proposal is completed by hand',
-};
-/** A code in words; an unknown code comes back unchanged, an absent one says so. */
-function describeNorthstarReason(code) {
-    if (!code)
-        return 'no reason was recorded';
-    return exports.NORTHSTAR_REASON_WORDS[code] ?? code;
-}
 function utcStamp(value) {
     const stamp = shortDate(typeof value === 'string' ? value : undefined);
     return stamp === '—' ? undefined : `${stamp} UTC`;
@@ -303,7 +229,7 @@ function describeDecisionRefusal(body, ctx) {
             const when = utcStamp(body.decidedAt);
             return {
                 code,
-                text: `This intent was already invalidated${why ? ` (${describeNorthstarReason(why)})` : ''}${when ? ` at ${when}` : ''} — nothing changed.`,
+                text: `This intent was already invalidated${why ? ` (${(0, data_provider_1.describeNorthstarReason)(why)})` : ''}${when ? ` at ${when}` : ''} — nothing changed.`,
             };
         }
         let by = '';
@@ -329,7 +255,7 @@ function describeDecisionRefusal(body, ctx) {
             text: `No intent ${ctx.intentId} in this northstar's 50 most recent reviews. If it is older, pass --review <review-id>.`,
         };
     }
-    const words = describeNorthstarReason(code);
+    const words = (0, data_provider_1.describeNorthstarReason)(code);
     return { code, text: `${words.charAt(0).toUpperCase()}${words.slice(1)}.` };
 }
 /**
@@ -390,7 +316,7 @@ function describeDecisionOutcome(result, ctx) {
         text = `${what}, so the approval was not applied and the intent was invalidated. ${reviewNow}`;
     }
     else if (code) {
-        text = `Your approval is recorded, but nothing was applied: ${describeNorthstarReason(code)}.`;
+        text = `Your approval is recorded, but nothing was applied: ${(0, data_provider_1.describeNorthstarReason)(code)}.`;
     }
     else {
         text = `Your approval is recorded, but the change has not landed yet (verdict: ${verdict}). It is retried automatically; check \`${bin} northstars intents list ${ctx.northstarId}\`.`;
@@ -423,6 +349,93 @@ function listFooter(input) {
         ? `${head} --limit is already at its maximum (${input.max}), so narrow the list with --status`
         : `${head} raise --limit (max ${input.max})`;
 }
+/* --------------------------------------------------------------------------
+ * Which workspace a northstar lives in (OSK-21643)
+ *
+ * The web Northstars list is scoped to the person's ACTIVE workspace and sends `X-Workspace-Id`, so
+ * a northstar with no workspace is hidden from it while a workspace is active. The API creates a
+ * northstar in the workspace the request names and in none otherwise, which is what a CLI without
+ * `--workspace` sends. Nothing on either surface said so, and a northstar made here simply seemed
+ * to be missing from the web.
+ *
+ * Every sentence about it comes from this block, so `list`, `show`, `create`, their `--help` and
+ * the docs cannot say different things. The docs quote `personalNorthstarNote` byte for byte and a
+ * spec holds them to it.
+ * -------------------------------------------------------------------------- */
+/** What a northstar with no workspace is called wherever a workspace is named. */
+exports.PERSONAL_NORTHSTAR_WORKSPACE = 'personal';
+/** Why a personal northstar can look missing on the web. The one sentence the others build on. */
+exports.NORTHSTAR_WEB_SCOPE_SENTENCE = `The ${data_provider_1.BRAND.displayName} web Northstars list shows only the active workspace's Northstars, so a personal one is hidden there while a workspace is active.`;
+/** Help text shared by `list` and `show`: where a northstar's workspace is printed. */
+exports.NORTHSTAR_WORKSPACE_READ_HELP = `A northstar belongs to the workspace it was created in, or is "${exports.PERSONAL_NORTHSTAR_WORKSPACE}" when it has none. ` +
+    `${exports.NORTHSTAR_WEB_SCOPE_SENTENCE}`;
+/** Help text for `create`: which workspace it lands in, and how to choose one. */
+exports.NORTHSTAR_WORKSPACE_CREATE_HELP = 'The northstar is created in the workspace the global --workspace <id> flag names, or the one chosen once with ' +
+    '`workspaces use`. With neither, or for a workspace you are not a member of, it is personal (no workspace), and ' +
+    'the output says so. ' +
+    `${exports.NORTHSTAR_WEB_SCOPE_SENTENCE} An Agent session always uses its own session workspace, and --workspace does not change it.`;
+/** The workspace id a northstar carries, or undefined for a personal one (absent, null or blank). */
+function northstarWorkspaceId(northstar) {
+    const id = typeof northstar.workspaceId === 'string' ? northstar.workspaceId.trim() : '';
+    return id || undefined;
+}
+/**
+ * A workspace id short enough for a table: `038b2251-6a0c-4e2b-9f7d-c1d0f3a8b2aa` is `038b2251…` and
+ * `ws_01H8XKPQ7ABCDEF` is `ws_01H8XKPQ…`. Unlike a review id (`shortReviewId`) the short form is NOT
+ * accepted back by `--workspace`, which needs the full id, so a shortened value ends in `…` to say
+ * it is a prefix. The full id is in `--json` and in `skrr workspaces list`.
+ */
+const WORKSPACE_ID_SHORT_CHARS = 8;
+function shortWorkspaceId(id) {
+    const prefixed = /^([a-z]+_)(.+)$/i.exec(id);
+    const prefix = prefixed?.[1] ?? '';
+    const rest = prefixed?.[2] ?? id;
+    return rest.length > WORKSPACE_ID_SHORT_CHARS
+        ? `${prefix}${rest.slice(0, WORKSPACE_ID_SHORT_CHARS)}…`
+        : id;
+}
+/** The workspace a northstar lives in, in one word or id: `personal` when it has none. */
+function northstarWorkspaceLabel(northstar, options = {}) {
+    const id = northstarWorkspaceId(northstar);
+    if (!id)
+        return exports.PERSONAL_NORTHSTAR_WORKSPACE;
+    return options.short ? shortWorkspaceId(id) : id;
+}
+/** The line `show` and `create` print: the full workspace id, or `personal`. */
+function northstarWorkspaceLine(northstar) {
+    return `Workspace   ${northstarWorkspaceLabel(northstar)}`;
+}
+/** Read from the environment `--workspace` and `workspaces use` both write (`withWorkspaceHeader`). */
+function ambientPersonalContext(env = process.env) {
+    return {
+        autonomous: env.OVERSKY_AUTONOMOUS_SESSION === '1',
+        requestedWorkspaceId: env.OVERSKY_WORKSPACE_ID?.trim() || undefined,
+    };
+}
+/**
+ * What `create` adds when the northstar landed in no workspace. Three causes, three endings:
+ *
+ *   - an Agent session takes its workspace from the session and ignores `--workspace`, so telling
+ *     it to pass the flag would send it round in a circle;
+ *   - a workspace WAS requested but the person is not a member of it: the server does not refuse,
+ *     it creates the northstar personal (`resolveWorkspaceContext`), so "pass --workspace" would
+ *     be said to someone who just did;
+ *   - nothing was requested, and the way out is the flag.
+ */
+function personalNorthstarNote(context = ambientPersonalContext()) {
+    const lead = `Not in a workspace (${exports.PERSONAL_NORTHSTAR_WORKSPACE}). ${exports.NORTHSTAR_WEB_SCOPE_SENTENCE}`;
+    if (context.autonomous) {
+        return `${lead} This Agent session has no workspace to create it in, and --workspace does not change that.`;
+    }
+    if (context.requestedWorkspaceId) {
+        return `${lead} Workspace ${context.requestedWorkspaceId} was requested, but a northstar is created in a workspace only for a member of it: check \`skrr workspaces list\`.`;
+    }
+    return `${lead} Pass the global --workspace <id> flag to create one inside a workspace.`;
+}
+/** The note for a northstar `create` just made: nothing when it is in a workspace. */
+function createdNorthstarNote(northstar, context) {
+    return northstarWorkspaceId(northstar) ? undefined : personalNorthstarNote(context);
+}
 function renderNorthstarList(rows, log) {
     if (rows.length === 0) {
         log('No northstars.');
@@ -437,6 +450,7 @@ function renderNorthstarList(rows, log) {
         commitments: String(row.state?.activeCommitmentCount ?? 0),
         open: String(row.state?.openRecommendationCount ?? 0),
         reviewed: shortDate(row.state?.lastReviewedAt),
+        workspace: northstarWorkspaceLabel(row, { short: true }),
     })), [
         { key: 'id', header: 'ID' },
         { key: 'title', header: 'TITLE', maxWidth: 40 },
@@ -446,6 +460,7 @@ function renderNorthstarList(rows, log) {
         { key: 'commitments', header: 'ACTIVE' },
         { key: 'open', header: 'OPEN REC' },
         { key: 'reviewed', header: 'REVIEWED' },
+        { key: 'workspace', header: 'WORKSPACE' },
     ], log);
 }
 /** A budget that was never set says so; `—` is kept for a timestamp that does not exist yet. */
@@ -470,6 +485,7 @@ function renderNorthstar(status, log) {
     log(`Attention   total ${notSet(ns.attentionBudget?.totalWeight)} · max active ${describeMaxActive(ns.attentionBudget?.maxActiveCommitments)}`);
     const cadence = ns.reviewCadence ?? {};
     log(`Review      ${cadence.mode ?? 'manual'}${cadence.intervalMs ? ` every ${humanMs(cadence.intervalMs)}` : ''}   next ${shortDate(cadence.nextReviewAt)}   last ${shortDate(ns.state?.lastReviewedAt)}`);
+    log(northstarWorkspaceLine(ns));
     if (ns.goalIds?.length)
         log(`Goals       ${ns.goalIds.join(', ')}`);
     if (ns.agentIds?.length)
@@ -544,15 +560,15 @@ function reviewerReadiness(reviewer) {
         if (admission.admitted)
             return '  [ready]';
         if (admission.reason === 'analysis_mode_not_agent_assisted') {
-            return `  [not in use: ${describeNorthstarReason(admission.reason)}]`;
+            return `  [not in use: ${(0, data_provider_1.describeNorthstarReason)(admission.reason)}]`;
         }
-        return `  [not ready: ${describeNorthstarReason(admission.reason)}]`;
+        return `  [not ready: ${(0, data_provider_1.describeNorthstarReason)(admission.reason)}]`;
     }
     if (reviewer.ready)
         return '  [ready]';
     // No reason from an older server is "unknown", never a guess: the old fallback
     // said "offline" about an agent that was reachable and merely not Always-On.
-    return `  [not ready: ${reviewer.reason ? describeNorthstarReason(reviewer.reason) : 'reason unknown'}]`;
+    return `  [not ready: ${reviewer.reason ? (0, data_provider_1.describeNorthstarReason)(reviewer.reason) : 'reason unknown'}]`;
 }
 /** The `governance configure` flags that move what a commitment's allocation is computed from. */
 exports.ALLOCATION_INPUT_FLAGS = [
@@ -761,13 +777,13 @@ function reviewNote(review) {
 }
 function agentTurnNote(review) {
     if (review.status === 'failed') {
-        return `failed: ${review.errorMessage ?? describeNorthstarReason(review.reason)}`;
+        return `failed: ${review.errorMessage ?? (0, data_provider_1.describeNorthstarReason)(review.reason)}`;
     }
     if (review.status === 'awaiting_agent')
         return 'waiting for the agent turn';
     if (review.analysisMode === 'agent_assisted' && review.status === 'succeeded') {
         if (review.reason && AGENT_TURN_NOT_STARTED.has(review.reason)) {
-            return `agent turn not started: ${describeNorthstarReason(review.reason)}`;
+            return `agent turn not started: ${(0, data_provider_1.describeNorthstarReason)(review.reason)}`;
         }
         if (!review.autonomousRunId)
             return 'agent turn not started: no reason was recorded';
@@ -776,7 +792,7 @@ function agentTurnNote(review) {
 }
 /** `Reason` line of one review: the words, with the raw code kept beside them for grep. */
 function describeReviewReason(reason) {
-    const words = describeNorthstarReason(reason);
+    const words = (0, data_provider_1.describeNorthstarReason)(reason);
     return words === reason ? reason : `${words}  [${reason}]`;
 }
 function renderReviewList(reviews, log) {
@@ -848,7 +864,7 @@ function renderIntentList(intents, log, options = {}) {
         // The intent's OWN rating (see `intentRisk`), never its recommendation's.
         risk: intentRisk(intent),
         // No sentence from the governor: the policy code in words (an unknown code stays as it is).
-        why: intent.reason ?? (intent.verdictReason ? describeNorthstarReason(intent.verdictReason) : '—'),
+        why: intent.reason ?? (intent.verdictReason ? (0, data_provider_1.describeNorthstarReason)(intent.verdictReason) : '—'),
         code: intent.verdictReason ?? '',
         source: intent.source ?? 'deterministic',
     }));