@playdrop/playdrop-cli 0.12.1 → 0.12.3

package/config/client-meta.json

@@ -1,5 +1,5 @@
 {
-  "version": "0.12.1",
+  "version": "0.12.2",
   "build": 1,
   "runtimeSdkVersion": "0.10.0",
   "clients": {

package/dist/clientInfo.js

@@ -36,17 +36,6 @@ function readCliPackageVersion() {
     if (cachedCliPackageVersion) {
         return cachedCliPackageVersion;
     }
-    const candidateMetaPaths = [
-        path_1.default.resolve(__dirname, '..', 'config', 'client-meta.json'),
-        path_1.default.resolve(__dirname, '..', '..', '..', 'config', 'client-meta.json'),
-    ];
-    for (const candidatePath of candidateMetaPaths) {
-        const clientMetaVersion = readVersionFromJson(candidatePath, 'version');
-        if (clientMetaVersion) {
-            cachedCliPackageVersion = clientMetaVersion;
-            return clientMetaVersion;
-        }
-    }
     const packageJsonPath = path_1.default.resolve(__dirname, '..', 'package.json');
     const version = readVersionFromJson(packageJsonPath, 'version');
     if (!version) {

package/dist/commands/login.d.ts

@@ -1,3 +1,4 @@
+import type { Readable } from 'stream';
 import { resetOpenBrowserForTests, setOpenBrowserForTests } from '../browser';
 export { resetOpenBrowserForTests, setOpenBrowserForTests, };
 type LoginOptions = {
@@ -5,6 +6,17 @@ type LoginOptions = {
     password?: string;
     key?: string;
     handoffToken?: string;
+    handoffTokenStdin?: boolean;
     json?: boolean;
 };
-export declare function login(env: string, options?: LoginOptions): Promise<void>;
+type LoginRuntime = {
+    stdin?: Readable;
+};
+export declare const HANDOFF_TOKEN_STDIN_MAX_BYTES: number;
+type HandoffTokenStdinErrorCode = 'empty' | 'too_large' | 'read_failed';
+export declare class HandoffTokenStdinError extends Error {
+    readonly code: HandoffTokenStdinErrorCode;
+    constructor(code: HandoffTokenStdinErrorCode);
+}
+export declare function readHandoffTokenFromStdin(input?: Readable): Promise<string>;
+export declare function login(env: string, options?: LoginOptions, runtime?: LoginRuntime): Promise<void>;

package/dist/commands/login.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.setOpenBrowserForTests = exports.resetOpenBrowserForTests = void 0;
+exports.HandoffTokenStdinError = exports.HANDOFF_TOKEN_STDIN_MAX_BYTES = exports.setOpenBrowserForTests = exports.resetOpenBrowserForTests = void 0;
+exports.readHandoffTokenFromStdin = readHandoffTokenFromStdin;
 exports.login = login;
 const types_1 = require("@playdrop/types");
 const config_1 = require("../config");
@@ -12,6 +13,40 @@ Object.defineProperty(exports, "resetOpenBrowserForTests", { enumerable: true, g
 Object.defineProperty(exports, "setOpenBrowserForTests", { enumerable: true, get: function () { return browser_1.setOpenBrowserForTests; } });
 const output_1 = require("../output");
 const messages_1 = require("../messages");
+exports.HANDOFF_TOKEN_STDIN_MAX_BYTES = 8 * 1024;
+class HandoffTokenStdinError extends Error {
+    constructor(code) {
+        super(`handoff_token_stdin_${code}`);
+        this.name = 'HandoffTokenStdinError';
+        this.code = code;
+    }
+}
+exports.HandoffTokenStdinError = HandoffTokenStdinError;
+async function readHandoffTokenFromStdin(input = process.stdin) {
+    const chunks = [];
+    let byteCount = 0;
+    try {
+        for await (const chunk of input) {
+            const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(String(chunk));
+            byteCount += buffer.byteLength;
+            if (byteCount > exports.HANDOFF_TOKEN_STDIN_MAX_BYTES) {
+                throw new HandoffTokenStdinError('too_large');
+            }
+            chunks.push(buffer);
+        }
+    }
+    catch (error) {
+        if (error instanceof HandoffTokenStdinError) {
+            throw error;
+        }
+        throw new HandoffTokenStdinError('read_failed');
+    }
+    const token = Buffer.concat(chunks, byteCount).toString('utf8').trim();
+    if (!token) {
+        throw new HandoffTokenStdinError('empty');
+    }
+    return token;
+}
 function sleep(ms) {
     return new Promise((resolve) => setTimeout(resolve, ms));
 }
@@ -193,7 +228,7 @@ async function loginInBrowser(env, baseUrl, options = {}) {
     ], { command: 'login' });
     process.exitCode = 1;
 }
-async function login(env, options = {}) {
+async function login(env, options = {}, runtime = {}) {
     const envConfig = (0, environment_1.resolveEnvironmentConfig)(env);
     if (!envConfig) {
         const choices = (0, environment_1.formatEnvironmentList)();
@@ -207,12 +242,16 @@ async function login(env, options = {}) {
     const username = options.username?.trim();
     const password = options.password;
     const apiKey = options.key?.trim();
-    const handoffToken = options.handoffToken?.trim();
+    const argvHandoffToken = options.handoffToken?.trim();
+    const hasApiKeyArgument = options.key !== undefined;
+    const hasHandoffTokenArgument = options.handoffToken !== undefined;
+    const readsHandoffTokenFromStdin = options.handoffTokenStdin === true;
     const hasDirectCredentials = Boolean(username || password);
     const explicitLoginMethods = [
-        apiKey ? 'key' : null,
+        hasApiKeyArgument ? 'key' : null,
         hasDirectCredentials ? 'credentials' : null,
-        handoffToken ? 'handoff' : null,
+        hasHandoffTokenArgument ? 'handoff' : null,
+        readsHandoffTokenFromStdin ? 'handoff-stdin' : null,
     ].filter(Boolean);
     if (explicitLoginMethods.length > 1) {
         (0, messages_1.printErrorWithHelp)('Choose exactly one login method.', [
@@ -220,6 +259,7 @@ async function login(env, options = {}) {
             'Use "--username" with "--password" for direct login.',
             'Use "--key" by itself for API key login.',
             'Use "--handoff-token" by itself for native app handoff login.',
+            'Use "--handoff-token-stdin" by itself to read a native app handoff token from stdin.',
         ], { command: 'login' });
         process.exitCode = 1;
         return;
@@ -232,6 +272,33 @@ async function login(env, options = {}) {
         process.exitCode = 1;
         return;
     }
+    if (hasApiKeyArgument && !apiKey) {
+        (0, messages_1.printErrorWithHelp)('The API key cannot be empty.', ['Provide a non-empty value to "--key".'], { command: 'login' });
+        process.exitCode = 1;
+        return;
+    }
+    if (hasHandoffTokenArgument && !argvHandoffToken) {
+        (0, messages_1.printErrorWithHelp)('The native app handoff token cannot be empty.', ['Request a fresh handoff token from the PlayDrop app and retry.'], { command: 'login' });
+        process.exitCode = 1;
+        return;
+    }
+    let handoffToken = argvHandoffToken;
+    if (readsHandoffTokenFromStdin) {
+        try {
+            handoffToken = await readHandoffTokenFromStdin(runtime.stdin ?? process.stdin);
+        }
+        catch (error) {
+            const inputError = error instanceof HandoffTokenStdinError ? error : null;
+            const message = inputError?.code === 'too_large'
+                ? `Native app handoff input exceeded the ${exports.HANDOFF_TOKEN_STDIN_MAX_BYTES}-byte limit.`
+                : inputError?.code === 'empty'
+                    ? 'Native app handoff input was empty.'
+                    : 'Could not read native app handoff input from stdin.';
+            (0, messages_1.printErrorWithHelp)(message, ['Request a fresh handoff token from the PlayDrop app and retry.'], { command: 'login' });
+            process.exitCode = 1;
+            return;
+        }
+    }
     try {
         if (apiKey) {
             await loginWithKey(env, envConfig.apiBase, apiKey, { json: options.json });

package/dist/commands/review.d.ts

@@ -33,26 +33,6 @@ export type ReviewRatingCardOptions = {
     punchline?: string;
     title?: string;
 };
-export type ReviewListWindowsOptions = {
-    pid: string;
-};
-export type ReviewScreenshotOptions = {
-    metadata?: string;
-    out: string;
-    pid: string;
-    windowId?: string;
-};
-export declare function buildReviewListWindowsRecorderArgs(options: ReviewListWindowsOptions): string[];
-export declare function buildReviewScreenshotRecorderArgs(options: ReviewScreenshotOptions): {
-    args: string[];
-    metadataPath: string;
-    outputPath: string;
-};
-export declare function listReviewCaptureWindows(options: ReviewListWindowsOptions): Promise<void>;
-export declare function captureReviewScreenshot(options: ReviewScreenshotOptions): Promise<{
-    metadataPath: string;
-    outputPath: string;
-}>;
 export declare function validateGameReviewResult(input: ValidateGameReviewResultInput): Promise<ReviewValidationResult>;
 export declare function validateReviewResultCommand(options: ReviewValidateResultOptions): Promise<void>;
 export declare function composeReviewEvidence(options: ReviewComposeEvidenceOptions): Promise<{

package/dist/commands/review.js

@@ -4,20 +4,14 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.REQUIRED_REVIEW_EVIDENCE_FILES = exports.REVIEW_CRITERIA = void 0;
-exports.buildReviewListWindowsRecorderArgs = buildReviewListWindowsRecorderArgs;
-exports.buildReviewScreenshotRecorderArgs = buildReviewScreenshotRecorderArgs;
-exports.listReviewCaptureWindows = listReviewCaptureWindows;
-exports.captureReviewScreenshot = captureReviewScreenshot;
 exports.validateGameReviewResult = validateGameReviewResult;
 exports.validateReviewResultCommand = validateReviewResultCommand;
 exports.composeReviewEvidence = composeReviewEvidence;
 exports.createReviewRatingCard = createReviewRatingCard;
 const node_path_1 = __importDefault(require("node:path"));
-const node_child_process_1 = require("node:child_process");
 const node_fs_1 = require("node:fs");
 const sharp_1 = __importDefault(require("sharp"));
 const output_1 = require("../output");
-const captureListing_1 = require("./captureListing");
 exports.REVIEW_CRITERIA = [
     'Gameplay / Core Loop',
     'Depth / Replayability',
@@ -45,6 +39,7 @@ const STATE_OUTCOME = {
     PASSED: 'Passed',
 };
 exports.REQUIRED_REVIEW_EVIDENCE_FILES = [
+    'first-frame.png',
     'core.png',
     'win.png',
     'loss.png',
@@ -52,7 +47,6 @@ exports.REQUIRED_REVIEW_EVIDENCE_FILES = [
     'rating-card.png',
 ];
 const REVIEW_EVIDENCE_MAX_BYTES = 10 * 1024 * 1024;
-const REVIEW_RECORDER_TIMEOUT_MS = 15000;
 function resolveFilePath(filePath, code) {
     const normalized = typeof filePath === 'string' ? filePath.trim() : '';
     if (!normalized) {
@@ -174,111 +168,6 @@ async function assertPngFile(filePath) {
         }
     }
 }
-async function assertNonBlankPngFile(filePath) {
-    await assertPngFile(filePath);
-    const image = (0, sharp_1.default)(filePath);
-    const metadata = await image.metadata();
-    if (!metadata.width || !metadata.height) {
-        throw new Error(`review_screenshot_invalid_image:${filePath}`);
-    }
-    const stats = await image.stats();
-    const colorChannels = stats.channels.slice(0, 3);
-    const brightest = Math.max(...colorChannels.map((channel) => channel.max));
-    if (brightest <= 5) {
-        throw new Error(`review_screenshot_blank:${filePath}`);
-    }
-}
-function parsePositiveInteger(value, code) {
-    const normalized = typeof value === 'string' ? value.trim() : '';
-    const parsed = Number.parseInt(normalized, 10);
-    if (!Number.isSafeInteger(parsed) || parsed <= 0 || String(parsed) !== normalized) {
-        throw new Error(code);
-    }
-    return parsed;
-}
-function buildReviewListWindowsRecorderArgs(options) {
-    const pid = parsePositiveInteger(options.pid, 'invalid_review_window_pid');
-    return ['--list-windows', '--pid', String(pid)];
-}
-function buildReviewScreenshotRecorderArgs(options) {
-    const pid = parsePositiveInteger(options.pid, 'invalid_review_window_pid');
-    const outputPath = resolveFilePath(options.out, 'missing_out');
-    const metadataPath = options.metadata
-        ? resolveFilePath(options.metadata, 'invalid_review_screenshot_metadata')
-        : outputPath.replace(/\.png$/i, '') + '.metadata.json';
-    const args = [
-        '--pid',
-        String(pid),
-        '--screenshot',
-        outputPath,
-        '--metadata',
-        metadataPath,
-    ];
-    if (options.windowId !== undefined && options.windowId !== '') {
-        const windowId = parsePositiveInteger(options.windowId, 'invalid_review_window_id');
-        args.push('--window-id', String(windowId));
-    }
-    return { args, metadataPath, outputPath };
-}
-function runRecorder(args) {
-    return new Promise((resolve, reject) => {
-        const recorderPath = (0, captureListing_1.resolveListingRecorderPath)();
-        const child = (0, node_child_process_1.spawn)(recorderPath, args, {
-            stdio: ['ignore', 'pipe', 'pipe'],
-        });
-        let stdout = '';
-        let stderr = '';
-        let settled = false;
-        const timer = setTimeout(() => {
-            if (settled) {
-                return;
-            }
-            settled = true;
-            child.kill('SIGKILL');
-            reject(new Error(`review_recorder_timeout:${REVIEW_RECORDER_TIMEOUT_MS}`));
-        }, REVIEW_RECORDER_TIMEOUT_MS);
-        child.stdout.on('data', (chunk) => {
-            stdout += chunk.toString();
-        });
-        child.stderr.on('data', (chunk) => {
-            stderr += chunk.toString();
-        });
-        child.on('error', (error) => {
-            if (settled) {
-                return;
-            }
-            settled = true;
-            clearTimeout(timer);
-            reject(new Error(`review_recorder_unavailable:${recorderPath}:${error.message}`));
-        });
-        child.on('close', (code) => {
-            if (settled) {
-                return;
-            }
-            settled = true;
-            clearTimeout(timer);
-            if (code === 0) {
-                resolve(stdout);
-                return;
-            }
-            const detail = (stderr || stdout || `exit ${code}`).trim();
-            reject(new Error(`review_recorder_failed:${detail}`));
-        });
-    });
-}
-async function listReviewCaptureWindows(options) {
-    const output = await runRecorder(buildReviewListWindowsRecorderArgs(options));
-    process.stdout.write(output);
-}
-async function captureReviewScreenshot(options) {
-    const { args, metadataPath, outputPath } = buildReviewScreenshotRecorderArgs(options);
-    await node_fs_1.promises.mkdir(node_path_1.default.dirname(outputPath), { recursive: true });
-    await node_fs_1.promises.mkdir(node_path_1.default.dirname(metadataPath), { recursive: true });
-    await runRecorder(args);
-    await assertNonBlankPngFile(outputPath);
-    (0, output_1.printSuccess)(`Review screenshot written to ${outputPath}`);
-    return { metadataPath, outputPath };
-}
 async function validateGameReviewResult(input) {
     const normalizedState = String(input.reviewState || '').trim().toUpperCase();
     if (!TERMINAL_REVIEW_STATES.has(normalizedState)) {

package/dist/commands/worker/instrument-evidence.d.ts

@@ -0,0 +1,17 @@
+import { type InstrumentEvidenceCapture, type InstrumentEvidenceManifest } from '@playdrop/types';
+export declare const INSTRUMENT_EVIDENCE_MANIFEST_FILE = "instrument-evidence.json";
+export declare function createWorkerInstrumentScreenshotCollector(workspaceDir: string): {
+    push: (chunk: string) => number;
+    finish: () => number;
+};
+export declare function saveInstrumentEvidenceCapture(input: {
+    workspaceDir: string;
+    evidenceDir: string;
+    groupId: string;
+    name: string;
+    screenshotId: string;
+}): Promise<InstrumentEvidenceCapture>;
+export declare function readAndValidateInstrumentEvidenceManifest(input: {
+    workspaceDir: string;
+    evidenceDir: string;
+}): InstrumentEvidenceManifest;

package/dist/commands/worker/instrument-evidence.js

@@ -0,0 +1,239 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.INSTRUMENT_EVIDENCE_MANIFEST_FILE = void 0;
+exports.createWorkerInstrumentScreenshotCollector = createWorkerInstrumentScreenshotCollector;
+exports.saveInstrumentEvidenceCapture = saveInstrumentEvidenceCapture;
+exports.readAndValidateInstrumentEvidenceManifest = readAndValidateInstrumentEvidenceManifest;
+const types_1 = require("@playdrop/types");
+const node_crypto_1 = require("node:crypto");
+const node_fs_1 = require("node:fs");
+const node_path_1 = __importDefault(require("node:path"));
+const sharp_1 = __importDefault(require("sharp"));
+const SCREENSHOT_STORE_DIR = '.playdrop-instrument-screenshots';
+const SCREENSHOT_INDEX_FILE = 'index.json';
+exports.INSTRUMENT_EVIDENCE_MANIFEST_FILE = 'instrument-evidence.json';
+const GROUP_ID_PATTERN = /^[a-z0-9][a-z0-9_-]{0,63}$/;
+const SHA256_PATTERN = /^[a-f0-9]{64}$/;
+function sha256(buffer) {
+    return (0, node_crypto_1.createHash)('sha256').update(buffer).digest('hex');
+}
+function isPathInside(parent, child) {
+    const relative = node_path_1.default.relative(parent, child);
+    return relative === '' || (!!relative && !relative.startsWith('..') && !node_path_1.default.isAbsolute(relative));
+}
+function writeJsonAtomic(filePath, value) {
+    (0, node_fs_1.mkdirSync)(node_path_1.default.dirname(filePath), { recursive: true });
+    const tempPath = `${filePath}.${process.pid}.tmp`;
+    (0, node_fs_1.writeFileSync)(tempPath, `${JSON.stringify(value, null, 2)}\n`, 'utf8');
+    (0, node_fs_1.renameSync)(tempPath, filePath);
+}
+function readJsonRecord(filePath, code) {
+    let parsed;
+    try {
+        parsed = JSON.parse((0, node_fs_1.readFileSync)(filePath, 'utf8'));
+    }
+    catch (error) {
+        throw new Error(`${code}:${error instanceof Error ? error.message : String(error)}`);
+    }
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+        throw new Error(code);
+    }
+    return parsed;
+}
+function screenshotStorePath(workspaceDir) {
+    return node_path_1.default.join(workspaceDir, SCREENSHOT_STORE_DIR);
+}
+function screenshotIndexPath(workspaceDir) {
+    return node_path_1.default.join(screenshotStorePath(workspaceDir), SCREENSHOT_INDEX_FILE);
+}
+function readScreenshotIndex(workspaceDir) {
+    const filePath = screenshotIndexPath(workspaceDir);
+    if (!(0, node_fs_1.existsSync)(filePath)) {
+        return { version: 1, screenshots: {} };
+    }
+    const parsed = readJsonRecord(filePath, 'invalid_instrument_screenshot_index');
+    const screenshots = parsed['screenshots'];
+    if (parsed['version'] !== 1 || !screenshots || typeof screenshots !== 'object' || Array.isArray(screenshots)) {
+        throw new Error('invalid_instrument_screenshot_index');
+    }
+    return parsed;
+}
+function extensionForMediaType(mediaType) {
+    return mediaType === 'image/jpeg' ? 'jpg' : 'png';
+}
+function createWorkerInstrumentScreenshotCollector(workspaceDir) {
+    const resolvedWorkspace = node_path_1.default.resolve(workspaceDir);
+    const parser = new types_1.ClaudeChromeScreenshotStreamParser((screenshot) => {
+        const buffer = Buffer.from(screenshot.dataBase64, 'base64');
+        if (buffer.length <= 0) {
+            throw new Error(`invalid_claude_screenshot_payload:${screenshot.screenshotId}`);
+        }
+        const storeDir = screenshotStorePath(resolvedWorkspace);
+        (0, node_fs_1.mkdirSync)(storeDir, { recursive: true });
+        const fileName = `${screenshot.screenshotId}.${extensionForMediaType(screenshot.mediaType)}`;
+        const filePath = node_path_1.default.join(storeDir, fileName);
+        (0, node_fs_1.writeFileSync)(filePath, buffer);
+        const index = readScreenshotIndex(resolvedWorkspace);
+        index.screenshots[screenshot.screenshotId] = {
+            screenshotId: screenshot.screenshotId,
+            tabId: screenshot.tabId,
+            toolUseId: screenshot.toolUseId,
+            mediaType: screenshot.mediaType,
+            fileName,
+            sha256: sha256(buffer),
+            capturedAt: new Date().toISOString(),
+            width: screenshot.width,
+            height: screenshot.height,
+        };
+        writeJsonAtomic(screenshotIndexPath(resolvedWorkspace), index);
+    });
+    return {
+        push: (chunk) => parser.push(chunk),
+        finish: () => parser.finish(),
+    };
+}
+function normalizeEvidenceName(value) {
+    const normalized = value.trim();
+    if (!types_1.INSTRUMENT_EVIDENCE_NAMES.includes(normalized)) {
+        throw new Error(`invalid_instrument_evidence_name:${value}`);
+    }
+    return normalized;
+}
+function normalizeGroupId(value) {
+    const normalized = value.trim().toLowerCase();
+    if (!GROUP_ID_PATTERN.test(normalized)) {
+        throw new Error(`invalid_instrument_evidence_group:${value}`);
+    }
+    return normalized;
+}
+function resolveEvidenceDir(workspaceDir, evidenceDir) {
+    const resolvedWorkspace = node_path_1.default.resolve(workspaceDir);
+    const resolvedEvidenceDir = node_path_1.default.resolve(evidenceDir);
+    if (!isPathInside(resolvedWorkspace, resolvedEvidenceDir)) {
+        throw new Error('instrument_evidence_dir_outside_workspace');
+    }
+    return resolvedEvidenceDir;
+}
+function readManifestIfPresent(evidenceDir) {
+    const filePath = node_path_1.default.join(evidenceDir, exports.INSTRUMENT_EVIDENCE_MANIFEST_FILE);
+    if (!(0, node_fs_1.existsSync)(filePath)) {
+        return null;
+    }
+    return readJsonRecord(filePath, 'invalid_instrument_evidence_manifest');
+}
+async function saveInstrumentEvidenceCapture(input) {
+    const evidenceName = normalizeEvidenceName(input.name);
+    const groupId = normalizeGroupId(input.groupId);
+    const screenshotId = input.screenshotId.trim();
+    const index = readScreenshotIndex(input.workspaceDir);
+    const screenshot = index.screenshots[screenshotId];
+    if (!screenshot) {
+        throw new Error(`instrument_screenshot_not_found:${screenshotId}`);
+    }
+    const evidenceDir = resolveEvidenceDir(input.workspaceDir, input.evidenceDir);
+    (0, node_fs_1.mkdirSync)(evidenceDir, { recursive: true });
+    const existing = readManifestIfPresent(evidenceDir);
+    if (existing && existing.groupId !== groupId) {
+        throw new Error(`instrument_evidence_group_mismatch:${existing.groupId}:${groupId}`);
+    }
+    if (existing && existing.controlledTabId !== screenshot.tabId) {
+        throw new Error(`instrument_evidence_tab_mismatch:${existing.controlledTabId}:${screenshot.tabId}`);
+    }
+    const fileName = `${evidenceName}.png`;
+    const sourcePath = node_path_1.default.join(screenshotStorePath(input.workspaceDir), screenshot.fileName);
+    const outputPath = node_path_1.default.join(evidenceDir, fileName);
+    const sourceBuffer = (0, node_fs_1.readFileSync)(sourcePath);
+    const outputBuffer = await (0, sharp_1.default)(sourceBuffer).png().toBuffer();
+    (0, node_fs_1.writeFileSync)(outputPath, outputBuffer);
+    const outputHash = sha256(outputBuffer);
+    const capture = {
+        name: evidenceName,
+        screenshotId,
+        tabId: screenshot.tabId,
+        toolUseId: screenshot.toolUseId,
+        mediaType: screenshot.mediaType,
+        fileName,
+        sourceSha256: screenshot.sha256,
+        sha256: outputHash,
+        capturedAt: screenshot.capturedAt,
+    };
+    const manifest = existing ?? {
+        version: 1,
+        groupId,
+        controlledTabId: screenshot.tabId,
+        captures: {},
+    };
+    manifest.captures[evidenceName] = capture;
+    writeJsonAtomic(node_path_1.default.join(evidenceDir, exports.INSTRUMENT_EVIDENCE_MANIFEST_FILE), manifest);
+    return capture;
+}
+function normalizeCapture(value, name) {
+    const capture = value && typeof value === 'object' && !Array.isArray(value)
+        ? value
+        : null;
+    const screenshotId = typeof capture?.['screenshotId'] === 'string' ? capture['screenshotId'].trim() : '';
+    const tabId = Number(capture?.['tabId']);
+    const toolUseId = typeof capture?.['toolUseId'] === 'string' ? capture['toolUseId'].trim() : '';
+    const mediaType = capture?.['mediaType'];
+    const fileName = typeof capture?.['fileName'] === 'string' ? capture['fileName'].trim() : '';
+    const hash = typeof capture?.['sha256'] === 'string' ? capture['sha256'].trim().toLowerCase() : '';
+    const sourceHash = typeof capture?.['sourceSha256'] === 'string' ? capture['sourceSha256'].trim().toLowerCase() : '';
+    const capturedAt = typeof capture?.['capturedAt'] === 'string' ? capture['capturedAt'].trim() : '';
+    if (capture?.['name'] !== name
+        || !screenshotId
+        || !Number.isInteger(tabId)
+        || tabId <= 0
+        || !toolUseId
+        || (mediaType !== 'image/jpeg' && mediaType !== 'image/png')
+        || node_path_1.default.basename(fileName) !== fileName
+        || !fileName
+        || !SHA256_PATTERN.test(sourceHash)
+        || !SHA256_PATTERN.test(hash)
+        || !capturedAt) {
+        throw new Error(`invalid_instrument_evidence_capture:${name}`);
+    }
+    return {
+        name,
+        screenshotId,
+        tabId,
+        toolUseId,
+        mediaType,
+        fileName,
+        sourceSha256: sourceHash,
+        sha256: hash,
+        capturedAt,
+    };
+}
+function readAndValidateInstrumentEvidenceManifest(input) {
+    const evidenceDir = resolveEvidenceDir(input.workspaceDir, input.evidenceDir);
+    const parsed = readManifestIfPresent(evidenceDir);
+    if (!parsed || parsed.version !== 1) {
+        throw new Error('missing_instrument_evidence_manifest');
+    }
+    const groupId = normalizeGroupId(parsed.groupId);
+    const controlledTabId = Number(parsed.controlledTabId);
+    if (!Number.isInteger(controlledTabId) || controlledTabId <= 0) {
+        throw new Error('invalid_instrument_evidence_tab');
+    }
+    const captures = {};
+    const screenshotIds = new Set();
+    for (const name of types_1.INSTRUMENT_EVIDENCE_NAMES) {
+        const capture = normalizeCapture(parsed.captures?.[name], name);
+        if (capture.tabId !== controlledTabId) {
+            throw new Error(`instrument_evidence_tab_mismatch:${controlledTabId}:${capture.tabId}`);
+        }
+        const filePath = node_path_1.default.join(evidenceDir, capture.fileName);
+        if (!(0, node_fs_1.existsSync)(filePath) || sha256((0, node_fs_1.readFileSync)(filePath)) !== capture.sha256) {
+            throw new Error(`instrument_evidence_file_hash_mismatch:${name}`);
+        }
+        if (screenshotIds.has(capture.screenshotId)) {
+            throw new Error(`duplicate_instrument_evidence_screenshot:${capture.screenshotId}`);
+        }
+        screenshotIds.add(capture.screenshotId);
+        captures[name] = capture;
+    }
+    return { version: 1, groupId, controlledTabId, captures };
+}

package/dist/commands/worker/runtime.d.ts

@@ -50,6 +50,7 @@ export declare function runLoggedProcess(input: {
     maxOutputChars: number;
     transcriptFlushIntervalMs?: number;
     onTranscriptChunks?: (chunks: LoggedProcessTranscriptChunk[]) => Promise<void> | void;
+    onStdoutText?: (text: string) => boolean | void;
     onChild?: (controls: {
         terminate: () => void;
     }) => void;

package/dist/commands/worker/runtime.js

@@ -377,6 +377,17 @@ async function runLoggedProcess(input) {
             if (input.onTranscriptChunks) {
                 pendingTranscriptChunks.push({ stream, content: text });
             }
+            if (stream === 'stdout' && input.onStdoutText) {
+                try {
+                    const flushNow = input.onStdoutText(text) === true;
+                    if (flushNow && input.onTranscriptChunks) {
+                        queueTranscriptFlush().catch(handleTranscriptFlushError);
+                    }
+                }
+                catch (error) {
+                    handleTranscriptFlushError(error);
+                }
+            }
             combined = tailText(combined + text, input.maxOutputChars);
         };
         const timeout = setTimeout(() => {