@skrr-ai/cli 0.1.21 → 0.1.23

package/dist/commands/agents/chat.js

@@ -1,5 +1,9 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.STREAM_LOST_EXIT_CODE = exports.DETACH_EXIT_CODE = void 0;
+exports.interruptedDetachMessage = interruptedDetachMessage;
+exports.reconcileTerminalFromMessages = reconcileTerminalFromMessages;
+exports.inspectTurnCommand = inspectTurnCommand;
 exports.noOutputFailureMessage = noOutputFailureMessage;
 exports.noStreamJsonPayload = noStreamJsonPayload;
 exports.chatStreamHeaderLines = chatStreamHeaderLines;
@@ -8,6 +12,104 @@ const data_provider_1 = require("@skrr-ai/data-provider");
 const base_command_1 = require("../../base-command");
 const agentic_stream_1 = require("../../lib/agentic-stream");
 const web_url_1 = require("../../lib/web-url");
+/**
+ * Exit code for a run the USER stopped watching, by pressing Ctrl-C.
+ *
+ * OSK-2944 established that exiting 1 on a lost stream made "the run failed"
+ * and "we lost the view of a live run" indistinguishable, and invited duplicate
+ * execution. So a detach gets its own non-zero code.
+ *
+ * It must be non-zero on EVERY output mode. The `--jsonl` branch used to
+ * `return` here, which leaves the exit code at 0, so a script driving the CLI
+ * read a detached — possibly already-failed — run as a success. That is the
+ * mode automation actually uses.
+ */
+exports.DETACH_EXIT_CODE = 130;
+/**
+ * Exit code for a detach nobody asked for — the stream was lost, or could not
+ * be attached at all.
+ *
+ * 130 is the conventional "killed by SIGINT" code, and it was returned for a
+ * detach that no signal caused: a script reading it concludes the user pressed
+ * Ctrl-C, which is the opposite of what happened (OSK-7660). Reserving 130 for
+ * an actual interrupt and giving the unattended case its own code keeps both
+ * answers true.
+ */
+exports.STREAM_LOST_EXIT_CODE = 75;
+/**
+ * What to say when the user pressed Ctrl-C and the run did not stop.
+ *
+ * A cancel is REQUESTED over the session; whether the harness honours it is not
+ * something this process can guarantee. Measured on a local harness, where the
+ * answer is checkable with `ps`: the CLI exited, and the shell and the `sleep
+ * 200` it had spawned were still alive at +10s, +26s and +53s — while the CLI
+ * said nothing about it at all (OSK-7733). Three things compound there: work
+ * the user asked to stop keeps consuming their machine and their vendor tokens;
+ * they are not told, so they will not go and kill it; and the record is left
+ * `unfinished: true` with no error, so the cancellation is invisible in history
+ * too.
+ *
+ * Silence is the one unacceptable option, because the user will believe they
+ * cancelled. This says what was asked, what is not guaranteed, and how to look.
+ */
+function interruptedDetachMessage(input) {
+    return (`Cancel requested for run ${input.sessionId}, but no terminal event arrived before the ` +
+        'grace period ended. The runtime MAY STILL BE EXECUTING — a tool call already running on ' +
+        'your machine is not guaranteed to stop. ' +
+        `Check what it did with: ${inspectTurnCommand(input.conversationId)}` +
+        (process.platform === 'win32'
+            ? ''
+            : ', and look for a surviving process with `ps -ef | grep -i claude`'));
+}
+/**
+ * What the durable record says about a turn, read from its messages.
+ *
+ * The stream is not the only witness and must not be the only one consulted: a
+ * run refused during admission writes `error: true` plus the reason on the
+ * response message and never closes the session stream, so a joined subscriber
+ * waits forever for an event that will not come (OSK-7624, OSK-7635, OSK-7720,
+ * OSK-7735). Exported as a pure function so the mapping from a message row to a
+ * terminal verdict is testable without a socket.
+ *
+ * Returns null while the row is still in flight — the caller keeps waiting,
+ * because a long tool call is silence, not a failure.
+ */
+function reconcileTerminalFromMessages(messages, responseMessageId) {
+    const row = (responseMessageId && messages.find((m) => m?.messageId === responseMessageId)) ||
+        [...messages].reverse().find((m) => m && m.isCreatedByUser === false);
+    if (!row)
+        return null;
+    const agentic = row.metadata?.agentic;
+    const recordedError = typeof agentic?.error === 'string' ? agentic.error : undefined;
+    const text = typeof row.text === 'string' ? row.text : '';
+    if (row.error === true) {
+        return {
+            status: 'failed',
+            ...(text ? { text } : {}),
+            // The reason exists on the row; it simply never reached the surface. Say
+            // it, rather than the transport error that masked it (OSK-7595).
+            error: recordedError ?? 'The run failed. No reason was recorded on the message.',
+        };
+    }
+    // `unfinished: false` is the persister's terminal marker; an empty body with
+    // it set is a turn that ended having produced nothing, which is still
+    // terminal and still better reported than waited on.
+    if (row.unfinished === false)
+        return { status: 'completed', text };
+    return null;
+}
+/**
+ * How to look at a turn the CLI is no longer watching.
+ *
+ * NOT `skrr agents chat --conversation <id>`, which is what this used to print:
+ * that command requires the `agentId` argument and `--prompt`, so it exits with
+ * `Missing 1 required arg: agentId` and never reattaches. A recovery
+ * instruction that cannot be run is worse than none — it costs the reader a
+ * round trip to discover the product was wrong.
+ */
+function inspectTurnCommand(conversationId) {
+    return `skrr messages list ${conversationId ?? '<conversation-id>'}`;
+}
 /**
  * A terminal run that produced no text is NOT a success to report silently.
  *
@@ -23,8 +125,7 @@ function noOutputFailureMessage(input) {
     if (input.text?.trim())
         return null;
     return (`The turn ended with no output (status: ${input.status}). ` +
-        'It may have failed on the runtime. Inspect it with: skrr agents chat ' +
-        `--conversation ${input.conversationId ?? '<conversation-id>'}`);
+        `It may have failed on the runtime. Inspect it with: ${inspectTurnCommand(input.conversationId)}`);
 }
 function noStreamJsonPayload(input) {
     const { result, conversationId, agentId, baseURL, threadRootMessageId } = input;
@@ -97,7 +198,19 @@ class AgentsChat extends base_command_1.BaseCommand {
                 'agent’s runtime, tools, session, or working directory and cannot perform work — ' +
                 'it is for inline text assistance. Use --no-stream for a real turn.',
         }),
-        jsonl: core_1.Flags.boolean({ description: 'Emit one JSON event per line while streaming' }),
+        jsonl: core_1.Flags.boolean({
+            description: 'Emit one JSON event per line while streaming. Every line is a complete JSON value. ' +
+                'Assistant text arrives as `text.delta` whose `text` is the CUMULATIVE answer so far, ' +
+                'not a delta — take the last one, or `run.result` at the end. The same text is ' +
+                'mirrored inside `session.output` envelopes for consumers that want the raw stream, ' +
+                'so folding both doubles the answer: pick ONE lane. Inside a `session.output`, ' +
+                '`envelopes[].__seq` is the dedupe key and the ordering key — the same envelope is ' +
+                'delivered by more than one room, and a re-delivery repeats its `__seq`. A ' +
+                '`stream.gap` event means envelopes in that seq range never arrived and the streamed ' +
+                'text is short; `run.result` and the persisted message remain authoritative. Tool ' +
+                'calls arrive as `tool.started` / `tool.completed`, once per `toolUseId`, on cloud ' +
+                'and local-harness runs alike.',
+        }),
         json: core_1.Flags.boolean({
             description: 'Emit the final one-shot response as JSON (use with --no-stream)',
         }),
@@ -122,7 +235,7 @@ class AgentsChat extends base_command_1.BaseCommand {
      * canonical scope at all. Naming that at launch is cheap; discovering it
      * mid-run costs a session.
      */
-    static TASK_REF_IN_PROMPT = /\b(?:[A-Z][A-Z0-9]*-\d+|[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})\b/;
+    static TASK_REF_IN_PROMPT = /\b(?:OSK-\d+|[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})\b/;
     async run() {
         this.requireAuth();
         const { args, flags } = await this.parse(AgentsChat);
@@ -131,6 +244,15 @@ class AgentsChat extends base_command_1.BaseCommand {
                 exit: 2,
             });
         }
+        if (flags.quick && flags.jsonl) {
+            // Accepted-and-ignored is worse than rejected: the caller had a parser
+            // waiting, got prose, and read the `JSONDecodeError` as the quick path
+            // having failed — which it had not (OSK-7647). `--quick` is a single
+            // one-shot response, so there is no event stream for `--jsonl` to carry.
+            this.error('--jsonl has no meaning with --quick: the persona-only summarizer returns one ' +
+                'response and streams no events. Use --quick --json for a machine-readable ' +
+                'one-shot, or drop --quick for a real streamed turn.', { exit: 2 });
+        }
         if (flags['approve-tools'] && !process.stdin.isTTY) {
             this.error('--approve-tools requires an interactive terminal.', { exit: 2 });
         }
@@ -171,7 +293,12 @@ class AgentsChat extends base_command_1.BaseCommand {
                 'Address every task operation with this id explicitly, e.g.',
                 `  skrr tasks show ${taskId} --json`,
                 `  skrr tasks comments add ${taskId} --body "<progress>"`,
-                `  skrr tasks complete ${taskId} --summary "<what you did>" --artifacts "<refs>"`,
+                // `--deliverables`, not `--artifacts`: the flag was renamed with the
+                // domain and this line was not, so an agent following it verbatim got
+                // `Nonexistent flag: --artifacts` and had to reason its way out —
+                // costing a tool call, a model turn, and a paragraph of apology in the
+                // user-visible task output (OSK-7683).
+                `  skrr tasks complete ${taskId} --summary "<what you did>" --deliverables "<refs>"`,
                 '',
                 'This is a chat turn, not a managed task run: the task is NOT checked out and its ' +
                     'status is not managed for you. Do not go looking for an implicit task context — ' +
@@ -181,11 +308,22 @@ class AgentsChat extends base_command_1.BaseCommand {
                 this.log(`Bound to task ${task.identifier ?? taskId} (chat turn — task not checked out)`);
             }
         }
-        else if (AgentsChat.TASK_REF_IN_PROMPT.test(flags.prompt)) {
-            this.warn('The prompt names what looks like a task reference, but this turn is NOT bound to a ' +
-                'task: the session will report OVERSKY_SESSION_TASK_CONTEXT=main_chat and ' +
-                '`skrr tasks show` without an id will fail with TASK_CONTEXT_MISSING. Pass ' +
-                '--task <id> to inject the canonical scope, or use `skrr tasks start` for a managed run.');
+        else {
+            // Quote what matched. The warning states as fact that a task reference is
+            // present, and the old pattern `[A-Z][A-Z0-9]*-\d+` matched any uppercase
+            // token followed by a hyphen and digits — `UTF-8`, `GPT-4`, `RFC-2119`,
+            // `ERROR-500`, and every marker string a probe used — so it fired on
+            // prompts naming no task and gave the reader nothing to check it against.
+            // A warning that cries wolf on ordinary text is a warning people stop
+            // reading, and this one guards a genuinely expensive mistake (OSK-7736).
+            const match = AgentsChat.TASK_REF_IN_PROMPT.exec(flags.prompt);
+            if (match) {
+                this.warn(`The prompt names what looks like a task reference ("${match[0]}"), but this turn is ` +
+                    'NOT bound to a task: the session will report ' +
+                    'OVERSKY_SESSION_TASK_CONTEXT=main_chat and `skrr tasks show` without an id will ' +
+                    'fail with TASK_CONTEXT_MISSING. Pass --task <id> to inject the canonical scope, ' +
+                    'or use `skrr tasks start` for a managed run.');
+            }
         }
         // OSK-2936 — `--quick` is the ONLY route to the non-executing summarizer,
         // and it says so.
@@ -253,7 +391,10 @@ class AgentsChat extends base_command_1.BaseCommand {
         // `--no-stream` runs the SAME turn; it only withholds the live output.
         const quiet = !!flags['no-stream'];
         if (flags.jsonl) {
-            this.log(JSON.stringify({
+            // Written through the one JSONL helper, not `this.log`: oclif routes that
+            // through `util.format`, which rewrites `%s`-shaped sequences that appear
+            // in ordinary agent output (OSK-7629).
+            (0, agentic_stream_1.writeJsonLine)(process.stdout, {
                 type: 'run.accepted',
                 sessionId: started.sessionId,
                 conversationId: started.conversationId,
@@ -261,7 +402,7 @@ class AgentsChat extends base_command_1.BaseCommand {
                 responseMessageId: started.responseMessageId,
                 agentId: args.agentId,
                 url: (0, web_url_1.agentUrlFrom)(this.cliConfig.baseURL, { id: args.agentId }),
-            }));
+            });
         }
         else if (!quiet) {
             for (const line of chatStreamHeaderLines({
@@ -274,6 +415,20 @@ class AgentsChat extends base_command_1.BaseCommand {
                 this.log(line);
             }
         }
+        // The durable record, consulted when the stream goes quiet. Without this
+        // the CLI has no terminal condition for a run-level failure at all: the
+        // refusal is written to the message and the session stream is never closed,
+        // so an interactive user waits forever and a script that shells out to
+        // `agents chat` never returns (OSK-7735).
+        const conversationId = started.conversationId;
+        const reconcileTerminal = conversationId
+            ? async () => {
+                const messages = (await data_provider_1.dataService.getMessagesByConvoId(conversationId));
+                if (!Array.isArray(messages))
+                    return null;
+                return reconcileTerminalFromMessages(messages, started.responseMessageId);
+            }
+            : undefined;
         const client = new agentic_stream_1.AgenticStreamClient({
             baseURL: this.cliConfig.baseURL,
             token: this.resolvedCredential.token,
@@ -282,6 +437,7 @@ class AgentsChat extends base_command_1.BaseCommand {
             jsonl: flags.jsonl,
             quiet,
             approveTools: flags['approve-tools'],
+            reconcileTerminal,
         });
         // OSK-2938 — Ctrl-C must be bounded, visible, and honest about what it
         // did NOT stop.
@@ -311,7 +467,8 @@ class AgentsChat extends base_command_1.BaseCommand {
                 client.cancel();
                 if (!flags.jsonl) {
                     this.log(`\nCancelling run ${started.sessionId}… (waiting up to ${CANCEL_GRACE_MS / 1000}s; ` +
-                        'press Ctrl-C again to detach)');
+                        'press Ctrl-C again to detach). A tool call already running on the runtime is ' +
+                        'not guaranteed to stop.');
                 }
                 graceTimer = setTimeout(() => detach?.(), CANCEL_GRACE_MS);
                 graceTimer.unref?.();
@@ -333,28 +490,51 @@ class AgentsChat extends base_command_1.BaseCommand {
                 }),
                 detached,
             ]);
+            // Ask the record before saying the run may still be running. That was
+            // said of a turn which had completed thirteen seconds earlier, and of
+            // turns the server had already finalised as errors — "it may still be
+            // executing" is the most expensive thing to be wrong about here, because
+            // it is what stops a caller retrying or alerting (OSK-7595, OSK-7660).
+            let reconciled = null;
             if (outcome === 'detached') {
-                // Never claim the run stopped — we only stopped watching it.
-                const message = `Detached from run ${started.sessionId} before it reached a terminal state. ` +
-                    'It may still be executing on the runtime. ' +
-                    `Check with: skrr agents chat --conversation ${started.conversationId ?? '<conversation-id>'}`;
+                if (await client.probeTerminal('detach'))
+                    reconciled = client.settledResult();
+            }
+            if (outcome === 'detached' && !reconciled) {
+                const message = interrupts > 0
+                    ? interruptedDetachMessage({
+                        sessionId: started.sessionId,
+                        conversationId: started.conversationId,
+                    })
+                    : `Detached from run ${started.sessionId} before it reached a terminal state. ` +
+                        'It may still be executing on the runtime. ' +
+                        `Check with: ${inspectTurnCommand(started.conversationId)}`;
+                // 130 only when a signal actually caused this; otherwise the stream was
+                // lost and claiming SIGINT lies to every script reading the code
+                // (OSK-7660).
+                const exit = interrupts > 0 ? exports.DETACH_EXIT_CODE : exports.STREAM_LOST_EXIT_CODE;
                 if (flags.jsonl) {
-                    this.log(JSON.stringify({
+                    (0, agentic_stream_1.writeJsonLine)(process.stdout, {
                         type: 'run.detached',
                         sessionId: started.sessionId,
                         conversationId: started.conversationId,
+                        interrupted: interrupts > 0,
                         message,
-                    }));
+                    });
+                    // A detach is not a success in any output mode. `--jsonl` is the mode
+                    // automation drives, so leaving this at 0 is the one that actually
+                    // costs someone a wrong decision.
+                    process.exitCode = exit;
                     return;
                 }
-                this.error(message, { exit: 130 });
+                this.error(message, { exit });
             }
-            const result = outcome;
+            const result = reconciled ?? outcome;
             if (flags.jsonl) {
                 // The event stream already contains the terminal event. This summary
                 // makes shell consumers able to find the final text without replaying
                 // the event reducer.
-                this.log(JSON.stringify({ type: 'run.result', ...result }));
+                (0, agentic_stream_1.writeJsonLine)(process.stdout, { type: 'run.result', ...result });
             }
             else if (quiet && flags.json) {
                 // A real executed turn — the metadata says so, unlike `--quick`.

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

@@ -27,6 +27,44 @@ export declare function agentCreateMissingFieldsMessage(missing: string[]): stri
  * be reported.
  */
 export declare function agentCreateMissingFields(payload: Record<string, unknown>): string[];
+/**
+ * OSK-7680 — what creating ONE agent also starts.
+ *
+ * Within ~10 seconds of `agents create`, the new agent owns five
+ * system-managed commitments, four of them already active, on 30m/1h/2h/12h/1d
+ * cadences, three of them in Execute mode. Nothing in the create output said
+ * so: it carried only `proactiveProvisioning: {status: 'pending'}`, which does
+ * not read as "I am about to enrol this agent in four recurring autonomous
+ * loops". The person who asked for one agent got a standing workload, and the
+ * default `commitments list --agent <id>` then answered "No commitments."
+ *
+ * Said at creation because that is the moment the decision is being made and
+ * the moment `--no-relationship-loops` is still available. The opt-out already
+ * existed; only the disclosure was missing, and an opt-out nobody is told about
+ * is not one.
+ */
+/**
+ * KEYS THE SERVER DID NOT KEEP.
+ *
+ * OSK-7704 — a `--from-json` body carrying
+ * `"machineRequirements": {"capabilities": ["daemonTools"]}` created the agent
+ * and dropped the field: no warning, no 400, and `agents show --json` has no
+ * such key. The escape hatch the help points at for anything the flags do not
+ * cover accepts arbitrary keys and silently discards the ones the server does
+ * not model, so a caller who declares a requirement believes they declared it.
+ *
+ * Compared against the CREATED AGENT rather than a hard-coded field list: the
+ * server owns which keys it models, that set changes, and a list here would
+ * drift into warning about fields that now work. A key that came back — under
+ * any value, including `null` where the server deliberately stores one — is
+ * kept; anything absent from the response was not.
+ *
+ * A warning, never a refusal. Some keys legitimately do not round-trip (a
+ * write-only secret, a field the read projection omits), and turning those into
+ * a failed create would be worse than the silence.
+ */
+export declare function unappliedPayloadKeys(sent: Record<string, unknown>, created: unknown, ignore?: readonly string[]): string[];
+export declare function backgroundLoopLines(agentId: string, relationshipLoopsSkipped: boolean): string[];
 export default class AgentsCreate extends BaseCommand {
     static description: string;
     static examples: string[];

package/dist/commands/agents/create.js

@@ -2,6 +2,8 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.agentCreateMissingFieldsMessage = agentCreateMissingFieldsMessage;
 exports.agentCreateMissingFields = agentCreateMissingFields;
+exports.unappliedPayloadKeys = unappliedPayloadKeys;
+exports.backgroundLoopLines = backgroundLoopLines;
 const core_1 = require("@oclif/core");
 const data_provider_1 = require("@skrr-ai/data-provider");
 const base_command_1 = require("../../base-command");
@@ -55,6 +57,72 @@ function agentCreateMissingFields(payload) {
         missing.push('--target');
     return missing;
 }
+/**
+ * OSK-7680 — what creating ONE agent also starts.
+ *
+ * Within ~10 seconds of `agents create`, the new agent owns five
+ * system-managed commitments, four of them already active, on 30m/1h/2h/12h/1d
+ * cadences, three of them in Execute mode. Nothing in the create output said
+ * so: it carried only `proactiveProvisioning: {status: 'pending'}`, which does
+ * not read as "I am about to enrol this agent in four recurring autonomous
+ * loops". The person who asked for one agent got a standing workload, and the
+ * default `commitments list --agent <id>` then answered "No commitments."
+ *
+ * Said at creation because that is the moment the decision is being made and
+ * the moment `--no-relationship-loops` is still available. The opt-out already
+ * existed; only the disclosure was missing, and an opt-out nobody is told about
+ * is not one.
+ */
+/**
+ * KEYS THE SERVER DID NOT KEEP.
+ *
+ * OSK-7704 — a `--from-json` body carrying
+ * `"machineRequirements": {"capabilities": ["daemonTools"]}` created the agent
+ * and dropped the field: no warning, no 400, and `agents show --json` has no
+ * such key. The escape hatch the help points at for anything the flags do not
+ * cover accepts arbitrary keys and silently discards the ones the server does
+ * not model, so a caller who declares a requirement believes they declared it.
+ *
+ * Compared against the CREATED AGENT rather than a hard-coded field list: the
+ * server owns which keys it models, that set changes, and a list here would
+ * drift into warning about fields that now work. A key that came back — under
+ * any value, including `null` where the server deliberately stores one — is
+ * kept; anything absent from the response was not.
+ *
+ * A warning, never a refusal. Some keys legitimately do not round-trip (a
+ * write-only secret, a field the read projection omits), and turning those into
+ * a failed create would be worse than the silence.
+ */
+function unappliedPayloadKeys(sent, created, ignore = []) {
+    if (!created || typeof created !== 'object' || Array.isArray(created))
+        return [];
+    const back = created;
+    const skip = new Set(ignore);
+    return Object.keys(sent)
+        .filter((key) => !skip.has(key))
+        .filter((key) => sent[key] !== undefined)
+        .filter((key) => !Object.prototype.hasOwnProperty.call(back, key))
+        .sort();
+}
+function backgroundLoopLines(agentId, relationshipLoopsSkipped) {
+    if (relationshipLoopsSkipped) {
+        return [
+            'Background loops: relationship portfolio skipped (--no-relationship-loops). ' +
+                'Self-reflection is still seeded and runs on its own cadence.',
+            `  skrr commitments list --agent ${agentId} --include-system   # what it still runs`,
+        ];
+    }
+    return [
+        'Background loops: this agent is being enrolled in system-managed commitments — ' +
+            'self-reflection, conversation continuity, relationship pulse, commitment incubator ' +
+            'and open-loop closer. They run on their own cadence, unprompted, and are hidden ' +
+            'from the default commitments list.',
+        `  skrr commitments list --agent ${agentId} --include-system   # see them`,
+        `  skrr commitments operating-review ${agentId}                # what they are doing`,
+        '  skrr commitments pause <commitment-id>                      # stop one',
+        '  skrr agents create --no-relationship-loops                  # a single-purpose agent next time',
+    ];
+}
 class AgentsCreate extends base_command_1.BaseCommand {
     static description = 'Create a new agent in the selected workspace, or in your default workspace when --workspace is omitted (`skrr workspaces list` names it)';
     static examples = [
@@ -91,7 +159,17 @@ class AgentsCreate extends base_command_1.BaseCommand {
         }),
         category: core_1.Flags.string({ description: 'Agent category' }),
         target: core_1.Flags.string({
-            description: 'Required execution target. Use a Harness id, Hosted Machine session, or Agent Worker. Use hosted-machine, sbs_..., agent-worker, or a connected Harness id.',
+            description: 'Required execution target. Use a Harness id, Hosted Machine session, or Agent Worker. ' +
+                'Use hosted-machine, sbs_..., agent-worker, or a connected Harness id. ' +
+                // There is no "unplaced" agent to create: a body that reaches the API
+                // without one is given an explicit `agent-worker` target server-side,
+                // so an operator who expected an unset field gets a real, visible
+                // placement they did not choose (OSK-7654). This command refuses the
+                // omission rather than letting that happen silently — say so, so the
+                // refusal reads as a contract rather than a missing feature.
+                'There is no unplaced agent: a create that omits this is given an ' +
+                '`agent-worker` target by the server, so this command asks instead of ' +
+                'letting a placement be chosen for you.',
         }),
         'next-target': core_1.Flags.string({
             description: 'Next execution target in exact execution order after --target. Repeat in the order it should be tried.',
@@ -229,17 +307,32 @@ class AgentsCreate extends base_command_1.BaseCommand {
         catch (err) {
             this.handleApiError(err);
         }
+        // Said before anything else, and in both output modes: a caller who
+        // declared a requirement the server does not model has NOT declared it, and
+        // finding that out later — from a run that landed somewhere it should not
+        // have — is the expensive way (OSK-7704).
+        // relationshipLoops is an input-only provisioning control. The server
+        // applies it by deciding which system commitments to seed, so it is not an
+        // Agent document field and is intentionally absent from the response.
+        const unapplied = unappliedPayloadKeys(payload, created, ['relationshipLoops']);
+        if (unapplied.length > 0) {
+            this.warn(`The server did not keep ${unapplied.join(', ')} — ${unapplied.length === 1 ? 'that field is' : 'those fields are'} not part of the agent it created. Check \`skrr agents show <id> --json\`.`);
+        }
         if (flags.json) {
             this.log(JSON.stringify((0, web_url_1.withAgentUrl)(this.cliConfig.baseURL, created), null, 2));
             return;
         }
         const a = created;
-        this.log(`Created agent ${a.id ?? a._id ?? '?'} — ${a.name ?? '(no name)'}`);
+        const agentId = String(a.id ?? a._id ?? '?');
+        this.log(`Created agent ${agentId} — ${a.name ?? '(no name)'}`);
         // Chosen for the user, so say so: a silent default is the kind of thing
         // people discover much later, when it matters.
         if (appliedDefaults.length > 0) {
             this.log(`Defaults applied: ${appliedDefaults.join(', ')}`);
         }
+        for (const line of backgroundLoopLines(agentId, flags['no-relationship-loops'] === true)) {
+            this.log(line);
+        }
         this.log(`URL: ${(0, web_url_1.withAgentUrl)(this.cliConfig.baseURL, a).url ?? '-'}`);
     }
 }

package/dist/commands/agents/schedule-trace.js

@@ -77,7 +77,18 @@ class AgentsScheduleTrace extends base_command_1.BaseCommand {
         if (events.length === 0) {
             // An empty trace is a real answer — nothing touched this day's schedule —
             // and must not read as a failed lookup.
+            //
+            // It is also a CLAIM, and it was wrong once (OSK-7658): the trace saw only
+            // triggers the smart-schedule planner had minted, so a one-shot from
+            // `skrr agents schedule --at` that fired and replied rendered as "nothing
+            // happened". The server-side filter is fixed; the sentence now names the
+            // two surfaces that would disagree, because a reader who has just been
+            // told nothing happened on a day they watched something happen should not
+            // have to guess where to look next.
             this.log('No schedule events for this day.');
+            this.log('');
+            this.log(`  ${this.config.bin} agents schedule-overview ${args.agent}   # what is armed, and recent fires`);
+            this.log(`  ${this.config.bin} agents activity ${args.agent}            # what the agent actually did`);
             return;
         }
         (0, format_1.renderTable)(events.map((e) => ({

package/dist/commands/agents/show.js

@@ -57,6 +57,10 @@ function agentExecutionOrderLines(agent) {
     const entries = projected.length > 0 ? projected : fallback;
     if (entries.length === 0)
         return ['Execution order: automatic (no configured target)'];
+    // Only the SERVER's projection knows whether a selector resolves. The local
+    // fallback is built from the stored policy and has no resolution information
+    // at all, so it must not claim one either way.
+    const resolved = projected.length > 0;
     return [
         'Execution order:',
         ...entries.map((entry, index) => {
@@ -64,10 +68,34 @@ function agentExecutionOrderLines(agent) {
             const target = typeof entry.name === 'string' && entry.name ? entry.name : entry.selector;
             const label = typeof entry.label === 'string' && entry.label ? ` — ${entry.label}` : '';
             const status = typeof entry.status === 'string' ? ` (${entry.status})` : '';
-            return `  ${position}. ${target || '(invalid target)'}${status}${label}`;
+            // An UNRESOLVABLE target used to render as an absence — no name, no
+            // `(online)`/`(offline)` marker — on a line that otherwise looks like a
+            // normal one. `attach-harness` accepts an id that resolves to nothing
+            // with `ok: true`, so the typo persists silently, and an operator
+            // reviewing someone else's config reads entry 2 as a harness whose
+            // status is momentarily unknown. Entry 2 in a chain is by definition the
+            // one you have not looked at recently. An unresolvable target is a
+            // strictly worse condition than an offline one, and offline is loud
+            // (OSK-7677). An absence becomes a statement.
+            const unresolvable = resolved &&
+                !status &&
+                !(typeof entry.name === 'string' && entry.name) &&
+                !isSynthetic(entry)
+                ? '  [!] no such harness — nothing is registered under this id'
+                : '';
+            return `  ${position}. ${target || '(invalid target)'}${status}${label}${unresolvable}`;
         }),
     ];
 }
+/** The platform's own products resolve by name, not by a harness lookup. */
+function isSynthetic(entry) {
+    const kind = typeof entry.kind === 'string' ? entry.kind : '';
+    if (kind === 'agent-worker' || kind === 'hosted-machine' || kind === 'hosted-job-machine') {
+        return true;
+    }
+    const selector = typeof entry.selector === 'string' ? entry.selector : '';
+    return selector.startsWith('__oversky_') || selector.startsWith('sbs_');
+}
 class AgentsShow extends base_command_1.BaseCommand {
     static description = 'Show details for a single agent';
     static examples = [

package/dist/commands/api-keys/create.d.ts

@@ -0,0 +1,24 @@
+import { BaseCommand } from '../../base-command';
+/**
+ * Mint a Managed Agents API key for a Space.
+ *
+ * The secret is displayed EXACTLY ONCE. There is no endpoint that reveals it
+ * again, so this command says that where the value is printed rather than in a
+ * footnote — a caller that scrolls past it has to rotate.
+ */
+export default class ApiKeysCreate extends BaseCommand {
+    static description: string;
+    static examples: string[];
+    static args: {
+        name: import("@oclif/core/lib/interfaces").Arg<string | undefined, Record<string, unknown>>;
+    };
+    static flags: {
+        space: import("@oclif/core/lib/interfaces").OptionFlag<string, import("@oclif/core/lib/interfaces").CustomOptions>;
+        name: import("@oclif/core/lib/interfaces").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
+        env: import("@oclif/core/lib/interfaces").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
+        scope: import("@oclif/core/lib/interfaces").OptionFlag<string[] | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
+        'expires-at': 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>;
+}