@skrr-ai/cli 0.1.36 → 0.1.37

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

@@ -0,0 +1,26 @@
+import { BaseCommand } from '../../base-command';
+/**
+ * `skrr followups remind` — a `reminder` follow-up.
+ *
+ * A passive reminder (the default) delivers the user's own words back at T
+ * and needs no agent. `--active` wakes the agent to word it, which is why it
+ * needs an agent context the passive form does not.
+ */
+export default class FollowupsRemind extends BaseCommand {
+    static description: string;
+    static examples: string[];
+    static flags: {
+        subject: import("@oclif/core/lib/interfaces").OptionFlag<string, import("@oclif/core/lib/interfaces").CustomOptions>;
+        content: 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>;
+        why: import("@oclif/core/lib/interfaces").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
+        active: import("@oclif/core/lib/interfaces").BooleanFlag<boolean>;
+        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/remind.js

@@ -0,0 +1,106 @@
+"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 remind` — a `reminder` follow-up.
+ *
+ * A passive reminder (the default) delivers the user's own words back at T
+ * and needs no agent. `--active` wakes the agent to word it, which is why it
+ * 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 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',
+        '<%= config.bin %> followups remind --subject task:OSK-42 --content "ping me" --at 2026-09-20T09:00:00Z --active --agent agent_1',
+    ];
+    static flags = {
+        subject: core_1.Flags.string({ description: 'Subject ref: type:externalKey', required: true }),
+        content: core_1.Flags.string({ description: "The reminder's own words", required: true }),
+        at: core_1.Flags.string({ description: 'ISO-8601 instant to remind at', exclusive: ['in'] }),
+        in: core_1.Flags.string({
+            description: 'Duration from now (90m, 2h, 3d)',
+            exclusive: ['at'],
+        }),
+        why: core_1.Flags.string({ description: 'Why this wake exists (defaults to the content)' }),
+        active: core_1.Flags.boolean({
+            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' }),
+        json: core_1.Flags.boolean({ description: 'Output as JSON' }),
+    };
+    async run() {
+        this.requireAuth();
+        const { flags } = await this.parse(FollowupsRemind);
+        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,
+            });
+        }
+        // A passive reminder runs no agent, so it may legitimately have none — the
+        // ONLY kind/form where the resolver is allowed to fall through empty.
+        let agent;
+        try {
+            agent = (0, followups_1.resolveFollowUpAgent)(flags.agent);
+        }
+        catch (err) {
+            if (flags.active) {
+                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: 'reminder',
+                form: flags.active ? 'active' : 'passive',
+                producer: agent?.boundToSession ? 'agent_in_turn' : 'user_explicit',
+                ...(agent ? { agentId: agent.id } : {}),
+                subject: (0, followups_1.parseSubjectRef)(flags.subject),
+                why: flags.why ?? flags.content,
+                content: flags.content,
+                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 reminder exists and was not duplicated.`);
+            return;
+        }
+        if (response.dropped) {
+            this.log('Dropped by the daily budget — no reminder was armed.');
+            return;
+        }
+        this.log(`Reminder armed: ${row?.id} at ${row?.nextRunAt ?? at}.`);
+    }
+}
+exports.default = FollowupsRemind;

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

@@ -0,0 +1,15 @@
+import { BaseCommand } from '../../base-command';
+/** `skrr followups reschedule <id>` — move a pending wake to a new time. */
+export default class FollowupsReschedule extends BaseCommand {
+    static description: string;
+    static examples: string[];
+    static args: {
+        id: import("@oclif/core/lib/interfaces").Arg<string, Record<string, unknown>>;
+    };
+    static flags: {
+        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>;
+        json: import("@oclif/core/lib/interfaces").BooleanFlag<boolean>;
+    };
+    run(): Promise<void>;
+}

package/dist/commands/followups/reschedule.js

@@ -0,0 +1,48 @@
+"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 reschedule <id>` — move a pending wake to a new time. */
+class FollowupsReschedule extends base_command_1.BaseCommand {
+    static description = 'Reschedule a pending follow-up';
+    static examples = [
+        '<%= config.bin %> followups reschedule fu_abc --in 2h',
+        '<%= config.bin %> followups reschedule fu_abc --at 2026-09-20T09:00:00Z',
+    ];
+    static args = {
+        id: core_1.Args.string({ description: 'Follow-up (trigger) id', required: true, ignoreStdin: true }),
+    };
+    static flags = {
+        at: core_1.Flags.string({ description: 'New instant (ISO-8601)', exclusive: ['in'] }),
+        in: core_1.Flags.string({ description: 'New offset from now (90m, 2h)', exclusive: ['at'] }),
+        json: core_1.Flags.boolean({ description: 'Output as JSON' }),
+    };
+    async run() {
+        this.requireAuth();
+        const { args, flags } = await this.parse(FollowupsReschedule);
+        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,
+            });
+        }
+        let result;
+        try {
+            result = (await followups_1.followupsApi.reschedule(args.id, { at }));
+        }
+        catch (err) {
+            this.handleApiError(err);
+            return;
+        }
+        if (flags.json) {
+            this.log(JSON.stringify(result, null, 2));
+            return;
+        }
+        this.log(`Follow-up ${args.id} rescheduled to ${at}.`);
+    }
+}
+exports.default = FollowupsReschedule;

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

@@ -0,0 +1,23 @@
+import { BaseCommand } from '../../base-command';
+/**
+ * `skrr followups resolve <id>` — settle with the honest outcome.
+ *
+ * Distinct from `cancel` on purpose: "the thing I was waiting for happened"
+ * (`resolved`) and "never mind" (`abandoned`) are different facts, and a
+ * system that cannot tell them apart cannot tell a working watch from a
+ * pointless one. The runtime's own terminals (expired/exhausted/escalated)
+ * are not accepted here.
+ */
+export default class FollowupsResolve extends BaseCommand {
+    static description: string;
+    static examples: string[];
+    static args: {
+        id: import("@oclif/core/lib/interfaces").Arg<string, Record<string, unknown>>;
+    };
+    static flags: {
+        outcome: import("@oclif/core/lib/interfaces").OptionFlag<string, import("@oclif/core/lib/interfaces").CustomOptions>;
+        note: 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/resolve.js

@@ -0,0 +1,54 @@
+"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 resolve <id>` — settle with the honest outcome.
+ *
+ * Distinct from `cancel` on purpose: "the thing I was waiting for happened"
+ * (`resolved`) and "never mind" (`abandoned`) are different facts, and a
+ * system that cannot tell them apart cannot tell a working watch from a
+ * pointless one. The runtime's own terminals (expired/exhausted/escalated)
+ * are not accepted here.
+ */
+class FollowupsResolve extends base_command_1.BaseCommand {
+    static description = 'Settle a follow-up with its honest outcome';
+    static examples = [
+        '<%= config.bin %> followups resolve fu_abc --outcome resolved --note "the deploy landed"',
+        '<%= config.bin %> followups resolve fu_abc --outcome abandoned',
+    ];
+    static args = {
+        id: core_1.Args.string({ description: 'Follow-up (trigger) id', required: true, ignoreStdin: true }),
+    };
+    static flags = {
+        outcome: core_1.Flags.string({
+            description: 'How it ended',
+            options: [...followups_1.FOLLOWUP_RESOLVE_OUTCOMES],
+            required: true,
+        }),
+        note: core_1.Flags.string({ description: 'What happened, for the audit' }),
+        json: core_1.Flags.boolean({ description: 'Output as JSON' }),
+    };
+    async run() {
+        this.requireAuth();
+        const { args, flags } = await this.parse(FollowupsResolve);
+        let result;
+        try {
+            result = (await followups_1.followupsApi.resolve(args.id, {
+                outcome: flags.outcome,
+                ...(flags.note ? { note: flags.note } : {}),
+            }));
+        }
+        catch (err) {
+            this.handleApiError(err);
+            return;
+        }
+        if (flags.json) {
+            this.log(JSON.stringify(result, null, 2));
+            return;
+        }
+        this.log(`Follow-up ${args.id} settled: ${flags.outcome}.`);
+    }
+}
+exports.default = FollowupsResolve;

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

@@ -0,0 +1,12 @@
+import { BaseCommand } from '../../base-command';
+/** `skrr followups show <id>` — one follow-up, the same shape as the list rows. */
+export default class FollowupsShow extends BaseCommand {
+    static description: 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/followups/show.js

@@ -0,0 +1,45 @@
+"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 show <id>` — one follow-up, the same shape as the list rows. */
+class FollowupsShow extends base_command_1.BaseCommand {
+    static description = 'Show one follow-up';
+    static args = {
+        id: core_1.Args.string({ description: 'Follow-up (trigger) 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(FollowupsShow);
+        let response;
+        try {
+            response = await followups_1.followupsApi.show(args.id);
+        }
+        catch (err) {
+            this.handleApiError(err);
+            return;
+        }
+        if (flags.json) {
+            this.log(JSON.stringify(response, null, 2));
+            return;
+        }
+        const row = response.followup;
+        this.log((0, followups_1.followupSummaryLine)(row));
+        for (const [label, value] of [
+            ['why', row.why],
+            ['intent', row.intentKey],
+            ['producer', row.producer],
+            ['terminal', row.terminal ? `${row.terminal} (${row.terminalReason ?? '—'})` : undefined],
+            ['deadline', row.deadlineAt],
+            ['escalated to', row.escalatedInitiativeId],
+        ]) {
+            if (value)
+                this.log(`    ${label}: ${value}`);
+        }
+    }
+}
+exports.default = FollowupsShow;

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

@@ -0,0 +1,51 @@
+import { BaseCommand } from '../../base-command';
+/**
+ * `skrr followups watch` — a `watch` follow-up: keep an eye on an
+ * asynchronous tail until a condition settles or a stop fires.
+ *
+ * Two forms, matching the service vocabulary exactly:
+ *
+ *   predicate  `--url` + `--until <json>` — a machine-settled observation of
+ *              an HTTPS endpoint. Free (no agent turn per check), termination
+ *              guaranteed by `--deadline`. Prefer this when the thing watched
+ *              is a URL whose response can answer the question.
+ *   recipe     `--check` + `--success` + `--abort` + `--wait <kind>` — a
+ *              deterministic check a future agent turn runs. One turn per
+ *              check; the abort criterion is mandatory because a watch that
+ *              cannot stop is a leak.
+ */
+export default class FollowupsWatch 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>;
+        agent: import("@oclif/core/lib/interfaces").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
+        url: import("@oclif/core/lib/interfaces").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
+        until: import("@oclif/core/lib/interfaces").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
+        grant: import("@oclif/core/lib/interfaces").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
+        deadline: import("@oclif/core/lib/interfaces").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
+        'check-every': import("@oclif/core/lib/interfaces").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
+        'max-checks': import("@oclif/core/lib/interfaces").OptionFlag<number | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
+        'root-path': import("@oclif/core/lib/interfaces").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
+        'resume-prompt': import("@oclif/core/lib/interfaces").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
+        check: import("@oclif/core/lib/interfaces").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
+        success: import("@oclif/core/lib/interfaces").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
+        abort: import("@oclif/core/lib/interfaces").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
+        wait: import("@oclif/core/lib/interfaces").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
+        'wait-at': import("@oclif/core/lib/interfaces").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
+        'wait-entity': import("@oclif/core/lib/interfaces").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
+        'wait-event': import("@oclif/core/lib/interfaces").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
+        'wait-filter-field': import("@oclif/core/lib/interfaces").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
+        'wait-filter-mode': import("@oclif/core/lib/interfaces").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
+        'wait-filter-value': import("@oclif/core/lib/interfaces").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
+        'wait-interval-seconds': import("@oclif/core/lib/interfaces").OptionFlag<number | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
+        'wait-max-attempts': import("@oclif/core/lib/interfaces").OptionFlag<number | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
+        'wait-fallback': 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/watch.js

@@ -0,0 +1,207 @@
+"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 watch` — a `watch` follow-up: keep an eye on an
+ * asynchronous tail until a condition settles or a stop fires.
+ *
+ * Two forms, matching the service vocabulary exactly:
+ *
+ *   predicate  `--url` + `--until <json>` — a machine-settled observation of
+ *              an HTTPS endpoint. Free (no agent turn per check), termination
+ *              guaranteed by `--deadline`. Prefer this when the thing watched
+ *              is a URL whose response can answer the question.
+ *   recipe     `--check` + `--success` + `--abort` + `--wait <kind>` — a
+ *              deterministic check a future agent turn runs. One turn per
+ *              check; the abort criterion is mandatory because a watch that
+ *              cannot stop is a leak.
+ */
+class FollowupsWatch extends base_command_1.BaseCommand {
+    static description = 'Watch an asynchronous tail until it settles — the watch follow-up';
+    static examples = [
+        '<%= config.bin %> followups watch --subject task:OSK-42 --why "deploy still running" --url https://ci.example.com/api/build/9 --until \'{"field":"status","eq":"done"}\' --deadline 6h',
+        '<%= config.bin %> followups watch --subject task:OSK-42 --why "pr review" --check "gh pr view 42 --json state" --success "state == MERGED" --abort "state == CLOSED" --wait event --wait-entity github --wait-event pull_request --wait-fallback 2h',
+        '<%= config.bin %> followups watch --subject conv:abc --why "vendor reply" --check "check inbox" --success "reply arrived" --abort "3 days" --wait clock --wait-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 watch exists, in one line', required: true }),
+        agent: core_1.Flags.string({ description: 'Agent ID (default: bound session agent)' }),
+        // predicate form
+        url: core_1.Flags.string({ description: 'HTTPS endpoint to observe (predicate form)' }),
+        until: core_1.Flags.string({ description: 'Predicate tree as JSON (predicate form)' }),
+        grant: core_1.Flags.string({ description: 'Grant id supplying the watch credentials' }),
+        deadline: core_1.Flags.string({ description: 'When the watch must stop (predicate form, required)' }),
+        'check-every': core_1.Flags.string({ description: 'Observation interval (predicate form)' }),
+        'max-checks': core_1.Flags.integer({ description: 'Observation cap (predicate form)' }),
+        'root-path': core_1.Flags.string({ description: 'JSON root path inside the response' }),
+        'resume-prompt': core_1.Flags.string({ description: 'What to tell the settling turn' }),
+        // recipe form
+        check: core_1.Flags.string({ description: 'The deterministic check to run (recipe form)' }),
+        success: core_1.Flags.string({ description: 'What state means the wait resolved (recipe form)' }),
+        abort: core_1.Flags.string({ description: 'When to stop and escalate (recipe form)' }),
+        wait: core_1.Flags.string({
+            description: 'Wait kind (recipe form)',
+            options: [...followups_1.WATCH_WAIT_KINDS],
+        }),
+        'wait-at': core_1.Flags.string({ description: 'Instant/duration for --wait clock' }),
+        'wait-entity': core_1.Flags.string({ description: 'Entity type for --wait event' }),
+        'wait-event': core_1.Flags.string({ description: 'Event type for --wait event' }),
+        'wait-filter-field': core_1.Flags.string({ description: 'Payload field for an event filter' }),
+        'wait-filter-mode': core_1.Flags.string({
+            description: 'Event filter mode',
+            options: ['equals', 'contains', 'in_set'],
+        }),
+        'wait-filter-value': core_1.Flags.string({ description: 'Event filter value' }),
+        'wait-interval-seconds': core_1.Flags.integer({ description: 'Poll interval for --wait poll_until' }),
+        'wait-max-attempts': core_1.Flags.integer({ description: 'Attempt cap for --wait poll_until' }),
+        'wait-fallback': core_1.Flags.string({ description: 'SLA backstop for --wait event/poll_until' }),
+        // delivery
+        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 watch was authored in' }),
+        json: core_1.Flags.boolean({ description: 'Output as JSON' }),
+    };
+    async run() {
+        this.requireAuth();
+        const { flags } = await this.parse(FollowupsWatch);
+        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 },
+            });
+        }
+        const predicate = flags.url !== undefined || flags.until !== undefined;
+        const recipe = flags.check !== undefined || flags.success !== undefined || flags.abort !== undefined;
+        if (predicate && recipe) {
+            this.failWithCliError({
+                message: 'Predicate and recipe flags cannot mix. A watch is either an observed URL (--url/--until) or a checked recipe (--check/--success/--abort/--wait).',
+                code: 'FOLLOWUP_INVALID_FORM',
+                exit: 2,
+                retryable: false,
+            });
+        }
+        if (!predicate && !recipe) {
+            this.failWithCliError({
+                message: 'A watch needs a form: --url + --until for a predicate watch, or --check + --success + --abort + --wait for a recipe watch.',
+                code: 'FOLLOWUP_INVALID_FORM',
+                exit: 2,
+                retryable: false,
+            });
+        }
+        const body = {
+            kind: 'watch',
+            producer: agent.boundToSession ? 'agent_in_turn' : 'user_explicit',
+            agentId: agent.id,
+            subject: (0, followups_1.parseSubjectRef)(flags.subject),
+            why: flags.why,
+            ...(flags.endpoint ? { endpointId: flags.endpoint } : {}),
+            ...(flags['endpoint-target'] ? { endpointTarget: flags['endpoint-target'] } : {}),
+            ...(flags.pin ? { pinnedConversationId: flags.pin } : {}),
+        };
+        if (predicate) {
+            if (!flags.url || !flags.until) {
+                this.failWithCliError({
+                    message: 'A predicate watch needs both --url <https> and --until <predicate-json>.',
+                    code: 'FOLLOWUP_KIND_FIELD_MISSING',
+                    exit: 2,
+                    retryable: false,
+                });
+            }
+            if (!flags.deadline) {
+                this.failWithCliError({
+                    message: '--deadline is required — a watch that cannot stop is a leak.',
+                    code: 'FOLLOWUP_KIND_FIELD_MISSING',
+                    exit: 2,
+                    retryable: false,
+                });
+            }
+            Object.assign(body, {
+                form: 'predicate',
+                url: flags.url,
+                until: (0, triggers_1.parseJsonObject)(flags.until, '--until'),
+                grantId: flags.grant,
+                deadline: flags.deadline,
+                checkEvery: flags['check-every'],
+                maxChecks: flags['max-checks'],
+                rootPath: flags['root-path'],
+                resumePrompt: flags['resume-prompt'],
+            });
+        }
+        else {
+            for (const field of ['check', 'success', 'abort', 'wait']) {
+                if (!flags[field]) {
+                    this.failWithCliError({
+                        message: `A recipe watch needs --${field}.`,
+                        code: 'FOLLOWUP_KIND_FIELD_MISSING',
+                        exit: 2,
+                        retryable: false,
+                    });
+                }
+            }
+            const wait = { kind: flags.wait };
+            if (flags.wait === 'clock') {
+                wait.at = flags['wait-at'];
+            }
+            else if (flags.wait === 'event') {
+                Object.assign(wait, {
+                    entityType: flags['wait-entity'],
+                    eventType: flags['wait-event'],
+                    filterField: flags['wait-filter-field'],
+                    filterMode: flags['wait-filter-mode'],
+                    filterValue: flags['wait-filter-value'],
+                    fallback: flags['wait-fallback'],
+                });
+            }
+            else {
+                Object.assign(wait, {
+                    intervalSeconds: flags['wait-interval-seconds'],
+                    maxAttempts: flags['wait-max-attempts'],
+                    fallback: flags['wait-fallback'],
+                });
+            }
+            Object.assign(body, {
+                form: 'recipe',
+                check: flags.check,
+                success: flags.success,
+                abort: flags.abort,
+                wait,
+            });
+        }
+        let response;
+        try {
+            response = await followups_1.followupsApi.create(body);
+        }
+        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} — an identical watch exists and was not duplicated.`);
+            return;
+        }
+        if (response.dropped) {
+            this.log('Dropped by the daily watch budget — no watch was armed.');
+            return;
+        }
+        this.log(`Watch armed: ${row?.id}${row?.deadlineAt ? `, deadline ${row.deadlineAt}` : ''}.`);
+    }
+}
+exports.default = FollowupsWatch;

package/dist/commands/goals/labels/add.js

@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 const core_1 = require("@oclif/core");
 const data_provider_1 = require("@skrr-ai/data-provider");
 const base_command_1 = require("../../../base-command");
+const label_ref_1 = require("../../../lib/label-ref");
 class GoalsLabelsAdd extends base_command_1.BaseCommand {
     static description = 'Attach a label to a goal';
     static examples = [
@@ -15,7 +16,7 @@ class GoalsLabelsAdd extends base_command_1.BaseCommand {
     static flags = {
         json: core_1.Flags.boolean({ description: 'Output the updated goal as JSON' }),
         label: core_1.Flags.string({
-            description: 'Label ID — must be applicable to goals (see `skrr labels list --applicable-to goal`)',
+            description: 'Label — id, or a name from `skrr labels list --applicable-to goal`. An unknown name is refused, never created.',
             required: true,
         }),
     };
@@ -25,9 +26,25 @@ class GoalsLabelsAdd extends base_command_1.BaseCommand {
         // `goals update` deliberately refuses labelIds — the server routes label
         // changes through this atomic endpoint so exclusive-group eviction and
         // usage counters stay correct. Re-attaching an attached label is a no-op.
+        // A name is resolved against the DECLARED vocabulary; an unknown one is
+        // refused with the near misses named, never created. See lib/label-ref.
+        let labelId = flags.label;
+        try {
+            [labelId] = await (0, label_ref_1.resolveLabelRefs)([flags.label], {
+                applicableTo: 'goal',
+                ...(process.env.OVERSKY_WORKSPACE_ID
+                    ? { workspaceId: process.env.OVERSKY_WORKSPACE_ID }
+                    : {}),
+            });
+        }
+        catch (err) {
+            if (err instanceof label_ref_1.LabelRefError)
+                this.error(err.message, { exit: 1 });
+            this.handleApiError(err);
+        }
         let result;
         try {
-            result = await data_provider_1.dataService.addLabelToGoal({ goalId: args.id, labelId: flags.label });
+            result = await data_provider_1.dataService.addLabelToGoal({ goalId: args.id, labelId });
         }
         catch (err) {
             this.handleApiError(err);