@skrr-ai/cli 0.1.36 → 0.1.37

package/dist/commands/agents/unmute.js

@@ -0,0 +1,38 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const core_1 = require("@oclif/core");
+const base_command_1 = require("../../base-command");
+const agent_pin_mute_1 = require("../../lib/agent-pin-mute");
+/**
+ * Per-USER preference, not agent config: it changes your view of the agent and
+ * nobody else's. Idempotent over a toggle endpoint — see `lib/agent-pin-mute.ts`.
+ */
+class AgentsUnmute extends base_command_1.BaseCommand {
+    static description = "Un-silence an agent's notifications for you";
+    static examples = ['<%= config.bin %> agents unmute <agent-id>'];
+    static args = {
+        id: core_1.Args.string({ description: 'Agent ID', required: true, ignoreStdin: true }),
+    };
+    static flags = {
+        json: core_1.Flags.boolean({ description: 'Output as JSON' }),
+    };
+    async run() {
+        this.requireAuth();
+        const { args, flags } = await this.parse(AgentsUnmute);
+        let result;
+        try {
+            result = await (0, agent_pin_mute_1.setAgentFlag)(args.id, 'mute', false);
+        }
+        catch (err) {
+            this.handleApiError(err);
+        }
+        if (flags.json) {
+            this.log(this.agentJson(args.id, { mute: result.value, changed: result.changed }));
+            return;
+        }
+        this.log(result.changed
+            ? `Agent ${args.id}: mute is now ${result.value}`
+            : `Agent ${args.id}: mute was already ${result.value} — nothing to do`);
+    }
+}
+exports.default = AgentsUnmute;

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

@@ -0,0 +1,16 @@
+import { BaseCommand } from '../../base-command';
+/**
+ * Per-USER preference, not agent config: it changes your view of the agent and
+ * nobody else's. Idempotent over a toggle endpoint — see `lib/agent-pin-mute.ts`.
+ */
+export default class AgentsUnpin extends BaseCommand {
+    static description: string;
+    static examples: string[];
+    static args: {
+        id: import("@oclif/core/lib/interfaces").Arg<string, Record<string, unknown>>;
+    };
+    static flags: {
+        json: import("@oclif/core/lib/interfaces").BooleanFlag<boolean>;
+    };
+    run(): Promise<void>;
+}

package/dist/commands/agents/unpin.js

@@ -0,0 +1,38 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const core_1 = require("@oclif/core");
+const base_command_1 = require("../../base-command");
+const agent_pin_mute_1 = require("../../lib/agent-pin-mute");
+/**
+ * Per-USER preference, not agent config: it changes your view of the agent and
+ * nobody else's. Idempotent over a toggle endpoint — see `lib/agent-pin-mute.ts`.
+ */
+class AgentsUnpin extends base_command_1.BaseCommand {
+    static description = 'Remove an agent from your pinned list';
+    static examples = ['<%= config.bin %> agents unpin <agent-id>'];
+    static args = {
+        id: core_1.Args.string({ description: 'Agent ID', required: true, ignoreStdin: true }),
+    };
+    static flags = {
+        json: core_1.Flags.boolean({ description: 'Output as JSON' }),
+    };
+    async run() {
+        this.requireAuth();
+        const { args, flags } = await this.parse(AgentsUnpin);
+        let result;
+        try {
+            result = await (0, agent_pin_mute_1.setAgentFlag)(args.id, 'pin', false);
+        }
+        catch (err) {
+            this.handleApiError(err);
+        }
+        if (flags.json) {
+            this.log(this.agentJson(args.id, { pin: result.value, changed: result.changed }));
+            return;
+        }
+        this.log(result.changed
+            ? `Agent ${args.id}: pin is now ${result.value}`
+            : `Agent ${args.id}: pin was already ${result.value} — nothing to do`);
+    }
+}
+exports.default = AgentsUnpin;

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

@@ -40,6 +40,18 @@ export default class AgentsUpdate extends BaseCommand {
         'hide-sequential-outputs': import("@oclif/core/lib/interfaces").BooleanFlag<boolean>;
         'is-collaborative': import("@oclif/core/lib/interfaces").BooleanFlag<boolean>;
         'recursion-limit': import("@oclif/core/lib/interfaces").OptionFlag<number | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
+        avatar: import("@oclif/core/lib/interfaces").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
+        'conversation-starter': import("@oclif/core/lib/interfaces").OptionFlag<string[] | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
+        'todo-working-hours': import("@oclif/core/lib/interfaces").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
+        'reasoning-tool-escape': import("@oclif/core/lib/interfaces").OptionFlag<string[] | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
+        'commitment-responsibility': import("@oclif/core/lib/interfaces").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
+        'commitment-responsibility-ceiling': import("@oclif/core/lib/interfaces").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
+        'max-turns': import("@oclif/core/lib/interfaces").OptionFlag<number | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
+        'tool-resources': import("@oclif/core/lib/interfaces").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
+        'install-channel': import("@oclif/core/lib/interfaces").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
+        'auto-minor-updates': import("@oclif/core/lib/interfaces").BooleanFlag<boolean>;
+        'project-id': import("@oclif/core/lib/interfaces").OptionFlag<string[] | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
+        'remove-project-id': import("@oclif/core/lib/interfaces").OptionFlag<string[] | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
     };
     run(): Promise<void>;
 }

package/dist/commands/agents/update.js

@@ -32,7 +32,9 @@ class AgentsUpdate extends base_command_1.BaseCommand {
         }),
         provider: core_1.Flags.string({ description: 'New provider' }),
         model: core_1.Flags.string({ description: 'New model' }),
-        category: core_1.Flags.string({ description: 'New category' }),
+        category: core_1.Flags.string({
+            description: 'New category. `skrr agents categories` lists what this account accepts.',
+        }),
         target: core_1.Flags.string({
             description: 'Execution target. Use a Harness id, Hosted Machine session, or Agent Worker. Use hosted-machine, sbs_..., agent-worker, or a connected Harness id.',
         }),
@@ -54,7 +56,10 @@ class AgentsUpdate extends base_command_1.BaseCommand {
         'network-agent-ids': core_1.Flags.string({ description: 'Network agent IDs JSON array' }),
         'network-include-public': core_1.Flags.boolean({ description: 'Include public agents in network' }),
         'character-3d-id': core_1.Flags.string({ description: '3D character ID' }),
-        'scene-background': core_1.Flags.string({ description: 'Scene background' }),
+        'scene-background': core_1.Flags.string({
+            description: 'Backdrop for the 3D view: default, preset:<id>, or image:<filepath>@<source>. ' +
+                'A bare string is refused — the stored field is a typed reference, not a name.',
+        }),
         'tone-mode': core_1.Flags.string({ description: 'Tone mode' }),
         'tone-id': core_1.Flags.string({ description: 'Tone ID' }),
         'tone-notes': core_1.Flags.string({ description: 'Per-agent tone notes' }),
@@ -72,6 +77,53 @@ class AgentsUpdate extends base_command_1.BaseCommand {
         'hide-sequential-outputs': core_1.Flags.boolean({ description: 'Hide sequential outputs' }),
         'is-collaborative': core_1.Flags.boolean({ description: 'Enable collaboration' }),
         'recursion-limit': core_1.Flags.integer({ description: 'Agent recursion limit' }),
+        avatar: core_1.Flags.string({
+            description: "The agent's face, as a reference rather than a file: default, preset:<id> " +
+                '(`skrr agents avatar presets`), asset:<id> (`skrr agents avatar library`), or ' +
+                'image:<filepath>@<source>. To upload a new image use `skrr agents avatar upload`.',
+        }),
+        'conversation-starter': core_1.Flags.string({
+            description: 'Suggested opening prompt shown on the agent (repeatable; replaces the list)',
+            multiple: true,
+        }),
+        'todo-working-hours': core_1.Flags.string({
+            description: 'When this agent schedules its own work: HH:MM-HH:MM[@<IANA timezone>], e.g. ' +
+                '09:00-18:00@America/Los_Angeles',
+        }),
+        'reasoning-tool-escape': core_1.Flags.string({
+            description: 'Tool a reasoning-only turn may still use (repeatable; replaces the list). ' +
+                'These are ESCAPES, not a fenced tool surface.',
+            options: [...agent_config_1.REASONING_TOOL_ESCAPES],
+            multiple: true,
+        }),
+        'commitment-responsibility': core_1.Flags.string({
+            description: "Default work authority for this agent's commitments",
+            options: [...agent_config_1.COMMITMENT_RESPONSIBILITY_LEVELS],
+        }),
+        'commitment-responsibility-ceiling': core_1.Flags.string({
+            description: 'Ceiling a commitment may not exceed, whatever it asks for',
+            options: [...agent_config_1.COMMITMENT_RESPONSIBILITY_LEVELS],
+        }),
+        'max-turns': core_1.Flags.integer({ description: 'Maximum turns in one agent run (1-500)' }),
+        'tool-resources': core_1.Flags.string({
+            description: 'Tool resources JSON object (file_search / context / image_edit bindings)',
+        }),
+        'install-channel': core_1.Flags.string({
+            description: 'Release policy: which channel installs of this agent follow',
+            options: [...agent_config_1.RELEASE_INSTALL_CHANNELS],
+        }),
+        'auto-minor-updates': core_1.Flags.boolean({
+            description: 'Release policy: allow installs to take minor updates automatically',
+            allowNo: true,
+        }),
+        'project-id': core_1.Flags.string({
+            description: 'Prompt-store project this agent belongs to (repeatable)',
+            multiple: true,
+        }),
+        'remove-project-id': core_1.Flags.string({
+            description: 'Prompt-store project to detach this agent from (repeatable)',
+            multiple: true,
+        }),
     };
     async run() {
         this.requireAuth();
@@ -107,7 +159,16 @@ class AgentsUpdate extends base_command_1.BaseCommand {
             workingDirectory: flags['working-directory'],
             defaultPermissionMode: flags['default-permission-mode'],
         });
-        payload = (0, agent_config_1.mergeAgentConfigFlags)(payload, flags);
+        // `mergeAgentConfigFlags` parses the typed flags (avatar, scene background,
+        // working hours, every JSON flag). A parse failure is the caller's input, so
+        // it is reported as a CLI error with the accepted forms — not as an unhandled
+        // throw, and not as a 400 from the server naming a zod path.
+        try {
+            payload = (0, agent_config_1.mergeAgentConfigFlags)(payload, flags);
+        }
+        catch (err) {
+            this.error(err.message, { exit: 1 });
+        }
         if (Object.keys(payload).length === 0) {
             this.error('Nothing to update. Pass at least one flag (e.g. --name) or --from-json.', {
                 exit: 1,

package/dist/commands/followups/act.d.ts

@@ -0,0 +1,22 @@
+import { BaseCommand } from '../../base-command';
+/**
+ * `skrr followups act` — an `act` follow-up: a typed built-in action at a
+ * time, for an action already exactly known and already agreed to.
+ */
+export default class FollowupsAct extends BaseCommand {
+    static description: string;
+    static examples: string[];
+    static flags: {
+        subject: import("@oclif/core/lib/interfaces").OptionFlag<string, import("@oclif/core/lib/interfaces").CustomOptions>;
+        why: import("@oclif/core/lib/interfaces").OptionFlag<string, import("@oclif/core/lib/interfaces").CustomOptions>;
+        action: import("@oclif/core/lib/interfaces").OptionFlag<string, import("@oclif/core/lib/interfaces").CustomOptions>;
+        at: import("@oclif/core/lib/interfaces").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
+        in: import("@oclif/core/lib/interfaces").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
+        agent: import("@oclif/core/lib/interfaces").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
+        endpoint: import("@oclif/core/lib/interfaces").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
+        'endpoint-target': import("@oclif/core/lib/interfaces").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
+        pin: import("@oclif/core/lib/interfaces").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
+        json: import("@oclif/core/lib/interfaces").BooleanFlag<boolean>;
+    };
+    run(): Promise<void>;
+}

package/dist/commands/followups/act.js

@@ -0,0 +1,102 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const core_1 = require("@oclif/core");
+const base_command_1 = require("../../base-command");
+const followups_1 = require("../../lib/followups");
+const agent_resolver_1 = require("../../lib/agent-resolver");
+const triggers_1 = require("../../lib/triggers");
+/**
+ * `skrr followups act` — an `act` follow-up: a typed built-in action at a
+ * time, for an action already exactly known and already agreed to.
+ */
+class FollowupsAct extends base_command_1.BaseCommand {
+    static description = 'Run an agreed action at a time — the act follow-up';
+    static examples = [
+        '<%= config.bin %> followups act --subject task:OSK-42 --why "user approved the merge" --action \'{"builtinType":"task_merge","config":{"taskId":"OSK-42"}}\' --at 2026-09-20T09:00:00Z',
+    ];
+    static flags = {
+        subject: core_1.Flags.string({ description: 'Subject ref: type:externalKey', required: true }),
+        why: core_1.Flags.string({ description: 'Why this wake exists, in one line', required: true }),
+        action: core_1.Flags.string({
+            description: 'Action payload JSON: {"builtinType": "...", "config": {...}, "refId?": "..."}',
+            required: true,
+        }),
+        at: core_1.Flags.string({ description: 'ISO-8601 instant to act at', exclusive: ['in'] }),
+        in: core_1.Flags.string({ description: 'Duration from now (2h, 3d)', exclusive: ['at'] }),
+        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 act was authored in' }),
+        json: core_1.Flags.boolean({ description: 'Output as JSON' }),
+    };
+    async run() {
+        this.requireAuth();
+        const { flags } = await this.parse(FollowupsAct);
+        const at = flags.at ?? flags.in;
+        if (!at) {
+            this.failWithCliError({
+                message: 'Either --at <iso> or --in <duration> is required.',
+                code: 'FOLLOWUP_KIND_FIELD_MISSING',
+                exit: 2,
+                retryable: false,
+            });
+        }
+        const action = (0, triggers_1.parseJsonObject)(flags.action, '--action');
+        if (typeof action?.builtinType !== 'string' || !action.builtinType) {
+            this.failWithCliError({
+                message: '--action needs a builtinType: {"builtinType": "...", "config": {...}}.',
+                code: 'FOLLOWUP_KIND_FIELD_MISSING',
+                exit: 2,
+                retryable: false,
+            });
+        }
+        let agent;
+        try {
+            agent = (0, followups_1.resolveFollowUpAgent)(flags.agent);
+        }
+        catch (err) {
+            const failure = (0, agent_resolver_1.agentResolutionFailure)(err);
+            this.failWithCliError({
+                message: failure.message,
+                code: failure.code,
+                exit: 2,
+                retryable: false,
+                details: { suggestion: failure.suggestion, context: failure.details },
+            });
+        }
+        let response;
+        try {
+            response = await followups_1.followupsApi.create({
+                kind: 'act',
+                producer: agent.boundToSession ? 'agent_in_turn' : 'user_explicit',
+                agentId: agent.id,
+                subject: (0, followups_1.parseSubjectRef)(flags.subject),
+                why: flags.why,
+                action,
+                at,
+                ...(flags.endpoint ? { endpointId: flags.endpoint } : {}),
+                ...(flags['endpoint-target'] ? { endpointTarget: flags['endpoint-target'] } : {}),
+                ...(flags.pin ? { pinnedConversationId: flags.pin } : {}),
+            });
+        }
+        catch (err) {
+            this.handleApiError(err);
+            return;
+        }
+        if (flags.json) {
+            this.log(JSON.stringify(response, null, 2));
+            return;
+        }
+        const row = response.followup;
+        if (response.reused) {
+            this.log(`Already armed: ${row?.id} — the same act exists and was not duplicated.`);
+            return;
+        }
+        if (response.dropped) {
+            this.log('Dropped by the daily act budget — no act was armed.');
+            return;
+        }
+        this.log(`Act armed: ${row?.id} at ${row?.nextRunAt ?? at}.`);
+    }
+}
+exports.default = FollowupsAct;

package/dist/commands/followups/cancel.d.ts

@@ -0,0 +1,17 @@
+import { BaseCommand } from '../../base-command';
+/**
+ * `skrr followups cancel <id>` — abandon a follow-up. If the wait already
+ * paid off, say so instead (`resolve --outcome resolved`): the audit keeps
+ * the difference.
+ */
+export default class FollowupsCancel extends BaseCommand {
+    static description: string;
+    static args: {
+        id: import("@oclif/core/lib/interfaces").Arg<string, Record<string, unknown>>;
+    };
+    static flags: {
+        reason: import("@oclif/core/lib/interfaces").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
+        json: import("@oclif/core/lib/interfaces").BooleanFlag<boolean>;
+    };
+    run(): Promise<void>;
+}

package/dist/commands/followups/cancel.js

@@ -0,0 +1,40 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const core_1 = require("@oclif/core");
+const base_command_1 = require("../../base-command");
+const followups_1 = require("../../lib/followups");
+/**
+ * `skrr followups cancel <id>` — abandon a follow-up. If the wait already
+ * paid off, say so instead (`resolve --outcome resolved`): the audit keeps
+ * the difference.
+ */
+class FollowupsCancel extends base_command_1.BaseCommand {
+    static description = 'Abandon a follow-up';
+    static args = {
+        id: core_1.Args.string({ description: 'Follow-up (trigger) id', required: true, ignoreStdin: true }),
+    };
+    static flags = {
+        reason: core_1.Flags.string({ description: 'Why it is being cancelled' }),
+        json: core_1.Flags.boolean({ description: 'Output as JSON' }),
+    };
+    async run() {
+        this.requireAuth();
+        const { args, flags } = await this.parse(FollowupsCancel);
+        let result;
+        try {
+            result = (await followups_1.followupsApi.cancel(args.id, {
+                ...(flags.reason ? { reason: flags.reason } : {}),
+            }));
+        }
+        catch (err) {
+            this.handleApiError(err);
+            return;
+        }
+        if (flags.json) {
+            this.log(JSON.stringify(result, null, 2));
+            return;
+        }
+        this.log(`Follow-up ${args.id} cancelled.`);
+    }
+}
+exports.default = FollowupsCancel;

package/dist/commands/followups/checkin.d.ts

@@ -0,0 +1,27 @@
+import { BaseCommand } from '../../base-command';
+/**
+ * `skrr followups checkin` — a `checkin` follow-up: the agent decides to come
+ * back later. `--in` arms the `once` form (the agent's pick); `--frequency`
+ * arms `recurring` (a cadence the user picked).
+ *
+ * This is permission AND restraint: a check-in may stay silent on wake when
+ * there is nothing worth saying — silence is the designed outcome, not a
+ * failure.
+ */
+export default class FollowupsCheckin extends BaseCommand {
+    static description: string;
+    static examples: string[];
+    static flags: {
+        subject: import("@oclif/core/lib/interfaces").OptionFlag<string, import("@oclif/core/lib/interfaces").CustomOptions>;
+        why: import("@oclif/core/lib/interfaces").OptionFlag<string, import("@oclif/core/lib/interfaces").CustomOptions>;
+        in: import("@oclif/core/lib/interfaces").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
+        frequency: import("@oclif/core/lib/interfaces").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
+        timezone: import("@oclif/core/lib/interfaces").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
+        agent: import("@oclif/core/lib/interfaces").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
+        endpoint: import("@oclif/core/lib/interfaces").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
+        'endpoint-target': import("@oclif/core/lib/interfaces").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
+        pin: import("@oclif/core/lib/interfaces").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
+        json: import("@oclif/core/lib/interfaces").BooleanFlag<boolean>;
+    };
+    run(): Promise<void>;
+}

package/dist/commands/followups/checkin.js

@@ -0,0 +1,107 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const core_1 = require("@oclif/core");
+const base_command_1 = require("../../base-command");
+const followups_1 = require("../../lib/followups");
+const agent_resolver_1 = require("../../lib/agent-resolver");
+/**
+ * `skrr followups checkin` — a `checkin` follow-up: the agent decides to come
+ * back later. `--in` arms the `once` form (the agent's pick); `--frequency`
+ * arms `recurring` (a cadence the user picked).
+ *
+ * This is permission AND restraint: a check-in may stay silent on wake when
+ * there is nothing worth saying — silence is the designed outcome, not a
+ * failure.
+ */
+class FollowupsCheckin extends base_command_1.BaseCommand {
+    static description = 'Come back to this later — the check-in follow-up';
+    static examples = [
+        '<%= config.bin %> followups checkin --subject conversation:conv_9 --why "waiting on their answer about the move" --in 90m',
+        '<%= config.bin %> followups checkin --subject task:OSK-42 --why "weekly touch-base" --frequency "0 9 * * MON" --timezone America/New_York',
+    ];
+    static flags = {
+        subject: core_1.Flags.string({ description: 'Subject ref: type:externalKey', required: true }),
+        why: core_1.Flags.string({ description: 'Why this wake exists, in one line', required: true }),
+        in: core_1.Flags.string({
+            description: 'Duration from now (90m, 2h) — the once form',
+            exclusive: ['frequency'],
+        }),
+        frequency: core_1.Flags.string({
+            description: 'Cron cadence — the recurring form (user-picked)',
+            exclusive: ['in'],
+        }),
+        timezone: core_1.Flags.string({
+            description: 'IANA timezone for --frequency',
+            dependsOn: ['frequency'],
+        }),
+        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 check-in was authored in' }),
+        json: core_1.Flags.boolean({ description: 'Output as JSON' }),
+    };
+    async run() {
+        this.requireAuth();
+        const { flags } = await this.parse(FollowupsCheckin);
+        if (!flags.in && !flags.frequency) {
+            this.failWithCliError({
+                message: 'Either --in <duration> or --frequency <cron> is required.',
+                code: 'FOLLOWUP_KIND_FIELD_MISSING',
+                exit: 2,
+                retryable: false,
+            });
+        }
+        let agent;
+        try {
+            agent = (0, followups_1.resolveFollowUpAgent)(flags.agent);
+        }
+        catch (err) {
+            const failure = (0, agent_resolver_1.agentResolutionFailure)(err);
+            this.failWithCliError({
+                message: failure.message,
+                code: failure.code,
+                exit: 2,
+                retryable: false,
+                details: { suggestion: failure.suggestion, context: failure.details },
+            });
+        }
+        let response;
+        try {
+            response = await followups_1.followupsApi.create({
+                kind: 'checkin',
+                producer: agent.boundToSession ? 'agent_in_turn' : 'user_explicit',
+                agentId: agent.id,
+                subject: (0, followups_1.parseSubjectRef)(flags.subject),
+                why: flags.why,
+                ...(flags.in ? { form: 'once', in: flags.in } : {}),
+                ...(flags.frequency
+                    ? { form: 'recurring', frequency: flags.frequency, timezone: flags.timezone }
+                    : {}),
+                ...(flags.endpoint ? { endpointId: flags.endpoint } : {}),
+                ...(flags['endpoint-target'] ? { endpointTarget: flags['endpoint-target'] } : {}),
+                ...(flags.pin ? { pinnedConversationId: flags.pin } : {}),
+            });
+        }
+        catch (err) {
+            this.handleApiError(err);
+            return;
+        }
+        if (flags.json) {
+            this.log(JSON.stringify(response, null, 2));
+            return;
+        }
+        const row = response.followup;
+        if (response.reused) {
+            this.log(`Already armed: ${row?.id} — one pending check-in per conversation, and this is it.`);
+            return;
+        }
+        if (response.dropped) {
+            // silent_drop is the check-in budget's contract: the answer to "one
+            // greeting too many" is quiet, not an error the caller can retry.
+            this.log('Dropped by the daily check-in budget — staying quiet is the correct outcome.');
+            return;
+        }
+        this.log(`Check-in armed: ${row?.id} at ${row?.nextRunAt ?? flags.in ?? flags.frequency}.`);
+    }
+}
+exports.default = FollowupsCheckin;

package/dist/commands/followups/list.d.ts

@@ -0,0 +1,24 @@
+import { BaseCommand } from '../../base-command';
+/**
+ * `skrr followups list` — what is still owed, one row per follow-up across
+ * all four kinds.
+ *
+ * Default scope is ONE agent (the session's, or `--agent`) — "what do I still
+ * owe" is the question an agent asks. `--all-agents` is the human's view and
+ * is opt-in, so an agent cannot accidentally read another agent's
+ * obligations and start reasoning about them.
+ */
+export default class FollowupsList extends BaseCommand {
+    static description: string;
+    static examples: string[];
+    static flags: {
+        agent: import("@oclif/core/lib/interfaces").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
+        'all-agents': import("@oclif/core/lib/interfaces").BooleanFlag<boolean>;
+        kind: import("@oclif/core/lib/interfaces").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
+        subject: import("@oclif/core/lib/interfaces").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
+        state: import("@oclif/core/lib/interfaces").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
+        limit: import("@oclif/core/lib/interfaces").OptionFlag<number | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
+        json: import("@oclif/core/lib/interfaces").BooleanFlag<boolean>;
+    };
+    run(): Promise<void>;
+}

package/dist/commands/followups/list.js

@@ -0,0 +1,90 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const core_1 = require("@oclif/core");
+const base_command_1 = require("../../base-command");
+const followups_1 = require("../../lib/followups");
+const agent_resolver_1 = require("../../lib/agent-resolver");
+/**
+ * `skrr followups list` — what is still owed, one row per follow-up across
+ * all four kinds.
+ *
+ * Default scope is ONE agent (the session's, or `--agent`) — "what do I still
+ * owe" is the question an agent asks. `--all-agents` is the human's view and
+ * is opt-in, so an agent cannot accidentally read another agent's
+ * obligations and start reasoning about them.
+ */
+class FollowupsList extends base_command_1.BaseCommand {
+    static description = 'List follow-ups — armed, proposed, paused, or settled';
+    static examples = [
+        '<%= config.bin %> followups list',
+        '<%= config.bin %> followups list --agent agent_1 --kind watch --state armed',
+        '<%= config.bin %> followups list --all-agents --kind checkin',
+        '<%= config.bin %> followups list --subject task:OSK-42 --json',
+    ];
+    static flags = {
+        agent: core_1.Flags.string({
+            description: 'Agent ID (default: bound session agent)',
+            exclusive: ['all-agents'],
+        }),
+        'all-agents': core_1.Flags.boolean({
+            description: 'List across every agent — the human view',
+            exclusive: ['agent'],
+            default: false,
+        }),
+        kind: core_1.Flags.string({ description: 'Filter by kind', options: [...followups_1.FOLLOWUP_KINDS] }),
+        subject: core_1.Flags.string({ description: 'Filter by subject ref: type:externalKey' }),
+        state: core_1.Flags.string({ description: 'Filter by state', options: [...followups_1.FOLLOWUP_STATES] }),
+        limit: core_1.Flags.integer({ description: 'Max results (1..500)', min: 1, max: 500 }),
+        json: core_1.Flags.boolean({ description: 'Output as JSON' }),
+    };
+    async run() {
+        this.requireAuth();
+        const { flags } = await this.parse(FollowupsList);
+        let agentId;
+        if (!flags['all-agents']) {
+            try {
+                agentId = (0, followups_1.resolveFollowUpAgent)(flags.agent).id;
+            }
+            catch (err) {
+                const failure = (0, agent_resolver_1.agentResolutionFailure)(err);
+                this.failWithCliError({
+                    message: failure.message,
+                    code: failure.code,
+                    exit: 2,
+                    retryable: false,
+                    details: { suggestion: failure.suggestion, context: failure.details },
+                });
+            }
+        }
+        let response;
+        try {
+            response = await followups_1.followupsApi.list({
+                ...(agentId ? { agentId } : {}),
+                ...(flags['all-agents'] ? { allAgents: true } : {}),
+                ...(flags.kind ? { kind: flags.kind } : {}),
+                ...(flags.subject ? { subject: flags.subject } : {}),
+                ...(flags.state ? { state: flags.state } : {}),
+                ...(flags.limit ? { limit: flags.limit } : {}),
+            });
+        }
+        catch (err) {
+            this.handleApiError(err);
+            return;
+        }
+        if (flags.json) {
+            this.log(JSON.stringify(response, null, 2));
+            return;
+        }
+        const rows = response.followups ?? [];
+        if (rows.length === 0) {
+            this.log('No follow-ups.');
+            return;
+        }
+        for (const row of rows) {
+            this.log((0, followups_1.followupSummaryLine)(row));
+            if (row.why)
+                this.log(`    why: ${row.why}`);
+        }
+    }
+}
+exports.default = FollowupsList;