@skrr-ai/cli 0.1.129 → 0.1.131

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',
     }));

package/dist/lib/reflection.d.ts

@@ -36,15 +36,73 @@ export declare const MAX_REFLECTION_CADENCE_MINUTES: number;
  * out to `skrr` from Bash.
  */
 export declare const REFLECTION_PROMPT = "[Self-reflection] Step back and review your own schedule and cadence \u2014 this is a planning turn, not a chat turn.\n\n1. Look at your whole schedule in one view: your recent fires (past), your upcoming triggers, your open tasks, and today's to-dos. (Use your schedule-overview tool, or run `skrr agents schedule-overview <your-agent-id>`.)\n2. Judge your own rhythm honestly: are you waking too often (many fires, little changed) or too rarely (things slipping past their time)?\n3. If your reflection cadence is wrong, retune it \u2014 reschedule THIS self-reflection trigger to a better interval.\n4. Fix what is slipping: reschedule, create, or cancel triggers and tasks so your plan matches reality.\n\nBe deliberate and minimal. Every trigger you keep spends the user's compute \u2014 keep only what earns its place. If nothing needs changing, do nothing and end the turn.";
+/**
+ * A cadence the caller got wrong: unparseable, empty, or not a positive number of
+ * minutes. Mirrors `InvalidCadenceError` in the server copy, minus its 4xx `status`:
+ * that field is how an MCP server tells the caller's mistake from its own failure,
+ * and on the CLI the same field would make `handleApiError` read this as an HTTP
+ * response. Commands catch it and report it as a usage error.
+ */
+export declare class InvalidCadenceError extends Error {
+    readonly code = "INVALID_CADENCE";
+    constructor(message: string);
+}
 export declare function parseCadenceToMinutes(input: string): number;
 /** Clamp a cadence to the allowed reflection window. */
 export declare function clampCadenceMinutes(minutes: number): number;
+/** What `applyCadenceBounds` did to a requested cadence. */
+export interface CadenceBounds {
+    minutes: number;
+    requestedMinutes: number;
+    clamped: boolean;
+    /** The limit that moved the request, or null when it was inside the window. */
+    bound: 'minimum' | 'maximum' | null;
+}
+/**
+ * Apply the reflection window to a requested cadence and SAY what happened, so every
+ * caller can report "asked 5m, applied 15m" instead of only the clamped number
+ * (OSK-21486, OSK-21493, OSK-21602). `bound` names the limit that moved it.
+ */
+export declare function applyCadenceBounds(requestedMinutes: number): CadenceBounds;
+/**
+ * One sentence for a clamp ("5m is below the 15m minimum; applied 15m."), or null when
+ * the request was inside the window. Shared by the MCP result `note` and the CLI line.
+ */
+export declare function describeCadenceClamp({ minutes, requestedMinutes, bound, }: Pick<CadenceBounds, 'minutes' | 'requestedMinutes' | 'bound'>): string | null;
 /** Render minutes back as a compact human cadence ("6h", "90m", "1d"). */
 export declare function describeCadenceMinutes(minutes: number): string;
 /** The agent's single self-reflection trigger, or undefined if none exists. */
 export declare function findReflectionTrigger(triggers: TriggerDefinition[]): TriggerDefinition | undefined;
 /** Read a reflection trigger's current interval in minutes, if it has one. */
 export declare function reflectionCadenceMinutes(trigger: TriggerDefinition): number | undefined;
+/**
+ * The loop's next run, for display: its scheduled time while it is enabled, else `-`. A
+ * paused loop has no next run, and a loop with nothing scheduled does not have its LAST fire
+ * promoted to one (the server copy keeps `nextRunAt` and `lastFiredAt` apart the same way).
+ */
+export declare function reflectionNextRunLabel(trigger: TriggerDefinition): string;
+/**
+ * Whether the loop's fires run, as the SERVER says it (`GET /api/triggers?include=autonomy`), or
+ * null when it did not say. Nothing is derived here: the verdict depends on the agent's
+ * initiative mode and on which door created the loop, and a local copy of that judgement is free
+ * to disagree with the fire path (OSK-21606). A server that predates the field, or one that could
+ * not reach a verdict, sends nothing, and that is UNKNOWN, never `runs`.
+ */
+export declare function reflectionAutonomy(trigger: TriggerDefinition): {
+    autonomy: 'runs' | 'suggests_only';
+    note?: string;
+} | null;
+/**
+ * The one plain sentence a text view prints under the loop when its fires will not run for the
+ * owner; null when they do, when the server did not say, or when the loop is paused (a paused
+ * loop fires nothing, so the gate is not what the reader needs to hear about).
+ */
+export declare function reflectionAutonomyNote(trigger: TriggerDefinition, bin: string): string | null;
+/** The `--json` fields for the same verdict: absent when unknown, so absence reads as unknown. */
+export declare function reflectionAutonomyFields(trigger: TriggerDefinition): {
+    autonomy?: 'runs' | 'suggests_only';
+    note?: string;
+};
 /**
  * Build the `POST /api/triggers` body for a fresh self-reflection loop. Uses the
  * proven `scope:agent + kind:schedule + mode:run_only` shape and coalesces so a

package/dist/lib/reflection.js

@@ -1,11 +1,17 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.REFLECTION_PROMPT = exports.MAX_REFLECTION_CADENCE_MINUTES = exports.MIN_REFLECTION_CADENCE_MINUTES = exports.DEFAULT_REFLECTION_CADENCE_MINUTES = exports.REFLECTION_LABEL = void 0;
+exports.InvalidCadenceError = exports.REFLECTION_PROMPT = exports.MAX_REFLECTION_CADENCE_MINUTES = exports.MIN_REFLECTION_CADENCE_MINUTES = exports.DEFAULT_REFLECTION_CADENCE_MINUTES = exports.REFLECTION_LABEL = void 0;
 exports.parseCadenceToMinutes = parseCadenceToMinutes;
 exports.clampCadenceMinutes = clampCadenceMinutes;
+exports.applyCadenceBounds = applyCadenceBounds;
+exports.describeCadenceClamp = describeCadenceClamp;
 exports.describeCadenceMinutes = describeCadenceMinutes;
 exports.findReflectionTrigger = findReflectionTrigger;
 exports.reflectionCadenceMinutes = reflectionCadenceMinutes;
+exports.reflectionNextRunLabel = reflectionNextRunLabel;
+exports.reflectionAutonomy = reflectionAutonomy;
+exports.reflectionAutonomyNote = reflectionAutonomyNote;
+exports.reflectionAutonomyFields = reflectionAutonomyFields;
 exports.buildReflectionTriggerPayload = buildReflectionTriggerPayload;
 /**
  * reflection.ts — the agent self-reflection ("meta cadence") loop.
@@ -52,9 +58,42 @@ exports.REFLECTION_PROMPT = `[Self-reflection] Step back and review your own sch
 4. Fix what is slipping: reschedule, create, or cancel triggers and tasks so your plan matches reality.
 
 Be deliberate and minimal. Every trigger you keep spends the user's compute — keep only what earns its place. If nothing needs changing, do nothing and end the turn.`;
+/**
+ * A cadence the caller got wrong: unparseable, empty, or not a positive number of
+ * minutes. Mirrors `InvalidCadenceError` in the server copy, minus its 4xx `status`:
+ * that field is how an MCP server tells the caller's mistake from its own failure,
+ * and on the CLI the same field would make `handleApiError` read this as an HTTP
+ * response. Commands catch it and report it as a usage error.
+ */
+class InvalidCadenceError extends Error {
+    code = 'INVALID_CADENCE';
+    constructor(message) {
+        super(message);
+        this.name = 'InvalidCadenceError';
+    }
+}
+exports.InvalidCadenceError = InvalidCadenceError;
+/**
+ * A cadence must be a positive, finite number of minutes. `0` is not "off" and not "the
+ * minimum": rounding it up to the floor turned an attempt to switch the loop off into one
+ * that wakes the agent 96 times a day (OSK-21493).
+ */
+function requirePositiveMinutes(minutes, raw) {
+    if (!Number.isFinite(minutes)) {
+        throw new InvalidCadenceError(`That cadence is too large to be a number of minutes. Pick between ${describeCadenceMinutes(exports.MIN_REFLECTION_CADENCE_MINUTES)} and ${describeCadenceMinutes(exports.MAX_REFLECTION_CADENCE_MINUTES)}.`);
+    }
+    if (minutes <= 0) {
+        const shown = raw.length > 24 ? `${raw.slice(0, 24)}…` : raw;
+        throw new InvalidCadenceError(`"${shown}" is not a cadence — it cannot mean "off". To pause the loop, disable it instead ` +
+            '(skrr agents reflect <agent> --disable, or the self_reflection_disable tool); otherwise ' +
+            `pick between ${describeCadenceMinutes(exports.MIN_REFLECTION_CADENCE_MINUTES)} and ${describeCadenceMinutes(exports.MAX_REFLECTION_CADENCE_MINUTES)}.`);
+    }
+    return minutes;
+}
 /**
  * Parse a human cadence into minutes. Accepts `6h`, `90m`, `2h30m`, `1d`, or a
- * bare number (interpreted as minutes). Throws on unparseable input.
+ * bare number (interpreted as minutes). Throws `InvalidCadenceError` on
+ * unparseable input.
  */
 // Longest-first alternation, and CADENCE_FULL is anchored so the WHOLE string
 // must be consumed. Without the anchor, "1 month" matches `1` + `m` and silently
@@ -67,14 +106,14 @@ function parseCadenceToMinutes(input) {
         .trim()
         .toLowerCase();
     if (!raw) {
-        throw new Error('Empty cadence. Use a form like "6h", "90m", "2h30m", or "360".');
+        throw new InvalidCadenceError('Empty cadence. Use a form like "6h", "90m", "2h30m", or "360".');
     }
     // Bare number → minutes.
     if (/^\d+(\.\d+)?$/.test(raw)) {
-        return Math.round(Number(raw));
+        return requirePositiveMinutes(Math.round(Number(raw)), raw);
     }
     if (!CADENCE_FULL.test(raw)) {
-        throw new Error(`Could not parse cadence "${input}". Use minutes/hours/days — e.g. "6h", "90m", "2h30m", "360". ` +
+        throw new InvalidCadenceError(`Could not parse cadence "${input}". Use minutes/hours/days — e.g. "6h", "90m", "2h30m", "360". ` +
             '(Months and seconds are not units here.)');
     }
     let total = 0;
@@ -90,12 +129,39 @@ function parseCadenceToMinutes(input) {
         else
             total += n;
     }
-    return Math.round(total);
+    return requirePositiveMinutes(Math.round(total), raw);
 }
 /** Clamp a cadence to the allowed reflection window. */
 function clampCadenceMinutes(minutes) {
     return Math.max(exports.MIN_REFLECTION_CADENCE_MINUTES, Math.min(exports.MAX_REFLECTION_CADENCE_MINUTES, Math.round(minutes)));
 }
+/**
+ * Apply the reflection window to a requested cadence and SAY what happened, so every
+ * caller can report "asked 5m, applied 15m" instead of only the clamped number
+ * (OSK-21486, OSK-21493, OSK-21602). `bound` names the limit that moved it.
+ */
+function applyCadenceBounds(requestedMinutes) {
+    const requested = Math.round(requestedMinutes);
+    const minutes = clampCadenceMinutes(requested);
+    let bound = null;
+    if (minutes > requested)
+        bound = 'minimum';
+    else if (minutes < requested)
+        bound = 'maximum';
+    return { minutes, requestedMinutes: requested, clamped: bound !== null, bound };
+}
+/**
+ * One sentence for a clamp ("5m is below the 15m minimum; applied 15m."), or null when
+ * the request was inside the window. Shared by the MCP result `note` and the CLI line.
+ */
+function describeCadenceClamp({ minutes, requestedMinutes, bound, }) {
+    if (!bound)
+        return null;
+    const limit = bound === 'minimum' ? exports.MIN_REFLECTION_CADENCE_MINUTES : exports.MAX_REFLECTION_CADENCE_MINUTES;
+    const side = bound === 'minimum' ? 'below' : 'above';
+    return (`${describeCadenceMinutes(requestedMinutes)} is ${side} the ${describeCadenceMinutes(limit)} ` +
+        `${bound}; applied ${describeCadenceMinutes(minutes)}.`);
+}
 /** Render minutes back as a compact human cadence ("6h", "90m", "1d"). */
 function describeCadenceMinutes(minutes) {
     if (minutes > 0 && minutes % (60 * 24) === 0)
@@ -113,6 +179,49 @@ function reflectionCadenceMinutes(trigger) {
     const ms = trigger.schedule?.intervalMs;
     return typeof ms === 'number' && Number.isFinite(ms) ? Math.round(ms / 60_000) : undefined;
 }
+/**
+ * The loop's next run, for display: its scheduled time while it is enabled, else `-`. A
+ * paused loop has no next run, and a loop with nothing scheduled does not have its LAST fire
+ * promoted to one (the server copy keeps `nextRunAt` and `lastFiredAt` apart the same way).
+ */
+function reflectionNextRunLabel(trigger) {
+    return (0, triggers_1.scheduledRunAt)(trigger) ?? '-';
+}
+/**
+ * Whether the loop's fires run, as the SERVER says it (`GET /api/triggers?include=autonomy`), or
+ * null when it did not say. Nothing is derived here: the verdict depends on the agent's
+ * initiative mode and on which door created the loop, and a local copy of that judgement is free
+ * to disagree with the fire path (OSK-21606). A server that predates the field, or one that could
+ * not reach a verdict, sends nothing, and that is UNKNOWN, never `runs`.
+ */
+function reflectionAutonomy(trigger) {
+    if (trigger.enabled === false)
+        return null;
+    const { autonomy, autonomyNote } = trigger;
+    if (autonomy !== 'runs' && autonomy !== 'suggests_only')
+        return null;
+    const note = typeof autonomyNote === 'string' && autonomyNote.trim() ? autonomyNote.trim() : '';
+    return { autonomy, ...(note ? { note } : {}) };
+}
+/**
+ * The one plain sentence a text view prints under the loop when its fires will not run for the
+ * owner; null when they do, when the server did not say, or when the loop is paused (a paused
+ * loop fires nothing, so the gate is not what the reader needs to hear about).
+ */
+function reflectionAutonomyNote(trigger, bin) {
+    const verdict = reflectionAutonomy(trigger);
+    if (!verdict || verdict.autonomy !== 'suggests_only')
+        return null;
+    return (verdict.note ??
+        `This loop's fires only create an inbox suggestion. Run ${bin} triggers preflight ${trigger.id ?? '<trigger-id>'} to see why.`);
+}
+/** The `--json` fields for the same verdict: absent when unknown, so absence reads as unknown. */
+function reflectionAutonomyFields(trigger) {
+    const verdict = reflectionAutonomy(trigger);
+    if (!verdict)
+        return {};
+    return { autonomy: verdict.autonomy, ...(verdict.note ? { note: verdict.note } : {}) };
+}
 /**
  * Build the `POST /api/triggers` body for a fresh self-reflection loop. Uses the
  * proven `scope:agent + kind:schedule + mode:run_only` shape and coalesces so a

package/dist/lib/schedule.d.ts

@@ -145,6 +145,8 @@ export interface ScheduleTrace {
     has_more?: boolean;
     next_cursor?: string | null;
 }
+/** Calendar day at an instant in the zone used for the schedule query. */
+export declare function scheduleTraceToday(now: Date, timezone: string): string;
 export declare function scheduleTracePath(params: {
     agentId: string;
     date: string;

package/dist/lib/schedule.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.scheduleApi = void 0;
+exports.scheduleTraceToday = scheduleTraceToday;
 exports.scheduleTracePath = scheduleTracePath;
 exports.isSmartScheduleProposal = isSmartScheduleProposal;
 exports.describeNonProposal = describeNonProposal;
@@ -29,6 +30,17 @@ exports.proposalToApproveTodos = proposalToApproveTodos;
 const data_provider_1 = require("@skrr-ai/data-provider");
 const format_1 = require("./format");
 const triggers_1 = require("./triggers");
+/** Calendar day at an instant in the zone used for the schedule query. */
+function scheduleTraceToday(now, timezone) {
+    const parts = new Intl.DateTimeFormat('en-CA', {
+        timeZone: timezone,
+        year: 'numeric',
+        month: '2-digit',
+        day: '2-digit',
+    }).formatToParts(now);
+    const part = (type) => parts.find((item) => item.type === type)?.value;
+    return `${part('year')}-${part('month')}-${part('day')}`;
+}
 function scheduleTracePath(params) {
     return (0, triggers_1.withQuery)('/api/todos/smart-schedule/trace', {
         agentId: params.agentId,

package/dist/lib/task-operations.js

@@ -28,6 +28,8 @@ function taskActionCommand(action, taskId, targetId, bin = 'skrr', context = {})
         request_approval: `tasks approvals create ${task} --type <review|sign_off|deployment>`,
         resolve_approval: `tasks approvals resolve ${task} ${target} --status <approved|rejected>`,
         resolve_task_hold: `tasks move ${task} --status <status>`,
+        resume_schedule: `tasks resume-schedule ${task}`,
+        retry_schedule: `tasks retry-schedule ${task} --at <time>`,
         retry_task: `tasks retry ${task}`,
         set_execution_mode: `tasks update ${task} --execution-mode <agent|human>`,
         start_task: `tasks start ${task}`,

package/dist/lib/task-schedule-notes.d.ts

@@ -0,0 +1,46 @@
+/**
+ * What a schedule command did to the schedule, as sentences.
+ *
+ * The server already knows these things and reports them as response-only fields
+ * (`schedulePaused`, `scheduleChange`, `scheduleResume`, `scheduleElapsedWhileArchived`).
+ * The commands printed "Scheduled ..." / "Resumed ..." / "unarchived" regardless, so a
+ * person could not tell that a time was recorded but nothing was armed (OSK-21521), that
+ * a slot which fell inside their pause was skipped (OSK-21513), or that a time which
+ * passed while a Task was archived was dropped rather than run (OSK-21494).
+ */
+type Instant = string | Date | null | undefined;
+export type ScheduleResult = {
+    schedulePaused?: {
+        pausedAt?: Instant;
+    };
+    scheduleChange?: {
+        changed?: boolean;
+        reason?: string;
+    };
+};
+/**
+ * Lines to print under `Scheduled task ...`. A paused series is told as such, with the one
+ * command that un-pauses it, because `schedule` never does.
+ */
+export declare function scheduleResultLines(result: ScheduleResult | null | undefined, taskRef: string, bin?: string): string[];
+export type ResumeResult = {
+    scheduleResume?: {
+        skippedScheduledFor?: Instant;
+        nextRunAt?: Instant;
+    };
+};
+/** What resuming did to the slot that fell inside the pause, or nothing when none did. */
+export declare function resumeResultLines(result: ResumeResult | null | undefined): string[];
+export type UnarchiveResult = {
+    scheduleElapsedWhileArchived?: {
+        skippedScheduledFor?: Instant;
+        nextRunAt?: Instant;
+    };
+};
+/** What unarchiving did to a schedule that came due while the Task was archived. */
+export declare function unarchiveResultLines(result: UnarchiveResult | null | undefined, taskRef: string, bin?: string): string[];
+/** At archive time: a kept time that will not fire while archived. */
+export declare function archiveResultLines(result: {
+    scheduledFor?: Instant;
+} | null | undefined): string[];
+export {};