@meshy-ai/cli 0.1.3 → 0.3.0

package/dist/internal/task-command.js

@@ -1,119 +1,510 @@
 /**
- * Factory that wires the uniform get/list/delete/wait/create subcommands for
- * any async-task resource. Keeps the per-resource modules focused on their
- * unique create-flag shape.
+ * Factory that wires the uniform create/get/list/wait/stream/delete
+ * subcommands for any registered task resource. Per-resource modules only
+ * contribute their unique `create` flag shape and payload validation.
+ *
+ * Two output schemas share one execution path:
+ *   legacy — the 0.2.0 payloads and `-o` status report, with two documented
+ *            fixes: `get` of a non-terminal task exits 0, and async create
+ *            never polls.
+ *   v1     — one `meshy.cli/v1` envelope whose result carries the TaskView,
+ *            the submission record and the download manifest.
+ *
+ * Money rules enforced here, independent of schema:
+ *   - every create is exactly one POST, journaled before it is sent;
+ *   - a lost or malformed response is `submission_unknown` (exit 10), never a
+ *     retry and never a "please run it again" hint;
+ *   - local targets that would fail after the POST (an existing --save-json
+ *     file, an -o path outside the workspace, a missing --project) are checked
+ *     before it, so a detectable conflict costs zero requests;
+ *   - once the server has accepted a task, every later failure — saving JSON,
+ *     polling, downloading, recording, a signal — still reports that task id,
+ *     the submission record and the `get`/`wait` commands that resume it;
+ *   - SIGINT stops waiting/streaming (exit 130) and never deletes anything.
  */
 import { Command, Option } from "commander";
-import { downloadArtifacts } from "./download.js";
-import { resolveImageFields, resolveModelFields } from "./file-input.js";
-import { pollUntilTerminal } from "./poll.js";
-import { emit } from "./output.js";
-import { mergePayload, parseJsonFlag } from "./payload.js";
+import { MeshyApiError } from "../client/errors.js";
+import { requireTaskResource } from "../client/resource-registry.js";
+import { TransportError } from "../client/transport.js";
+import { isTerminalStatus, summarizeTask } from "../client/types.js";
+import { emitResult, openCommand, rejectOutputFlagForV1, saveRawJson } from "./command-helpers.js";
+import { abortSignal, wasInterrupted } from "./context.js";
+import { downloadArtifacts, looksLikeFile } from "./download.js";
+import { classifyError, CliError, UsageError } from "./errors.js";
+import { normalizeMediaPayload } from "./file-input.js";
+import { logger } from "./logger.js";
+import { mergeNestedObjects, mergePayload, parseJsonFlag } from "./payload.js";
+import { emitEnvelope, emitStreamEvent, emit } from "./output.js";
+import { parseTimeoutSeconds, pollUntilTerminal } from "./poll.js";
 import { printReport } from "./report.js";
+import { errorEnvelope, okEnvelope, warning } from "./result.js";
+import { buildRuntime } from "./runtime.js";
 import { getUpdateNotice } from "./update-notifier.js";
-import { buildRuntime, readGlobalFlags } from "./runtime.js";
-import { summarizeTask, TERMINAL_STATUSES } from "../client/types.js";
-import { UsageError } from "./errors.js";
-import { logger } from "./logger.js";
+import { streamTask } from "./stream.js";
+import { toTaskView } from "./task-view.js";
+import { beginOperation, credentialBinding, credentialFingerprint, newOperationId, operationsRoot, payloadFingerprint, updateOperation, } from "./operation-store.js";
+import { originOf } from "./config.js";
+import { resolveWithinRoot, freezeRoot } from "./paths.js";
+import { assertProjectMetadataPresent, indexRootFor, projectRecordCommand, recordTask, saveTaskSnapshot, stageFromTaskType } from "./project-store.js";
+import { existsSync } from "node:fs";
+import { dirname, join, resolve as resolvePath } from "node:path";
+const TASK_JSON_OPTIONS = (cmd) => cmd
+    .option("--save-json <file>", "save the full task JSON as received (never overwrites)")
+    .option("--include-raw", "v1: include the untouched task response under result.task.raw")
+    .option("--project <dir>", "initialised meshy_output project: save task_<id>.json there and record the task in metadata.json")
+    .option("--stage <name>", "stage label for the project record (default: derived from the task type, e.g. preview | refine | build)");
+const NOT_REQUESTED = () => ({ state: "not_requested", files: [], metadata_path: null });
+function taskResult(o) {
+    return {
+        task: o.task ? toTaskView(o.raw ?? o.task, { descriptor: o.descriptor, includeRaw: o.includeRaw }) : null,
+        submission: o.submission,
+        downloads: o.downloads ?? NOT_REQUESTED(),
+        saved_json: o.savedJson ?? null,
+        ...(o.extra ?? {}),
+    };
+}
+function nextCommands(descriptor, taskId) {
+    const base = `meshy ${descriptor.commandPath.join(" ")}`;
+    return {
+        get: `${base} get ${taskId} --output-schema v1`,
+        wait: `${base} wait ${taskId} --output-schema v1`,
+        stream: `${base} stream ${taskId} --format ndjson --output-schema v1`,
+    };
+}
+/**
+ * Re-throw any error as a CliError whose `result` carries `result` — keeping
+ * the original classification (code, HTTP status, hint, recovery, exit code).
+ * A CliError's own partial result (files written so far, a failed download
+ * manifest) is merged on top, so nothing already known is lost.
+ */
+export function wrapWithResult(err, result) {
+    if (err instanceof CliError) {
+        return new CliError({
+            code: err.code,
+            message: err.message,
+            exitCode: err.exitCode,
+            httpStatus: err.httpStatus,
+            retryable: err.retryable,
+            recovery: err.recovery,
+            hint: err.hint,
+            details: err.details,
+            warnings: err.warnings,
+            result: { ...result, ...(err.result ?? {}) },
+            cause: err,
+        });
+    }
+    const c = classifyError(err);
+    return new CliError({
+        code: c.code,
+        message: c.message,
+        exitCode: c.exitCode,
+        httpStatus: c.httpStatus,
+        retryable: c.retryable,
+        recovery: c.recovery,
+        hint: c.hint,
+        details: c.details,
+        warnings: c.warnings,
+        result: { ...result, ...(c.result ?? {}) },
+        cause: err,
+    });
+}
+/** `wrapWithResult` with the task result shape: the id, submission and next commands always survive. */
+function withTaskContext(err, ctx) {
+    const next = nextCommands(ctx.descriptor, ctx.taskId);
+    const base = taskResult({
+        task: ctx.task ?? null,
+        raw: ctx.raw ?? null,
+        descriptor: ctx.descriptor,
+        includeRaw: Boolean(ctx.includeRaw),
+        submission: ctx.submission,
+        savedJson: ctx.savedJson ?? null,
+        extra: { task_id: ctx.taskId, next, ...(ctx.extra ?? {}) },
+    });
+    let own = {};
+    if (err instanceof CliError && err.result) {
+        own = { ...err.result };
+        // A bookkeeping error's `task: null` must not erase a task we do know.
+        if (own["task"] === null && ctx.task)
+            delete own["task"];
+    }
+    const wrapped = wrapWithResult(err, base);
+    return new CliError({
+        code: wrapped.code,
+        message: wrapped.message,
+        exitCode: wrapped.exitCode,
+        httpStatus: wrapped.httpStatus,
+        retryable: wrapped.retryable,
+        recovery: wrapped.recovery,
+        hint: wrapped.hint ?? wrapped.recovery?.command ?? next.wait,
+        details: wrapped.details,
+        warnings: wrapped.warnings,
+        result: { ...base, ...own, task_id: ctx.taskId, next },
+        cause: err,
+    });
+}
+function parentTaskIdFromPayload(payload) {
+    if (!payload)
+        return null;
+    for (const k of ["preview_task_id", "input_task_id", "rig_task_id"]) {
+        if (typeof payload[k] === "string" && payload[k])
+            return payload[k];
+    }
+    return null;
+}
+/** Resolve --project: an initialised project directory, inside the workspace when one is set. */
+function resolveProjectDir(projectFlag, workspace, cwd = process.cwd()) {
+    const projectDir = resolvePath(cwd, projectFlag);
+    if (!existsSync(join(projectDir, "metadata.json"))) {
+        throw new CliError({
+            code: "local_io",
+            message: `--project ${projectFlag} is not an initialised project (no metadata.json); run \`meshy project init\` first`,
+        });
+    }
+    if (workspace)
+        resolveWithinRoot(projectDir, workspace, { cwd, label: "--project" });
+    return projectDir;
+}
+/**
+ * --project: snapshot the task (when a full task is known) and record it.
+ * Failures keep the task id in the error result — a bookkeeping problem must
+ * never read as "no task was created". The recovery context (task, journal
+ * operation, stage, workspace) exists before the project is even looked at, so
+ * every failure of this phase — the directory resolving outside the workspace,
+ * a metadata.json that vanished or was damaged after the preflight, a lock, a
+ * full disk — carries it. Two kinds of failure, two answers: a project that no
+ * longer lies inside the write boundary gets no command that would cross it;
+ * anything else gets the one `meshy project record …` invocation (with the
+ * original `--workspace`) that redoes just the record once the project is
+ * restored. Nothing is re-submitted.
+ */
+function attachToProject(opts, opened, descriptor, taskId, task, raw, extra, warnings) {
+    const projectFlag = opts.project;
+    if (!projectFlag)
+        return null;
+    const projectDir = resolvePath(projectFlag);
+    // The boundary was frozen before the first request (the workspace, or the
+    // project directory itself when no workspace is given); it is never resolved
+    // again from a path that may have been replaced since.
+    const root = opened.flags.workspaceRoot ?? opts.__projectRoot ?? freezeRoot(projectDir, { label: "--project" });
+    const workspace = opened.flags.workspaceRoot?.given;
+    const stage = opts.stage ?? (typeof extra.payload?.["mode"] === "string" ? extra.payload["mode"] : descriptor.creativeLab?.stage ?? stageFromTaskType(task?.type, descriptor.id));
+    const input = {
+        taskId,
+        stage,
+        resource: descriptor.id,
+        taskType: task?.type ?? null,
+        endpoint: descriptor.legacyEndpoint,
+        parentTaskId: parentTaskIdFromPayload(extra.payload ?? null),
+        status: task?.status ?? null,
+        taskJson: null,
+        operationId: extra.operationId ?? null,
+        files: extra.files ?? [],
+    };
+    // 1. The location. The frozen boundary must still be the directory it was,
+    //    and the project must resolve inside it now — a workspace or project
+    //    replaced by a symlink while the request was in flight, or a project that
+    //    now resolves elsewhere, is a boundary problem: the task exists and is
+    //    journaled, but no recovery command may be handed out that writes across
+    //    that line. What passes is written through its real path.
+    let located;
+    try {
+        located = resolveWithinRoot(projectDir, root, { label: "--project" }).path;
+    }
+    catch (err) {
+        throw projectBoundaryFailure(err, taskId, projectFlag, input);
+    }
+    // 2. The record itself, including "is this (still) an initialised project".
+    try {
+        if (opts.__projectInitialised === false && !existsSync(join(located, "metadata.json"))) {
+            throw new CliError({ code: "local_io", message: `--project ${projectFlag} is not an initialised project (no metadata.json); run \`meshy project init\` first` });
+        }
+        assertProjectMetadataPresent(located, projectFlag);
+        const snapshot = task && raw ? saveTaskSnapshot(located, taskId, raw) : null;
+        input.taskJson = snapshot?.relative ?? null;
+        const indexRoot = indexRootFor(located, undefined, opened.flags.workspaceRoot);
+        const rec = recordTask(located, input, { root: indexRoot.root, skipIndex: indexRoot.skipIndex });
+        if (!rec.index.updated)
+            warnings.push(warning("index_dirty", `metadata.json committed but history.json was not updated: ${rec.index.error}; run \`meshy project rebuild-index\``));
+        if (rec.migrated_from_legacy)
+            warnings.push(warning("metadata_migrated", "legacy metadata.json migrated to schema_version 2 (backup kept beside it)"));
+        return { project_dir: projectDir, snapshot: snapshot?.path ?? null, stage, action: rec.action, index: rec.index };
+    }
+    catch (err) {
+        // The task exists and the journal is written; only the project entry is
+        // missing. The recovery redoes that one step under the original boundary.
+        const command = projectRecordCommand(projectDir, input, { workspace });
+        throw new CliError({
+            code: err instanceof CliError ? err.code : "local_io",
+            message: `task ${taskId} exists${input.operationId ? ` (operation ${input.operationId})` : ""} but recording it in ${projectDir} failed: ${err instanceof Error ? err.message : String(err)}; restore the project, then run: ${command}`,
+            httpStatus: err instanceof CliError ? err.httpStatus : null,
+            retryable: err instanceof CliError ? err.retryable : false,
+            recovery: { action: "record_project", automatic: false, command },
+            hint: command,
+            details: err instanceof CliError ? err.details : undefined,
+            cause: err,
+        });
+    }
+}
+/**
+ * The project directory no longer resolves inside the workspace (or is a
+ * symlink). The task is known and journaled; the caller learns that, and that
+ * nothing was recorded — but no `meshy project record` command is offered,
+ * because the only one that would succeed is one without the boundary.
+ */
+function projectBoundaryFailure(err, taskId, projectFlag, input) {
+    const reason = err instanceof Error ? err.message : String(err);
+    return new CliError({
+        code: "local_io",
+        message: `task ${taskId} exists${input.operationId ? ` (operation ${input.operationId})` : ""} but --project ${projectFlag} is no longer a target inside the authorised boundary: ${reason}; nothing was recorded (no project lock, snapshot or metadata was written). Restore the project inside the workspace, then record the task with \`meshy project record\` from that workspace`,
+        details: { project: projectFlag, task_id: taskId, operation_id: input.operationId ?? null, stage: input.stage, recorded: false },
+        cause: err,
+    });
+}
+/** --save-json inside the task's context: a full disk or a vanished directory never hides the task id. */
+function saveJsonInContext(opts, opened, raw, ctx) {
+    if (!opts.saveJson)
+        return null;
+    try {
+        return saveRawJson(String(opts.saveJson), raw, { workspace: opened.flags.workspaceRoot });
+    }
+    catch (err) {
+        throw withTaskContext(err, ctx);
+    }
+}
+function attachInContext(opts, opened, descriptor, taskId, task, raw, extra, warnings, ctx) {
+    try {
+        return attachToProject(opts, opened, descriptor, taskId, task, raw, extra, warnings);
+    }
+    catch (err) {
+        throw withTaskContext(err, ctx);
+    }
+}
+// ---------------------------------------------------------------------------
+// Pre-submission checks: anything local that would fail *after* a billable POST
+// and can be detected now is refused now, with "nothing was submitted".
+// ---------------------------------------------------------------------------
+/** `-o` target: inside the workspace (or its own directory), no symlink leaf, not an existing file. */
+export function preflightOutputPath(output, workspace, cwd = process.cwd()) {
+    const abs = resolvePath(cwd, output);
+    resolveWithinRoot(abs, workspace ?? dirname(abs), { cwd, label: "--output" });
+    if (looksLikeFile(abs) && existsSync(abs)) {
+        throw new CliError({
+            code: "local_io",
+            message: `--output ${output} already exists; choose another path (nothing was submitted)`,
+            recovery: { action: "choose_path", automatic: false },
+        });
+    }
+}
+/** `--save-json` target: inside the workspace (or its own directory), no symlink leaf, not an existing file. */
+export function preflightSaveJsonPath(target, workspace, cwd = process.cwd()) {
+    const abs = resolvePath(cwd, target);
+    const resolved = resolveWithinRoot(abs, workspace ?? dirname(abs), { cwd, label: "--save-json target" });
+    if (existsSync(resolved.path)) {
+        throw new CliError({
+            code: "local_io",
+            message: `--save-json target ${target} already exists; choose another path (nothing was submitted)`,
+            recovery: { action: "choose_path", automatic: false },
+        });
+    }
+}
+/**
+ * Freeze the project's write boundary before the first request: with a
+ * workspace it is the workspace (already frozen with the flags); without one it
+ * is the project directory as it is right now. Whether the project was
+ * initialised at this moment is remembered too, so a later "no metadata.json"
+ * can say which it was. Nothing is refused here for get/wait/stream — a
+ * bookkeeping problem stays a bookkeeping problem after the request (one
+ * outcome); create's preflight refuses an uninitialised project before its POST.
+ */
+function beginProjectContext(opts, opened) {
+    const projectFlag = opts.project;
+    if (!projectFlag || opts.__projectRoot)
+        return;
+    const projectDir = resolvePath(projectFlag);
+    opts.__projectInitialised = existsSync(join(projectDir, "metadata.json"));
+    opts.__projectRoot = opened.flags.workspaceRoot ?? freezeRoot(projectDir, { label: "--project" });
+}
+function preflightLocalTargets(opts, opened) {
+    if (opts.saveJson)
+        preflightSaveJsonPath(String(opts.saveJson), opened.flags.workspaceRoot);
+    if (opened.flags.output)
+        preflightOutputPath(opened.flags.output, opened.flags.workspaceRoot);
+    if (opts.project) {
+        try {
+            resolveProjectDir(String(opts.project), opened.flags.workspaceRoot);
+            beginProjectContext(opts, opened);
+        }
+        catch (err) {
+            if (err instanceof CliError) {
+                throw new CliError({ code: err.code, message: `${err.message} (nothing was submitted)`, recovery: err.recovery, cause: err });
+            }
+            throw err;
+        }
+    }
+}
 export function buildResourceCommand(spec) {
-    const cmd = new Command(spec.name).description(spec.description);
+    const descriptor = requireTaskResource(spec.name);
+    const endpointOf = spec.endpointOf ?? ((client) => client.endpointFor(descriptor));
+    const prefix = spec.commandPrefix ?? spec.name;
+    const defaultSchema = spec.defaultSchema ?? "legacy";
+    const cmd = new Command(spec.commandName ?? spec.name).description(spec.description);
     // create
     const createCmd = new Command("create").description(spec.create.description);
     spec.create.configure(createCmd);
-    createCmd
-        .addOption(new Option("--data <json>", "raw JSON payload (or @file.json); merges with flags"))
-        .addOption(new Option("--async", "return the task_id immediately without polling; query later with `<resource> wait <id>` or `get <id>`").default(false))
+    TASK_JSON_OPTIONS(createCmd)
+        .addOption(new Option("--data <json>", "raw JSON payload (or @file.json); merges with flags (flags win)"))
+        .addOption(new Option("--async", "submit once and return the task id immediately (no polling); query later with `get`, `wait` or `stream`").default(false))
         .addOption(new Option("--timeout <seconds>", "max seconds to poll in sync mode").default("600"))
+        .addOption(new Option("--operation-id <id>", "local journal id for this submission; repeating it returns the recorded outcome instead of submitting again (local record only, not a server idempotency key)"))
         .action(async (opts, thisCmd) => {
-        const runtime = await buildRuntime(readGlobalFlags(thisCmd));
-        const endpoint = spec.endpointOf(runtime.client);
+        const opened = openCommand(thisCmd, `${prefix}.create`, defaultSchema);
+        const timeoutSeconds = parseTimeoutSeconds(opts.timeout ?? "600");
+        const runAsync = Boolean(opts.async);
+        const includeRaw = Boolean(opts.includeRaw);
+        const runtime = await buildRuntime(opened.flags);
+        const endpoint = endpointOf(runtime.client);
+        // 1. Build and validate the payload — every local failure happens here, before the journal and the POST.
         const data = parseJsonFlag(opts.data, "--data");
-        // Resolve local file paths + preflight URLs for image and 3D-model
-        // inputs before building the payload — fail fast on missing inputs.
-        await resolveImageFields(opts);
-        await resolveModelFields(opts);
         const flagPayload = spec.create.toPayload(opts);
         const defaults = spec.create.toDefaults?.(opts) ?? {};
-        const payload = mergePayload(defaults, data, flagPayload);
-        logger.debug("create payload", payload);
-        const taskId = await endpoint.create(payload);
-        const runAsync = Boolean(opts.async);
-        const timeoutSeconds = Number(opts.timeout ?? 600);
+        const layers = [defaults, data, flagPayload];
+        let merged = mergePayload(...layers);
+        if (spec.create.nestedObjectKeys && spec.create.nestedObjectKeys.length > 0) {
+            merged = mergeNestedObjects(merged, layers, spec.create.nestedObjectKeys);
+        }
+        spec.create.validatePayload?.(merged, opts);
+        const { payload } = await normalizeMediaPayload(merged, descriptor.mediaFields, { signal: abortSignal() });
+        logger.debug("create payload", redactForLog(payload));
+        // 2. Local targets that would fail after the POST are refused before it.
+        preflightLocalTargets(opts, opened);
+        // 3. Journal, then exactly one POST.
+        const submitted = await submitCreate(runtime, descriptor, endpoint, payload, opts.operationId ?? null);
+        const { taskId, raw: createRaw, operationId, warnings } = submitted;
+        const submission = { state: "accepted", operation_id: operationId, task_id: taskId, request_id: submitted.requestId };
         if (runAsync) {
+            const ctx = { descriptor, taskId, task: null, raw: null, submission, includeRaw };
+            const savedJson = saveJsonInContext(opts, opened, createRaw, ctx);
+            const project = attachInContext(opts, opened, descriptor, taskId, null, null, { operationId, payload }, warnings, { ...ctx, savedJson });
+            if (opened.schema === "v1") {
+                await emitEnvelope(okEnvelope(opened.command, taskResult({
+                    task: null,
+                    raw: null,
+                    descriptor,
+                    includeRaw: false,
+                    submission,
+                    savedJson,
+                    extra: { task_id: taskId, next: nextCommands(descriptor, taskId), project },
+                }), warnings), opened.format);
+                return;
+            }
             emit({
                 resource: spec.name,
                 task_id: taskId,
                 status: "PENDING",
-                hint: `meshy-cli ${spec.name} wait ${taskId}`,
-            }, { format: runtime.flags.format, file: undefined });
+                hint: `meshy-cli ${descriptor.commandPath.join(" ")} wait ${taskId}`,
+                operation_id: operationId,
+                ...(project ? { project_dir: project.project_dir } : {}),
+            }, { format: opened.format, file: undefined });
             return;
         }
-        const started = Date.now();
-        const { task, timedOut } = await pollUntilTerminal(endpoint, taskId, {
-            timeoutSeconds,
-            intervalMs: runtime.config.pollIntervalMs,
-        });
-        const elapsed = (Date.now() - started) / 1000;
-        await emitTerminalOutcome(task, timedOut, elapsed, spec.name, runtime);
+        // 4. Sync: poll the id we just recorded.
+        await waitAndReport(opened, runtime, descriptor, endpoint, taskId, timeoutSeconds, { ...opts, __payload: payload, __operationId: operationId }, submission, warnings);
     });
     cmd.addCommand(createCmd);
     // get
-    cmd
-        .command("get <task-id>")
-        .description("Retrieve a single task by id")
-        .action(async (taskId, _opts, thisCmd) => {
-        const runtime = await buildRuntime(readGlobalFlags(thisCmd));
-        const task = await spec.endpointOf(runtime.client).retrieve(taskId);
-        await emitTerminalOutcome(task, false, undefined, spec.name, runtime);
+    TASK_JSON_OPTIONS(cmd.command("get <task-id>").description("Retrieve a single task by id (any status is a successful query)")).action(async (taskId, opts, thisCmd) => {
+        const opened = openCommand(thisCmd, `${prefix}.get`, defaultSchema);
+        beginProjectContext(opts, opened);
+        const runtime = await buildRuntime(opened.flags);
+        const { task, raw } = await endpointOf(runtime.client).retrieveDetailed(taskId, { signal: abortSignal() });
+        const submission = { state: "accepted", operation_id: null };
+        const includeRaw = Boolean(opts.includeRaw);
+        const warnings = [];
+        const ctx = { descriptor, taskId, task, raw, submission, includeRaw };
+        const savedJson = saveJsonInContext(opts, opened, raw, ctx);
+        const project = attachInContext(opts, opened, descriptor, taskId, task, raw, {}, warnings, { ...ctx, savedJson });
+        if (opened.schema === "v1") {
+            const downloads = await maybeDownloadV1(opened, descriptor, task, raw, submission, warnings, { savedJson, includeRaw, project });
+            await emitEnvelope(okEnvelope(opened.command, taskResult({ task, raw, descriptor, includeRaw, submission, downloads, savedJson, extra: project ? { project } : {} }), warnings), opened.format);
+            return;
+        }
+        // Legacy shape, same rule: a download failure still names the task.
+        try {
+            await emitLegacyOutcome(task, false, undefined, spec.name, runtime, { query: true });
+        }
+        catch (err) {
+            throw withTaskContext(err, { ...ctx, savedJson, extra: project ? { project } : {} });
+        }
     });
     // wait
-    cmd
+    TASK_JSON_OPTIONS(cmd
         .command("wait <task-id>")
         .description("Poll until the task reaches a terminal status")
-        .option("--timeout <seconds>", "max seconds to wait", "600")
-        .action(async (taskId, opts, thisCmd) => {
-        const runtime = await buildRuntime(readGlobalFlags(thisCmd));
-        const endpoint = spec.endpointOf(runtime.client);
-        const timeoutSeconds = Number(opts.timeout ?? 600);
-        const started = Date.now();
-        const { task, timedOut } = await pollUntilTerminal(endpoint, taskId, {
-            timeoutSeconds,
-            intervalMs: runtime.config.pollIntervalMs,
-        });
-        const elapsed = (Date.now() - started) / 1000;
-        await emitTerminalOutcome(task, timedOut, elapsed, spec.name, runtime);
+        .option("--timeout <seconds>", "max seconds to wait (0 = a single query)", "600")).action(async (taskId, opts, thisCmd) => {
+        const opened = openCommand(thisCmd, `${prefix}.wait`, defaultSchema);
+        beginProjectContext(opts, opened);
+        const timeoutSeconds = parseTimeoutSeconds(opts.timeout ?? "600");
+        const runtime = await buildRuntime(opened.flags);
+        const endpoint = endpointOf(runtime.client);
+        await waitAndReport(opened, runtime, descriptor, endpoint, taskId, timeoutSeconds, opts, { state: "accepted", operation_id: null }, []);
+    });
+    // stream
+    TASK_JSON_OPTIONS(cmd
+        .command("stream <task-id>")
+        .description("Follow the task over Server-Sent Events until it is terminal")
+        .option("--timeout <seconds>", "total deadline for the stream", "600")
+        .option("--idle-timeout <seconds>", "abort when no bytes arrive for this long (keep-alives count)", "60")).action(async (taskId, opts, thisCmd) => {
+        const opened = openCommand(thisCmd, `${prefix}.stream`, defaultSchema);
+        beginProjectContext(opts, opened);
+        if (!descriptor.supports.stream)
+            throw new UsageError(`${spec.name} does not support stream`);
+        const timeoutSeconds = parseTimeoutSeconds(opts.timeout ?? "600");
+        const idleSeconds = parseTimeoutSeconds(opts.idleTimeout ?? "60", "--idle-timeout");
+        if (timeoutSeconds === 0)
+            throw new UsageError("--timeout 0 is not meaningful for stream; use `get` for a single query");
+        const runtime = await buildRuntime(opened.flags);
+        const endpoint = endpointOf(runtime.client);
+        await streamAndReport(opened, runtime, descriptor, endpoint, taskId, timeoutSeconds, idleSeconds, opts);
     });
     // delete
     cmd
         .command("delete <task-id>")
         .description("Delete a task")
         .action(async (taskId, _opts, thisCmd) => {
-        const runtime = await buildRuntime(readGlobalFlags(thisCmd));
-        await spec.endpointOf(runtime.client).delete(taskId);
-        emit({ resource: spec.name, task_id: taskId, deleted: true }, {
-            format: runtime.flags.format,
-            file: runtime.flags.output,
-        });
+        const opened = openCommand(thisCmd, `${prefix}.delete`, defaultSchema);
+        rejectOutputFlagForV1(opened, undefined);
+        const runtime = await buildRuntime(opened.flags);
+        const raw = await endpointOf(runtime.client).delete(taskId, { signal: abortSignal() });
+        await emitResult(opened, { resource: spec.name, task_id: taskId, deleted: true }, { resource: spec.name, endpoint: descriptor.legacyEndpoint, task_id: taskId, deleted: true, response: raw ?? null }, { legacyFile: opened.flags.output });
     });
-    // list (optional — some endpoints don't support it)
-    if (spec.supportsList !== false) {
+    // list
+    if (spec.supportsList !== false && descriptor.supports.list) {
         cmd
             .command("list")
             .description("List recent tasks")
             .option("--page <n>", "page number (1-based)", "1")
             .option("--page-size <n>", "page size", "10")
             .option("--sort-by <field>", "sort order (e.g. -created_at)", "-created_at")
+            .option("--save-json <file>", "save the raw list response (never overwrites)")
+            .option("--include-raw", "v1: include each raw task under items[].raw")
             .action(async (opts, thisCmd) => {
-            const runtime = await buildRuntime(readGlobalFlags(thisCmd));
-            const tasks = await spec.endpointOf(runtime.client).list({
-                page_num: Number(opts.page ?? 1),
-                page_size: Number(opts.pageSize ?? 10),
-                sort_by: opts.sortBy ?? "-created_at",
-            });
-            emit(tasks.map((t) => summarizeTask(t)), {
-                format: runtime.flags.format,
-                file: runtime.flags.output,
-            });
+            const opened = openCommand(thisCmd, `${prefix}.list`, defaultSchema);
+            rejectOutputFlagForV1(opened, opts.saveJson);
+            const runtime = await buildRuntime(opened.flags);
+            const page = { page_num: Number(opts.page ?? 1), page_size: Number(opts.pageSize ?? 10), sort_by: String(opts.sortBy ?? "-created_at") };
+            if (!Number.isInteger(page.page_num) || page.page_num < 1)
+                throw new UsageError("--page must be a positive integer");
+            if (!Number.isInteger(page.page_size) || page.page_size < 1)
+                throw new UsageError("--page-size must be a positive integer");
+            const { tasks, raw } = await endpointOf(runtime.client).listDetailed(page, { signal: abortSignal() });
+            const savedJson = opts.saveJson ? saveRawJson(opts.saveJson, raw, { workspace: opened.flags.workspaceRoot }) : null;
+            const rawItems = Array.isArray(raw) ? raw : [];
+            await emitResult(opened, tasks.map((t) => summarizeTask(t)), {
+                items: tasks.map((t, i) => toTaskView(rawItems[i] ?? t, { descriptor, includeRaw: Boolean(opts.includeRaw) })),
+                count: tasks.length,
+                page,
+                saved_json: savedJson,
+            }, { legacyFile: opened.flags.output });
         });
     }
     else {
@@ -126,18 +517,500 @@ export function buildResourceCommand(spec) {
     }
     return cmd;
 }
+/** Strip media payloads before logging. */
+function redactForLog(payload) {
+    const out = {};
+    for (const [k, v] of Object.entries(payload)) {
+        if (typeof v === "string" && v.startsWith("data:"))
+            out[k] = `data:<${v.length} chars>`;
+        else if (Array.isArray(v))
+            out[k] = v.map((x) => (typeof x === "string" && x.startsWith("data:") ? `data:<${x.length} chars>` : x));
+        else
+            out[k] = v;
+    }
+    return out;
+}
 /**
- * Decide how to report a task whose status is (expected to be) terminal:
- *   - with `-o`: download artifacts to the filesystem and print the status
- *     report. Failed/timed-out tasks print the FAIL form without downloads.
- *   - without `-o`: emit the familiar JSON/pretty summary to stdout.
+ * The credential identity a submission is journaled under: bound to the key
+ * digest, the OAuth subject or the OAuth login id. `verified` is false when
+ * none of those exists (a pre-login-id OAuth profile): such a credential may
+ * start operations but is refused a replay of an existing record.
  */
-export async function emitTerminalOutcome(task, timedOut, elapsedSeconds, resourceName, runtime) {
+export function credentialIdentityFor(runtime, apiOrigin) {
+    const parts = {
+        source: runtime.config.credentialSource,
+        profile: runtime.config.credentialProfile ?? null,
+        origin: apiOrigin,
+        kind: runtime.config.credentialKind,
+        secret: runtime.config.credentialKind === "api_key" ? runtime.config.apiKey : null,
+        subject: runtime.config.credentialSubject ?? null,
+        loginId: runtime.config.credentialLoginId ?? null,
+    };
+    return { fingerprint: credentialFingerprint(parts), verified: credentialBinding(parts).verified };
+}
+/**
+ * Journal → single POST → journal update. Every failure path leaves a record
+ * that says what is known; the unknown state is reported as exit 10 with the
+ * operation id and never as a suggestion to submit again. Shared by the
+ * resource commands and `make`, so there is exactly one submission state
+ * machine.
+ */
+export async function submitCreate(runtime, descriptor, endpoint, payload, requestedOperationId, ctx = {}) {
+    const root = operationsRoot();
+    const operationId = requestedOperationId ?? newOperationId();
+    const apiOrigin = originOf(endpoint.transportBaseUrl) ?? endpoint.transportBaseUrl;
+    const credential = credentialIdentityFor(runtime, apiOrigin);
+    const identity = {
+        resource: descriptor.id,
+        endpoint: descriptor.legacyEndpoint,
+        apiOrigin,
+        credentialFingerprint: credential.fingerprint,
+        credentialVerified: credential.verified,
+        payloadFingerprint: payloadFingerprint(payload),
+    };
+    const label = ctx.label ?? "the create request";
+    const extra = ctx.extraResult ?? {};
+    const warnings = [];
+    let begin;
+    try {
+        begin = beginOperation(root, operationId, identity);
+    }
+    catch (err) {
+        if (err instanceof CliError)
+            throw err;
+        throw new CliError({ code: "local_io", message: `cannot write the operation journal under ${root}: ${err instanceof Error ? err.message : String(err)}; nothing was submitted`, cause: err });
+    }
+    if (begin.outcome === "existing") {
+        return replayExisting(begin.record, descriptor, operationId, extra);
+    }
+    if (abortSignal().aborted) {
+        updateOperation(root, operationId, { state: "not_submitted", error: "interrupted before the request was sent" });
+        throw new CliError({ code: "interrupted", message: "interrupted before the request was sent; nothing was submitted", result: { submission: { state: "not_submitted", operation_id: operationId }, task: null, ...extra } });
+    }
+    let created;
+    try {
+        created = await endpoint.createDetailed(payload, { signal: abortSignal() });
+    }
+    catch (err) {
+        const submission = classifySubmissionFailure(err);
+        try {
+            updateOperation(root, operationId, {
+                state: submission.state,
+                http_status: err instanceof MeshyApiError && err.status ? err.status : null,
+                error: err instanceof Error ? err.message : String(err),
+            });
+        }
+        catch (journalErr) {
+            warnings.push(warning("journal_write_failed", `operation journal update failed: ${journalErr instanceof Error ? journalErr.message : String(journalErr)}`));
+        }
+        if (submission.state === "rejected" || submission.state === "not_submitted") {
+            // Definite outcomes keep their own classification (validation/auth/network …).
+            if (err instanceof CliError)
+                throw err;
+            const wrapped = err instanceof MeshyApiError ? err : err instanceof Error ? err : new Error(String(err));
+            throw attachSubmission(wrapped, { state: submission.state, operation_id: operationId }, warnings);
+        }
+        const interrupted = wasInterrupted();
+        throw new CliError({
+            code: interrupted ? "interrupted" : "submission_unknown",
+            message: interrupted
+                ? `interrupted while ${label} was in flight; the server may or may not have created a task (operation ${operationId})`
+                : `${label} was sent but its outcome is unknown (${err instanceof Error ? err.message : String(err)}); the server may or may not have created a task`,
+            httpStatus: err instanceof MeshyApiError && err.status ? err.status : null,
+            recovery: {
+                action: "reconcile",
+                automatic: false,
+                command: `meshy ${descriptor.commandPath.join(" ")} list --output-schema v1   # then match operation ${operationId} by time/prompt before creating again`,
+            },
+            result: { submission: { state: "unknown", operation_id: operationId, task_id: null }, task: null, downloads: NOT_REQUESTED(), ...extra },
+            warnings,
+            cause: err,
+        });
+    }
+    try {
+        updateOperation(root, operationId, { state: "accepted", task_id: created.taskId, request_id: created.requestId, http_status: 200 });
+    }
+    catch (journalErr) {
+        // The server has the task; the id must survive this failure — a local write
+        // problem is local_io, never an unknown submission.
+        throw new CliError({
+            code: "local_io",
+            message: `task ${created.taskId} was created but the operation journal could not be updated: ${journalErr instanceof Error ? journalErr.message : String(journalErr)}`,
+            result: {
+                submission: { state: "accepted", operation_id: operationId, task_id: created.taskId, request_id: created.requestId },
+                task: null,
+                task_id: created.taskId,
+                next: nextCommands(descriptor, created.taskId),
+                ...extra,
+            },
+            cause: journalErr,
+        });
+    }
+    return { taskId: created.taskId, raw: created.raw, requestId: created.requestId, operationId, warnings };
+}
+function replayExisting(record, descriptor, operationId, extra) {
+    if (record.state === "accepted" && record.task_id) {
+        return {
+            taskId: record.task_id,
+            raw: { result: record.task_id, replayed_from_journal: true },
+            requestId: record.request_id,
+            operationId,
+            warnings: [warning("operation_replayed", `operation ${operationId} was already accepted as task ${record.task_id} on ${record.updated_at}; no new request was sent`)],
+        };
+    }
+    if (record.state === "unknown" || record.state === "started") {
+        throw new CliError({
+            code: "submission_unknown",
+            message: `operation ${operationId} is recorded as '${record.state}' since ${record.updated_at}; reconcile it before submitting again (nothing was sent now)`,
+            recovery: { action: "reconcile", automatic: false, command: `meshy ${descriptor.commandPath.join(" ")} list --output-schema v1` },
+            result: { submission: { state: "unknown", operation_id: operationId, task_id: record.task_id }, task: null, ...extra },
+        });
+    }
+    throw new CliError({
+        code: "operation_conflict",
+        message: `operation ${operationId} was already ${record.state} on ${record.updated_at} (${record.error ?? "no detail"}); use a new --operation-id to submit again`,
+        result: { submission: { state: record.state, operation_id: operationId, task_id: record.task_id }, task: null, ...extra },
+    });
+}
+function classifySubmissionFailure(err) {
+    if (err instanceof TransportError) {
+        return { state: err.neverSent ? "not_submitted" : "unknown" };
+    }
+    if (err instanceof MeshyApiError) {
+        if (err.status >= 400 && err.status < 500)
+            return { state: "rejected" };
+        return { state: "unknown" }; // 5xx, malformed 2xx, unknown status
+    }
+    return { state: "unknown" };
+}
+function attachSubmission(err, submission, warnings) {
+    err.submission = submission;
+    err.warnings = warnings;
+    return err;
+}
+/**
+ * v1 `-o`: download a SUCCEEDED task's assets through the legacy layout,
+ * confined to the workspace when one is set. A failure keeps the task in the
+ * result — the assets are still on the server, the task still exists.
+ */
+async function maybeDownloadV1(opened, descriptor, task, raw, submission, warnings, ctx) {
+    const output = opened.flags.output;
+    if (!output)
+        return NOT_REQUESTED();
+    if (task.status !== "SUCCEEDED")
+        return { state: "not_ready", files: [], metadata_path: null };
+    try {
+        const { files, metadataPath, materialLinks } = await downloadArtifacts(task, output, descriptor.id, { root: opened.flags.workspaceRoot, signal: abortSignal() });
+        if (materialLinks)
+            warnings.push(...materialLinks.warnings);
+        return {
+            state: "completed",
+            files: files.map((f) => ({ key: f.key, path: f.path, status: f.status, bytes: f.bytes, sha256: f.sha256, error: f.error })),
+            metadata_path: metadataPath,
+            material_links: materialLinks,
+        };
+    }
+    catch (err) {
+        // Whatever the downloader already committed stays in the manifest, and the
+        // failure keeps its own class: an HTTP 503 on the second asset is a network
+        // failure with its status, a Ctrl-C is `interrupted` (130) — never a bare local_io.
+        const partial = err instanceof CliError && err.result && err.result["downloads"] && typeof err.result["downloads"] === "object"
+            ? err.result["downloads"]
+            : { state: "failed", files: [], metadata_path: null };
+        const interrupted = (err instanceof CliError && err.code === "interrupted") || wasInterrupted();
+        const failure = new CliError({
+            code: interrupted ? "interrupted" : err instanceof CliError ? err.code : "local_io",
+            message: `task ${task.id} is SUCCEEDED but downloading its assets ${interrupted ? "was interrupted" : "failed"}: ${err instanceof Error ? err.message : String(err)}`,
+            httpStatus: err instanceof CliError ? err.httpStatus : null,
+            retryable: err instanceof CliError ? err.retryable : false,
+            recovery: err instanceof CliError && err.recovery ? err.recovery : { action: "download", automatic: false, command: `meshy download --resource ${descriptor.id} --task-id ${task.id} --all --output-dir <dir>` },
+            hint: err instanceof CliError ? err.hint : undefined,
+            details: err instanceof CliError ? err.details : undefined,
+            result: { downloads: partial },
+            warnings: [...warnings, ...(err instanceof CliError ? err.warnings : [])],
+            cause: err,
+        });
+        throw withTaskContext(failure, {
+            descriptor,
+            taskId: task.id,
+            task,
+            raw,
+            submission,
+            includeRaw: ctx.includeRaw,
+            savedJson: ctx.savedJson,
+            extra: ctx.project ? { project: ctx.project } : {},
+        });
+    }
+}
+async function waitAndReport(opened, runtime, descriptor, endpoint, taskId, timeoutSeconds, opts, submission, warnings) {
+    const started = performance.now();
+    const includeRaw = Boolean(opts.includeRaw);
+    // A holder (not a bare `let`) so the callback's assignment is visible to the
+    // catch block without TypeScript narrowing it away.
+    const seen = { last: null, polls: 0 };
+    let poll;
+    try {
+        poll = await pollUntilTerminal(endpoint, taskId, {
+            timeoutSeconds,
+            intervalMs: runtime.config.pollIntervalMs,
+            requestTimeoutMs: runtime.config.readTimeoutMs,
+            signal: abortSignal(),
+            onTick: (task, raw) => {
+                seen.last = { task, raw };
+                seen.polls += 1;
+                if (opened.schema === "v1" && opened.format !== "ndjson") {
+                    process.stderr.write(`[${descriptor.id}] ${task.status}${typeof task.progress === "number" ? ` ${task.progress}%` : ""}\n`);
+                }
+            },
+        });
+    }
+    catch (err) {
+        if (wasInterrupted() || abortSignal().aborted) {
+            throw interruptedError(descriptor, taskId, seen.last, submission, opts, opened);
+        }
+        // A polling failure (5xx, network, malformed task) is not "no task": the
+        // id, the submission and the last status seen travel with the error.
+        const elapsed = (performance.now() - started) / 1000;
+        throw withTaskContext(err, {
+            descriptor,
+            taskId,
+            task: seen.last?.task ?? null,
+            raw: seen.last?.raw ?? null,
+            submission,
+            includeRaw,
+            extra: { wait: { timed_out: false, elapsed_seconds: Number(elapsed.toFixed(2)), polls: seen.polls } },
+        });
+    }
+    const elapsed = (performance.now() - started) / 1000;
+    const { task, raw, timedOut, aborted } = poll;
+    const waitInfo = { timed_out: timedOut, elapsed_seconds: Number(elapsed.toFixed(2)), polls: poll.polls };
+    if (aborted)
+        throw interruptedError(descriptor, taskId, task ? { task, raw } : seen.last, submission, opts, opened);
+    if (task === null) {
+        // The deadline passed before the first response arrived; the task id is all we know — and it is enough.
+        if (opened.schema !== "v1") {
+            emitLegacyTimeoutWithoutTask(taskId, descriptor.id, runtime);
+            return;
+        }
+        throw new CliError({
+            code: "timed_out",
+            message: `task ${taskId} did not answer within ${timeoutSeconds}s (no status was received in time); the server keeps running it`,
+            recovery: { action: "wait", automatic: false, command: nextCommands(descriptor, taskId).wait },
+            result: taskResult({ task: null, raw: null, descriptor, includeRaw, submission, extra: { task_id: taskId, wait: waitInfo, next: nextCommands(descriptor, taskId) } }),
+            warnings,
+        });
+    }
+    const ctx = { descriptor, taskId, task, raw, submission, includeRaw, extra: { wait: waitInfo } };
+    const savedJson = saveJsonInContext(opts, opened, raw, ctx);
+    const project = attachInContext(opts, opened, descriptor, taskId, task, raw, { operationId: opts.__operationId ?? submission.operation_id ?? null, payload: opts.__payload ?? null }, warnings, { ...ctx, savedJson });
+    const projectExtra = project ? { project } : {};
+    if (opened.schema !== "v1") {
+        // The legacy reporter downloads too; whatever fails there — an asset host
+        // 503, a sidecar that cannot be published, Ctrl-C — the error still
+        // carries the accepted task id, the real submission and the resume command.
+        try {
+            await emitLegacyOutcome(task, timedOut, elapsed, descriptor.id, runtime, { query: false });
+        }
+        catch (err) {
+            throw withTaskContext(err, { ...ctx, savedJson, extra: { wait: waitInfo, ...projectExtra } });
+        }
+        return;
+    }
+    if (timedOut) {
+        throw new CliError({
+            code: "timed_out",
+            message: `task ${taskId} did not reach a terminal status within ${timeoutSeconds}s (last status: ${task.status}); the server keeps running it`,
+            recovery: { action: "wait", automatic: false, command: nextCommands(descriptor, taskId).wait },
+            result: taskResult({ task, raw, descriptor, includeRaw, submission, savedJson, extra: { task_id: taskId, wait: waitInfo, next: nextCommands(descriptor, taskId), ...projectExtra } }),
+            warnings,
+        });
+    }
+    if (task.status !== "SUCCEEDED") {
+        throw new CliError({
+            code: "task_failed",
+            message: task.task_error?.message ? `task ${taskId} ${task.status}: ${task.task_error.message}` : `task ${taskId} ended as ${task.status}`,
+            result: taskResult({ task, raw, descriptor, includeRaw, submission, savedJson, extra: { task_id: taskId, wait: waitInfo, ...projectExtra } }),
+            warnings,
+        });
+    }
+    const downloads = await maybeDownloadV1(opened, descriptor, task, raw, submission, warnings, { savedJson, includeRaw, project });
+    await emitEnvelope(okEnvelope(opened.command, taskResult({ task, raw, descriptor, includeRaw, submission, downloads, savedJson, extra: { wait: waitInfo, ...projectExtra } }), warnings), opened.format);
+}
+/** Legacy shape for a wait that timed out before any status arrived: still the task id, still exit 8. */
+function emitLegacyTimeoutWithoutTask(taskId, resourceName, runtime) {
+    if (runtime.flags.output) {
+        const report = { status: "FAIL", taskId, type: resourceName, timedOut: true };
+        const notice = getUpdateNotice();
+        if (notice)
+            report._notice = notice;
+        printReport(report);
+    }
+    else {
+        emit({ resource: resourceName, id: taskId, status: null, timed_out: true }, { format: runtime.flags.format });
+    }
+    process.exitCode = 8;
+}
+function interruptedError(descriptor, taskId, last, submission, opts, opened, savedJson = null) {
+    let saved = savedJson;
+    if (!saved && opts.saveJson && last) {
+        try {
+            saved = saveRawJson(opts.saveJson, last.raw, { workspace: opened.flags.workspaceRoot });
+        }
+        catch {
+            saved = null;
+        }
+    }
+    return new CliError({
+        code: "interrupted",
+        message: `interrupted while waiting for task ${taskId}; the server keeps running it — resume with \`${nextCommands(descriptor, taskId).wait}\``,
+        recovery: { action: "wait", automatic: false, command: nextCommands(descriptor, taskId).wait },
+        result: taskResult({ task: last?.task ?? null, raw: last?.raw ?? null, descriptor, includeRaw: Boolean(opts.includeRaw), submission, savedJson: saved, extra: { task_id: taskId, next: nextCommands(descriptor, taskId) } }),
+    });
+}
+async function streamAndReport(opened, runtime, descriptor, endpoint, taskId, timeoutSeconds, idleSeconds, opts) {
+    const includeRaw = Boolean(opts.includeRaw);
+    const ndjson = opened.format === "ndjson";
+    let sequence = 0;
+    const submission = { state: "accepted", operation_id: null };
+    const warnings = [];
+    const outcome = await streamTask(endpoint, taskId, {
+        timeoutMs: timeoutSeconds * 1000,
+        idleTimeoutMs: idleSeconds * 1000,
+        signal: abortSignal(),
+        onUnknownEvent: (ev) => {
+            warnings.push(warning("unknown_sse_event", `ignored SSE event '${ev.event}'`));
+        },
+        onTask: async (task, raw) => {
+            if (opened.schema === "v1" && ndjson) {
+                sequence += 1;
+                const event = {
+                    ...okEnvelope(opened.command, taskResult({ task, raw, descriptor, includeRaw, submission })),
+                    event: "task",
+                    sequence,
+                };
+                await emitStreamEvent(event);
+            }
+            else if (opened.schema === "v1") {
+                process.stderr.write(`[${descriptor.id}] ${task.status}${typeof task.progress === "number" ? ` ${task.progress}%` : ""}\n`);
+            }
+        },
+    });
+    const streamInfo = { events: outcome.events, ended: outcome.reason, elapsed_seconds: Number((outcome.elapsedMs / 1000).toFixed(2)) };
+    const ctx = { descriptor, taskId, task: outcome.task, raw: outcome.raw, submission, includeRaw, extra: { stream: streamInfo, task_id: taskId } };
+    // Once the stream has started, every later step — saving JSON, recording the
+    // project, downloading — is part of the same terminal outcome: one `outcome`
+    // event (ndjson) or one envelope (json/pretty), never a bare error after it.
+    let savedJson = null;
+    let project = null;
+    let bookkeepingError = null;
+    try {
+        savedJson = opts.saveJson && outcome.raw ? saveJsonInContext(opts, opened, outcome.raw, ctx) : null;
+        project = outcome.task ? attachInContext(opts, opened, descriptor, taskId, outcome.task, outcome.raw, {}, warnings, { ...ctx, savedJson }) : null;
+    }
+    catch (err) {
+        bookkeepingError = err instanceof CliError ? err : withTaskContext(err, ctx);
+    }
+    const projectExtra = project ? { project } : {};
+    let finalError = null;
+    const resultWith = (downloads) => taskResult({ task: outcome.task, raw: outcome.raw, descriptor, includeRaw, submission, downloads, savedJson, extra: { stream: streamInfo, task_id: taskId, next: nextCommands(descriptor, taskId), ...projectExtra } });
+    let result = resultWith();
+    switch (outcome.reason) {
+        case "terminal":
+            if (outcome.task && outcome.task.status !== "SUCCEEDED") {
+                finalError = new CliError({
+                    code: "task_failed",
+                    message: outcome.task.task_error?.message ? `task ${taskId} ${outcome.task.status}: ${outcome.task.task_error.message}` : `task ${taskId} ended as ${outcome.task.status}`,
+                    result,
+                    warnings,
+                });
+            }
+            break;
+        case "timeout":
+            finalError = new CliError({ code: "timed_out", message: `stream deadline of ${timeoutSeconds}s reached (last status: ${outcome.task?.status ?? "none"}); the server keeps running the task`, recovery: { action: "wait", automatic: false, command: nextCommands(descriptor, taskId).wait }, result, warnings });
+            break;
+        case "idle_timeout":
+            finalError = new CliError({ code: "network", message: `no bytes received for ${idleSeconds}s on the stream (last status: ${outcome.task?.status ?? "none"})`, recovery: { action: "wait", automatic: false, command: nextCommands(descriptor, taskId).wait }, result, warnings });
+            break;
+        case "disconnected":
+            finalError = new CliError({ code: "network", message: outcome.error?.message ?? "stream disconnected before a terminal status", recovery: { action: "wait", automatic: false, command: nextCommands(descriptor, taskId).wait }, result, warnings });
+            break;
+        case "interrupted":
+            finalError = new CliError({ code: "interrupted", message: `interrupted while streaming task ${taskId}; the server keeps running it`, recovery: { action: "wait", automatic: false, command: nextCommands(descriptor, taskId).wait }, result, warnings });
+            break;
+        case "error":
+        case "protocol":
+            finalError = wrapStreamError(outcome.error, result, warnings);
+            break;
+    }
+    if (bookkeepingError) {
+        if (finalError) {
+            // The stream's own failure is the outcome; the bookkeeping failure rides along as a warning.
+            finalError.warnings.push(warning("bookkeeping_failed", bookkeepingError.message));
+        }
+        else {
+            finalError = bookkeepingError;
+        }
+    }
+    if (opened.schema !== "v1") {
+        // Legacy has no stream shape to preserve: reuse the terminal summary path (which honours -o itself).
+        if (finalError)
+            throw finalError;
+        if (outcome.task) {
+            try {
+                await emitLegacyOutcome(outcome.task, false, outcome.elapsedMs / 1000, descriptor.id, runtime, { query: false });
+            }
+            catch (err) {
+                throw withTaskContext(err, { ...ctx, savedJson, extra: { stream: streamInfo, ...projectExtra } });
+            }
+        }
+        return;
+    }
+    // The terminal outcome includes the requested download whatever the output
+    // format: `-o` means "put the assets on disk", not "only when printing JSON".
+    if (!finalError && outcome.task && outcome.task.status === "SUCCEEDED") {
+        try {
+            const downloads = await maybeDownloadV1(opened, descriptor, outcome.task, outcome.raw, submission, warnings, { savedJson, includeRaw, project });
+            result = resultWith(downloads);
+        }
+        catch (err) {
+            finalError = err instanceof CliError ? err : withTaskContext(err, ctx);
+        }
+    }
+    if (ndjson) {
+        sequence += 1;
+        const body = finalError ? errorEnvelope(opened.command, finalError).envelope : okEnvelope(opened.command, result, warnings);
+        const event = { ...body, event: "outcome", sequence };
+        await emitStreamEvent(event);
+        // The outcome line already carries the error; exit with its code without a second envelope.
+        if (finalError)
+            process.exitCode = finalError.exitCode;
+        return;
+    }
+    if (finalError)
+        throw finalError;
+    await emitEnvelope(okEnvelope(opened.command, result, warnings), opened.format);
+}
+function wrapStreamError(err, result, warnings) {
+    if (err instanceof CliError) {
+        return new CliError({ code: err.code, message: err.message, httpStatus: err.httpStatus, recovery: err.recovery, result, warnings: [...err.warnings, ...warnings], cause: err });
+    }
+    if (err instanceof MeshyApiError) {
+        const code = err.code === "server" ? "server" : err.code;
+        return new CliError({ code, message: err.message, httpStatus: err.status || null, result, warnings, cause: err });
+    }
+    return new CliError({ code: "protocol", message: "stream ended abnormally", result, warnings });
+}
+/**
+ * Legacy reporter. `query: true` is `get`: a valid task is a successful query
+ * whatever its status (0.2.0 exited 1 for PENDING/IN_PROGRESS — fixed); a
+ * terminal FAILED/CANCELED still exits 1 for compatibility.
+ */
+async function emitLegacyOutcome(task, timedOut, elapsedSeconds, resourceName, runtime, mode) {
     const output = runtime.flags.output;
     const succeeded = !timedOut && task.status === "SUCCEEDED";
     if (output) {
         if (succeeded) {
-            const { savedFiles, metadataPath } = await downloadArtifacts(task, output, resourceName);
+            const { savedFiles, metadataPath } = await downloadArtifacts(task, output, resourceName, { root: runtime.flags.workspaceRoot, signal: abortSignal() });
             const successReport = {
                 status: "SUCCESS",
                 taskId: task.id,
@@ -149,41 +1022,48 @@ export async function emitTerminalOutcome(task, timedOut, elapsedSeconds, resour
             if (successNotice)
                 successReport._notice = successNotice;
             printReport(successReport);
-        }
-        else {
-            const report = {
-                status: "FAIL",
-                taskId: task.id,
-                type: task.type || resourceName,
-            };
-            if (timedOut)
-                report.timedOut = true;
-            else if (task.task_error?.message)
-                report.error = task.task_error.message;
-            else if (task.status)
-                report.error = `task status: ${task.status}`;
-            const failNotice = getUpdateNotice();
-            if (failNotice)
-                report._notice = failNotice;
-            printReport(report);
-            process.exitCode = timedOut ? 8 : 1;
-        }
-        if (succeeded)
             return;
-    }
-    else {
-        // No -o: keep the JSON/pretty summary for machine consumption.
-        emit({
-            resource: resourceName,
-            ...summarizeTask(task, elapsedSeconds),
-            ...(timedOut ? { timed_out: true } : {}),
-        }, { format: runtime.flags.format });
-    }
-    if (!output) {
+        }
+        const report = {
+            status: "FAIL",
+            taskId: task.id,
+            type: task.type || resourceName,
+        };
+        if (timedOut)
+            report.timedOut = true;
+        else if (task.task_error?.message)
+            report.error = task.task_error.message;
+        else if (task.status)
+            report.error = `task status: ${task.status}`;
+        const failNotice = getUpdateNotice();
+        if (failNotice)
+            report._notice = failNotice;
+        printReport(report);
         if (timedOut)
             process.exitCode = 8;
-        else if (!TERMINAL_STATUSES.has(task.status) || task.status !== "SUCCEEDED")
+        else if (mode.query && !isTerminalStatus(task.status))
+            process.exitCode = 0;
+        else
             process.exitCode = 1;
+        return;
     }
+    emit({
+        resource: resourceName,
+        ...summarizeTask(task, elapsedSeconds),
+        ...(timedOut ? { timed_out: true } : {}),
+    }, { format: runtime.flags.format });
+    if (timedOut)
+        process.exitCode = 8;
+    else if (task.status === "SUCCEEDED")
+        process.exitCode = 0;
+    else if (!isTerminalStatus(task.status))
+        process.exitCode = mode.query ? 0 : 1;
+    else
+        process.exitCode = 1;
+}
+/** Kept for make.ts (legacy path). */
+export async function emitTerminalOutcome(task, timedOut, elapsedSeconds, resourceName, runtime) {
+    await emitLegacyOutcome(task, timedOut, elapsedSeconds, resourceName, runtime, { query: false });
 }
+export { taskResult as buildTaskResult, nextCommands as taskNextCommands };
 //# sourceMappingURL=task-command.js.map