@skrr-ai/cli 0.1.100 → 0.1.102

package/dist/commands/compass/update.js

@@ -1,10 +1,26 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveExpectedVersion = resolveExpectedVersion;
 const core_1 = require("@oclif/core");
 const base_command_1 = require("../../base-command");
 const prompt_1 = require("../../lib/prompt");
 const compasses_1 = require("../../lib/compasses");
 const web_url_1 = require("../../lib/web-url");
+/**
+ * The server fences every compass write on the version the caller last saw
+ * (`expectedVersion`, required), so a stale writer gets a conflict instead of
+ * silently overwriting a newer revision. Precedence: an explicit flag, then a
+ * value the caller put in `--json-body` (passed through untouched, so an invalid
+ * one is the server's to refuse), then the current version read just now.
+ */
+async function resolveExpectedVersion(explicit, fileBody, fetchCurrentVersion) {
+    if (explicit !== undefined)
+        return { version: explicit, source: 'flag' };
+    if (fileBody.expectedVersion !== undefined) {
+        return { version: fileBody.expectedVersion, source: 'json-body' };
+    }
+    return { version: await fetchCurrentVersion(), source: 'current' };
+}
 /**
  * `skrr compass update <compass-id> --agent <id>`
  *
@@ -22,6 +38,7 @@ class CompassUpdate extends base_command_1.BaseCommand {
         '<%= config.bin %> compass update agch_abc --agent agent_xyz --title "Reliability & cost"',
         '<%= config.bin %> compass update agch_abc --agent agent_xyz --invariant "p99 under 300ms" --reason "new SLO"',
         '<%= config.bin %> compass update agch_abc --agent agent_xyz --json-body ./compass.json',
+        '<%= config.bin %> compass update agch_abc --agent agent_xyz --title "New" --expected-version 4',
     ];
     static args = {
         compassId: core_1.Args.string({ ignoreStdin: true, description: 'Compass ID', required: true }),
@@ -37,6 +54,11 @@ class CompassUpdate extends base_command_1.BaseCommand {
             multiple: true,
         }),
         reason: core_1.Flags.string({ description: 'Why — recorded on the revision ledger' }),
+        'expected-version': core_1.Flags.integer({
+            min: 1,
+            description: 'Compass version this change is based on; the update is refused if it moved. ' +
+                'Defaults to the version read at the start of this command.',
+        }),
         'json-body': core_1.Flags.string({ description: 'Path to a JSON file with the full body' }),
     };
     async run() {
@@ -61,6 +83,11 @@ class CompassUpdate extends base_command_1.BaseCommand {
         }
         let compass;
         try {
+            const expected = await resolveExpectedVersion(flags['expected-version'], fileBody, async () => (await compasses_1.compassApi.get(args.compassId, { agentId: flags.agent })).version);
+            body.expectedVersion = expected.version;
+            if (expected.source === 'current' && !flags.json) {
+                this.logToStderr(`No --expected-version given; updating from the current version (v${String(expected.version)}).`);
+            }
             compass = await compasses_1.compassApi.update(args.compassId, body);
         }
         catch (err) {

package/dist/commands/machines/dedicated/exec.js

@@ -104,7 +104,9 @@ class DedicatedMachinesExec extends base_command_1.BaseCommand {
             description: `How long to let it run, such as 30s or 5m (default 2m, max ${dedicated_machines_1.DEDICATED_EXEC_MAX_TIMEOUT_MS / 60000}m). The process group is killed at the deadline.`,
         }),
         'request-id': core_1.Flags.string({
-            description: 'Idempotency key for this command. Repeating the invocation with the same id returns the run it already started (and its output, for 5 minutes after it ends) instead of running it again. Letters, digits and . _ : / - only.',
+            description: 'Idempotency key for this command. Repeating the invocation with the same id returns the run it already started instead of running it again. ' +
+                'Output is kept for at most 5 minutes after it ends and at most 60 seconds after the first terminal read, whichever expires sooner. ' +
+                'Letters, digits and . _ : / - only.',
         }),
         workspace: core_1.Flags.string({ description: 'Workspace scope' }),
         json: core_1.Flags.boolean({ description: 'Output the result as JSON' }),

package/dist/commands/proposals/discard.d.ts

@@ -1,5 +1,9 @@
 import { ProposalDecisionCommand } from '../../lib/proposal-decision-command';
 export default class ProposalsDiscard extends ProposalDecisionCommand {
     static description: string;
+    static args: {
+        kind: import("@oclif/core/lib/interfaces").Arg<string, Record<string, unknown>>;
+        id: import("@oclif/core/lib/interfaces").Arg<string, Record<string, unknown>>;
+    };
     static decision: "discard";
 }

package/dist/commands/proposals/discard.js

@@ -3,6 +3,9 @@ Object.defineProperty(exports, "__esModule", { value: true });
 const proposal_decision_command_1 = require("../../lib/proposal-decision-command");
 class ProposalsDiscard extends proposal_decision_command_1.ProposalDecisionCommand {
     static description = 'Discard one displayed proposal through its domain authority';
+    // Own, not inherited: oclif spreads the command class into the parser input, and a static a
+    // subclass only inherits is dropped, which left these commands with no declared KIND/ID (OSK-15346).
+    static args = proposal_decision_command_1.ProposalDecisionCommand.args;
     static decision = 'discard';
 }
 exports.default = ProposalsDiscard;

package/dist/commands/proposals/keep.d.ts

@@ -1,5 +1,9 @@
 import { ProposalDecisionCommand } from '../../lib/proposal-decision-command';
 export default class ProposalsKeep extends ProposalDecisionCommand {
     static description: string;
+    static args: {
+        kind: import("@oclif/core/lib/interfaces").Arg<string, Record<string, unknown>>;
+        id: import("@oclif/core/lib/interfaces").Arg<string, Record<string, unknown>>;
+    };
     static decision: "keep";
 }

package/dist/commands/proposals/keep.js

@@ -3,6 +3,9 @@ Object.defineProperty(exports, "__esModule", { value: true });
 const proposal_decision_command_1 = require("../../lib/proposal-decision-command");
 class ProposalsKeep extends proposal_decision_command_1.ProposalDecisionCommand {
     static description = 'Keep one displayed proposal through its domain authority';
+    // Own, not inherited: oclif spreads the command class into the parser input, and a static a
+    // subclass only inherits is dropped, which left these commands with no declared KIND/ID (OSK-15346).
+    static args = proposal_decision_command_1.ProposalDecisionCommand.args;
     static decision = 'keep';
 }
 exports.default = ProposalsKeep;

package/dist/commands/proposals/snooze.d.ts

@@ -1,5 +1,9 @@
 import { ProposalDecisionCommand } from '../../lib/proposal-decision-command';
 export default class ProposalsSnooze extends ProposalDecisionCommand {
     static description: string;
+    static args: {
+        kind: import("@oclif/core/lib/interfaces").Arg<string, Record<string, unknown>>;
+        id: import("@oclif/core/lib/interfaces").Arg<string, Record<string, unknown>>;
+    };
     static decision: "snooze";
 }

package/dist/commands/proposals/snooze.js

@@ -3,6 +3,9 @@ Object.defineProperty(exports, "__esModule", { value: true });
 const proposal_decision_command_1 = require("../../lib/proposal-decision-command");
 class ProposalsSnooze extends proposal_decision_command_1.ProposalDecisionCommand {
     static description = 'Snooze one displayed proposal through its domain authority';
+    // Own, not inherited: oclif spreads the command class into the parser input, and a static a
+    // subclass only inherits is dropped, which left these commands with no declared KIND/ID (OSK-15346).
+    static args = proposal_decision_command_1.ProposalDecisionCommand.args;
     static decision = 'snooze';
 }
 exports.default = ProposalsSnooze;

package/dist/commands/signals/monitors/validate.js

@@ -5,7 +5,7 @@ const signal_command_1 = require("../../../signal-command");
 const signals_1 = require("../../../lib/signals");
 const prompt_1 = require("../../../lib/prompt");
 class MonitorsValidate extends signal_command_1.SignalCommand {
-    static description = 'Compile-only check of a Monitor definition; nothing is persisted';
+    static description = 'Compile-only check of a Monitor definition; nothing is persisted. Requires active Signal Sources owned by you in the selected workspace. Inspect each source with signals sources show before validating.';
     static flags = {
         json: core_1.Flags.boolean({ description: 'Output as JSON' }),
         'from-json': core_1.Flags.string({

package/dist/commands/spaces/workflows/cancel-node.d.ts

@@ -0,0 +1,16 @@
+import { BaseCommand } from '../../../base-command';
+export default class SpacesWorkflowsCancelNode extends BaseCommand {
+    static description: string;
+    static examples: string[];
+    static args: {
+        spaceId: import("@oclif/core/lib/interfaces").Arg<string, Record<string, unknown>>;
+        runId: import("@oclif/core/lib/interfaces").Arg<string, Record<string, unknown>>;
+        nodeKey: import("@oclif/core/lib/interfaces").Arg<string, Record<string, unknown>>;
+    };
+    static flags: {
+        'from-json': import("@oclif/core/lib/interfaces").OptionFlag<string, import("@oclif/core/lib/interfaces").CustomOptions>;
+        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/spaces/workflows/cancel-node.js

@@ -0,0 +1,44 @@
+"use strict";
+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 prompt_1 = require("../../../lib/prompt");
+const workflow_node_control_1 = require("../../../lib/workflow-node-control");
+class SpacesWorkflowsCancelNode extends base_command_1.BaseCommand {
+    static description = 'Request cancellation of one exact workflow node attempt and show the returned execution state';
+    static examples = [
+        '<%= config.bin %> spaces workflows run <space> <run> --json > reviewed-run.json',
+        '<%= config.bin %> spaces workflows cancel-node <space> <run> <node> --from-json reviewed-run.json',
+    ];
+    static args = {
+        spaceId: core_1.Args.string({ description: 'Owning Space ID', required: true, ignoreStdin: true }),
+        runId: core_1.Args.string({ description: 'Workflow run ID', required: true, ignoreStdin: true }),
+        nodeKey: core_1.Args.string({ description: 'Node key to stop', required: true, ignoreStdin: true }),
+    };
+    static flags = {
+        'from-json': core_1.Flags.string({ description: 'Saved canonical workflow run snapshot, or - for stdin', required: true }),
+        reason: core_1.Flags.string({ description: 'Cancellation reason (at most 500 characters)' }),
+        json: core_1.Flags.boolean({ description: 'Output the updated workflow run as JSON' }),
+    };
+    async run() {
+        this.requireAuth();
+        const { args, flags } = await this.parse(SpacesWorkflowsCancelNode);
+        try {
+            const body = (0, workflow_node_control_1.nodeCancellationFromSnapshot)(args.spaceId, args.runId, args.nodeKey, await (0, prompt_1.readJsonBody)(flags['from-json']), flags.reason);
+            const run = await data_provider_1.dataService.cancelSpaceWorkflowNode(args.spaceId, args.runId, args.nodeKey, body);
+            if (flags.json) {
+                this.log(JSON.stringify(run, null, 2));
+                return;
+            }
+            const node = run.nodes?.find((item) => item.nodeKey === args.nodeKey);
+            this.log(`Cancellation for ${args.nodeKey}: ${node?.cancellation?.state ?? 'unknown'}.`);
+            this.log(`Returned node state: ${node?.status ?? 'unknown'}.`);
+            this.log(`Workflow run ${run.id}: ${run.status}.`);
+        }
+        catch (error) {
+            this.handleApiError(error);
+        }
+    }
+}
+exports.default = SpacesWorkflowsCancelNode;

package/dist/commands/spaces/workflows/cancel.d.ts

@@ -1,4 +1,43 @@
 import { BaseCommand } from '../../../base-command';
+/**
+ * Child workflow runs a cancelled run was waiting on. A cancelled node keeps its `waitingFor`,
+ * and every node kind that starts a child run (`workflow_call` = subworkflow, `loop` iteration,
+ * `task_plan`) records that run as `waitingFor.workflowRunId`. Reading the id rather than the
+ * kind means a new child-starting node kind is not silently missed.
+ */
+export declare function childWorkflowRunIds(run: {
+    id?: string;
+    nodes?: Array<{
+        waitingFor?: unknown;
+    }>;
+}): string[];
+/**
+ * Lines for a cancel that has not finished converging. `cancellation.state: settled` with
+ * nothing pending is the only converged answer; anything else must not read as "stopped".
+ */
+export declare function describeCancellationProgress(spaceId: string, run: {
+    id: string;
+    cancellation?: {
+        state?: string;
+        descendantsPending?: boolean;
+        executorsPending?: number;
+    };
+}): string[];
+/**
+ * The lines that tell a person which child runs a `preserve_children` cancel left running.
+ * "Cancelled" next to a child that is still waiting forever is the part nobody could see
+ * (OSK-15331), so say it and say how to stop them. Re-cancelling the parent with
+ * `--scope subtree` widens the stop to every descendant (the server persists the wider
+ * decision before touching any descendant). An unreadable child is reported as unreadable,
+ * never as stopped.
+ */
+export declare function describePreservedChildren(spaceId: string, parentRunId: string, children: Array<{
+    id: string;
+    status?: string;
+    unreadable?: boolean;
+}>, { reviewedScope }?: {
+    reviewedScope?: boolean;
+}): string[];
 export default class SpacesWorkflowsCancel extends BaseCommand {
     static description: string;
     static args: {
@@ -7,6 +46,7 @@ export default class SpacesWorkflowsCancel extends BaseCommand {
     };
     static flags: {
         json: import("@oclif/core/lib/interfaces").BooleanFlag<boolean>;
+        scope: import("@oclif/core/lib/interfaces").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
         yes: import("@oclif/core/lib/interfaces").BooleanFlag<boolean>;
     };
     run(): Promise<void>;

package/dist/commands/spaces/workflows/cancel.js

@@ -1,10 +1,84 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.childWorkflowRunIds = childWorkflowRunIds;
+exports.describeCancellationProgress = describeCancellationProgress;
+exports.describePreservedChildren = describePreservedChildren;
 const core_1 = require("@oclif/core");
 const data_provider_1 = require("@skrr-ai/data-provider");
 const base_command_1 = require("../../../base-command");
 const prompt_1 = require("../../../lib/prompt");
 const space_output_1 = require("../../../lib/space-output");
+const CANCELLATION_SCOPES = [
+    'preserve_children',
+    'subtree',
+];
+/**
+ * Child workflow runs a cancelled run was waiting on. A cancelled node keeps its `waitingFor`,
+ * and every node kind that starts a child run (`workflow_call` = subworkflow, `loop` iteration,
+ * `task_plan`) records that run as `waitingFor.workflowRunId`. Reading the id rather than the
+ * kind means a new child-starting node kind is not silently missed.
+ */
+function childWorkflowRunIds(run) {
+    const ids = new Set();
+    for (const node of run.nodes ?? []) {
+        const waitingFor = node.waitingFor;
+        const childId = waitingFor?.workflowRunId;
+        if (typeof childId === 'string' && childId && childId !== run.id)
+            ids.add(childId);
+    }
+    return [...ids];
+}
+/**
+ * Lines for a cancel that has not finished converging. `cancellation.state: settled` with
+ * nothing pending is the only converged answer; anything else must not read as "stopped".
+ */
+function describeCancellationProgress(spaceId, run) {
+    const c = run.cancellation;
+    if (!c)
+        return [];
+    const pending = c.state !== 'settled' || c.descendantsPending || Number(c.executorsPending) > 0;
+    if (!pending)
+        return [];
+    const detail = `state ${c.state ?? 'unknown'}, descendant runs pending: ${c.descendantsPending ? 'yes' : 'no'}, executors pending: ${Number(c.executorsPending) || 0}`;
+    // `failed` means the cleanup gave up: reading again never converges it, only a reconcile retries.
+    if (c.state === 'failed') {
+        return [
+            `Cancellation cleanup gave up (${detail}).`,
+            `  Retry it with: skrr spaces workflows reconcile ${spaceId} ${run.id}`,
+        ];
+    }
+    return [
+        `Cancellation is still converging (${detail}).`,
+        `  Re-read it with: skrr spaces workflows run ${spaceId} ${run.id}`,
+    ];
+}
+/**
+ * The lines that tell a person which child runs a `preserve_children` cancel left running.
+ * "Cancelled" next to a child that is still waiting forever is the part nobody could see
+ * (OSK-15331), so say it and say how to stop them. Re-cancelling the parent with
+ * `--scope subtree` widens the stop to every descendant (the server persists the wider
+ * decision before touching any descendant). An unreadable child is reported as unreadable,
+ * never as stopped.
+ */
+function describePreservedChildren(spaceId, parentRunId, children, { reviewedScope = false } = {}) {
+    const live = children.filter((child) => child.unreadable || (0, data_provider_1.isActiveWorkflowRunStatus)(child.status));
+    if (live.length === 0)
+        return [];
+    const lines = [
+        `Left running (scope preserve_children): ${live.length} child workflow run${live.length === 1 ? '' : 's'} started by this run.`,
+    ];
+    for (const child of live) {
+        lines.push(`  ${child.id} (${child.unreadable ? 'status unreadable' : child.status})`);
+    }
+    if (reviewedScope) {
+        // A stop under a reviewed scope is frozen to that review, so cancelling the parent again
+        // does not widen it; each child is stopped on its own.
+        lines.push(`This run was stopped under a reviewed scope, so cancelling it again will not widen the stop.`, `Stop a child with: skrr spaces workflows cancel ${spaceId} <child-run-id> --scope subtree --yes`);
+        return lines;
+    }
+    lines.push(`Stop them now: skrr spaces workflows cancel ${spaceId} ${parentRunId} --scope subtree --yes`, `  (widens this cancel to every descendant run), or stop one: skrr spaces workflows cancel ${spaceId} <child-run-id> --scope subtree --yes`);
+    return lines;
+}
 class SpacesWorkflowsCancel extends base_command_1.BaseCommand {
     static description = 'Cancel a workflow run and stop further graph coordination';
     static args = {
@@ -12,15 +86,25 @@ class SpacesWorkflowsCancel extends base_command_1.BaseCommand {
         runId: core_1.Args.string({ description: 'Workflow run ID', required: true, ignoreStdin: true }),
     };
     static flags = {
-        json: core_1.Flags.boolean({ description: 'Output the cancelled run as JSON' }),
+        json: core_1.Flags.boolean({
+            description: 'Output the cancelled run as JSON (cancellation.scope and the waitingFor.workflowRunId of the cancelled nodes show which child runs were left running)',
+        }),
+        scope: core_1.Flags.string({
+            description: 'What happens to child workflow runs this run started: preserve_children (default) leaves them running, subtree stops every descendant run too',
+            options: [...CANCELLATION_SCOPES],
+        }),
         yes: core_1.Flags.boolean({ char: 'y', description: 'Skip confirmation prompt' }),
     };
     async run() {
         this.requireAuth();
         const { args, flags } = await this.parse(SpacesWorkflowsCancel);
+        const scope = flags.scope;
         let confirmed;
         try {
-            confirmed = await (0, prompt_1.confirmDestructive)(`Cancel workflow run ${args.runId}? This stops workflow coordination; already-dispatched task execution may continue.`, flags.yes);
+            const scopeNote = scope === 'subtree'
+                ? ' Child workflow runs it started are cancelled too.'
+                : ' Child workflow runs it started keep running (--scope subtree stops them too).';
+            confirmed = await (0, prompt_1.confirmDestructive)(`Cancel workflow run ${args.runId}? This stops workflow coordination; already-dispatched task execution may continue.${scopeNote}`, flags.yes);
         }
         catch (error) {
             this.error(error.message, {
@@ -34,7 +118,7 @@ class SpacesWorkflowsCancel extends base_command_1.BaseCommand {
         }
         let run;
         try {
-            run = await data_provider_1.dataService.cancelSpaceWorkflowRun(args.spaceId, args.runId);
+            run = await data_provider_1.dataService.cancelSpaceWorkflowRun(args.spaceId, args.runId, scope ? { scope } : {});
         }
         catch (error) {
             this.handleApiError(error);
@@ -45,6 +129,28 @@ class SpacesWorkflowsCancel extends base_command_1.BaseCommand {
             return;
         }
         this.log(`Cancelled workflow run ${run.id} (${run.status}).`);
+        for (const line of describeCancellationProgress(args.spaceId, run))
+            this.log(line);
+        if ((run.cancellation?.scope ?? run.cancellationScope ?? scope) === 'subtree')
+            return;
+        const childIds = childWorkflowRunIds(run);
+        if (childIds.length === 0)
+            return;
+        const children = await Promise.all(childIds.map(async (id) => {
+            try {
+                const child = await data_provider_1.dataService.getSpaceWorkflowRun(args.spaceId, id);
+                return { id, status: child.status };
+            }
+            catch {
+                return { id, unreadable: true };
+            }
+        }));
+        const reviewedScope = Boolean(run.cancellationExpectedScope);
+        for (const line of describePreservedChildren(args.spaceId, run.id, children, {
+            reviewedScope,
+        })) {
+            this.log(line);
+        }
     }
 }
 exports.default = SpacesWorkflowsCancel;

package/dist/commands/spaces/workflows/run.d.ts

@@ -16,6 +16,15 @@ export declare function describeNodeAttention(node: {
         message?: string;
     } | null;
 }): string;
+export declare function describeLoopItemsNote(node: {
+    nodeKey?: unknown;
+    nodeType?: unknown;
+    output?: {
+        itemsStatus?: unknown;
+        itemsKey?: unknown;
+        itemsFoundType?: unknown;
+    } | null;
+}): string;
 export default class SpacesWorkflowsRun extends BaseCommand {
     static description: string;
     static args: {

package/dist/commands/spaces/workflows/run.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.describeNodeAttention = describeNodeAttention;
+exports.describeLoopItemsNote = describeLoopItemsNote;
 const core_1 = require("@oclif/core");
 const data_provider_1 = require("@skrr-ai/data-provider");
 const base_command_1 = require("../../../base-command");
@@ -26,6 +27,38 @@ function describeNodeAttention(node) {
         return `${reason}: ${message}`;
     return reason || message || 'needs attention';
 }
+/**
+ * A note for a loop that succeeded having iterated nothing because its
+ * collection never arrived, or '' when there is nothing to say (OSK-15324).
+ *
+ * A zero-iteration loop is `succeeded`, so the plain table reads as healthy
+ * whether the list was legitimately empty or the value the author meant never
+ * reached the loop. The server records which on the node output; say it. An
+ * empty list is the legitimate case and stays silent.
+ */
+/** One printable line: control characters (an ESC sequence included) become spaces. */
+function oneLine(value) {
+    // eslint-disable-next-line no-control-regex
+    return (0, format_1.collapseWhitespace)(value.replace(/[\u0000-\u001f\u007f-\u009f]/g, ' '));
+}
+function describeLoopItemsNote(node) {
+    if (node.nodeType !== 'loop')
+        return '';
+    const output = node.output;
+    // `itemsKey` is author-chosen free text, unlike a node key, so it is printed the way the
+    // table prints a cell: one line, no control characters.
+    const key = oneLine(typeof output?.itemsKey === 'string' && output.itemsKey ? output.itemsKey : 'items');
+    const name = oneLine(String(node.nodeKey ?? 'loop'));
+    if (output?.itemsStatus === 'missing') {
+        return `${name}: ran 0 iterations because its input "${key}" was missing or null`;
+    }
+    if (output?.itemsStatus === 'not_array') {
+        const found = typeof output.itemsFoundType === 'string' ? output.itemsFoundType : 'a value';
+        const article = /^[aeiou]/i.test(found) ? 'an' : 'a';
+        return `${name}: ran 0 iterations because its input "${key}" was ${article} ${oneLine(found)}, not a list`;
+    }
+    return '';
+}
 class SpacesWorkflowsRun extends base_command_1.BaseCommand {
     static description = 'Inspect a workflow run and each durable node state';
     static args = {
@@ -84,6 +117,11 @@ class SpacesWorkflowsRun extends base_command_1.BaseCommand {
                     ? [{ key: 'attention', header: 'ATTENTION' }]
                     : []),
             ], (line) => this.log(line));
+            for (const node of nodes) {
+                const note = describeLoopItemsNote(node);
+                if (note)
+                    this.log(`Note: ${note}`);
+            }
         }
     }
 }

package/dist/commands/spaces/workflows/update.js

@@ -61,7 +61,7 @@ class SpacesWorkflowsUpdate extends base_command_1.BaseCommand {
             description: 'Expected semantic revision; pass with --presentation-revision. For graph/draft writes, omit both to fetch the latest server revisions',
         }),
         'max-duration': core_1.Flags.string({
-            description: 'Run duration limit, e.g. 90m, 4h or 2d. A run still open past it is cancelled with WORKFLOW_RUN_DEADLINE. Applies from the next publish; runs already started keep their deadline',
+            description: 'Run duration limit from 5m to 90d inclusive, e.g. 90m, 4h or 2d. A run still open past it is cancelled with WORKFLOW_RUN_DEADLINE. Applies from the next publish; runs already started keep their deadline',
         }),
         'clear-max-duration': core_1.Flags.boolean({ description: 'Remove the run duration limit' }),
         'presentation-revision': core_1.Flags.integer({

package/dist/commands/tasks/schedule.js

@@ -28,7 +28,7 @@ class TasksSchedule extends base_command_1.BaseCommand {
             dependsOn: ['cron'],
         }),
         'max-runs': core_1.Flags.integer({
-            description: 'Cap total fires (recurring only)',
+            description: 'Cap total occurrences (recurring only): each scheduled fire counts, and so does an occurrence you complete by hand before the scheduler touches it',
             dependsOn: ['cron'],
         }),
         'end-date': core_1.Flags.string({

package/dist/commands/triggers/capabilities.js

@@ -37,6 +37,13 @@ class TriggersCapabilities extends base_command_1.BaseCommand {
             ? capabilities.templateVariables.map((v) => typeof v === 'object' && v !== null ? String(v.name) : String(v))
             : capabilities.templateVariableNames;
         this.log(`Template vars: ${Array.isArray(vars) ? vars.join(', ') : '-'}`);
+        // Some scopes cannot create a trigger until something else is set up, and the refusal
+        // otherwise arrives only after submitting.
+        const needs = capabilities.prerequisites;
+        if (Array.isArray(needs)) {
+            for (const need of needs)
+                this.log(`Needs: ${String(need)}`);
+        }
         // Beside the modes, because `external_work_task` is a mode that cannot be
         // authored without one of these.
         const contracts = capabilities.effectContracts;

package/dist/commands/triggers/create.js

@@ -20,7 +20,10 @@ class TriggersCreate extends base_command_1.BaseCommand {
         'from-json': core_1.Flags.string({
             description: 'Path to a JSON file (or "-" for stdin) to use as the request body',
         }),
-        scope: core_1.Flags.string({ description: 'Trigger scope kind', options: [...triggers_1.TRIGGER_SCOPE_KINDS] }),
+        scope: core_1.Flags.string({
+            description: 'Trigger scope kind. A scope can have prerequisites (a space_oracle Space needs a Leader agent): `triggers capabilities <scope>` lists them under "Needs"',
+            options: [...triggers_1.TRIGGER_SCOPE_KINDS],
+        }),
         ref: core_1.Flags.string({
             description: 'Scope ref as key=value (repeatable), for example --ref agentId=abc',
             multiple: true,

package/dist/lib/commitments.d.ts

@@ -247,6 +247,23 @@ export declare const commitmentApi: {
         };
     }>;
     get: (id: string) => Promise<CommitmentStatusResponse>;
+    controlPreview: (id: string, query: Parameters<typeof withQuery>[1]) => Promise<Record<string, unknown>>;
+    applyControl: (id: string, body: Record<string, unknown>) => Promise<Record<string, unknown>>;
+    controlReceipt: (id: string, controlId: string) => Promise<Record<string, unknown>>;
+    workPlan: (id: string) => Promise<Record<string, unknown>>;
+    observationSummary: (query?: {
+        agentId?: string;
+    }) => Promise<Record<string, unknown>>;
+    draftObservationProbe: (body: Record<string, unknown>) => Promise<Record<string, unknown>>;
+    observationProbe: (id: string, body?: {
+        expectedVersion?: number;
+        timeoutMs?: number;
+    }) => Promise<Record<string, unknown>>;
+    verifyReadiness: (id: string, body: {
+        expectedVersion: number;
+        timeoutMs?: number;
+    }) => Promise<Record<string, unknown>>;
+    readinessReceipt: (id: string, receiptId: string) => Promise<Record<string, unknown>>;
     create: (body: Record<string, unknown>) => Promise<Commitment>;
     update: (id: string, body: Record<string, unknown>) => Promise<Commitment>;
     draftPreflight: (body: Record<string, unknown>) => Promise<CommitmentPreflightReport>;
@@ -629,6 +646,8 @@ export type WatchFlagInputs = {
     spaceIds?: string[];
     monitorIds?: string[];
 };
+/** Keep the canonical one-binding-per-source contract without discarding conflicting intent. */
+export declare function normalizeWatchedSourceDeclarations<T>(declarations: T[]): T[];
 export declare function buildWatchedSources(inputs: WatchFlagInputs): Array<Record<string, unknown>> | undefined;
 /** The evidence-health shape carried on a check's `inputs`. */
 export type EvidenceHealthView = {

package/dist/lib/commitments.js

@@ -9,6 +9,7 @@ exports.parseCommitmentConcurrencyLimit = parseCommitmentConcurrencyLimit;
 exports.commitmentConcurrencyEnvelopePatch = commitmentConcurrencyEnvelopePatch;
 exports.describeCommitmentConcurrency = describeCommitmentConcurrency;
 exports.parseIntervalToMs = parseIntervalToMs;
+exports.normalizeWatchedSourceDeclarations = normalizeWatchedSourceDeclarations;
 exports.buildWatchedSources = buildWatchedSources;
 exports.describeEvidenceHealth = describeEvidenceHealth;
 exports.describeIntervalMs = describeIntervalMs;
@@ -33,6 +34,7 @@ exports.renderCommitmentCases = renderCommitmentCases;
 exports.renderCommitmentCaseDetail = renderCommitmentCaseDetail;
 exports.renderCommitmentRemediationProposals = renderCommitmentRemediationProposals;
 exports.renderCommitmentRemediationProposal = renderCommitmentRemediationProposal;
+const node_util_1 = require("node:util");
 const data_provider_1 = require("@skrr-ai/data-provider");
 /**
  * commitments.ts — request-based client for the Commitments subsystem
@@ -138,6 +140,15 @@ exports.commitmentApi = {
     // GET /:id returns `{ commitment, latestCheck }` — NOT a bare contract.
     // Unwrap before rendering, or every field reads as undefined.
     get: (id) => data_provider_2.request.get(base(id)),
+    controlPreview: (id, query) => data_provider_2.request.get((0, triggers_1.withQuery)(`${base(id)}/control-preview`, query)),
+    applyControl: (id, body) => data_provider_2.request.post(`${base(id)}/control`, body),
+    controlReceipt: (id, controlId) => data_provider_2.request.get(`${base(id)}/control/${encodeURIComponent(controlId)}`),
+    workPlan: (id) => data_provider_2.request.get(`${base(id)}/work-plan`),
+    observationSummary: (query = {}) => data_provider_2.request.get((0, triggers_1.withQuery)('/api/commitments/observation-summary', query)),
+    draftObservationProbe: (body) => data_provider_2.request.post('/api/commitments/observation-probe', body),
+    observationProbe: (id, body = {}) => data_provider_2.request.post(`${base(id)}/observation-probe`, body),
+    verifyReadiness: (id, body) => data_provider_2.request.post(`${base(id)}/readiness-receipt`, body),
+    readinessReceipt: (id, receiptId) => data_provider_2.request.get(`${base(id)}/readiness-receipt/${encodeURIComponent(receiptId)}`),
     create: (body) => data_provider_2.request.post('/api/commitments', body),
     update: (id, body) => data_provider_2.request.patch(base(id), body),
     draftPreflight: (body) => data_provider_2.request.post('/api/commitments/preflight', body),
@@ -496,11 +507,33 @@ function parseIntervalToMs(input) {
     }
     return ms;
 }
+/** Keep the canonical one-binding-per-source contract without discarding conflicting intent. */
+function normalizeWatchedSourceDeclarations(declarations) {
+    const bySource = new Map();
+    const normalized = [];
+    for (const binding of declarations) {
+        if (!binding || typeof binding !== 'object' ||
+            !('source' in binding) || typeof binding.source !== 'string') {
+            normalized.push(binding); // The API owns validation of the remaining DTO.
+            continue;
+        }
+        if (bySource.has(binding.source)) {
+            if (!(0, node_util_1.isDeepStrictEqual)(bySource.get(binding.source), binding)) {
+                throw new Error(`Watched source "${binding.source}" has conflicting declarations. ` +
+                    'Choose one complete binding per source.');
+            }
+            continue;
+        }
+        bySource.set(binding.source, binding);
+        normalized.push(binding);
+    }
+    return normalized;
+}
 function buildWatchedSources(inputs) {
     const watched = (inputs.watch ?? []).filter(Boolean);
     const metricKeys = (inputs.metricKey ?? []).filter(Boolean);
-    const spaceIds = (inputs.spaceIds ?? []).filter(Boolean);
-    const monitorIds = (inputs.monitorIds ?? []).filter(Boolean);
+    const spaceIds = [...new Set((inputs.spaceIds ?? []).filter(Boolean))];
+    const monitorIds = [...new Set((inputs.monitorIds ?? []).filter(Boolean))];
     const githubEvents = (inputs.githubEvents ?? []).filter(Boolean);
     const githubRepository = String(inputs.githubRepository || '')
         .trim()
@@ -584,7 +617,7 @@ function buildWatchedSources(inputs) {
             rows.push({ source, enabled: true });
         }
     }
-    return rows;
+    return normalizeWatchedSourceDeclarations(rows);
 }
 /**
  * One line an author can act on, or nothing.