@skrr-ai/cli 0.1.42 → 0.1.44

package/dist/commands/instructions/install.js

@@ -1,5 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.conflictingTargetOf = conflictingTargetOf;
+exports.describeTargetConflict = describeTargetConflict;
 const core_1 = require("@oclif/core");
 const auth_core_1 = require("@skrr-ai/auth-core");
 const data_provider_1 = require("@skrr-ai/data-provider");
@@ -9,6 +11,41 @@ const harness_provider_input_1 = require("../../lib/harness-provider-input");
 const prompt_1 = require("../../lib/prompt");
 /** The providers a managed instruction can target, canonical spellings. */
 const MANAGED_INSTRUCTION_PROVIDERS = ['claude', 'codex', auth_core_1.FIRST_PARTY_HARNESS.provider];
+function conflictingTargetOf(body) {
+    const value = body?.conflictingTarget;
+    return value && typeof value.id === 'string' && value.id ? value : null;
+}
+/**
+ * What to do about a placement that already has a target, as commands.
+ *
+ * Re-running an install whose first attempt had failed printed "An unexpected
+ * error occurred. Code: TARGET_CONFLICT" (OSK-4631): no target, no path, no next
+ * step, and no word on whether the re-run had partly applied. The API now names
+ * the target in the way; this turns that into the commands for its state. A live
+ * target is changed or removed, never installed twice; one being removed can be
+ * restored, or purged once its daemon confirms cleanup.
+ */
+function describeTargetConflict(target, { bin, placement, created }) {
+    const state = [target.desiredState, target.status].filter(Boolean).join(', ');
+    const lines = target.desiredState === 'removed'
+        ? [
+            `Target ${target.id} already holds ${placement} on that machine and is being removed${state ? ` (${state})` : ''}.`,
+            `Bring it back with \`${bin} instructions restore-target ${target.id}\`, or install again ` +
+                `after its daemon confirms cleanup and \`${bin} instructions purge-target ${target.id}\`.`,
+        ]
+        : [
+            `Target ${target.id} already manages ${placement} on that machine${state ? ` (${state})` : ''}.`,
+            ...(target.status === 'error'
+                ? [`Its last sync failed; \`${bin} instructions status\` shows why.`]
+                : []),
+            `Change what it applies with \`${bin} instructions update-target ${target.id} --bundle <id>\`, ` +
+                `or drop it with \`${bin} instructions remove ${target.id}\`.`,
+        ];
+    lines.push(created.length
+        ? `Created before this refusal: ${created.join(', ')}.`
+        : 'No target was created by this command.');
+    return lines.join(' ');
+}
 class InstructionsInstall extends base_command_1.BaseCommand {
     static description = 'Opt in a daemon target to ongoing managed instruction reconciliation';
     static flags = {
@@ -32,7 +69,13 @@ class InstructionsInstall extends base_command_1.BaseCommand {
             default: MANAGED_INSTRUCTION_PROVIDERS,
         }),
         scope: core_1.Flags.string({ description: 'global or project', options: ['global', 'project'] }),
-        project: core_1.Flags.string({ description: 'Absolute project path on the daemon machine' }),
+        project: core_1.Flags.string({
+            // The daemon writes a project target at the repository root, so a path
+            // outside any Git repository is accepted here and then fails on the
+            // machine. Saying so is the only warning this command can give: the path
+            // is checked where it lives, not here (OSK-4626).
+            description: "Absolute project path on the daemon's machine, inside a Git repository (the block is written at its root)",
+        }),
         mode: core_1.Flags.string({
             description: 'Project footprint',
             options: ['local', 'team'],
@@ -87,12 +130,20 @@ class InstructionsInstall extends base_command_1.BaseCommand {
         if (providers.includes('codex') && Buffer.byteLength(previewBody, 'utf8') > 30 * 1024) {
             this.error('Codex managed instruction bodies are limited to 30 KiB; no targets were created', { exit: 2 });
         }
-        if (!flags.json) {
+        // The body is shown so the confirmation below is informed. With `--yes`
+        // there is no confirmation to inform, and printing a ~9 KB body anyway put
+        // the command's actual outcome — often a refusal — a screen of scrollback
+        // away (OSK-4631). Say what was authorized, and where to read it.
+        if (!flags.json && !flags.yes) {
             this.log('Exact managed instruction body:');
             this.log('---');
             this.log(previewBody);
             this.log('---');
         }
+        else if (!flags.json) {
+            this.log(`Authorizing ${Buffer.byteLength(previewBody, 'utf8').toLocaleString()} bytes of instruction ` +
+                `${flags.bundle}; \`${this.config.bin} instructions show ${flags.bundle}\` prints them.`);
+        }
         const teamWarning = scope === 'project' && flags.mode === 'team'
             ? ' Team mode writes to repository files and may affect every contributor.'
             : '';
@@ -101,8 +152,8 @@ class InstructionsInstall extends base_command_1.BaseCommand {
             return this.log('Aborted.');
         const daemonId = await this.resolveDaemon(flags.daemon);
         const results = [];
-        try {
-            for (const provider of providers) {
+        for (const provider of providers) {
+            try {
                 results.push(await data_provider_1.dataService.createManagedInstructionTarget({
                     daemonId,
                     bundleId: flags.bundle,
@@ -115,15 +166,40 @@ class InstructionsInstall extends base_command_1.BaseCommand {
                     label: flags.label,
                 }));
             }
-        }
-        catch (error) {
-            this.handleApiError(error);
+            catch (error) {
+                // One target per provider, created in turn, so a refusal part-way
+                // through leaves the earlier ones in place. Say which.
+                const created = results.map((result) => `${(0, harness_provider_input_1.canonicalHarnessInput)(result.target.provider)} (${result.target.id})`);
+                const refusal = (0, base_command_1.apiRefusal)(error);
+                const conflict = refusal.code === 'TARGET_CONFLICT' ? conflictingTargetOf(refusal.body) : null;
+                if (conflict) {
+                    this.failWithCliError({
+                        message: describeTargetConflict(conflict, {
+                            bin: this.config.bin,
+                            placement: `${(0, harness_provider_input_1.canonicalHarnessInput)(provider)} ${scope}${flags.project ? ` ${flags.project}` : ''}`,
+                            created,
+                        }),
+                        code: 'TARGET_CONFLICT',
+                        status: 409,
+                        exit: 1,
+                        retryable: false,
+                        details: { ...refusal.body, created: results.map((result) => result.target) },
+                    });
+                }
+                if (created.length) {
+                    this.warn(`Created before this failure: ${created.join(', ')}.`);
+                }
+                this.handleApiError(error);
+            }
         }
         if (flags.json)
             return this.log(JSON.stringify(results, null, 2));
         for (const result of results) {
             this.log(`Install queued: ${(0, harness_provider_input_1.canonicalHarnessInput)(result.target.provider)} ${result.target.scope}${result.target.projectPath ? ` ${result.target.projectPath}` : ''} (${result.target.id})`);
         }
+        // Queued is not applied: the daemon checks the placement when it writes, and
+        // a path it cannot use fails there, after this command has exited 0.
+        this.log(`The daemon applies these on its next sync; \`${this.config.bin} instructions status\` shows when, or why not.`);
     }
     /**
      * The daemon the targets are created on, by the rule every daemon-picking

package/dist/commands/instructions/list.js

@@ -4,6 +4,7 @@ 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 instruction_provenance_1 = require("../../lib/instruction-provenance");
 class InstructionsList extends base_command_1.BaseCommand {
     static description = 'List version-controlled instruction prompts';
     static flags = {
@@ -32,12 +33,16 @@ class InstructionsList extends base_command_1.BaseCommand {
             id: bundle.id,
             name: bundle.name,
             version: String(bundle.currentVersionNumber),
+            // The built-in release the CURRENT body is, if any — a separate counter
+            // from VERSION, which is this prompt's own (OSK-4647).
+            template: (0, instruction_provenance_1.builtInLabel)(bundle.currentVersion),
             status: bundle.deletedAt ? 'deleted' : bundle.status,
             updated: bundle.updatedAt,
         })), [
             { key: 'id', header: 'ID' },
             { key: 'name', header: 'NAME', maxWidth: 32 },
             { key: 'version', header: 'VERSION' },
+            { key: 'template', header: 'TEMPLATE' },
             { key: 'status', header: 'STATUS' },
             { key: 'updated', header: 'UPDATED' },
         ], (line) => this.log(line));

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

@@ -9,4 +9,10 @@ export default class InstructionsShow extends BaseCommand {
         versions: import("@oclif/core/lib/interfaces").BooleanFlag<boolean>;
     };
     run(): Promise<void>;
+    /**
+     * The built-in release this server would install today, or undefined. Read
+     * from the offer, which already reports it as `templateVersion`; a failure
+     * costs only the "is there a newer one" clause, never the command.
+     */
+    private latestTemplateVersion;
 }

package/dist/commands/instructions/show.js

@@ -4,6 +4,7 @@ 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 instruction_provenance_1 = require("../../lib/instruction-provenance");
 class InstructionsShow extends base_command_1.BaseCommand {
     static description = 'Show exact prompt content and version history';
     static args = {
@@ -38,6 +39,9 @@ class InstructionsShow extends base_command_1.BaseCommand {
                 (0, format_1.renderTable)(response.versions.map((version) => ({
                     id: version.id,
                     version: String(version.versionNumber),
+                    // Its own column, never folded into VERSION: the prompt's counter
+                    // and the built-in release are different numbers (OSK-4647).
+                    template: (0, instruction_provenance_1.builtInLabel)(version),
                     hash: version.hash.slice(0, 12),
                     status: version.archivedAt
                         ? 'archived'
@@ -48,10 +52,20 @@ class InstructionsShow extends base_command_1.BaseCommand {
                 })), [
                     { key: 'id', header: 'ID' },
                     { key: 'version', header: 'VERSION' },
-                    { key: 'hash', header: 'HASH' },
+                    { key: 'hash', header: 'BODY HASH' },
                     { key: 'status', header: 'STATUS' },
+                    { key: 'template', header: 'TEMPLATE' },
                     { key: 'message', header: 'MESSAGE', maxWidth: 48 },
                 ], (line) => this.log(line));
+                // Three hashes answer "is my file current?", and this table shows one.
+                // A file's `v=` is the body as rendered for its target, so beside an
+                // agent-identity section it matches none of these (OSK-4644).
+                this.log('');
+                this.log("BODY HASH is the version as written. A managed file's `v=` is the body as");
+                this.log('rendered for its target, which differs when it fills in an agent identity;');
+                this.log(`compare it with FILE HASH in \`${this.config.bin} instructions status\`.`);
+                this.log("VERSION counts this prompt's saved bodies; TEMPLATE is the built-in release a");
+                this.log('body was taken from, which is a separate number.');
                 return;
             }
             const response = await data_provider_1.dataService.getManagedInstructionBundle(args.id);
@@ -61,6 +75,9 @@ class InstructionsShow extends base_command_1.BaseCommand {
             this.log(`${bundle.name} (${bundle.id}) — v${bundle.currentVersionNumber} — ${bundle.status}`);
             if (bundle.description)
                 this.log(bundle.description);
+            const provenance = (0, instruction_provenance_1.describeTemplateProvenance)(bundle, await this.latestTemplateVersion(bundle.sourceTemplateKey));
+            if (provenance)
+                this.log(provenance);
             this.log('');
             this.log(bundle.currentVersion?.body || '(no active content)');
         }
@@ -84,5 +101,21 @@ class InstructionsShow extends base_command_1.BaseCommand {
             this.handleApiError(error);
         }
     }
+    /**
+     * The built-in release this server would install today, or undefined. Read
+     * from the offer, which already reports it as `templateVersion`; a failure
+     * costs only the "is there a newer one" clause, never the command.
+     */
+    async latestTemplateVersion(templateKey) {
+        if (!templateKey)
+            return undefined;
+        try {
+            const offer = await data_provider_1.dataService.getManagedInstructionOffer(templateKey);
+            return offer?.preset?.templateVersion;
+        }
+        catch {
+            return undefined;
+        }
+    }
 }
 exports.default = InstructionsShow;

package/dist/commands/instructions/status.js

@@ -5,6 +5,7 @@ const data_provider_1 = require("@skrr-ai/data-provider");
 const base_command_1 = require("../../base-command");
 const format_1 = require("../../lib/format");
 const instruction_input_1 = require("../../lib/instruction-input");
+const instruction_provenance_1 = require("../../lib/instruction-provenance");
 class InstructionsStatus extends base_command_1.BaseCommand {
     static description = 'Show managed targets, applied versions, paths, and reconciliation errors';
     static flags = {
@@ -42,12 +43,14 @@ class InstructionsStatus extends base_command_1.BaseCommand {
             // Leave it empty.
         }
         let bundleNames = new Map();
+        let bundlesById = new Map();
         try {
             const bundleResponse = await data_provider_1.dataService.listManagedInstructionBundles({
                 includeArchived: true,
                 includeDeleted: true,
             });
             bundleNames = (0, instruction_input_1.buildBundleNameIndex)(bundleResponse.bundles);
+            bundlesById = new Map(bundleResponse.bundles.map((bundle) => [bundle.id, bundle]));
         }
         catch {
             // Leave the index empty — rows show the full bundle id instead.
@@ -73,7 +76,17 @@ class InstructionsStatus extends base_command_1.BaseCommand {
             target: target.appliedPath ||
                 (target.scope === 'global' ? 'global' : target.projectPath || 'project'),
             desired: target.desiredState,
-            applied: target.appliedVersionNumber ? `v${target.appliedVersionNumber}` : '-',
+            // `v3 (built-in v5)`: the prompt's version, and the built-in release
+            // it is when that is known. `APPLIED v3` alone read as two releases
+            // behind a preset announced as v5 (OSK-4647).
+            applied: (0, instruction_provenance_1.appliedVersionLabel)(target.appliedVersionNumber, bundlesById.get(target.bundleId)),
+            // The hash the managed block in the file starts with (`v=`), cut to the
+            // same 12 characters `show --versions` prints. It is the body as
+            // rendered for THIS target, so it matches a version's hash only when
+            // nothing was filled in — and was `--json` only, which made "is the
+            // block in my CLAUDE.md current?" read as "my machine is running a body
+            // the server never heard of" (OSK-4644).
+            fileHash: target.appliedHash ? target.appliedHash.slice(0, 12) : '-',
             status: (0, instruction_input_1.describeTargetSync)(target, Date.now(), liveDaemonIds),
         })), [
             { key: 'id', header: 'TARGET ID' },
@@ -88,6 +101,7 @@ class InstructionsStatus extends base_command_1.BaseCommand {
             { key: 'target', header: 'PATH', maxWidth: 36 },
             { key: 'desired', header: 'DESIRED' },
             { key: 'applied', header: 'APPLIED' },
+            { key: 'fileHash', header: 'FILE HASH' },
             // Wide enough for the stall note to keep its remedy. Truncating at 48
             // cut `purge-target` off the end, which hid the one actionable half of
             // the sentence.
@@ -106,6 +120,8 @@ class InstructionsStatus extends base_command_1.BaseCommand {
             for (const command of rebinds)
                 this.log(`  ${command}`);
         }
+        for (const line of (0, instruction_input_1.failedTargetLines)(response.targets, this.config.bin))
+            this.log(line);
         // Where the text went.
         //
         // The count in the STATUS column says skrr overwrote something you

package/dist/commands/payments/wallet.js

@@ -52,8 +52,8 @@ class PaymentsWallet extends base_command_1.BaseCommand {
         // CLI — so anyone looking for "my balance" found USDC and drew the wrong
         // conclusion about their usage ceiling. Name the other one.
         this.log('');
-        this.log('This is the x402 crypto wallet, in USDC. Your hosted USAGE balance —');
-        this.log('the ceiling that refuses a turn — is `skrr balance show`.');
+        this.log('This is the x402 crypto wallet, in USDC. Your hosted USAGE balance and');
+        this.log('plan limits — the ceilings that refuse a turn — are `skrr balance show`.');
         const payments = history.payments ?? [];
         if (payments.length === 0) {
             this.log('');

package/dist/commands/tasks/attachments/set-role.d.ts

@@ -0,0 +1,24 @@
+import { BaseCommand } from '../../../base-command';
+/**
+ * `skrr tasks attachments set-role <task> <attachment> --role …`
+ *
+ * The one way to change what an existing asset IS on a Task. Its real use is
+ * promotion: an agent may only upload `evidence` or `deliverable`, because an
+ * `input` is forwarded into every future Run of the Task — so when an agent's
+ * screenshot should become an input, a person promotes it here. The server
+ * refuses the call from an agent, whatever credential it holds, and moves the
+ * asset's ledger link with the role.
+ */
+export default class TasksAttachmentsSetRole extends BaseCommand {
+    static description: string;
+    static examples: string[];
+    static args: {
+        id: import("@oclif/core/lib/interfaces").Arg<string, Record<string, unknown>>;
+        attachmentId: import("@oclif/core/lib/interfaces").Arg<string, Record<string, unknown>>;
+    };
+    static flags: {
+        role: import("@oclif/core/lib/interfaces").OptionFlag<string, import("@oclif/core/lib/interfaces").CustomOptions>;
+        json: import("@oclif/core/lib/interfaces").BooleanFlag<boolean>;
+    };
+    run(): Promise<void>;
+}

package/dist/commands/tasks/attachments/set-role.js

@@ -0,0 +1,60 @@
+"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");
+/**
+ * `skrr tasks attachments set-role <task> <attachment> --role …`
+ *
+ * The one way to change what an existing asset IS on a Task. Its real use is
+ * promotion: an agent may only upload `evidence` or `deliverable`, because an
+ * `input` is forwarded into every future Run of the Task — so when an agent's
+ * screenshot should become an input, a person promotes it here. The server
+ * refuses the call from an agent, whatever credential it holds, and moves the
+ * asset's ledger link with the role.
+ */
+class TasksAttachmentsSetRole extends base_command_1.BaseCommand {
+    static description = "Change an attachment's role (input, evidence, or deliverable). Making an asset an input " +
+        'sends it into every future Run of the task, so only a person can change a role.';
+    static examples = [
+        '<%= config.bin %> tasks attachments set-role <task-id> <attachment-id> --role input',
+        '<%= config.bin %> tasks attachments set-role <task-id> <attachment-id> --role evidence --json',
+    ];
+    static args = {
+        id: core_1.Args.string({ description: 'Task ID', required: true, ignoreStdin: true }),
+        attachmentId: core_1.Args.string({ description: 'Attachment ID', required: true, ignoreStdin: true }),
+    };
+    static flags = {
+        role: core_1.Flags.string({
+            required: true,
+            options: ['input', 'evidence', 'deliverable'],
+            description: 'input (forwarded into every future Run), evidence (supports an Update or Result), or deliverable (the media is the product)',
+        }),
+        json: core_1.Flags.boolean({ description: 'Output as JSON' }),
+    };
+    async run() {
+        this.requireAuth();
+        const { args, flags } = await this.parse(TasksAttachmentsSetRole);
+        let attachment;
+        try {
+            attachment = await data_provider_1.dataService.setTaskAttachmentRole({
+                taskId: args.id,
+                attachmentId: args.attachmentId,
+                role: flags.role,
+            });
+        }
+        catch (err) {
+            this.handleApiError(err);
+        }
+        if (flags.json) {
+            this.log(JSON.stringify(attachment, null, 2));
+            return;
+        }
+        const name = attachment.originalName || attachment.id;
+        const effect = attachment.role === 'input'
+            ? ' It will be sent into every future Run of this task.'
+            : ' It is no longer sent into Runs.';
+        this.log(`${name} is now ${attachment.role}.${effect}`);
+    }
+}
+exports.default = TasksAttachmentsSetRole;

package/dist/commands/tasks/attachments/upload.d.ts

@@ -8,6 +8,7 @@ export default class TasksAttachmentsUpload extends BaseCommand {
     static flags: {
         json: import("@oclif/core/lib/interfaces").BooleanFlag<boolean>;
         file: import("@oclif/core/lib/interfaces").OptionFlag<string, import("@oclif/core/lib/interfaces").CustomOptions>;
+        role: import("@oclif/core/lib/interfaces").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
     };
     run(): Promise<void>;
 }

package/dist/commands/tasks/attachments/upload.js

@@ -1,50 +1,14 @@
 "use strict";
-var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    var desc = Object.getOwnPropertyDescriptor(m, k);
-    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
-      desc = { enumerable: true, get: function() { return m[k]; } };
-    }
-    Object.defineProperty(o, k2, desc);
-}) : (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    o[k2] = m[k];
-}));
-var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
-    Object.defineProperty(o, "default", { enumerable: true, value: v });
-}) : function(o, v) {
-    o["default"] = v;
-});
-var __importStar = (this && this.__importStar) || (function () {
-    var ownKeys = function(o) {
-        ownKeys = Object.getOwnPropertyNames || function (o) {
-            var ar = [];
-            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
-            return ar;
-        };
-        return ownKeys(o);
-    };
-    return function (mod) {
-        if (mod && mod.__esModule) return mod;
-        var result = {};
-        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
-        __setModuleDefault(result, mod);
-        return result;
-    };
-})();
 Object.defineProperty(exports, "__esModule", { value: true });
-const fs = __importStar(require("node:fs"));
-const path = __importStar(require("node:path"));
-const node_buffer_1 = require("node:buffer");
 const core_1 = require("@oclif/core");
-const data_provider_1 = require("@skrr-ai/data-provider");
 const base_command_1 = require("../../../base-command");
-const file_mime_1 = require("../../../lib/file-mime");
+const task_asset_upload_1 = require("../../../lib/task-asset-upload");
 class TasksAttachmentsUpload extends base_command_1.BaseCommand {
     static description = 'Upload a file attachment to a task';
     static examples = [
         '<%= config.bin %> tasks attachments upload <task-id> --file ./report.pdf',
         '<%= config.bin %> tasks attachments upload <task-id> --file ./screenshot.png --json',
+        '<%= config.bin %> tasks attachments upload <task-id> --file ./demo.mp4 --role deliverable',
     ];
     static args = {
         id: core_1.Args.string({ description: 'Task ID', required: true, ignoreStdin: true }),
@@ -52,32 +16,34 @@ class TasksAttachmentsUpload extends base_command_1.BaseCommand {
     static flags = {
         json: core_1.Flags.boolean({ description: 'Output as JSON' }),
         file: core_1.Flags.string({ description: 'Path to the file to upload', required: true }),
+        role: core_1.Flags.string({
+            description: 'Asset role: evidence (supports an Update/Result), deliverable (the media is the product), or input (forwarded into every future Run — only a person may add one; a person promotes an agent upload with `attachments set-role`). Defaults to evidence when an agent uploads, input when a person does.',
+            options: ['input', 'evidence', 'deliverable'],
+        }),
     };
     async run() {
         this.requireAuth();
         const { args, flags } = await this.parse(TasksAttachmentsUpload);
-        const filePath = flags.file;
-        if (!fs.existsSync(filePath)) {
-            this.error(`File not found: ${filePath}`, { exit: 1 });
-        }
-        const buf = fs.readFileSync(filePath);
-        const filename = path.basename(filePath);
-        const fd = new FormData();
-        const mimeType = (0, file_mime_1.mimeTypeForFilename)(filename);
-        fd.append('file', new node_buffer_1.Blob([buf], { type: mimeType }), filename);
-        let result;
+        // The pipeline — buffered vs direct, session vs generic — lives in
+        // task-asset-upload.ts so `--attach` on updates/result/complete/comments
+        // makes the same routing decisions byte for byte (OSK-9863).
+        let asset;
         try {
-            result = await data_provider_1.dataService.uploadTaskAttachment({ taskId: args.id, formData: fd });
+            asset = await (0, task_asset_upload_1.uploadTaskAssetFile)({
+                taskId: args.id,
+                filePath: flags.file,
+                role: flags.role,
+            });
         }
         catch (err) {
             this.handleApiError(err);
         }
         if (flags.json) {
-            this.log(JSON.stringify(result, null, 2));
+            this.log(JSON.stringify(asset, null, 2));
             return;
         }
-        const a = result;
-        this.log(`Uploaded ${filename} (${buf.byteLength} bytes) → attachment ${a.id ?? a._id ?? '?'}`);
+        const dedup = asset.deduplicated ? ' (deduplicated — already on the task)' : '';
+        this.log(`Uploaded ${asset.filename} → attachment ${asset.id}${dedup}`);
     }
 }
 exports.default = TasksAttachmentsUpload;

package/dist/commands/tasks/comments/add.d.ts

@@ -16,6 +16,7 @@ export default class TasksCommentsAdd extends BaseCommand {
         'parent-comment': import("@oclif/core/lib/interfaces").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
         'anchor-mark-id': import("@oclif/core/lib/interfaces").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
         'anchor-quote': import("@oclif/core/lib/interfaces").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
+        attach: import("@oclif/core/lib/interfaces").OptionFlag<string[] | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
     };
     run(): Promise<void>;
     /**

package/dist/commands/tasks/comments/add.js

@@ -1,4 +1,37 @@
 "use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
 Object.defineProperty(exports, "__esModule", { value: true });
 const node_crypto_1 = require("node:crypto");
 const core_1 = require("@oclif/core");
@@ -55,6 +88,11 @@ class TasksCommentsAdd extends base_command_1.BaseCommand {
         'anchor-quote': core_1.Flags.string({
             description: 'Captured quote for the anchor (≤1000 chars; truncated to 500 to match the editor). Enables inline-comment mode when used without --anchor-mark-id.',
         }),
+        attach: core_1.Flags.string({
+            multiple: true,
+            description: 'Upload a file as a Task asset and reference it in the comment body ' +
+                '(`![name](task-asset:<id>)`, resolved to a signed URL at read time). Repeatable.',
+        }),
     };
     async run() {
         this.requireAuth();
@@ -107,9 +145,36 @@ class TasksCommentsAdd extends base_command_1.BaseCommand {
         // mentionedAgentIds, reopen, and interrupt are preserved. Boolean flags
         // default to false; only pass them through when actually set so they
         // don't clobber a `true` value from the JSON file.
+        // --attach: upload first, then append `task-asset:` references to the
+        // body — comments store stable asset ids, not URLs (OSK-9856/9863).
+        let attachSuffix = '';
+        if (flags.attach?.length) {
+            const { uploadTaskAssetFile, taskAssetMarkdownRef } = await Promise.resolve().then(() => __importStar(require('../../../lib/task-asset-upload')));
+            const refs = [];
+            for (const filePath of flags.attach) {
+                try {
+                    const asset = await uploadTaskAssetFile({
+                        taskId: task.id,
+                        filePath,
+                        role: 'evidence',
+                    });
+                    refs.push(taskAssetMarkdownRef(asset));
+                }
+                catch (err) {
+                    this.error(`--attach failed: ${err.message}`, { exit: 1 });
+                }
+            }
+            if (refs.length)
+                attachSuffix = `\n\n${refs.join('\n')}`;
+        }
         const mentionedFromFlag = flags['mention-agent'];
+        const baseBody = flags.body ?? (typeof commentBody.body === 'string' ? commentBody.body : undefined);
         const data = (0, prompt_1.mergeDefined)(commentBody, {
-            body: flags.body,
+            body: baseBody
+                ? `${baseBody}${attachSuffix}`
+                : attachSuffix
+                    ? attachSuffix.trimStart()
+                    : undefined,
             mentionedAgentIds: Array.isArray(mentionedFromFlag) && mentionedFromFlag.length > 0
                 ? mentionedFromFlag
                 : undefined,
@@ -163,7 +228,7 @@ class TasksCommentsAdd extends base_command_1.BaseCommand {
                 ? await (0, api_fetch_1.apiFetch)(sessionPath, {
                     method: 'POST',
                     body: {
-                        body: flags.body ?? commentBody.body,
+                        body: data.body,
                         ...(mentioned ? { mentionedAgentIds: mentioned } : {}),
                     },
                     headers: { 'X-Idempotency-Key': idempotencyKey },

package/dist/commands/tasks/complete.d.ts

@@ -26,6 +26,7 @@ export default class TasksComplete extends BaseCommand {
         'structured-json': import("@oclif/core/lib/interfaces").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
         deliverable: import("@oclif/core/lib/interfaces").OptionFlag<string[] | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
         evidence: import("@oclif/core/lib/interfaces").OptionFlag<string[] | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
+        attach: import("@oclif/core/lib/interfaces").OptionFlag<string[] | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
         remaining: import("@oclif/core/lib/interfaces").OptionFlag<string[] | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
         'source-run': import("@oclif/core/lib/interfaces").OptionFlag<string[] | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
         'run-id': import("@oclif/core/lib/interfaces").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;