@skrr-ai/cli 0.1.37 → 0.1.39

package/dist/commands/agents/scene-background/upload.js

@@ -0,0 +1,97 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const core_1 = require("@oclif/core");
+const promises_1 = require("node:fs/promises");
+const node_path_1 = require("node:path");
+const data_provider_1 = require("@skrr-ai/data-provider");
+const base_command_1 = require("../../../base-command");
+const agent_visual_refs_1 = require("../../../lib/agent-visual-refs");
+/**
+ * Upload an image as an agent's 3D backdrop.
+ *
+ * `--scene-background image:<filepath>@<source>` was documented and had no value
+ * that could succeed from the CLI. The server accepts an image backdrop only from
+ * the writer's own WALLPAPER upload namespace (`/images/<userId>/wallpaper-…`),
+ * and the only thing that writes there is `POST /api/files/images/wallpaper` —
+ * which nothing in `skrr` called. Every attempt ended in
+ * "Scene background image must be one you uploaded", and the flag's word
+ * `<filepath>` read like a path on disk, which sent people looking in the wrong
+ * place.
+ *
+ * This is that upload, followed by setting it, so the documented form finally
+ * has a producer. `--upload-only` prints the `--scene-background` value instead,
+ * for scripts that set it later or on several agents.
+ */
+class AgentsSceneBackgroundUpload extends base_command_1.BaseCommand {
+    static description = "Upload an image as an agent's 3D backdrop and set it";
+    static examples = [
+        '<%= config.bin %> agents scene-background upload agent_abc --file ./room.png',
+        '<%= config.bin %> agents scene-background upload agent_abc --file ./room.jpg --upload-only',
+    ];
+    static args = {
+        agentId: core_1.Args.string({ description: 'Agent ID', required: true, ignoreStdin: true }),
+    };
+    static flags = {
+        file: core_1.Flags.string({
+            description: 'Image to upload: PNG, JPEG, WebP or GIF (not SVG). Resized to at most 2560px wide.',
+            required: true,
+        }),
+        'upload-only': core_1.Flags.boolean({
+            description: 'Upload, then print the --scene-background value without changing the agent',
+        }),
+        json: core_1.Flags.boolean({ description: 'Output JSON' }),
+    };
+    async run() {
+        this.requireAuth();
+        const { args, flags } = await this.parse(AgentsSceneBackgroundUpload);
+        // The server gates on the part's MIME type, so an untyped Blob would be
+        // refused as "Unsupported file type" whatever its bytes were.
+        const type = (0, agent_visual_refs_1.imageUploadMimeType)(flags.file);
+        if (!type) {
+            this.error(`--file must be a .png, .jpg, .jpeg, .webp or .gif image (got ${(0, node_path_1.basename)(flags.file)}).`, { exit: 1 });
+        }
+        let bytes;
+        try {
+            bytes = await (0, promises_1.readFile)(flags.file);
+        }
+        catch (err) {
+            this.error(`Could not read --file ${flags.file}: ${err.message}`, { exit: 1 });
+        }
+        const form = new FormData();
+        form.append('file', new Blob([new Uint8Array(bytes)], { type }), (0, node_path_1.basename)(flags.file));
+        let uploaded;
+        try {
+            uploaded = (await data_provider_1.dataService.uploadWallpaper(form));
+        }
+        catch (err) {
+            this.handleApiError(err);
+        }
+        const sceneBackground = {
+            type: 'image',
+            filepath: uploaded.filepath,
+            source: uploaded.source,
+        };
+        const flagValue = `image:${sceneBackground.filepath}@${sceneBackground.source}`;
+        if (!flags['upload-only']) {
+            try {
+                await data_provider_1.dataService.updateAgent({
+                    agent_id: args.agentId,
+                    data: { sceneBackground },
+                });
+            }
+            catch (err) {
+                this.handleApiError(err);
+            }
+        }
+        if (flags.json) {
+            this.log(JSON.stringify({ agentId: args.agentId, sceneBackground, flagValue, applied: !flags['upload-only'] }, null, 2));
+            return;
+        }
+        this.log(flags['upload-only']
+            ? `Uploaded. Set it with: --scene-background ${flagValue}`
+            : `Backdrop for agent ${args.agentId} is now the uploaded image.`);
+        if (!flags['upload-only'])
+            this.printAgentUrl(args.agentId);
+    }
+}
+exports.default = AgentsSceneBackgroundUpload;

package/dist/commands/agents/show.js

@@ -8,6 +8,7 @@ const base_command_1 = require("../../base-command");
 const harness_provider_input_1 = require("../../lib/harness-provider-input");
 const web_url_1 = require("../../lib/web-url");
 const hosted_machines_1 = require("../../lib/hosted-machines");
+const agent_visual_refs_1 = require("../../lib/agent-visual-refs");
 /**
  * OSK-4901 — the tone line for `agents show` text output.
  *
@@ -139,6 +140,18 @@ class AgentsShow extends base_command_1.BaseCommand {
         this.log(`Provider:    ${a.provider ?? '-'}`);
         this.log(`Model:       ${a.model ?? '-'}`);
         this.log(`Tone:        ${agentToneLine(a)}`);
+        this.log(`Avatar:      ${(0, agent_visual_refs_1.agentAvatarLine)(a.avatar)}`);
+        this.log(`Backdrop:    ${(0, agent_visual_refs_1.agentSceneBackgroundLine)(a.sceneBackground)}`);
+        // Pin and mute are per-user, so they live in preferences rather than on the
+        // agent — which is why this view never showed either. Best-effort read.
+        try {
+            const prefs = (await data_provider_1.dataService.getAgentPreferences(String(a.id ?? args.id)))?.preferences;
+            this.log(`Pinned:      ${prefs?.isPinned ? 'yes' : 'no'}`);
+            this.log(`Muted:       ${prefs?.isMuted ? 'yes' : 'no'}`);
+        }
+        catch {
+            /* preferences unreadable — omit rather than claim "no" */
+        }
         this.log(`Category:    ${a.category ?? '-'}`);
         this.log(`Author:      ${a.author ?? '-'}`);
         // A cap the user cannot see is a cap they cannot diagnose: a saturated

package/dist/commands/agents/tools/calls.d.ts

@@ -1,12 +1,29 @@
 import { BaseCommand } from '../../../base-command';
+type ToolCallRow = {
+    messageId: string;
+    toolUseId: string;
+    name: string;
+    args: string;
+    output: string;
+    complete: boolean;
+    source: 'message' | 'ledger';
+};
 /**
- * Tool calls recorded in one conversation.
+ * The tool calls in a conversation, read from the conversation's own messages.
  *
- * `conversationId` is REQUIRED by the endpoint, not optional with a default, so
- * it is a required flag rather than something this command guesses — a
- * conversation-less listing would silently be somebody else's transcript or
- * nothing at all.
+ * This command read `GET /api/agents/tools/calls`, the `ToolCall` ledger — and
+ * nothing in the codebase writes that ledger: `createToolCall` has no caller. So
+ * it answered "No tool calls recorded" for EVERY conversation, including one where
+ * the agent had just run a Bash command, and for a conversation id that did not
+ * exist at all. Nobody could tell a broken command from an empty answer.
+ *
+ * Every agent turn records its tool calls as `tool_call` content parts on the
+ * assistant message (name, arguments, output), so that is the primary source. A
+ * conversation that does not exist is a NOT_FOUND, not an empty list. Ledger rows
+ * are still read and merged, so the endpoint stays reachable and a future writer
+ * is not silently ignored.
  */
+export declare function toolCallsFromMessages(messages: unknown): ToolCallRow[];
 export default class AgentsToolsCalls extends BaseCommand {
     static description: string;
     static examples: string[];
@@ -16,3 +33,4 @@ export default class AgentsToolsCalls extends BaseCommand {
     };
     run(): Promise<void>;
 }
+export {};

package/dist/commands/agents/tools/calls.js

@@ -1,19 +1,58 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.toolCallsFromMessages = toolCallsFromMessages;
 const core_1 = require("@oclif/core");
 const data_provider_1 = require("@skrr-ai/data-provider");
 const base_command_1 = require("../../../base-command");
 const format_1 = require("../../../lib/format");
+const clip = (value, width) => {
+    const text = value == null
+        ? ''
+        : typeof value === 'string'
+            ? value
+            : (JSON.stringify(value) ?? String(value));
+    const flat = text.replace(/\s+/g, ' ').trim();
+    return flat.length > width ? `${flat.slice(0, width - 1)}…` : flat;
+};
 /**
- * Tool calls recorded in one conversation.
+ * The tool calls in a conversation, read from the conversation's own messages.
  *
- * `conversationId` is REQUIRED by the endpoint, not optional with a default, so
- * it is a required flag rather than something this command guesses — a
- * conversation-less listing would silently be somebody else's transcript or
- * nothing at all.
+ * This command read `GET /api/agents/tools/calls`, the `ToolCall` ledger — and
+ * nothing in the codebase writes that ledger: `createToolCall` has no caller. So
+ * it answered "No tool calls recorded" for EVERY conversation, including one where
+ * the agent had just run a Bash command, and for a conversation id that did not
+ * exist at all. Nobody could tell a broken command from an empty answer.
+ *
+ * Every agent turn records its tool calls as `tool_call` content parts on the
+ * assistant message (name, arguments, output), so that is the primary source. A
+ * conversation that does not exist is a NOT_FOUND, not an empty list. Ledger rows
+ * are still read and merged, so the endpoint stays reachable and a future writer
+ * is not silently ignored.
  */
+function toolCallsFromMessages(messages) {
+    const rows = [];
+    for (const message of Array.isArray(messages) ? messages : []) {
+        const m = message;
+        for (const part of Array.isArray(m.content) ? m.content : []) {
+            const p = part;
+            if (p?.type !== 'tool_call' || !p.tool_call)
+                continue;
+            const call = p.tool_call;
+            rows.push({
+                messageId: String(m.messageId ?? '-'),
+                toolUseId: String(call.id ?? '-'),
+                name: String(call.name ?? '-'),
+                args: clip(call.args, 200),
+                output: clip(call.output, 200),
+                complete: Number(call.progress ?? 0) >= 1 || call.output != null,
+                source: 'message',
+            });
+        }
+    }
+    return rows;
+}
 class AgentsToolsCalls extends base_command_1.BaseCommand {
-    static description = 'List the tool calls recorded in one conversation';
+    static description = 'List the tool calls an agent made in one conversation';
     static examples = [
         '<%= config.bin %> agents tools calls --conversation <conversation-id>',
     ];
@@ -24,30 +63,54 @@ class AgentsToolsCalls extends base_command_1.BaseCommand {
     async run() {
         this.requireAuth();
         const { flags } = await this.parse(AgentsToolsCalls);
-        let calls;
+        let messages;
         try {
-            calls = await data_provider_1.dataService.getToolCalls({ conversationId: flags.conversation });
+            // NOT_FOUND here is the honest answer for a conversation that does not
+            // exist, and handleApiError reports it as such.
+            messages = await data_provider_1.dataService.getMessagesByConvoId(flags.conversation);
         }
         catch (err) {
             this.handleApiError(err);
         }
+        const rows = toolCallsFromMessages(messages);
+        try {
+            const ledger = (await data_provider_1.dataService.getToolCalls({
+                conversationId: flags.conversation,
+            }));
+            for (const entry of ledger ?? []) {
+                rows.push({
+                    messageId: String(entry.messageId ?? '-'),
+                    toolUseId: String(entry.toolId ?? '-'),
+                    name: String(entry.toolId ?? '-'),
+                    args: '',
+                    output: clip(entry.result, 200),
+                    complete: true,
+                    source: 'ledger',
+                });
+            }
+        }
+        catch {
+            /* the ledger is supplementary; the messages already answered */
+        }
         if (flags.json) {
-            this.log(JSON.stringify(calls, null, 2));
+            this.log(JSON.stringify(rows, null, 2));
             return;
         }
-        const rows = (calls ?? []);
         if (rows.length === 0) {
-            this.log(`No tool calls recorded in conversation ${flags.conversation}.`);
+            const count = Array.isArray(messages) ? messages.length : 0;
+            this.log(`Conversation ${flags.conversation} has ${count} message${count === 1 ? '' : 's'} and no tool calls.`);
             return;
         }
-        (0, format_1.renderTable)(rows.map((call) => ({
-            toolId: String(call.toolId ?? '-'),
-            messageId: String(call.messageId ?? '-'),
-            blockIndex: call.blockIndex === undefined ? '-' : String(call.blockIndex),
+        (0, format_1.renderTable)(rows.map((row) => ({
+            name: row.name,
+            args: row.args || '-',
+            output: row.complete ? row.output || '(empty)' : '(no result recorded)',
+            toolUseId: row.toolUseId,
         })), [
-            { key: 'toolId', header: 'TOOL', verbatim: true },
-            { key: 'messageId', header: 'MESSAGE', verbatim: true },
-            { key: 'blockIndex', header: 'BLOCK' },
+            { key: 'name', header: 'TOOL', maxWidth: 28 },
+            { key: 'args', header: 'ARGUMENTS', maxWidth: 48 },
+            { key: 'output', header: 'OUTPUT', maxWidth: 40 },
+            { key: 'toolUseId', header: 'TOOL USE ID', verbatim: true },
         ], (line) => this.log(line));
     }
 }

package/dist/commands/agents/update.js

@@ -2,6 +2,8 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 const core_1 = require("@oclif/core");
 const data_provider_1 = require("@skrr-ai/data-provider");
+const agent_visual_refs_1 = require("../../lib/agent-visual-refs");
+const create_1 = require("./create");
 const base_command_1 = require("../../base-command");
 const execution_target_1 = require("../../lib/execution-target");
 const prompt_1 = require("../../lib/prompt");
@@ -56,10 +58,7 @@ class AgentsUpdate extends base_command_1.BaseCommand {
         'network-agent-ids': core_1.Flags.string({ description: 'Network agent IDs JSON array' }),
         'network-include-public': core_1.Flags.boolean({ description: 'Include public agents in network' }),
         'character-3d-id': core_1.Flags.string({ description: '3D character ID' }),
-        'scene-background': core_1.Flags.string({
-            description: 'Backdrop for the 3D view: default, preset:<id>, or image:<filepath>@<source>. ' +
-                'A bare string is refused — the stored field is a typed reference, not a name.',
-        }),
+        'scene-background': core_1.Flags.string({ description: agent_visual_refs_1.SCENE_BACKGROUND_FLAG_HELP }),
         'tone-mode': core_1.Flags.string({ description: 'Tone mode' }),
         'tone-id': core_1.Flags.string({ description: 'Tone ID' }),
         'tone-notes': core_1.Flags.string({ description: 'Per-agent tone notes' }),
@@ -117,7 +116,9 @@ class AgentsUpdate extends base_command_1.BaseCommand {
             allowNo: true,
         }),
         'project-id': core_1.Flags.string({
-            description: 'Prompt-store project this agent belongs to (repeatable)',
+            description: 'Prompt-store project to add this agent to (repeatable): a 24-character ObjectId — in ' +
+                'practice the instance-wide project that shares an agent with everyone, which needs the ' +
+                'SHARED_GLOBAL permission. Not a Space project id (`skrr projects`).',
             multiple: true,
         }),
         'remove-project-id': core_1.Flags.string({
@@ -184,6 +185,15 @@ class AgentsUpdate extends base_command_1.BaseCommand {
         catch (err) {
             this.handleApiError(err);
         }
+        // The same check `agents create` makes. Without it, a key the server does
+        // not model — or a typo of one that it does, `max_turns` for `maxTurns` —
+        // was discarded with the same "Updated agent" line as a real change.
+        // `removeProjectIds` is an instruction, not a stored field, so it never
+        // comes back and is not reported.
+        const unapplied = (0, create_1.unappliedPayloadKeys)(payload, updated, ['removeProjectIds']);
+        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. Check \`skrr agents show <id> --json\` for the field names it stores.`);
+        }
         if (flags.json) {
             this.log(JSON.stringify((0, web_url_1.withAgentUrl)(this.cliConfig.baseURL, updated), null, 2));
             return;

package/dist/commands/code/{oversky-agent.d.ts → skrr-agent.d.ts}

@@ -2,7 +2,7 @@ import { Command } from '@oclif/core';
 /**
  * `skrr code skrr-agent` — read and write the agent a managed session runs as.
  *
- * ── Why the name carries the `oversky-` prefix ─────────────────────────────
+ * ── Why the name carries a product prefix ─────────────────────────────────
  *
  * The engine owns `agent`: the engine binary's `agent` is its own agent-management command.
  * `skrr code` forwards argv VERBATIM, and oclif's spaced-topic dispatch collates
@@ -28,8 +28,8 @@ import { Command } from '@oclif/core';
  * API through `apiFetch`, not the `dataService` adapter `BaseCommand.init`
  * installs.
  */
-export default class CodeOverskyAgent extends Command {
-    static aliases: string[];
+export default class CodeSkrrAgent extends Command {
+    static hiddenAliases: string[];
     static description: string;
     static examples: string[];
     static flags: {

package/dist/commands/code/{oversky-agent.js → skrr-agent.js}

@@ -9,7 +9,7 @@ const first_party_harness_managed_1 = require("../../lib/first-party-harness-man
 /**
  * `skrr code skrr-agent` — read and write the agent a managed session runs as.
  *
- * ── Why the name carries the `oversky-` prefix ─────────────────────────────
+ * ── Why the name carries a product prefix ─────────────────────────────────
  *
  * The engine owns `agent`: the engine binary's `agent` is its own agent-management command.
  * `skrr code` forwards argv VERBATIM, and oclif's spaced-topic dispatch collates
@@ -35,11 +35,14 @@ const first_party_harness_managed_1 = require("../../lib/first-party-harness-man
  * API through `apiFetch`, not the `dataService` adapter `BaseCommand.init`
  * installs.
  */
-class CodeOverskyAgent extends core_1.Command {
-    // `skrr code skrr-agent` is the spelling to teach; the `oversky-` one is the
-    // path this file has and stays reachable, because it is in scripts and in
-    // muscle memory.
-    static aliases = ['code:skrr-agent'];
+class CodeSkrrAgent extends core_1.Command {
+    // `skrr code skrr-agent` is the name (docs/product/skrr-naming-map.md). The
+    // file used to be `oversky-agent.ts`, and oclif names a command after its
+    // file, so help, `skrr commands` and `skrr usage` taught the retired spelling
+    // while every remedy taught this one, and each help page showed the name you
+    // typed as its own alias (OSK-9396). The old spelling stays reachable for
+    // scripts and muscle memory, and hidden, as the naming map records.
+    static hiddenAliases = ['code:oversky-agent'];
     static description = `Show or set the skrr agent a managed ${auth_core_1.FIRST_PARTY_HARNESS.displayName} session is attributed to`;
     static examples = [
         '<%= config.bin %> code skrr-agent',
@@ -68,7 +71,7 @@ class CodeOverskyAgent extends core_1.Command {
         json: core_1.Flags.boolean({ description: 'Emit the result as JSON' }),
     };
     async run() {
-        const { flags } = await this.parse(CodeOverskyAgent);
+        const { flags } = await this.parse(CodeSkrrAgent);
         // Every branch except `--clear` reads `/api/agents`, and this command extends
         // `Command` rather than `BaseCommand` — so nothing has resolved the stored
         // credential for `apiFetch` yet. Without this a signed-in user gets a bare
@@ -184,7 +187,7 @@ class CodeOverskyAgent extends core_1.Command {
         throw err;
     }
 }
-exports.default = CodeOverskyAgent;
+exports.default = CodeSkrrAgent;
 function summarize(agent) {
     return { id: agent.id, name: agent.name ?? null, source: agent.source };
 }

package/dist/commands/convos/messages.d.ts

@@ -1,4 +1,17 @@
 import { BaseCommand } from '../../base-command';
+/**
+ * The lines `skrr convos messages` prints for one message row.
+ *
+ * A failed turn used to print as its text and nothing else — usually empty,
+ * which reads as an agent that replied with whitespace, while `error: true` and
+ * the reason sat on the row being printed. It is now marked, and its reason is
+ * printed where the answer would be (OSK-9468). The reason is read through
+ * `resolveMessageFailure`, the one reader every surface shares; a legacy error
+ * row's text IS that reason, so only the answer is printed as the body.
+ */
+export declare function formatMessageLines(m: Record<string, unknown>, options?: {
+    metadata?: boolean;
+}): string[];
 /**
  * `skrr convos messages` — read a conversation's transcript.
  *

package/dist/commands/convos/messages.js

@@ -1,9 +1,47 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.formatMessageLines = formatMessageLines;
 const core_1 = require("@oclif/core");
 const data_provider_1 = require("@skrr-ai/data-provider");
 const base_command_1 = require("../../base-command");
 const message_content_1 = require("../../lib/message-content");
+/**
+ * The lines `skrr convos messages` prints for one message row.
+ *
+ * A failed turn used to print as its text and nothing else — usually empty,
+ * which reads as an agent that replied with whitespace, while `error: true` and
+ * the reason sat on the row being printed. It is now marked, and its reason is
+ * printed where the answer would be (OSK-9468). The reason is read through
+ * `resolveMessageFailure`, the one reader every surface shares; a legacy error
+ * row's text IS that reason, so only the answer is printed as the body.
+ */
+function formatMessageLines(m, options = {}) {
+    const who = m.isCreatedByUser ? 'user' : String(m.sender ?? 'assistant');
+    const when = m.createdAt ? new Date(String(m.createdAt)).toISOString() : '';
+    const failure = (0, data_provider_1.resolveMessageFailure)(m);
+    // Render each assistant text part as its own block so a tool-paused turn
+    // reads as separate paragraphs instead of one glued run-on line
+    // (OSK-4911). Whitespace is collapsed WITHIN a block for compactness; the
+    // blank line BETWEEN blocks is what the flattened `text` field dropped.
+    const body = (0, message_content_1.messageTextBlocks)(failure ? { ...m, text: failure.answer } : m)
+        .map((block) => block.replace(/\s+/g, ' ').trim())
+        .join('\n\n');
+    const clipped = body.length > 300 ? `${body.slice(0, 300)}…` : body;
+    const lines = [`${when}  ${who}${failure ? '  [failed]' : ''}`];
+    if (clipped || !failure) {
+        for (const line of clipped.split('\n')) {
+            lines.push(`  ${line}`);
+        }
+    }
+    if (failure) {
+        const reason = failure.reason?.replace(/\s+/g, ' ').trim();
+        lines.push(`  failed: ${reason || 'no reason was recorded on the message'}`);
+    }
+    if (options.metadata && m.metadata && Object.keys(m.metadata).length > 0) {
+        lines.push(`  metadata: ${JSON.stringify(m.metadata)}`);
+    }
+    return lines;
+}
 /**
  * `skrr convos messages` — read a conversation's transcript.
  *
@@ -70,22 +108,8 @@ class ConvosMessages extends base_command_1.BaseCommand {
             return;
         }
         for (const m of messages) {
-            const who = m.isCreatedByUser ? 'user' : String(m.sender ?? 'assistant');
-            const when = m.createdAt ? new Date(String(m.createdAt)).toISOString() : '';
-            // Render each assistant text part as its own block so a tool-paused turn
-            // reads as separate paragraphs instead of one glued run-on line
-            // (OSK-4911). Whitespace is collapsed WITHIN a block for compactness; the
-            // blank line BETWEEN blocks is what the flattened `text` field dropped.
-            const body = (0, message_content_1.messageTextBlocks)(m)
-                .map((block) => block.replace(/\s+/g, ' ').trim())
-                .join('\n\n');
-            const clipped = body.length > 300 ? `${body.slice(0, 300)}…` : body;
-            this.log(`${when}  ${who}`);
-            for (const line of clipped.split('\n')) {
-                this.log(`  ${line}`);
-            }
-            if (flags.metadata && m.metadata && Object.keys(m.metadata).length > 0) {
-                this.log(`  metadata: ${JSON.stringify(m.metadata)}`);
+            for (const line of formatMessageLines(m, { metadata: flags.metadata })) {
+                this.log(line);
             }
         }
         this.log(`\n${messages.length} message(s)`);

package/dist/commands/daemon/index.js

@@ -13,7 +13,14 @@ class Daemon extends core_1.Command {
     // "Wraps the `skrrd` binary" read, cold, as though you must already HAVE one —
     // the opposite of what `skrr daemon install` does now that it fetches the
     // signed release. Dogfooding 0.1.12 hit exactly that reading.
-    static description = 'Manage the local skrr runtime — install it, sign it in, and check on it.';
+    // "runtime" names two unrelated things in this product: the background
+    // service on the computer you are typing on, and a rented Linux VM (every
+    // Dedicated Runtime's daemon id is `dedicated-runtime-rtl_…`). This topic is
+    // always the first. A dogfood note put the cost precisely: when `daemon
+    // status` warned about an update, the reader had to stop and work out whether
+    // it meant their laptop or one of their VMs. Naming the computer removes the
+    // hesitation without renaming a domain.
+    static description = 'Manage the skrr background service on THIS computer — install it, sign it in, and check on it. A rented Linux VM is a machine, not this: see `skrr machines`.';
     static examples = [
         '<%= config.bin %> daemon install',
         '<%= config.bin %> daemon status',

package/dist/commands/daemon/logs.d.ts

@@ -24,6 +24,32 @@ export interface DaemonLogsFlags {
  * constrained to the same profile grammar instead of trusting a lock file as
  * an arbitrary path component.
  */
+/**
+ * How old the log is, said out loud before any of it is printed.
+ *
+ * A log file is the one surface whose CONTENT looks equally plausible whether
+ * it is live or nine days dead — every line is well-formed and timestamped, and
+ * the timestamps are only wrong if you happen to read them. Observed on this
+ * machine: a daemon running since 06:20 today, launched with
+ * `--log-file ~/Library/Logs/OverSky/daemon.app.log` whose parent directory did
+ * not exist, so it wrote nothing; `skrr daemon logs` then served
+ * `~/.skrr/profiles/default/logs/daemon.log`, last written nine days earlier,
+ * with no marker. The top line read `[2026-09-08 02:55:24]` and nothing said
+ * that was not today.
+ *
+ * The daemon's own logger now creates its directory and reports a failed open
+ * (its comment cites OSK-7737/OSK-7699), and `daemon status` learned to say the
+ * file predates the running daemon. `daemon logs` — the command you actually
+ * reach for — never did.
+ *
+ * Stated as a FACT first and a warning second: the age is always printed, so a
+ * fresh log confirms itself, and no threshold has to be right for the reader to
+ * be correctly informed. The warning only adds a next step.
+ */
+export declare function describeLogAge(mtimeMs: number, now?: number): {
+    line: string;
+    stale: boolean;
+};
 export declare function resolveLegacyDaemonLogPath(flags: Pick<DaemonLogsFlags, 'stderr'>, options?: {
     home?: string;
     env?: NodeJS.ProcessEnv;

package/dist/commands/daemon/logs.js

@@ -3,6 +3,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.describeLogAge = describeLogAge;
 exports.resolveLegacyDaemonLogPath = resolveLegacyDaemonLogPath;
 exports.readDaemonLogTail = readDaemonLogTail;
 exports.buildOverskyLogsArgs = buildOverskyLogsArgs;
@@ -19,6 +20,47 @@ const PROFILE_NAME = /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/;
  * constrained to the same profile grammar instead of trusting a lock file as
  * an arbitrary path component.
  */
+/**
+ * How old the log is, said out loud before any of it is printed.
+ *
+ * A log file is the one surface whose CONTENT looks equally plausible whether
+ * it is live or nine days dead — every line is well-formed and timestamped, and
+ * the timestamps are only wrong if you happen to read them. Observed on this
+ * machine: a daemon running since 06:20 today, launched with
+ * `--log-file ~/Library/Logs/OverSky/daemon.app.log` whose parent directory did
+ * not exist, so it wrote nothing; `skrr daemon logs` then served
+ * `~/.skrr/profiles/default/logs/daemon.log`, last written nine days earlier,
+ * with no marker. The top line read `[2026-09-08 02:55:24]` and nothing said
+ * that was not today.
+ *
+ * The daemon's own logger now creates its directory and reports a failed open
+ * (its comment cites OSK-7737/OSK-7699), and `daemon status` learned to say the
+ * file predates the running daemon. `daemon logs` — the command you actually
+ * reach for — never did.
+ *
+ * Stated as a FACT first and a warning second: the age is always printed, so a
+ * fresh log confirms itself, and no threshold has to be right for the reader to
+ * be correctly informed. The warning only adds a next step.
+ */
+function describeLogAge(mtimeMs, now = Date.now()) {
+    const ageMs = Math.max(0, now - mtimeMs);
+    const minutes = Math.floor(ageMs / 60_000);
+    const human = minutes < 1
+        ? 'less than a minute ago'
+        : minutes < 60
+            ? `${minutes} minute${minutes === 1 ? '' : 's'} ago`
+            : minutes < 60 * 24
+                ? `${Math.floor(minutes / 60)} hour${Math.floor(minutes / 60) === 1 ? '' : 's'} ago`
+                : `${Math.floor(minutes / (60 * 24))} day${Math.floor(minutes / (60 * 24)) === 1 ? '' : 's'} ago`;
+    const stamp = new Date(mtimeMs).toISOString().slice(0, 19).replace('T', ' ');
+    const stale = ageMs > 60 * 60_000;
+    return {
+        line: stale
+            ? `Log last written ${stamp}Z — ${human}. If your daemon is running it is not writing here; check \`skrr daemon status\` for the path it was started with.`
+            : `Log last written ${stamp}Z — ${human}.`,
+        stale,
+    };
+}
 function resolveLegacyDaemonLogPath(flags, options = {}) {
     const home = options.home ?? (0, node_os_1.homedir)();
     const env = options.env ?? process.env;
@@ -118,6 +160,20 @@ class DaemonLogs extends core_1.Command {
     async run() {
         const { flags } = await this.parse(DaemonLogs);
         const args = buildOverskyLogsArgs(flags);
+        // Before ANY log content, on stderr so it never pollutes a pipe. `--path`
+        // is exempt: its whole contract is one path on stdout.
+        if (!flags.path) {
+            try {
+                const candidate = resolveLegacyDaemonLogPath(flags);
+                if ((0, node_fs_1.existsSync)(candidate)) {
+                    const { line } = describeLogAge((0, node_fs_1.statSync)(candidate).mtimeMs);
+                    this.logToStderr(line);
+                }
+            }
+            catch {
+                // Never let the banner stop the logs from being shown.
+            }
+        }
         try {
             // `oversky 0.2.x` has profiles and writes the same files, but has no
             // `logs` subcommand. Probe top-level help first so forwarding does not

package/dist/commands/daemon/uninstall.js

@@ -19,7 +19,7 @@ class DaemonUninstall extends core_1.Command {
     // whole topic, and without a per-command alias only the bare topic
     // resolved: every subcommand under it failed.
     static aliases = ['daemons:uninstall'];
-    static summary = "Remove the local skrr runtime's background service (local state is left alone)";
+    static summary = 'Remove the skrr background service from THIS computer (local state is left alone; a rented VM is a machine, see `skrr machines`)';
     static description = (0, exec_runtime_binary_1.forwardedFlagsNote)('uninstall');
     static strict = false; // forward all args verbatim — see run()
     async run() {