@remixmate/cli 0.9.35 → 0.9.36

package/dist/diagnostics.d.ts

@@ -1,4 +1,24 @@
 export declare function traceHeaders(): Record<string, string>;
-export declare function cleanDiagnosticText(value: string): string;
+/**
+ * Redact a string for anything that leaves this process (diagnostic lines,
+ * execution traces).
+ *
+ * Kept in lockstep with ab-agent's `lib/telemetry.cleanText` — the two feed the
+ * same `media_chat_turn_trace` table, and a table whose rows were sanitized by
+ * two different rulesets is a table nobody can reason about. ANSI stripping,
+ * e-mail and phone redaction were added here to close that gap.
+ *
+ * `max` caps the result in BYTES, keeping the head. Callers that need the tail
+ * (a command's decisive line is its last one) slice before calling.
+ */
+export declare function cleanDiagnosticText(value: string, max?: number): string;
+/**
+ * Exit code → the outcome vocabulary of the logging contract.
+ *
+ * Exported because the execution trace (project/trace.ts) reports the same
+ * verdict for the same run: two mappings would let a run be `failure` in the
+ * diagnostic line and `success` in the database.
+ */
+export declare function outcomeOf(exitCode: number): 'success' | 'cancelled' | 'rejected' | 'failure';
 /** Opt-in line framing for hosts; stdout is exclusively the existing skill protocol. */
 export declare function diagnostic(exitCode: number, durationMs: number, error?: unknown): void;

package/dist/diagnostics.js

@@ -8,8 +8,22 @@ export function traceHeaders() {
     process.env.AB_OPERATION_ID ||= randomUUID();
     return { traceparent: header };
 }
-export function cleanDiagnosticText(value) {
-    let text = value.replace(/https?:\/\/[^\s"'<>]+/g, raw => {
+/**
+ * Redact a string for anything that leaves this process (diagnostic lines,
+ * execution traces).
+ *
+ * Kept in lockstep with ab-agent's `lib/telemetry.cleanText` — the two feed the
+ * same `media_chat_turn_trace` table, and a table whose rows were sanitized by
+ * two different rulesets is a table nobody can reason about. ANSI stripping,
+ * e-mail and phone redaction were added here to close that gap.
+ *
+ * `max` caps the result in BYTES, keeping the head. Callers that need the tail
+ * (a command's decisive line is its last one) slice before calling.
+ */
+export function cleanDiagnosticText(value, max = 2048) {
+    let text = value
+        .replace(/\x1b\[[0-9;]*m/g, '')
+        .replace(/https?:\/\/[^\s"'<>]+/g, raw => {
         try {
             const url = new URL(raw);
             return url.origin + url.pathname;
@@ -17,19 +31,36 @@ export function cleanDiagnosticText(value) {
         catch {
             return '[url]';
         }
-    }).replace(/(Bearer\s+|(?:token|secret|password|api[_-]?key)\s*[=:]\s*)[^\s,;}]+/gi, '$1[redacted]');
+    })
+        .replace(/(Bearer\s+|(?:token|secret|password|api[_-]?key)\s*[=:]\s*)[^\s,;}]+/gi, '$1[redacted]')
+        .replace(/[A-Z0-9._%+-]+@[A-Z0-9.-]+\.[A-Z]{2,}/gi, '[email]')
+        .replace(/\b1[3-9]\d{9}\b/g, '[phone]');
     for (const [key, secret] of Object.entries(process.env)) {
         if (/TOKEN|SECRET|PASSWORD|API_KEY/i.test(key) && secret && secret.length >= 6)
             text = text.split(secret).join('[redacted]');
     }
-    return Buffer.from(text).subarray(0, 2048).toString('utf8');
+    return Buffer.from(text).subarray(0, max).toString('utf8');
+}
+/**
+ * Exit code → the outcome vocabulary of the logging contract.
+ *
+ * Exported because the execution trace (project/trace.ts) reports the same
+ * verdict for the same run: two mappings would let a run be `failure` in the
+ * diagnostic line and `success` in the database.
+ */
+export function outcomeOf(exitCode) {
+    if (exitCode === 0)
+        return 'success';
+    if (exitCode === 130)
+        return 'cancelled';
+    return [2, 3, 4].includes(exitCode) ? 'rejected' : 'failure';
 }
 /** Opt-in line framing for hosts; stdout is exclusively the existing skill protocol. */
 export function diagnostic(exitCode, durationMs, error) {
     if (process.env.AB_DIAGNOSTICS !== '1')
         return;
     traceHeaders();
-    const outcome = exitCode === 0 ? 'success' : exitCode === 130 ? 'cancelled' : [2, 3, 4].includes(exitCode) ? 'rejected' : 'failure';
+    const outcome = outcomeOf(exitCode);
     const record = { schema_version: 1, timestamp: new Date().toISOString(), service: 'remixmate-cli', environment: process.env.APP_ENV ?? 'dev',
         level: outcome === 'failure' ? 'error' : 'info', event: 'cli.execution.completed', message: 'CLI execution completed', outcome,
         trace_id: process.env.AB_TRACEPARENT?.split('-')[1], operation_id: process.env.AB_OPERATION_ID,

package/dist/install.d.ts

@@ -37,6 +37,7 @@ export declare function detectHosts(): Host[];
  * 完全看不到它，只会以为这个 CLI 不支持 —— 正是这次 WorkBuddy 的翻车方式。
  */
 export declare function projectOnlyHosts(): HostId[];
+export declare function packageVersion(): string;
 export declare function installUsage(): void;
 export declare function uninstallUsage(): void;
 export declare function runInstall(argv: string[]): number;

package/dist/install.js

@@ -147,7 +147,7 @@ export function detectHosts() {
 export function projectOnlyHosts() {
     return HOST_IDS.filter((id) => isInstalled(id) && !spec(id).userDirName);
 }
-function packageVersion() {
+export function packageVersion() {
     try {
         const raw = readFileSync(path.join(PKG_ROOT, 'package.json'), 'utf-8');
         return JSON.parse(raw).version ?? 'unknown';

package/dist/manifest.json

@@ -1,7 +1,7 @@
 {
   "schemaVersion": 1,
-  "version": "0.9.35",
-  "generatedAt": "2026-09-18T05:50:52.540Z",
+  "version": "0.9.36",
+  "generatedAt": "2026-09-20T05:40:23.517Z",
   "skills": [
     {
       "id": "export-jianying",

package/dist/project/take.d.ts

@@ -23,6 +23,10 @@ export interface EnsuredTake {
     projectId: string;
     created: boolean;
     attempt: number;
+    /** The grouping key this take was resolved under — reused as the trace's session id. */
+    sessionKey: string;
+    /** Provenance label of the host we're running inside ('' when unknown). */
+    host: string;
 }
 /**
  * Look up the take for the current grouping key without creating anything.

package/dist/project/take.js

@@ -62,6 +62,8 @@ export async function findTake(ctx) {
         projectId: res.projectId ?? '',
         created: false,
         attempt: res.attempt ?? 0,
+        sessionKey: takeKey.key,
+        host: takeKey.host,
     };
 }
 /**
@@ -98,5 +100,7 @@ export async function ensureTake(ctx, opts) {
         projectId,
         created: res.created,
         attempt: res.attempt,
+        sessionKey: takeKey.key,
+        host: takeKey.host,
     };
 }

package/dist/project/trace.d.ts

@@ -0,0 +1,98 @@
+/**
+ * Execution-trace self-reporting — tell the backend what this invocation
+ * actually did, so a locally-run pipeline is not a blind spot.
+ *
+ * Why this exists: the cloud agent records every tool call, its arguments AND
+ * its result into `media_chat_turn_trace` (ab-agent/src/trace-persist.ts). The
+ * local path records nothing — a take created from codex / claude code has an
+ * empty conversation, zero tool calls and zero credits in the analytics tables,
+ * so every session-level metric silently excludes it.
+ *
+ * What we can honestly report and what we cannot: the CLI is a child process
+ * spawned once per skill call. It never sees the user's prompt or the host's
+ * reply — those live in the host's own transcript. So this module reports the
+ * one thing it genuinely observes: the invocation itself.
+ *
+ * See docs/cli-session-record-design.md §5.
+ */
+import { type HttpContext } from '../http.js';
+import type { ParsedArgs } from '../argv.js';
+import type { EnsuredTake } from './take.js';
+export interface TraceOptions {
+    skillName: string;
+    args: ParsedArgs;
+    take: EnsuredTake;
+    ctx: HttpContext;
+}
+/**
+ * Whether this invocation should report at all.
+ *
+ * The rule is deliberately narrow: report only when THIS process resolved the
+ * take. Everything else is already covered by someone else —
+ *   - under the cloud agent, CONVERSATION_ID arrives pre-set and ab-agent's own
+ *     TurnTracer already recorded the very same call;
+ *   - a nested `gen-image` spawned by prepare-video-assets inherits its
+ *     parent's CONVERSATION_ID, and the parent's row already covers it.
+ * Since runner.ts only builds a tracer after resolving a take itself, this
+ * function just honours the kill switch.
+ */
+export declare function tracingEnabled(env?: NodeJS.ProcessEnv): boolean;
+/**
+ * Collects one invocation's evidence and posts it as a single turn.
+ *
+ * Lifecycle (runner.ts): `begin()` → output flows through the tap → `finish()`
+ * in a finally block. Every failure mode ends in a warning on stderr: a lost
+ * trace row must never cost the user a render they already paid for.
+ */
+export declare class InvocationTrace {
+    private readonly opts;
+    private chunks;
+    private restore;
+    private flushed;
+    private constructor();
+    /** Returns null when tracing is off — callers can then skip output capture entirely. */
+    static begin(opts: TraceOptions): InvocationTrace | null;
+    /**
+     * Tap both output streams.
+     *
+     * One tap covers both dispatch paths: in-process handlers write here
+     * directly, and the Python child's piped output is re-emitted through the
+     * same `write` (see runner.ts). Restored in finish().
+     */
+    installCapture(): void;
+    /** Feed captured output. Keeps a bounded tail — the decisive line is the last one. */
+    absorb(chunk: unknown): void;
+    /**
+     * Emit the turn. Idempotent; never throws.
+     *
+     * `error` is the dispatcher's caught exception when there is one — a Python
+     * child that exits non-zero gives us no exception, only its output, which is
+     * exactly why the tail buffer exists.
+     */
+    finish(exitCode: number, durationMs: number, error?: unknown): Promise<void>;
+}
+/**
+ * Flags → a trace-safe object.
+ *
+ * Credentials are dropped outright; long strings are cut to their opening
+ * because an argument like `--prompt` is *content*, and this table is evidence,
+ * not an archive of what the user wrote.
+ */
+export declare function sanitiseArgs(args: ParsedArgs): Record<string, unknown>;
+/**
+ * Captured output → the tail we store.
+ *
+ * Two transformations before truncating, both about spending the 16KB on
+ * things a human would read:
+ *   - progress lines are the machine protocol — one fat JSON object per phase,
+ *     marked by a `__progress__` field (progress.ts, and the same shape from the
+ *     Python skills). Their payload is noise here, but WHICH PHASE a failed run
+ *     reached is the single most useful fact about it, so the line collapses to
+ *     its phase name instead of being dropped.
+ *   - `__diagnostic_v1__` lines are our own structured log of this very run;
+ *     keeping them would store the same verdict twice.
+ *
+ * Then keeps the TAIL, unlike ab-agent's head-first cleanText: a command's
+ * verdict — the error, or the URL it produced — is its last line.
+ */
+export declare function condense(raw: string): string;

package/dist/project/trace.js

@@ -0,0 +1,278 @@
+/**
+ * Execution-trace self-reporting — tell the backend what this invocation
+ * actually did, so a locally-run pipeline is not a blind spot.
+ *
+ * Why this exists: the cloud agent records every tool call, its arguments AND
+ * its result into `media_chat_turn_trace` (ab-agent/src/trace-persist.ts). The
+ * local path records nothing — a take created from codex / claude code has an
+ * empty conversation, zero tool calls and zero credits in the analytics tables,
+ * so every session-level metric silently excludes it.
+ *
+ * What we can honestly report and what we cannot: the CLI is a child process
+ * spawned once per skill call. It never sees the user's prompt or the host's
+ * reply — those live in the host's own transcript. So this module reports the
+ * one thing it genuinely observes: the invocation itself.
+ *
+ * See docs/cli-session-record-design.md §5.
+ */
+import os from 'node:os';
+import { cleanDiagnosticText, outcomeOf } from '../diagnostics.js';
+import { billingSummary } from '../billing.js';
+import { packageVersion } from '../install.js';
+import { mmPost } from '../http.js';
+/** Same ceiling ab-agent uses for a tool result — one table, one limit. */
+const TOOL_RESULT_MAX = 16 * 1024;
+/** Raw bytes held before trimming. Generous: trimming is the tail, cleaning is cheap. */
+const RAW_CAPTURE_MAX = 64 * 1024;
+/** Per-argument ceiling. Prompts and narration bodies are content, not evidence. */
+const ARG_VALUE_MAX = 512;
+/** `error_summary` is varchar(1024). */
+const ERROR_SUMMARY_MAX = 1024;
+const FLUSH_TIMEOUT_MS = 10_000;
+const SENSITIVE_KEY = /token|secret|password|api[_-]?key|authorization/i;
+/**
+ * Whether this invocation should report at all.
+ *
+ * The rule is deliberately narrow: report only when THIS process resolved the
+ * take. Everything else is already covered by someone else —
+ *   - under the cloud agent, CONVERSATION_ID arrives pre-set and ab-agent's own
+ *     TurnTracer already recorded the very same call;
+ *   - a nested `gen-image` spawned by prepare-video-assets inherits its
+ *     parent's CONVERSATION_ID, and the parent's row already covers it.
+ * Since runner.ts only builds a tracer after resolving a take itself, this
+ * function just honours the kill switch.
+ */
+export function tracingEnabled(env = process.env) {
+    return (env.REMIXMATE_TRACE ?? '').trim() !== '0';
+}
+/**
+ * Collects one invocation's evidence and posts it as a single turn.
+ *
+ * Lifecycle (runner.ts): `begin()` → output flows through the tap → `finish()`
+ * in a finally block. Every failure mode ends in a warning on stderr: a lost
+ * trace row must never cost the user a render they already paid for.
+ */
+export class InvocationTrace {
+    opts;
+    chunks = '';
+    restore = null;
+    flushed = false;
+    constructor(opts) {
+        this.opts = opts;
+    }
+    /** Returns null when tracing is off — callers can then skip output capture entirely. */
+    static begin(opts) {
+        if (!tracingEnabled())
+            return null;
+        if (!opts.take.conversationId)
+            return null;
+        return new InvocationTrace(opts);
+    }
+    /**
+     * Tap both output streams.
+     *
+     * One tap covers both dispatch paths: in-process handlers write here
+     * directly, and the Python child's piped output is re-emitted through the
+     * same `write` (see runner.ts). Restored in finish().
+     */
+    installCapture() {
+        if (this.restore)
+            return;
+        const out = process.stdout.write.bind(process.stdout);
+        const err = process.stderr.write.bind(process.stderr);
+        const tap = (original) => ((chunk, ...rest) => {
+            this.absorb(chunk);
+            return original(chunk, ...rest);
+        });
+        process.stdout.write = tap(out);
+        process.stderr.write = tap(err);
+        this.restore = () => {
+            process.stdout.write = out;
+            process.stderr.write = err;
+        };
+    }
+    /** Feed captured output. Keeps a bounded tail — the decisive line is the last one. */
+    absorb(chunk) {
+        try {
+            const text = typeof chunk === 'string'
+                ? chunk
+                : chunk instanceof Uint8Array
+                    ? Buffer.from(chunk).toString('utf8')
+                    : '';
+            if (!text)
+                return;
+            this.chunks += text;
+            if (this.chunks.length > RAW_CAPTURE_MAX * 2) {
+                this.chunks = this.chunks.slice(-RAW_CAPTURE_MAX);
+            }
+        }
+        catch {
+            // Capturing must never break the thing being captured.
+        }
+    }
+    /**
+     * Emit the turn. Idempotent; never throws.
+     *
+     * `error` is the dispatcher's caught exception when there is one — a Python
+     * child that exits non-zero gives us no exception, only its output, which is
+     * exactly why the tail buffer exists.
+     */
+    async finish(exitCode, durationMs, error) {
+        this.restore?.();
+        this.restore = null;
+        if (this.flushed)
+            return;
+        this.flushed = true;
+        const { skillName, args, take, ctx } = this.opts;
+        const output = condense(this.chunks);
+        const outcome = outcomeOf(exitCode);
+        const isError = exitCode !== 0;
+        const rows = [];
+        let stepSeq = 0;
+        // One env row per take, not per call: it describes the toolchain, and the
+        // toolchain does not change between two calls of the same pipeline.
+        if (take.created) {
+            rows.push({ sessionId: take.sessionKey, stepSeq: stepSeq++, kind: 'env', env: envSnapshot(take) });
+        }
+        rows.push({
+            sessionId: take.sessionKey,
+            stepSeq: stepSeq++,
+            kind: 'tool_call',
+            toolName: `cli__${skillName.replace(/-/g, '_')}`,
+            toolUseId: (process.env.AB_OPERATION_ID ?? '').slice(0, 64),
+            toolInput: sanitiseArgs(args),
+            toolResult: output || '[no output captured]',
+            isError,
+            durationMs: Math.round(durationMs),
+        });
+        rows.push({
+            sessionId: take.sessionKey,
+            stepSeq: stepSeq++,
+            kind: 'turn_result',
+            outcome,
+            errorSummary: isError ? summariseError(error, output) : '',
+            credits: billingSummary()?.credits ?? 0,
+        });
+        try {
+            await mmPost(ctx, `/chat/conversation/${encodeURIComponent(take.conversationId)}/trace`, 
+            // appendTurn: the server allocates turn_seq. N unrelated processes
+            // cannot number themselves, and cli-project-binding §5.1 already ruled
+            // out keeping local state. Older backends ignore the field and every
+            // row lands on turn 0 — still ordered, just ungrouped.
+            { appendTurn: true, traces: rows }, { timeoutMs: FLUSH_TIMEOUT_MS });
+        }
+        catch (err) {
+            process.stderr.write(`⚠️  执行轨迹未能上报（不影响本次产物）: ${cleanDiagnosticText(err.message, 256)}\n`);
+        }
+    }
+}
+/** Which rung of the grouping ladder produced this key (cli-project-binding §5.1). */
+function keySource(key) {
+    if (key.startsWith('custom:'))
+        return 'env-override';
+    if (key.startsWith('job:'))
+        return 'render-job';
+    return 'host';
+}
+/**
+ * What this take was produced by. Mirrors ab-agent's envSnapshot() in purpose:
+ * answer "which version started failing" without storing anything large.
+ */
+function envSnapshot(take) {
+    return {
+        // The discriminator every cross-channel metric needs — a CLI "turn" is one
+        // skill call, a cloud turn is a whole user request. Never compare blindly.
+        channel: 'cli',
+        cli_version: packageVersion(),
+        host: take.host || 'unknown',
+        take_key_source: keySource(take.sessionKey),
+        node: process.version,
+        platform: `${os.platform()}-${os.arch()}`,
+    };
+}
+/**
+ * Flags → a trace-safe object.
+ *
+ * Credentials are dropped outright; long strings are cut to their opening
+ * because an argument like `--prompt` is *content*, and this table is evidence,
+ * not an archive of what the user wrote.
+ */
+export function sanitiseArgs(args) {
+    const out = {};
+    for (const [key, value] of Object.entries(args).slice(0, 40)) {
+        if (SENSITIVE_KEY.test(key)) {
+            out[key] = '[redacted]';
+            continue;
+        }
+        if (typeof value === 'boolean') {
+            out[key] = value;
+            continue;
+        }
+        if (Array.isArray(value)) {
+            out[key] = value.slice(0, 20).map((v) => cleanDiagnosticText(String(v), ARG_VALUE_MAX));
+            continue;
+        }
+        out[key] = cleanDiagnosticText(String(value), ARG_VALUE_MAX);
+    }
+    return out;
+}
+/**
+ * Captured output → the tail we store.
+ *
+ * Two transformations before truncating, both about spending the 16KB on
+ * things a human would read:
+ *   - progress lines are the machine protocol — one fat JSON object per phase,
+ *     marked by a `__progress__` field (progress.ts, and the same shape from the
+ *     Python skills). Their payload is noise here, but WHICH PHASE a failed run
+ *     reached is the single most useful fact about it, so the line collapses to
+ *     its phase name instead of being dropped.
+ *   - `__diagnostic_v1__` lines are our own structured log of this very run;
+ *     keeping them would store the same verdict twice.
+ *
+ * Then keeps the TAIL, unlike ab-agent's head-first cleanText: a command's
+ * verdict — the error, or the URL it produced — is its last line.
+ */
+export function condense(raw) {
+    if (!raw)
+        return '';
+    const compacted = raw
+        .split('\n')
+        .map((line) => {
+        const trimmed = line.trim();
+        if (trimmed.startsWith('__diagnostic_v1__'))
+            return null;
+        if (!trimmed.startsWith('{') || !trimmed.includes('"__progress__"'))
+            return line;
+        try {
+            const phase = JSON.parse(trimmed).phase;
+            return typeof phase === 'string' ? `· phase=${phase}` : '· progress';
+        }
+        catch {
+            return '· progress';
+        }
+    })
+        .filter((line) => line !== null)
+        .join('\n')
+        .trim();
+    // Slice the tail before cleaning: cleanDiagnosticText truncates head-first.
+    const tail = compacted.length > TOOL_RESULT_MAX ? compacted.slice(-TOOL_RESULT_MAX) : compacted;
+    return cleanDiagnosticText(tail, TOOL_RESULT_MAX);
+}
+/**
+ * The one-line verdict.
+ *
+ * A thrown SkillError carries it directly. A Python child does not throw — it
+ * just exits non-zero, so fall back to the last line it printed, which is where
+ * argparse errors, tracebacks and our own ❌ messages end up.
+ */
+function summariseError(error, output) {
+    if (error instanceof Error && error.message) {
+        return cleanDiagnosticText(error.message, ERROR_SUMMARY_MAX);
+    }
+    const lastLine = output
+        .split('\n')
+        .map((l) => l.trim())
+        .filter((l) => l && !l.startsWith('· phase='))
+        .pop();
+    return lastLine ? cleanDiagnosticText(lastLine, ERROR_SUMMARY_MAX) : '';
+}

package/dist/runner.js

@@ -19,6 +19,7 @@ import { authChildEnv, ensureAuth } from './auth/ensure.js';
 import { emitBillingFooter } from './billing.js';
 import { resolveHttpContext } from './http.js';
 import { ensureTake, findTake } from './project/take.js';
+import { InvocationTrace } from './project/trace.js';
 /** Read the token override accepted by both the TS handlers and the Python skills. */
 function tokenFlag(args) {
     const value = args.token ?? args.priv_token;
@@ -28,6 +29,7 @@ export async function runSkill(skillName, opts) {
     const started = performance.now();
     let exitCode = EXIT.ERROR;
     let failure;
+    let trace = null;
     traceHeaders();
     const skill = findSkill(skillName, opts.baseDir ?? SKILLS_DIR);
     if (!skill) {
@@ -41,25 +43,43 @@ export async function runSkill(skillName, opts) {
             apiBaseUrl: typeof opts.parsedArgs.api_base_url === 'string' ? opts.parsedArgs.api_base_url : undefined,
             flagToken: tokenFlag(opts.parsedArgs),
         });
-        await applyTakeContext(skill, opts, auth);
+        const attached = await applyTakeContext(skill, opts, auth);
+        if (attached) {
+            // Only a take THIS process resolved gets reported — see trace.ts for why
+            // the cloud path and nested pipeline children must stay silent.
+            trace = InvocationTrace.begin({
+                skillName: skill.name,
+                args: opts.parsedArgs,
+                take: attached.take,
+                ctx: attached.ctx,
+            });
+            trace?.installCapture();
+        }
         switch (skill.entry.type) {
             case 'python':
                 // Python children talk to ab-api themselves and print their own billing
                 // footer; nothing was charged through this process.
-                return exitCode = await runPython(skill, opts.rawArgs, auth);
+                exitCode = await runPython(skill, opts.rawArgs, auth, trace);
+                break;
             case 'http':
             case 'builtin':
-                return exitCode = await runHandler(skill, opts.parsedArgs, auth);
+                exitCode = await runHandler(skill, opts.parsedArgs, auth);
+                break;
         }
     }
     catch (err) {
         failure = err;
         if (err instanceof SkillError) {
             process.stderr.write(cleanDiagnosticText(err.message) + '\n');
-            return exitCode = err.exitCode;
+            exitCode = err.exitCode;
         }
-        process.stderr.write(`❌ unexpected error: ${cleanDiagnosticText(err.stack ?? err.message)}\n`);
-        return EXIT.ERROR;
+        else {
+            process.stderr.write(`❌ unexpected error: ${cleanDiagnosticText(err.stack ?? err.message)}\n`);
+            exitCode = EXIT.ERROR;
+        }
+        // Single exit point below: the trace flush in `finally` must run before the
+        // value leaves, and an `await` there defeats TS's reachability analysis on
+        // returns made from inside the try/catch.
     }
     finally {
         // In `finally` because a run can fail *after* a billed step (e.g. the image
@@ -67,7 +87,12 @@ export async function runSkill(skillName, opts) {
         // reported either way. No-ops when nothing was charged.
         diagnostic(exitCode, performance.now() - started, failure);
         emitBillingFooter();
+        // Last, so the billing footer is still inside the captured tail. Never
+        // throws and never changes the exit code — a lost trace row must not cost
+        // the user a render they already paid for.
+        await trace?.finish(exitCode, performance.now() - started, failure);
     }
+    return exitCode;
 }
 /**
  * Decide the take mode from the skill's declaration *and* what this particular
@@ -118,11 +143,11 @@ export function resolveTakeMode(skill, args) {
 async function applyTakeContext(skill, opts, auth) {
     const mode = resolveTakeMode(skill, opts.parsedArgs);
     if (mode === 'none')
-        return;
+        return null;
     if ((process.env.CONVERSATION_ID ?? '').trim())
-        return;
+        return null;
     if (!auth.token)
-        return;
+        return null;
     try {
         const ctx = await resolveHttpContext(skill.name, {
             apiBaseUrl: auth.apiBaseUrl,
@@ -142,16 +167,32 @@ async function applyTakeContext(skill, opts, auth) {
             take = await findTake(ctx);
         }
         if (!take)
-            return;
+            return null;
         process.env.CONVERSATION_ID = take.conversationId;
         process.stdout.write(`📁 take ${take.created ? 'created' : 'reused'}: ${take.videoProjectId} ` +
             `(project ${take.projectId}${take.attempt ? `, attempt ${take.attempt}` : ''})\n`);
+        return { take, ctx };
     }
     catch (err) {
         process.stderr.write(`⚠️  无法归属本次产物（内容仍会正常生成，但不会出现在项目里）: ${cleanDiagnosticText(err.message)}\n`);
+        return null;
     }
 }
-async function runPython(skill, rawArgs, auth) {
+/**
+ * Spawn the Python skill.
+ *
+ * `stdio: 'inherit'` is the default and stays the default: the child writes
+ * straight to the terminal, which is exactly what a CLI should do. It does mean
+ * the parent sees nothing, so a failed render can only ever be reported as
+ * "exit code 1" — for the most valuable step in the pipeline.
+ *
+ * So when (and only when) we are tracing, stdout/stderr are piped and re-emitted
+ * verbatim, which routes them through the capture tap. stdin stays inherited so
+ * interactive prompts still work. Resolving on `close` rather than `exit` in
+ * that mode matters: `exit` can fire while the last chunk is still in the pipe,
+ * which is precisely the chunk holding the error message.
+ */
+async function runPython(skill, rawArgs, auth, trace) {
     if (!skill.scriptAbsolutePath) {
         throw new SkillError(`skill ${skill.name} has entry.type=python but no scriptAbsolutePath`);
     }
@@ -159,10 +200,14 @@ async function runPython(skill, rawArgs, auth) {
     return await new Promise((resolve) => {
         const proc = spawn('python3', [skill.scriptAbsolutePath, ...rawArgs], {
             cwd,
-            stdio: 'inherit',
+            stdio: trace ? ['inherit', 'pipe', 'pipe'] : 'inherit',
             env: { ...process.env, ...authChildEnv(auth), PYTHONUNBUFFERED: '1' },
         });
-        proc.on('exit', (code) => resolve(code ?? EXIT.ERROR));
+        if (trace) {
+            proc.stdout?.on('data', (chunk) => process.stdout.write(chunk));
+            proc.stderr?.on('data', (chunk) => process.stderr.write(chunk));
+        }
+        proc.on(trace ? 'close' : 'exit', (code) => resolve(code ?? EXIT.ERROR));
         proc.on('error', (err) => {
             process.stderr.write(`❌ failed to spawn python3: ${err.message}\n`);
             resolve(EXIT.SPAWN_FAILED);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@remixmate/cli",
-  "version": "0.9.35",
+  "version": "0.9.36",
   "description": "AI media generation skills for Claude Code / Codex — 12 skills covering image, video, voice, digital human, web screenshot, web recording, script, template registry, rendering, Jianying export, and video deconstruction.",
   "type": "module",
   "main": "dist/index.js",