@skrr-ai/cli 0.1.111 → 0.1.114

package/bin/update-npm-runner.cjs

@@ -3,9 +3,11 @@
 // Park before npm executes. The parent publishes this process group's durable
 // mutation ownership before authorizing execution, closing its crash window.
 const fs = require('node:fs');
+const path = require('node:path');
 const { spawn } = require('node:child_process');
 const requestFile = process.argv[2];
 const request = JSON.parse(fs.readFileSync(requestFile, 'utf8'));
+if (request.npmPrefix != null && !path.isAbsolute(request.npmPrefix)) throw new Error('Invalid npm prefix');
 const deadline = Date.now() + 30000;
 const timer = setInterval(() => {
   let authorization;
@@ -16,7 +18,8 @@ const timer = setInterval(() => {
   }
   if (authorization?.pid === process.pid && authorization?.token === request.token) {
     clearInterval(timer);
-    const child = spawn(request.npmPath, ['install', '-g', `@skrr-ai/cli@${request.version}`], {
+    const prefixArgs = request.npmPrefix ? ['--prefix', request.npmPrefix] : [];
+    const child = spawn(request.npmPath, ['install', '-g', ...prefixArgs, `@skrr-ai/cli@${request.version}`], {
       stdio: 'inherit',
       shell: process.platform === 'win32',
     });

package/bin/update-worker.cjs

@@ -41,7 +41,8 @@ async function run(directory, options = {}) {
     if (
       !/^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/.test(attempt.version) ||
       !path.isAbsolute(attempt.packageRoot) ||
-      !path.isAbsolute(attempt.npmPath)
+      !path.isAbsolute(attempt.npmPath) ||
+      (attempt.npmPrefix != null && !path.isAbsolute(attempt.npmPrefix))
     ) {
       throw new Error('Invalid persisted CLI update request');
     }
@@ -86,7 +87,8 @@ async function run(directory, options = {}) {
       });
       return;
     }
-    const rootResult = await execFileAsync(attempt.npmPath, ['root', '-g'], {
+    const prefixArgs = attempt.npmPrefix ? ['--prefix', attempt.npmPrefix] : [];
+    const rootResult = await execFileAsync(attempt.npmPath, ['root', '-g', ...prefixArgs], {
       timeout: 1500,
       maxBuffer: 64 * 1024,
       shell: process.platform === 'win32',
@@ -117,7 +119,8 @@ async function run(directory, options = {}) {
     await new Promise((resolve, reject) => {
       const requestFile = path.join(directory, `runner-${crypto.randomUUID()}.json`);
       const token = crypto.randomUUID();
-      runtime.writeJson(requestFile, { token, npmPath: attempt.npmPath, version: attempt.version });
+      runtime.writeJson(requestFile, { token, npmPath: attempt.npmPath, version: attempt.version,
+        ...(attempt.npmPrefix ? { npmPrefix: attempt.npmPrefix } : {}) });
       const child = spawn(
         process.execPath,
         [path.join(__dirname, 'update-npm-runner.cjs'), requestFile],

package/dist/commands/agents/create.d.ts

@@ -71,7 +71,8 @@ export declare function unappliedPayloadKeys(sent: Record<string, unknown>, crea
  * to claim a platform role that they had misspelled something.
  */
 export declare function unappliedPayloadKeysWarning(keys: readonly string[]): string;
-export declare function backgroundLoopLines(agentId: string, relationshipLoopsSkipped: boolean): string[];
+export declare function initialAutonomyReceipt(created: unknown, requested: unknown): boolean | 'unconfirmed';
+export declare function backgroundLoopLines(agentId: string, relationshipLoopsSkipped: boolean, initialAlwaysOn?: boolean | 'unconfirmed'): string[];
 /**
  * The flags `--from-spec` may be combined with: placement and identity for the
  * NEW row, which a spec document deliberately cannot carry (where an agent runs
@@ -96,6 +97,7 @@ export default class AgentsCreate extends BaseCommand {
         target: import("@oclif/core/lib/interfaces").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
         'next-target': import("@oclif/core/lib/interfaces").OptionFlag<string[] | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
         'working-directory': import("@oclif/core/lib/interfaces").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
+        'initial-always-on': import("@oclif/core/lib/interfaces").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
         'no-relationship-loops': import("@oclif/core/lib/interfaces").BooleanFlag<boolean>;
         'default-permission-mode': import("@oclif/core/lib/interfaces").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
         tools: import("@oclif/core/lib/interfaces").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;

package/dist/commands/agents/create.js

@@ -5,6 +5,7 @@ exports.agentCreateMissingFieldsMessage = agentCreateMissingFieldsMessage;
 exports.agentCreateMissingFields = agentCreateMissingFields;
 exports.unappliedPayloadKeys = unappliedPayloadKeys;
 exports.unappliedPayloadKeysWarning = unappliedPayloadKeysWarning;
+exports.initialAutonomyReceipt = initialAutonomyReceipt;
 exports.backgroundLoopLines = backgroundLoopLines;
 const core_1 = require("@oclif/core");
 const data_provider_1 = require("@skrr-ai/data-provider");
@@ -121,7 +122,25 @@ function unappliedPayloadKeysWarning(keys) {
     return (`The server did not keep ${keys.join(', ')}: ${one ? 'it is not an agent field' : 'they are not agent fields'}, ` +
         `or only the server sets ${one ? 'it' : 'them'}. \`skrr agents show <id> --json\` shows what the agent stores.`);
 }
-function backgroundLoopLines(agentId, relationshipLoopsSkipped) {
+function initialAutonomyReceipt(created, requested) {
+    if (requested !== false)
+        return true;
+    const provisioning = created && typeof created === 'object'
+        ? created.proactiveProvisioning : null;
+    return provisioning && typeof provisioning === 'object' &&
+        provisioning.initialAlwaysOn === false ? false : 'unconfirmed';
+}
+function backgroundLoopLines(agentId, relationshipLoopsSkipped, initialAlwaysOn = true) {
+    if (initialAlwaysOn === 'unconfirmed')
+        return [
+            'Passive creation was requested, but the server did not acknowledge it. Autonomous state is unconfirmed.',
+            `  skrr agents show ${agentId} --json   # inspect actual runtime state`,
+        ];
+    if (!initialAlwaysOn)
+        return [
+            'Passive creation acknowledged. Legacy task/memory scans were omitted. Explicit chats still run; Always-On can enable the seeded managed portfolio later.',
+            `  skrr agents always-on enable ${agentId}   # start autonomous work later`,
+        ];
     if (relationshipLoopsSkipped) {
         return [
             'Background loops: relationship portfolio skipped (--no-relationship-loops). ' +
@@ -156,6 +175,7 @@ exports.FROM_SPEC_COMPATIBLE_FLAGS = Object.freeze([
     'working-directory',
     'default-permission-mode',
     'no-relationship-loops',
+    'initial-always-on',
 ]);
 class AgentsCreate extends base_command_1.BaseCommand {
     static description = 'Create a new agent in the selected workspace, or in your default workspace when --workspace is omitted (`skrr workspaces list` names it)';
@@ -224,6 +244,10 @@ class AgentsCreate extends base_command_1.BaseCommand {
         'working-directory': core_1.Flags.string({
             description: 'Default working directory for local Harness sessions',
         }),
+        'initial-always-on': core_1.Flags.string({
+            description: 'Start autonomous work after creation (default: on). Use off for a passive agent; explicit chat still works. Relationship-loop seeding is configured separately.',
+            options: ['on', 'off'],
+        }),
         'no-relationship-loops': core_1.Flags.boolean({
             description: 'Single-purpose agent: skip the system-managed relationship portfolio (conversation continuity, relationship pulse, commitment incubator, open-loop closer). Self-reflection is still seeded.',
         }),
@@ -361,6 +385,7 @@ class AgentsCreate extends base_command_1.BaseCommand {
             // so an ordinary create carries no `relationshipLoops` key and the
             // server seeds the full portfolio exactly as it always has.
             relationshipLoops: flags['no-relationship-loops'] ? false : undefined,
+            initialAlwaysOn: flags['initial-always-on'] === undefined ? undefined : flags['initial-always-on'] === 'on',
         });
         // `mergeAgentConfigFlags` parses the typed flags (avatar, scene background,
         // working hours, every JSON flag). A parse failure is the caller's input, so
@@ -412,6 +437,7 @@ class AgentsCreate extends base_command_1.BaseCommand {
         // definition-field round-trip warning.
         const unapplied = unappliedPayloadKeys(payload, created, [
             'relationshipLoops',
+            'initialAlwaysOn',
             ...(0, agent_config_1.deprecatedFieldNames)(created),
         ]);
         for (const warning of (0, agent_config_1.deprecatedFieldsWarnings)(created))
@@ -426,6 +452,9 @@ class AgentsCreate extends base_command_1.BaseCommand {
             bin: this.config.bin,
             warn: (message) => this.warn(message),
         });
+        if (initialAutonomyReceipt(created, payload.initialAlwaysOn) === 'unconfirmed') {
+            this.warn('Passive creation was requested but not acknowledged by the server. Autonomous state is unconfirmed; inspect agents show before relying on it.');
+        }
         if (flags.json) {
             this.log(JSON.stringify((0, web_url_1.withAgentUrl)(this.cliConfig.baseURL, created), null, 2));
             return;
@@ -447,7 +476,7 @@ class AgentsCreate extends base_command_1.BaseCommand {
             this.log(`Avatar: ${(0, agent_visual_refs_1.agentAvatarLine)(a.avatar)}`);
             this.log('  Decided by your default-avatar policy — `skrr agents avatar default` shows or changes it.');
         }
-        for (const line of backgroundLoopLines(agentId, flags['no-relationship-loops'] === true)) {
+        for (const line of backgroundLoopLines(agentId, flags['no-relationship-loops'] === true, initialAutonomyReceipt(created, payload.initialAlwaysOn))) {
             this.log(line);
         }
         this.log(`URL: ${(0, web_url_1.withAgentUrl)(this.cliConfig.baseURL, a).url ?? '-'}`);
@@ -568,6 +597,7 @@ class AgentsCreate extends base_command_1.BaseCommand {
             workingDirectory: flags['working-directory'],
             defaultPermissionMode: flags['default-permission-mode'],
             relationshipLoops: flags['no-relationship-loops'] ? false : undefined,
+            initialAlwaysOn: flags['initial-always-on'] === undefined ? undefined : flags['initial-always-on'] === 'on',
         });
         let created;
         try {
@@ -605,6 +635,9 @@ class AgentsCreate extends base_command_1.BaseCommand {
                 details: { agentId, rolledBack: !rollback.includes('NOT'), issues: refusal?.issues },
             });
         }
+        if (initialAutonomyReceipt(created, payload.initialAlwaysOn) === 'unconfirmed') {
+            this.warn('Passive creation was requested but not acknowledged by the server. Autonomous state is unconfirmed; inspect agents show before relying on it.');
+        }
         if (flags.json) {
             this.log(JSON.stringify({
                 agent: (0, web_url_1.withAgentUrl)(this.cliConfig.baseURL, created),
@@ -628,7 +661,7 @@ class AgentsCreate extends base_command_1.BaseCommand {
             this.log(`Not taken from the file, because the server derives it from other fields: ${derived.join(', ')}.`);
         }
         this.log(`Keep the file in step: \`skrr agents push ${agentId} --file ${source === '-' ? '<file>' : source}\`.`);
-        for (const line of backgroundLoopLines(agentId, flags['no-relationship-loops'] === true)) {
+        for (const line of backgroundLoopLines(agentId, flags['no-relationship-loops'] === true, initialAutonomyReceipt(created, payload.initialAlwaysOn))) {
             this.log(line);
         }
         this.log(`URL: ${(0, web_url_1.withAgentUrl)(this.cliConfig.baseURL, created).url ?? '-'}`);

package/dist/commands/followups/plans/create.js

@@ -4,8 +4,10 @@ const core_1 = require("@oclif/core");
 const base_command_1 = require("../../../base-command");
 const prompt_1 = require("../../../lib/prompt");
 const lookbackPlans_1 = require("../../../lib/lookbackPlans");
+const lookbackPlanHelp_1 = require("../../../lib/lookbackPlanHelp");
 class LookbackPlansCreate extends base_command_1.BaseCommand {
-    static description = 'Schedule a bounded plan of 1–10 lookbacks, each free to stay silent';
+    static description = 'Schedule a bounded plan of 1–10 lookbacks, each free to stay silent\n\n' + lookbackPlanHelp_1.LOOKBACK_PLAN_INPUT_HELP +
+        '\n\nCreate also accepts {"agentId":"...","pinnedConversationId":"...","plan":{...}}. Source and delivery destination are separate; pin the original conversation to return there.';
     static examples = ['<%= config.bin %> followups plans create --from-json plan.json --agent agent_1 --json'];
     static flags = {
         'from-json': core_1.Flags.string({ description: 'Plan or create envelope JSON file; - reads stdin', required: true }),
@@ -20,7 +22,7 @@ class LookbackPlansCreate extends base_command_1.BaseCommand {
             body = (0, lookbackPlans_1.lookbackCreateBody)(await (0, prompt_1.readJsonBody)(flags['from-json']), flags.agent);
         }
         catch (err) {
-            this.failWithCliError({ message: err instanceof Error ? err.message : String(err), code: 'LOOKBACK_INVALID_FIELD', exit: 2, retryable: false });
+            this.failWithCliError((0, lookbackPlans_1.lookbackInputFailure)(err));
             return;
         }
         try {

package/dist/commands/followups/plans/example.d.ts

@@ -0,0 +1,6 @@
+import { BaseCommand } from '../../../base-command';
+export default class LookbackPlanExample extends BaseCommand {
+    static description: string;
+    static examples: string[];
+    run(): Promise<void>;
+}

package/dist/commands/followups/plans/example.js

@@ -0,0 +1,12 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const base_command_1 = require("../../../base-command");
+const lookbackPlanHelp_1 = require("../../../lib/lookbackPlanHelp");
+class LookbackPlanExample extends base_command_1.BaseCommand {
+    static description = 'Print an editable Plan JSON template without signing in\n\nReplace the source placeholders with a real completed assistant reply before creating a plan. This command schedules nothing.';
+    static examples = ['<%= config.bin %> followups plans example > plan.json'];
+    async run() {
+        this.log(JSON.stringify(lookbackPlanHelp_1.LOOKBACK_PLAN_EXAMPLE, null, 2));
+    }
+}
+exports.default = LookbackPlanExample;

package/dist/commands/followups/plans/revise.d.ts

@@ -1,6 +1,7 @@
 import { BaseCommand } from '../../../base-command';
 export default class LookbackPlansRevise extends BaseCommand {
     static description: string;
+    static examples: string[];
     static args: {
         id: import("@oclif/core/lib/interfaces").Arg<string, Record<string, unknown>>;
     };

package/dist/commands/followups/plans/revise.js

@@ -4,8 +4,11 @@ const core_1 = require("@oclif/core");
 const base_command_1 = require("../../../base-command");
 const prompt_1 = require("../../../lib/prompt");
 const lookbackPlans_1 = require("../../../lib/lookbackPlans");
+const lookbackPlanHelp_1 = require("../../../lib/lookbackPlanHelp");
 class LookbackPlansRevise extends base_command_1.BaseCommand {
-    static description = 'Revise pending lookbacks using the original source and step IDs';
+    static description = 'Revise pending lookbacks using the original source and step IDs\n\n' + lookbackPlanHelp_1.LOOKBACK_PLAN_INPUT_HELP +
+        '\n\nRevise accepts the plan itself, not a create envelope. Use the current --revision from show; a stale revision returns LOOKBACK_CONFLICT (409).';
+    static examples = ['<%= config.bin %> followups plans revise PLAN_ID --revision 1 --from-json revised-plan.json --json'];
     static args = { id: lookbackPlans_1.lookbackPlanIdArg };
     static flags = {
         revision: core_1.Flags.integer({ description: 'Expected current revision; stale edits are refused', min: 1, required: true }),
@@ -20,7 +23,7 @@ class LookbackPlansRevise extends base_command_1.BaseCommand {
             plan = (0, lookbackPlans_1.lookbackInput)(await (0, prompt_1.readJsonBody)(flags['from-json']), true);
         }
         catch (err) {
-            this.failWithCliError({ message: err instanceof Error ? err.message : String(err), code: 'LOOKBACK_INVALID_FIELD', exit: 2, retryable: false });
+            this.failWithCliError((0, lookbackPlans_1.lookbackInputFailure)(err));
             return;
         }
         try {

package/dist/commands/followups/remind.js

@@ -12,7 +12,7 @@ const agent_resolver_1 = require("../../lib/agent-resolver");
  * needs an agent context the passive form does not.
  */
 class FollowupsRemind extends base_command_1.BaseCommand {
-    static description = 'Remind the owner at a time — the reminder follow-up';
+    static description = 'Remind the owner at a time. By default, deliver the literal content through owner notifications without an agent turn. Use --active for agent-written delivery.';
     static examples = [
         '<%= config.bin %> followups remind --subject task:OSK-42 --content "pick the deploy up" --in 2h',
         '<%= config.bin %> followups remind --subject conversation:conv_9 --content "ask how the move went" --at 2026-09-20T09:00:00Z --active --agent agent_1',
@@ -34,15 +34,23 @@ class FollowupsRemind extends base_command_1.BaseCommand {
             description: 'Wake the agent to word the reminder (needs an agent context)',
             default: false,
         }),
-        agent: core_1.Flags.string({ description: 'Agent ID (default: bound session agent)' }),
-        endpoint: core_1.Flags.string({ description: 'Delivery endpoint id (EndpointRegistry)' }),
-        'endpoint-target': core_1.Flags.string({ description: 'Channel target for channel endpoints' }),
-        pin: core_1.Flags.string({ description: 'Conversation id the reminder was authored in' }),
+        agent: core_1.Flags.string({ description: 'Agent ID (default: bound session agent). Attribution only unless --active is set' }),
+        endpoint: core_1.Flags.string({ description: 'Active only: delivery endpoint id; requires --active' }),
+        'endpoint-target': core_1.Flags.string({ description: 'Active only: channel target for a channel endpoint; requires --active' }),
+        pin: core_1.Flags.string({ description: 'Active only: deliver into this conversation; requires --active. Do not combine with --endpoint other than pinned' }),
         json: core_1.Flags.boolean({ description: 'Output as JSON' }),
     };
     async run() {
         this.requireAuth();
         const { flags } = await this.parse(FollowupsRemind);
+        if (!flags.active && (flags.endpoint || flags['endpoint-target'] || flags.pin)) {
+            this.failWithCliError({
+                message: '--endpoint, --endpoint-target and --pin require --active. For a passive reminder, remove these flags; the literal content is delivered through owner notifications without an agent turn. --agent alone records attribution.',
+                code: 'FOLLOWUP_INVALID_ENDPOINT',
+                exit: 2,
+                retryable: false,
+            });
+        }
         const at = flags.at ?? flags.in;
         if (!at) {
             this.failWithCliError({

package/dist/commands/followups/watch.js

@@ -83,9 +83,9 @@ class FollowupsWatch extends base_command_1.BaseCommand {
             description: 'SLA backstop — required for --wait event (an event may never arrive), optional for poll_until',
         }),
         // delivery
-        endpoint: core_1.Flags.string({ description: 'Delivery endpoint id (EndpointRegistry)' }),
+        endpoint: core_1.Flags.string({ description: 'Delivery endpoint id (defaults to main). Use --pin to deliver into a specific conversation' }),
         'endpoint-target': core_1.Flags.string({ description: 'Channel target for channel endpoints' }),
-        pin: core_1.Flags.string({ description: 'Conversation id the watch was authored in' }),
+        pin: core_1.Flags.string({ description: 'Deliver into this conversation. Do not combine with --endpoint other than pinned' }),
         json: core_1.Flags.boolean({ description: 'Output as JSON' }),
     };
     async run() {

package/dist/lib/lookbackPlanHelp.d.ts

@@ -0,0 +1,19 @@
+/** Authored input, not a copy of the server's normalized Plan projection. */
+export declare const LOOKBACK_PLAN_EXAMPLE: {
+    objective: string;
+    stopCondition: string;
+    source: {
+        conversationId: string;
+        messageId: string;
+        replyCompletedAt: string;
+    };
+    steps: {
+        id: string;
+        instruction: string;
+        when: {
+            kind: string;
+            offset: string;
+        };
+    }[];
+};
+export declare const LOOKBACK_PLAN_INPUT_HELP: string;

package/dist/lib/lookbackPlanHelp.js

@@ -0,0 +1,27 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LOOKBACK_PLAN_INPUT_HELP = exports.LOOKBACK_PLAN_EXAMPLE = void 0;
+/** Authored input, not a copy of the server's normalized Plan projection. */
+exports.LOOKBACK_PLAN_EXAMPLE = {
+    objective: 'Check deployment health',
+    stopCondition: 'Deployment is ready or the owner cancels',
+    source: {
+        conversationId: 'YOUR_CONVERSATION_ID',
+        messageId: 'YOUR_COMPLETED_ASSISTANT_MESSAGE_ID',
+        replyCompletedAt: 'ACTUAL_REPLY_COMPLETION_ISO_TIMESTAMP',
+    },
+    steps: [{
+            id: 'health-check',
+            instruction: 'Read the latest original conversation. Report readiness once; otherwise stay silent.',
+            when: { kind: 'relative', offset: '10m' },
+        }],
+};
+exports.LOOKBACK_PLAN_INPUT_HELP = [
+    'Input is authored Plan JSON with objective, stopCondition, source and 1–10 steps. Generate an editable JSON file:',
+    'skrr followups plans example > plan.json',
+    'Replace the three source placeholders with a real completed assistant reply belonging to this agent. `skrr convos messages <conversation-id> --json` reads its messageId and completion updatedAt. Never use the current clock as a replacement anchor.',
+    'Relative time is measured from source.replyCompletedAt, not command invocation. Choose an offset whose resulting time is still in the future.',
+    'Each when supports {"kind":"relative","offset":"10m"}, {"kind":"absolute","at":"2026-10-21T12:00:00Z"}, or {"kind":"local","dateTime":"2026-10-21T09:00:00","timezone":"America/Los_Angeles"}. Replace example dates with future dates. Absolute time requires Z or a UTC offset; ambiguous/nonexistent local DST times are refused.',
+    'Optional fields: title, timezone; per step: id, label, expiresAfter (for example "1h"). Revision retains the exact source and existing step IDs. Do not submit the show response unchanged: remove lifecycle fields such as state, runAt and expiresAt.',
+    'A check may remain silent. Only armed:true confirms timer registration; saved/pending is not armed. Full guide is shipped at docs/v1/lookback-plans.md in the installed CLI package.',
+].join('\n\n');

package/dist/lib/lookbackPlans.d.ts

@@ -1,5 +1,14 @@
 import { lookbackPlansApi, type CreateLookbackPlanRequest, type LookbackPlan, type LookbackPlanInput } from '@skrr-ai/data-provider';
 export { lookbackPlansApi };
+export declare function lookbackInputFailure(error: unknown): {
+    exit: number;
+    retryable: boolean;
+    details?: {
+        field: string;
+    } | undefined;
+    code: "LOOKBACK_INVALID_FIELD" | "LOOKBACK_INVALID_TIME" | "LOOKBACK_INVALID_TIMEZONE" | "LOOKBACK_AMBIGUOUS_TIME" | "LOOKBACK_NONEXISTENT_TIME" | "LOOKBACK_LIMIT_EXCEEDED";
+    message: string;
+};
 export declare const lookbackPlanIdArg: import("@oclif/core/lib/interfaces").Arg<string, Record<string, unknown>>;
 /** JSON can be the plan itself or the canonical create envelope. Never copy identity fields. */
 export declare function lookbackCreateBody(input: Record<string, unknown>, explicitAgentId?: string): CreateLookbackPlanRequest;

package/dist/lib/lookbackPlans.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.lookbackPlanIdArg = exports.lookbackPlansApi = void 0;
+exports.lookbackInputFailure = lookbackInputFailure;
 exports.lookbackCreateBody = lookbackCreateBody;
 exports.lookbackInput = lookbackInput;
 exports.lookbackPlanSummary = lookbackPlanSummary;
@@ -9,6 +10,22 @@ const core_1 = require("@oclif/core");
 const data_provider_1 = require("@skrr-ai/data-provider");
 Object.defineProperty(exports, "lookbackPlansApi", { enumerable: true, get: function () { return data_provider_1.lookbackPlansApi; } });
 const followups_1 = require("./followups");
+class LookbackValidationError extends Error {
+    issue;
+    constructor(issue) {
+        super(`${issue.code}: ${issue.field}: ${issue.message}`);
+        this.issue = issue;
+    }
+}
+function lookbackInputFailure(error) {
+    return {
+        code: error instanceof LookbackValidationError ? error.issue.code : 'LOOKBACK_INVALID_FIELD',
+        message: error instanceof Error ? error.message : String(error),
+        ...(error instanceof LookbackValidationError ? { details: { field: error.issue.field } } : {}),
+        exit: 2,
+        retryable: false,
+    };
+}
 exports.lookbackPlanIdArg = core_1.Args.string({
     description: 'Lookback plan id', required: true, ignoreStdin: true,
     parse: async (value) => {
@@ -52,7 +69,7 @@ function lookbackCreateBody(input, explicitAgentId) {
 function lookbackInput(raw, allowPast = false) {
     const parsed = (0, data_provider_1.normalizeLookbackPlanInput)(raw, { allowPast });
     if (!parsed.ok)
-        throw new Error(`${parsed.code}: ${parsed.message}`);
+        throw new LookbackValidationError(parsed);
     // Send only authored fields. The server fixes normalized times, generated
     // step IDs, lifecycle and ownership; CLI must not forge those projections.
     return raw;
@@ -63,6 +80,9 @@ function lookbackPlanSummary(plan) {
         `  ${plan.steps.length} lookbacks${next ? `  next:${next.runAt}` : ''}`;
 }
 function lookbackArmingLine(result) {
+    if (['cancelled', 'completed', 'failed'].includes(result.plan.state)) {
+        return `Lookback plan ${result.plan.id}: ${result.plan.state} (r${result.plan.revision})${result.reused ? ' (existing plan)' : ''}.`;
+    }
     const status = result.armed ? 'armed' : 'saved; scheduling is pending';
     return `Lookback plan ${result.plan.id} ${status}${result.reused ? ' (existing plan)' : ''}.`;
 }

package/dist/lib/update-check.d.ts

@@ -1,4 +1,9 @@
 export type CliInstallKind = 'npm-global' | 'npm-local' | 'dev' | 'bundled' | 'image' | 'homebrew' | 'other';
+export interface CliInstallDescriptor {
+    kind: CliInstallKind;
+    writable?: boolean;
+    npmPrefix?: string;
+}
 export interface CliUpdateAttempt {
     status: 'queued' | 'running' | 'succeeded' | 'failed';
     version: string;
@@ -10,6 +15,7 @@ export interface CliUpdateAttempt {
     message?: string;
     packageRoot?: string;
     npmPath?: string;
+    npmPrefix?: string;
     coordinationVersion?: number;
     workerPid?: number;
     interrupted?: boolean;
@@ -19,10 +25,7 @@ export interface CheckCache {
     latest: string | null;
     npmPackage: string | null;
     baseURL: string;
-    install?: {
-        kind: CliInstallKind;
-        writable?: boolean;
-    };
+    install?: CliInstallDescriptor;
     packageRoot?: string;
     npmGlobalRoot?: string | null;
     autoUpdate?: {
@@ -45,6 +48,7 @@ export interface CliUpdateStatus {
     installedVersion: string | null;
     offeredVersion: string | null;
     owner: CliInstallKind;
+    npmPrefix?: string;
     state: 'up-to-date' | 'update-available' | 'pending' | 'restart-pending' | 'failed' | 'managed' | 'unknown' | 'check-failed';
     autoUpdateAllowed: boolean;
     autoUpdateReason: string | null;
@@ -76,12 +80,9 @@ export declare function resolveCliPackageDir(argv?: readonly string[]): string |
  * dir beside `dist` exists only in a checkout — published packages ship
  * `dist` and no `src`.
  */
-export declare function classifyCliInstall(env: NodeJS.ProcessEnv, argv: readonly string[], npmGlobalRoot: string | null, probeWritable?: boolean): {
-    kind: CliInstallKind;
-    writable?: boolean;
-};
-export declare function cliUpdateCommand(owner: CliInstallKind): string;
-export declare function buildNudgeLine(currentVersion: string, latest: string | null, _npmPackage: string | null, installKind?: CliInstallKind): string | null;
+export declare function classifyCliInstall(env: NodeJS.ProcessEnv, argv: readonly string[], npmGlobalRoot: string | null, probeWritable?: boolean): CliInstallDescriptor;
+export declare function cliUpdateCommand(owner: CliInstallKind, npmPrefix?: string): string;
+export declare function buildNudgeLine(currentVersion: string, latest: string | null, _npmPackage: string | null, installKind?: CliInstallKind, npmPrefix?: string): string | null;
 export type CliUpdateAction = {
     type: 'nudge';
     line: string;

package/dist/lib/update-check.js

@@ -207,6 +207,20 @@ function classifyCliInstall(env, argv, npmGlobalRoot, probeWritable = true) {
         return { kind: 'other' };
     }
     const nodeModulesDir = path.dirname(path.dirname(packageDir)); // …/node_modules
+    const npmPrefix = process.platform !== 'win32' && path.basename(path.dirname(nodeModulesDir)) === 'lib'
+        ? path.dirname(path.dirname(nodeModulesDir)) : undefined;
+    // npm's current default may differ from the prefix that installed this
+    // executable. A project directory named `lib` is insufficient evidence:
+    // the prefix's public bin must resolve to this exact installed entry.
+    let linkedGlobalPrefix = false;
+    if (npmPrefix) {
+        try {
+            linkedGlobalPrefix = !fs.existsSync(path.join(npmPrefix, 'package.json')) &&
+                fs.realpathSync(path.join(npmPrefix, 'bin', 'skrr')) ===
+                    fs.realpathSync(path.join(packageDir, 'bin', 'run.js'));
+        }
+        catch { /* no executable ownership proof */ }
+    }
     if (npmGlobalRoot) {
         let resolvedGlobal = npmGlobalRoot;
         try {
@@ -222,15 +236,13 @@ function classifyCliInstall(env, argv, npmGlobalRoot, probeWritable = true) {
         catch {
             /* compare the raw form */
         }
-        if (resolvedNodeModules !== resolvedGlobal)
+        if (resolvedNodeModules !== resolvedGlobal && !linkedGlobalPrefix)
             return { kind: 'npm-local' };
     }
-    else if (!/[/\\](lib|npm)[/\\]node_modules$/.test(nodeModulesDir)) {
+    else if (!linkedGlobalPrefix) {
         // `npm root -g` gave no answer, so prove the global shape from the path
-        // instead: npm's unix global root is always `<prefix>/lib/node_modules`
-        // (incl. nvm/volta) and on Windows `%APPDATA%\npm\node_modules`. A
-        // project-local `<project>/node_modules` never matches either — without
-        // proof we must not treat it as ours to auto-update.
+        // and matching public executable instead. Without ownership proof we
+        // must not treat a project's dependency as ours to auto-update.
         return { kind: 'npm-local' };
     }
     let writable = false;
@@ -245,7 +257,7 @@ function classifyCliInstall(env, argv, npmGlobalRoot, probeWritable = true) {
             /* read-only */
         }
     }
-    return { kind: 'npm-global', writable };
+    return { kind: 'npm-global', writable, ...(npmPrefix ? { npmPrefix } : {}) };
 }
 /**
  * Resolve `npm root -g` for install classification. Runs ONLY inside the
@@ -269,12 +281,14 @@ async function resolveNpmGlobalRoot(env = process.env) {
         return null;
     }
 }
-function cliUpdateCommand(owner) {
+function cliUpdateCommand(owner, npmPrefix) {
     switch (owner) {
         case 'npm-global':
-            return `npm install -g ${CLI_PACKAGE}@latest`;
+            return npmPrefix
+                ? `npm install --global --prefix '${npmPrefix.replace(/'/g, "'\\''")}' ${CLI_PACKAGE}@latest`
+                : `npm install -g ${CLI_PACKAGE}@latest`;
         case 'npm-local':
-            return `npm update ${CLI_PACKAGE}`;
+            return `Use npm in the project that owns ${CLI_PACKAGE}`;
         case 'dev':
             return 'npm --prefix cli run build';
         case 'bundled':
@@ -287,16 +301,18 @@ function cliUpdateCommand(owner) {
             return 'Update via your install method — see https://skrr.ai';
     }
 }
-function buildNudgeLine(currentVersion, latest, _npmPackage, installKind = 'npm-global') {
+function buildNudgeLine(currentVersion, latest, _npmPackage, installKind = 'npm-global', npmPrefix) {
     if (!latest || !isOlderVersion(currentVersion, latest))
         return null;
-    const command = installKind === 'npm-global' ? `npm update -g ${CLI_PACKAGE}` : cliUpdateCommand(installKind);
-    const context = installKind === 'npm-local'
-        ? ' in the owning project'
-        : installKind === 'dev'
-            ? ' to rebuild your checkout'
-            : '';
-    return `[skrr] Update available: ${currentVersion} → ${latest}. Run \`${command}\`${context}. Silence with OVERSKY_NO_UPDATE_NUDGE=1.\n`;
+    const command = installKind === 'npm-global' && !npmPrefix
+        ? `npm update -g ${CLI_PACKAGE}` : cliUpdateCommand(installKind, npmPrefix);
+    const context = installKind === 'dev'
+        ? ' to rebuild your checkout'
+        : '';
+    const advice = installKind === 'npm-local'
+        ? `Update ${CLI_PACKAGE} using the project that owns ${CLI_PACKAGE}.`
+        : `Run \`${command}\`${context}.`;
+    return `[skrr] Update available: ${currentVersion} → ${latest}. ${advice} Silence with OVERSKY_NO_UPDATE_NUDGE=1.\n`;
 }
 function decideCliUpdateAction(args) {
     const { currentVersion, cache, env, isTTY } = args;
@@ -327,10 +343,10 @@ function decideCliUpdateAction(args) {
         if (attempt?.status === 'failed')
             return {
                 type: 'nudge',
-                line: `[skrr] CLI update to ${cache.latest} failed. Inspect \`skrr update --status\` or run \`${cliUpdateCommand(install.kind)}\`.\n`,
+                line: `[skrr] CLI update to ${cache.latest} failed. Inspect \`skrr update --status\` or run \`${cliUpdateCommand(install.kind, install.npmPrefix)}\`.\n`,
             };
     }
-    const line = buildNudgeLine(currentVersion, cache.latest, CLI_PACKAGE, install.kind);
+    const line = buildNudgeLine(currentVersion, cache.latest, CLI_PACKAGE, install.kind, install.npmPrefix);
     return line ? { type: 'nudge', line } : null;
 }
 function readCache(env = process.env) {
@@ -462,10 +478,11 @@ function readCliUpdateStatus(opts) {
         installedVersion,
         offeredVersion,
         owner: install.kind,
+        ...(install.npmPrefix ? { npmPrefix: install.npmPrefix } : {}),
         state,
         autoUpdateAllowed: autoUpdateReason === null,
         autoUpdateReason,
-        command: cliUpdateCommand(install.kind),
+        command: cliUpdateCommand(install.kind, install.npmPrefix),
         lastCheckAt: matchingCache?.lastCheckAt ?? null,
         lastAttempt,
         logPath: path.join(directory, 'update.log'),
@@ -591,7 +608,7 @@ async function performCliUpdate(opts) {
         env.SKRR_CLI_UPDATE_SESSION_UNAVAILABLE === '1') {
         return {
             ...status,
-            message: `This CLI is owned by ${install.kind}${install.kind === 'npm-global' ? ' in a shared or external prefix' : ''}. ${cliUpdateCommand(install.kind)}.`,
+            message: `This CLI is owned by ${install.kind}${install.kind === 'npm-global' ? ' in a shared or external prefix' : ''}. ${cliUpdateCommand(install.kind, install.npmPrefix)}.`,
         };
     }
     const recoverableAttempt = status.lastAttempt && ['queued', 'running'].includes(status.lastAttempt.status);
@@ -620,6 +637,7 @@ async function performCliUpdate(opts) {
                 attemptedAt: Date.now(),
                 packageRoot: packageRoot(argv),
                 npmPath,
+                ...(install.npmPrefix ? { npmPrefix: install.npmPrefix } : {}),
                 coordinationVersion: api.COORDINATION_VERSION,
                 message: 'Waiting for active CLI sessions to exit; the next invocation uses the new version.',
             });
@@ -649,7 +667,7 @@ async function maybeWarnOutdatedCli(opts) {
             currentVersion: opts.currentVersion,
             cache: {
                 ...cache,
-                install: { kind: status.owner, writable: status.autoUpdateAllowed },
+                install: { kind: status.owner, writable: status.autoUpdateAllowed, npmPrefix: status.npmPrefix },
                 autoUpdate: status.lastAttempt
                     ? {
                         attemptedAt: status.lastAttempt.attemptedAt,