@playdrop/playdrop-cli 0.12.37 → 0.12.39

package/dist/commands/upload.js

@@ -4,6 +4,7 @@ exports.resolveUploadOwner = resolveUploadOwner;
 exports.resolveDefaultUploadCreator = resolveDefaultUploadCreator;
 exports.upload = upload;
 exports.resolveWorkerPlaydropAssetRequirement = resolveWorkerPlaydropAssetRequirement;
+exports.assertAgentNewGamePlaytestContract = assertAgentNewGamePlaytestContract;
 exports.assertTaskPlaytestEvidenceManifest = assertTaskPlaytestEvidenceManifest;
 exports.assertWorkerAppLocalUploadPreflight = assertWorkerAppLocalUploadPreflight;
 exports.publishWorkerAppProject = publishWorkerAppProject;
@@ -1222,6 +1223,22 @@ function resolveWorkerPlaydropAssetRequirement(value) {
     }
     return null;
 }
+function assertAgentNewGamePlaytestContract(task) {
+    if (!task.primarySurface) {
+        throw new Error('agent_task_primary_surface_required: NEW_GAME catalogue.json must declare primarySurface.');
+    }
+    if (!task.surfaceTargets.includes(task.primarySurface)) {
+        throw new Error(`agent_task_primary_surface_not_supported:${task.primarySurface}`);
+    }
+    if (!task.playtestTapes) {
+        throw new Error('agent_task_playtest_tapes_required: NEW_GAME catalogue.json must declare one playtest tape per supported surface.');
+    }
+    for (const surface of task.surfaceTargets) {
+        if (!task.playtestTapes[surface]) {
+            throw new Error(`agent_task_playtest_tape_missing:${surface}`);
+        }
+    }
+}
 const WORKER_SUPERVISOR_SOURCE_EXCLUDES = [
     'PLAYDROP_TASK.md',
     'AGENTS.md',
@@ -1670,6 +1687,70 @@ function readPlaytestEvidenceManifest(task) {
         throw new Error(formatPlaytestEvidenceManifestError(`playtest-evidence.json must be valid JSON. ${reason}`));
     }
 }
+function assertGreyboxReport(task) {
+    const reportPath = (0, node_path_1.join)(task.projectDir, 'greybox-report.json');
+    if (!(0, node_fs_1.existsSync)(reportPath)) {
+        throw new Error('agent_task_greybox_report_missing: greybox-report.json must prove the prototype and final start, agency, and restart checks.');
+    }
+    let report;
+    try {
+        const parsed = JSON.parse((0, node_fs_1.readFileSync)(reportPath, 'utf8'));
+        if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+            throw new Error('report must be a JSON object');
+        }
+        report = parsed;
+    }
+    catch (error) {
+        throw new Error(`agent_task_greybox_report_invalid: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    if (report.schemaVersion !== 1 || Object.keys(report).some((key) => !['schemaVersion', 'prototype', 'final'].includes(key))) {
+        throw new Error('agent_task_greybox_report_invalid: expected schemaVersion 1 with only prototype and final sections.');
+    }
+    for (const sectionName of ['prototype', 'final']) {
+        const rawSection = report[sectionName];
+        if (!rawSection || typeof rawSection !== 'object' || Array.isArray(rawSection)) {
+            throw new Error(`agent_task_greybox_report_invalid: ${sectionName} must contain start, agency, and restart.`);
+        }
+        const section = rawSection;
+        if (Object.keys(section).length !== 3
+            || Object.keys(section).some((key) => !['start', 'agency', 'restart'].includes(key))) {
+            throw new Error(`agent_task_greybox_report_invalid: ${sectionName} must contain exactly start, agency, and restart.`);
+        }
+        for (const checkName of ['start', 'agency', 'restart']) {
+            const rawCheck = section[checkName];
+            if (!rawCheck || typeof rawCheck !== 'object' || Array.isArray(rawCheck)) {
+                throw new Error(`agent_task_greybox_report_invalid: ${sectionName}.${checkName} must be an object.`);
+            }
+            const check = rawCheck;
+            const expectedKeys = checkName === 'agency'
+                ? ['passed', 'normalInput', 'controlCondition', 'observation']
+                : ['passed', 'observation'];
+            if (Object.keys(check).length !== expectedKeys.length
+                || Object.keys(check).some((key) => !expectedKeys.includes(key))
+                || check.passed !== true
+                || typeof check.observation !== 'string'
+                || !check.observation.trim()
+                || (checkName === 'agency' && (typeof check.normalInput !== 'string'
+                    || !check.normalInput.trim()
+                    || typeof check.controlCondition !== 'string'
+                    || !check.controlCondition.trim()))) {
+                throw new Error(`agent_task_greybox_report_invalid: ${sectionName}.${checkName} must be complete and passing.`);
+            }
+        }
+    }
+}
+async function collectUploadPreflightErrors(checks) {
+    const errors = [];
+    for (const check of checks) {
+        try {
+            await check();
+        }
+        catch (error) {
+            errors.push(error instanceof Error ? error.message : String(error));
+        }
+    }
+    return errors;
+}
 const PLAYTEST_EVIDENCE_MANIFEST_HELP = 'Expected shape: {"version":1,"entries":[{"environment":"local","url":"http://localhost:8080/...","surface":"desktop","checkedAt":"2026-07-05T00:00:00.000Z","captures":["evidence/input.png","evidence/win.png","evidence/loss.png"],"actions":["press ArrowRight","complete the final round","allow health to reach zero"],"statesObserved":["player moved right","victory overlay","defeat overlay"],"consoleErrors":[]}],"proof":{"primaryInput":{"action":"press ArrowRight","observed":"player moved right","capture":"evidence/input.png"},"win":{"action":"complete the final round","observed":"victory overlay appeared","capture":"evidence/win.png"},"loss":{"action":"allow health to reach zero","observed":"defeat overlay appeared","capture":"evidence/loss.png"}}}. NEW_GAME proof requires three distinct captures from a current non-final entry. The uploader appends hashes and the final published-route entry automatically.';
 function formatMissingPlaytestEvidenceManifestError(message) {
     return `agent_task_playtest_manifest_missing: ${message} ${PLAYTEST_EVIDENCE_MANIFEST_HELP}`;
@@ -1816,30 +1897,44 @@ async function assertWorkerAppLocalUploadPreflight(input) {
     if (input.kind === 'GAME_UPDATE') {
         return assertTaskPlaytestEvidenceManifest(input.task);
     }
-    (0, listingPreflight_1.assertAgentGameHeroListingPreflight)(input.task);
-    if (input.kind === 'NEW_GAME') {
-        (0, listingPreflight_1.assertAgentNewGameArtDirectionPreflight)(input.task);
+    let playtestProof = null;
+    const errors = await collectUploadPreflightErrors([
+        () => assertGreyboxReport(input.task),
+        () => (0, listingPreflight_1.assertAgentGameHeroListingPreflight)(input.task),
+        ...(input.kind === 'NEW_GAME' ? [() => (0, listingPreflight_1.assertAgentNewGameArtDirectionPreflight)(input.task)] : []),
+        ...(input.kind === 'NEW_GAME' ? [() => assertAgentNewGamePlaytestContract(input.task)] : []),
+        () => {
+            if (!appTaskSatisfiesPlaydropAssetRequirement(input.task, input.playdropAssetRequirement)) {
+                throw new Error('agent_task_playdrop_asset_dependency_missing: the creator asked for PlayDrop assets, but catalogue.json does not declare a matching uses.assets, uses.packs, or ownedAssets dependency.');
+            }
+        },
+        () => (0, ownedRuntimeImageValidation_1.assertOwnedRuntimeImagesAreValid)(input.task),
+        () => assertRequestedPlaydropAssetsAreUsedAtRuntime({
+            task: input.task,
+            requirement: input.playdropAssetRequirement,
+            creatorRequest: input.creatorRequest,
+        }),
+        () => assertNewGameDeclaredAssetsAreUsedAtRuntime({
+            creatorUsername: input.creatorUsername?.trim() ?? '',
+            task: input.task,
+        }),
+        () => (0, listingPreflight_1.assertAgentGameScreenshotListingPreflight)(input.task),
+        () => (0, listingPreflight_1.assertAgentGameCaptureReportPreflight)(input.task, {
+            requireCaptureReport: input.executionTarget === 'FIRST_PARTY',
+        }),
+        () => {
+            playtestProof = assertTaskPlaytestEvidenceManifest(input.task, {
+                requireOutcomeProof: input.kind === 'NEW_GAME',
+            });
+        },
+    ]);
+    if (errors.length === 1) {
+        throw new Error(errors[0]);
     }
-    if (!appTaskSatisfiesPlaydropAssetRequirement(input.task, input.playdropAssetRequirement)) {
-        throw new Error('agent_task_playdrop_asset_dependency_missing: the creator asked for PlayDrop assets, but catalogue.json does not declare a matching uses.assets, uses.packs, or ownedAssets dependency.');
+    if (errors.length > 1) {
+        throw new Error(`agent_task_upload_preflight_failed:\n${errors.map((error, index) => `${index + 1}. ${error}`).join('\n')}`);
     }
-    await (0, ownedRuntimeImageValidation_1.assertOwnedRuntimeImagesAreValid)(input.task);
-    assertRequestedPlaydropAssetsAreUsedAtRuntime({
-        task: input.task,
-        requirement: input.playdropAssetRequirement,
-        creatorRequest: input.creatorRequest,
-    });
-    await assertNewGameDeclaredAssetsAreUsedAtRuntime({
-        creatorUsername: input.creatorUsername?.trim() ?? '',
-        task: input.task,
-    });
-    (0, listingPreflight_1.assertAgentGameScreenshotListingPreflight)(input.task);
-    (0, listingPreflight_1.assertAgentGameCaptureReportPreflight)(input.task, {
-        requireCaptureReport: input.executionTarget === 'FIRST_PARTY',
-    });
-    return assertTaskPlaytestEvidenceManifest(input.task, {
-        requireOutcomeProof: input.kind === 'NEW_GAME',
-    });
+    return playtestProof;
 }
 // Task upload path used by "playdrop task upload": same internal pipeline as
 // "playdrop project publish", but always as one PRIVATE draft version for the

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

@@ -77,7 +77,12 @@ export declare function buildClaudeExecArgs(input: {
     pluginDir?: string | null;
 }): string[];
 export declare const PLAYWRIGHT_MCP_VERSION = "0.0.78";
-export declare function buildPlaywrightMcpServerConfig(): Record<string, unknown>;
+export type WorkerInstrumentSurface = 'DESKTOP' | 'MOBILE_LANDSCAPE' | 'MOBILE_PORTRAIT';
+export declare function buildPlaywrightMcpCommand(surface?: WorkerInstrumentSurface | null): {
+    command: string;
+    args: string[];
+};
+export declare function buildPlaywrightMcpServerConfig(surface?: WorkerInstrumentSurface | null): Record<string, unknown>;
 export declare function buildClaudePermissionSettings(input?: {
     workspaceDir?: string | null;
     denyReadRoots?: string[];

package/dist/commands/worker/runtime.js

@@ -17,6 +17,7 @@ exports.runLoggedProcess = runLoggedProcess;
 exports.buildCodexExecArgs = buildCodexExecArgs;
 exports.readCodexSandboxMode = readCodexSandboxMode;
 exports.buildClaudeExecArgs = buildClaudeExecArgs;
+exports.buildPlaywrightMcpCommand = buildPlaywrightMcpCommand;
 exports.buildPlaywrightMcpServerConfig = buildPlaywrightMcpServerConfig;
 exports.buildClaudePermissionSettings = buildClaudePermissionSettings;
 exports.buildClaudeDeniedPermissionRules = buildClaudeDeniedPermissionRules;
@@ -25,6 +26,7 @@ const node_child_process_1 = require("node:child_process");
 const promises_1 = require("node:fs/promises");
 const node_os_1 = __importDefault(require("node:os"));
 const node_path_1 = __importDefault(require("node:path"));
+const surfaceProfiles_1 = require("../../apps/surfaceProfiles");
 const CHILD_KILL_GRACE_MS = 10000;
 exports.DEFAULT_CODEX_TIMEOUT_MS = 2 * 60 * 60 * 1000;
 exports.DEFAULT_WORKER_TOKEN_CAP = 20000000;
@@ -647,12 +649,27 @@ const CLAUDE_BASE_TOOL_NAMES = [
 // never through @latest drift (see the 2026-07-13 auto-update incident).
 exports.PLAYWRIGHT_MCP_VERSION = '0.0.78';
 const PLAYWRIGHT_MCP_ALLOWED_TOOL_RULE = 'mcp__playwright';
-function buildPlaywrightMcpServerConfig() {
+function buildPlaywrightMcpCommand(surface) {
+    const surfaceArgs = surface ? (0, surfaceProfiles_1.buildPlaywrightMcpSurfaceArgs)(surface) : [];
+    return {
+        command: 'npx',
+        args: [
+            '-y',
+            `@playwright/mcp@${exports.PLAYWRIGHT_MCP_VERSION}`,
+            '--browser',
+            'chrome',
+            '--isolated',
+            ...surfaceArgs,
+        ],
+    };
+}
+function buildPlaywrightMcpServerConfig(surface) {
+    const server = buildPlaywrightMcpCommand(surface);
     return {
         mcpServers: {
             playwright: {
-                command: 'npx',
-                args: ['-y', `@playwright/mcp@${exports.PLAYWRIGHT_MCP_VERSION}`, '--browser', 'chrome', '--isolated'],
+                command: server.command,
+                args: server.args,
             },
         },
     };

package/dist/commands/worker.d.ts

@@ -1,9 +1,10 @@
 import type { ApiClient } from '@playdrop/api-client';
-import { type AgentExecutionTarget, type AgentRuntime, type AgentTaskNextStepSuggestion, type AgentTaskResponse, type AgentWorkerCapabilities, type AgentWorkerResponse, type AgentWorkerUpdatePolicyResponse, type WorkerTaskAssignmentV2, type WorkerTaskPluginV2, type WorkerClaimAgentTaskResponse } from '@playdrop/types';
+import { type AgentExecutionTarget, type AgentRuntime, type AgentTaskKind, type AgentTaskNextStepSuggestion, type AgentTaskResponse, type AgentWorkerCapabilities, type AgentWorkerResponse, type AgentWorkerUpdatePolicyResponse, type JsonValue, type WorkerTaskAssignmentV2, type WorkerTaskPluginV2, type WorkerClaimAgentTaskResponse } from '@playdrop/types';
 import { loadConfig } from '../config';
+import { runShell } from '../shellProbe';
 import { type WorkerPlaydropAssetRequirement } from './upload';
-import { type LoggedProcessResult, type LoggedProcessTranscriptChunk } from './worker/runtime';
-export { assertWorkerTokenUsageWithinCap, buildClaudeExecArgs, buildClaudePermissionSettings, buildCodexExecArgs, buildWorkerChildEnv, DEFAULT_CODEX_TIMEOUT_MS, DEFAULT_WORKER_TOKEN_CAP, extractAgentTokenUsage, extractCodexRolloutTokenUsage, extractCodexThreadId, extractCodexTokensUsed, readCodexRolloutTokenUsageForThread, readCodexSandboxMode, readEnvBoolean, runLoggedProcess } from './worker/runtime';
+import { type WorkerInstrumentSurface, type LoggedProcessResult, type LoggedProcessTranscriptChunk } from './worker/runtime';
+export { assertWorkerTokenUsageWithinCap, buildClaudeExecArgs, buildClaudePermissionSettings, buildCodexExecArgs, buildPlaywrightMcpCommand, buildWorkerChildEnv, DEFAULT_CODEX_TIMEOUT_MS, DEFAULT_WORKER_TOKEN_CAP, extractAgentTokenUsage, extractCodexRolloutTokenUsage, extractCodexThreadId, extractCodexTokensUsed, readCodexRolloutTokenUsageForThread, readCodexSandboxMode, readEnvBoolean, runLoggedProcess } from './worker/runtime';
 export type { AgentTokenUsage, LoggedProcessResult, LoggedProcessTranscriptChunk } from './worker/runtime';
 export declare const WORKER_SESSION_EXPIRED_MESSAGE = "worker session expired: run \"playdrop auth login\" and start the worker again";
 export declare const WORKER_CONTEXT_COMMAND_NOT_ALLOWED_MESSAGE = "worker_context_command_not_allowed: inside a PlayDrop worker task only task progress, task claim-slug, task upload/done/fail, assigned app scaffolding, project validation/build/dev/check/capture, read-only help/catalogue/documentation lookup, and PlayDrop AI generation are permitted.";
@@ -126,6 +127,24 @@ type WorkerTaskState = {
     leaseExpiresAt: string | null;
     claimedAt: string;
 };
+type WorkerTaskContextFile = {
+    taskId: number;
+    attempt: number;
+    taskToken: string;
+    taskType: string;
+    metadata: Record<string, JsonValue>;
+    kind: AgentTaskKind;
+    creatorUsername: string;
+    creatorRequest: string;
+    target: AgentExecutionTarget;
+    outputAppName: string | null;
+    outputVersion: string;
+    remixSourceRef?: string | null;
+    allowedTemplateKeys?: string[];
+    reviewAppVersionId?: number | null;
+    devPort: number;
+    env: string;
+};
 type WorkerCodexModel = {
     model: string;
     reasoningEffort: string;
@@ -147,6 +166,7 @@ export declare function claimBackoffDelayMs(currentMs: number, random?: () => nu
 export declare function resolveWorkerHomeDir(): string;
 export declare const WORKER_TASK_WORKSPACE_RETENTION = 20;
 export declare function pruneWorkerTaskWorkspaces(incomingWorkspaceDir: string, retention?: number): Promise<string[]>;
+export declare function resolveWorkerInstrumentSurface(taskContext: Pick<WorkerTaskContextFile, 'kind' | 'metadata'>): WorkerInstrumentSurface | null;
 export declare function hasAgentTaskUploadedArtifact(task: Pick<AgentTaskResponse, 'appId' | 'appVersionId'>): boolean;
 export declare function appendWorkerTranscriptChunks(input: {
     client: Pick<ApiClient, 'workerAppendAgentTaskTranscriptChunks'>;
@@ -176,6 +196,7 @@ export declare function assertAssignmentPluginBundleExtractionBounds(buffer: Buf
 export declare function stageAssignmentPluginBundle(input: {
     workspaceDir: string;
     pluginBundle: WorkerTaskPluginV2;
+    taskKind?: AgentTaskKind;
 }): Promise<string>;
 export declare function resolveDevPluginWorkingTree(input: {
     workingTree?: string;
@@ -328,6 +349,11 @@ export declare function assertLaunchAgentPlistCompatible(input: {
     wrapperPath: string;
     canonicalPlistPath: string;
 }): void;
+export declare function launchManagedWorker(label: string, plistPath: string, options: {
+    registrationChanged: boolean;
+    runCommand?: typeof runShell;
+    uid?: number;
+}): void;
 export declare function showWorkerStatus(options?: WorkerStatusOptions): Promise<WorkerStatusPayload>;
 export declare function setupWorker(options?: WorkerSetupOptions): Promise<void>;
 export declare function instrumentTaskChromeTitleMatchers(assignment: WorkerTaskAssignmentV2): string[];

package/dist/commands/worker.js

@@ -3,7 +3,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.WORKER_TASK_WORKSPACE_RETENTION = exports.WORKER_CONTEXT_COMMAND_NOT_ALLOWED_MESSAGE = exports.WORKER_SESSION_EXPIRED_MESSAGE = exports.runLoggedProcess = exports.readEnvBoolean = exports.readCodexSandboxMode = exports.readCodexRolloutTokenUsageForThread = exports.extractCodexTokensUsed = exports.extractCodexThreadId = exports.extractCodexRolloutTokenUsage = exports.extractAgentTokenUsage = exports.DEFAULT_WORKER_TOKEN_CAP = exports.DEFAULT_CODEX_TIMEOUT_MS = exports.buildWorkerChildEnv = exports.buildCodexExecArgs = exports.buildClaudePermissionSettings = exports.buildClaudeExecArgs = exports.assertWorkerTokenUsageWithinCap = void 0;
+exports.WORKER_TASK_WORKSPACE_RETENTION = exports.WORKER_CONTEXT_COMMAND_NOT_ALLOWED_MESSAGE = exports.WORKER_SESSION_EXPIRED_MESSAGE = exports.runLoggedProcess = exports.readEnvBoolean = exports.readCodexSandboxMode = exports.readCodexRolloutTokenUsageForThread = exports.extractCodexTokensUsed = exports.extractCodexThreadId = exports.extractCodexRolloutTokenUsage = exports.extractAgentTokenUsage = exports.DEFAULT_WORKER_TOKEN_CAP = exports.DEFAULT_CODEX_TIMEOUT_MS = exports.buildWorkerChildEnv = exports.buildPlaywrightMcpCommand = exports.buildCodexExecArgs = exports.buildClaudePermissionSettings = exports.buildClaudeExecArgs = exports.assertWorkerTokenUsageWithinCap = void 0;
 exports.allocateWorkerDevPort = allocateWorkerDevPort;
 exports.isWorkerContextCommandAllowed = isWorkerContextCommandAllowed;
 exports.resolveWorkerExecutionTargetFromRole = resolveWorkerExecutionTargetFromRole;
@@ -12,6 +12,7 @@ exports.nextClaimBackoffMs = nextClaimBackoffMs;
 exports.claimBackoffDelayMs = claimBackoffDelayMs;
 exports.resolveWorkerHomeDir = resolveWorkerHomeDir;
 exports.pruneWorkerTaskWorkspaces = pruneWorkerTaskWorkspaces;
+exports.resolveWorkerInstrumentSurface = resolveWorkerInstrumentSurface;
 exports.hasAgentTaskUploadedArtifact = hasAgentTaskUploadedArtifact;
 exports.appendWorkerTranscriptChunks = appendWorkerTranscriptChunks;
 exports.readTaskNextStepsFile = readTaskNextStepsFile;
@@ -65,6 +66,7 @@ exports.withTaskUploadLock = withTaskUploadLock;
 exports.readActivePersonalWorkerRuntimeState = readActivePersonalWorkerRuntimeState;
 exports.parseLaunchAgentProgramArguments = parseLaunchAgentProgramArguments;
 exports.assertLaunchAgentPlistCompatible = assertLaunchAgentPlistCompatible;
+exports.launchManagedWorker = launchManagedWorker;
 exports.showWorkerStatus = showWorkerStatus;
 exports.setupWorker = setupWorker;
 exports.instrumentTaskChromeTitleMatchers = instrumentTaskChromeTitleMatchers;
@@ -109,6 +111,7 @@ Object.defineProperty(exports, "assertWorkerTokenUsageWithinCap", { enumerable:
 Object.defineProperty(exports, "buildClaudeExecArgs", { enumerable: true, get: function () { return runtime_2.buildClaudeExecArgs; } });
 Object.defineProperty(exports, "buildClaudePermissionSettings", { enumerable: true, get: function () { return runtime_2.buildClaudePermissionSettings; } });
 Object.defineProperty(exports, "buildCodexExecArgs", { enumerable: true, get: function () { return runtime_2.buildCodexExecArgs; } });
+Object.defineProperty(exports, "buildPlaywrightMcpCommand", { enumerable: true, get: function () { return runtime_2.buildPlaywrightMcpCommand; } });
 Object.defineProperty(exports, "buildWorkerChildEnv", { enumerable: true, get: function () { return runtime_2.buildWorkerChildEnv; } });
 Object.defineProperty(exports, "DEFAULT_CODEX_TIMEOUT_MS", { enumerable: true, get: function () { return runtime_2.DEFAULT_CODEX_TIMEOUT_MS; } });
 Object.defineProperty(exports, "DEFAULT_WORKER_TOKEN_CAP", { enumerable: true, get: function () { return runtime_2.DEFAULT_WORKER_TOKEN_CAP; } });
@@ -148,6 +151,7 @@ const execFileAsync = (0, node_util_1.promisify)(node_child_process_1.execFile);
 exports.WORKER_SESSION_EXPIRED_MESSAGE = 'worker session expired: run "playdrop auth login" and start the worker again';
 const WORKER_CONTEXT_ALLOWED_COMMANDS = [
     ['task', 'context'],
+    ['task', 'help'],
     ['task', 'report'],
     ['task', 'report-catalogue'],
     ['task', 'claim-slug'],
@@ -170,6 +174,7 @@ const WORKER_CONTEXT_ALLOWED_COMMANDS = [
     ['search'],
     ['detail'],
     ['versions', 'browse'],
+    ['tags', 'browse'],
     ['documentation', 'browse'],
     ['documentation', 'read'],
     ['help'],
@@ -567,6 +572,48 @@ function buildWorkerTaskContextV2(assignment) {
         target: assignment.task.executionTarget,
     });
 }
+function normalizeWorkerInstrumentSurface(value) {
+    return value === 'DESKTOP' || value === 'MOBILE_LANDSCAPE' || value === 'MOBILE_PORTRAIT'
+        ? value
+        : null;
+}
+function resolveWorkerInstrumentSurface(taskContext) {
+    const playdrop = taskContext.metadata.playdrop;
+    if (!playdrop || typeof playdrop !== 'object' || Array.isArray(playdrop)) {
+        return null;
+    }
+    const metadata = playdrop;
+    if (taskContext.kind === 'GAME_REVIEW') {
+        const reviewTarget = metadata.reviewTarget;
+        if (!reviewTarget || typeof reviewTarget !== 'object' || Array.isArray(reviewTarget)) {
+            return null;
+        }
+        return normalizeWorkerInstrumentSurface(reviewTarget.primarySurface);
+    }
+    if (taskContext.kind === 'GAME_EVAL') {
+        const evalTarget = metadata.evalTarget;
+        if (!evalTarget || typeof evalTarget !== 'object' || Array.isArray(evalTarget)) {
+            return null;
+        }
+        const targets = evalTarget.targets;
+        if (!Array.isArray(targets) || targets.length === 0) {
+            return null;
+        }
+        const surfaces = new Set();
+        for (const target of targets) {
+            if (!target || typeof target !== 'object' || Array.isArray(target)) {
+                return null;
+            }
+            const surface = normalizeWorkerInstrumentSurface(target.primarySurface);
+            if (!surface) {
+                return null;
+            }
+            surfaces.add(surface);
+        }
+        return surfaces.size === 1 ? Array.from(surfaces)[0] ?? null : null;
+    }
+    return null;
+}
 function workerTaskContextPath(workspaceDir) {
     return node_path_1.default.join(workspaceDir, '.playdrop', 'task.json');
 }
@@ -1062,9 +1109,24 @@ function readAgentBundleManifest(extractedRoot) {
     if (!destinations.has('CLAUDE.md')) {
         throw new Error('agent_bundle_claude_file_missing');
     }
+    const taskAgentOverlays = manifest.workspace.taskAgentOverlays;
+    if (taskAgentOverlays !== undefined) {
+        if (!taskAgentOverlays || typeof taskAgentOverlays !== 'object' || Array.isArray(taskAgentOverlays)) {
+            throw new Error('agent_bundle_task_agent_overlays_invalid');
+        }
+        for (const [rawKind, rawSource] of Object.entries(taskAgentOverlays)) {
+            if (!WORKER_SUPPORTED_KINDS.includes(rawKind)) {
+                throw new Error(`agent_bundle_task_agent_overlay_kind_invalid:${rawKind}`);
+            }
+            const source = normalizeAgentBundlePath(extractedRoot, rawSource, 'agent_bundle_task_agent_overlay_source_invalid');
+            if (!isFile(source)) {
+                throw new Error(`agent_bundle_task_agent_overlay_source_missing:${rawSource ?? ''}`);
+            }
+        }
+    }
     return { manifest, pluginRoot };
 }
-async function stageAgentBundleWorkspaceFiles(extractedRoot, workspaceDir) {
+async function stageAgentBundleWorkspaceFiles(extractedRoot, workspaceDir, taskKind) {
     const resolved = readAgentBundleManifest(extractedRoot);
     for (const entry of resolved.manifest.workspace.files) {
         const source = normalizeAgentBundlePath(extractedRoot, entry.source, 'agent_bundle_workspace_source_invalid');
@@ -1072,6 +1134,16 @@ async function stageAgentBundleWorkspaceFiles(extractedRoot, workspaceDir) {
         await (0, promises_1.mkdir)(node_path_1.default.dirname(destination), { recursive: true });
         await (0, promises_1.copyFile)(source, destination);
     }
+    const overlaySource = taskKind
+        ? resolved.manifest.workspace.taskAgentOverlays?.[taskKind]
+        : null;
+    if (overlaySource) {
+        const agentsPath = resolveWorkspaceFileDestination(workspaceDir, 'AGENTS.md');
+        const overlayPath = normalizeAgentBundlePath(extractedRoot, overlaySource, 'agent_bundle_task_agent_overlay_source_invalid');
+        const base = (0, node_fs_1.readFileSync)(agentsPath, 'utf8').trimEnd();
+        const overlay = (0, node_fs_1.readFileSync)(overlayPath, 'utf8').trim();
+        await (0, promises_1.writeFile)(agentsPath, `${base}\n\n${overlay}\n`, 'utf8');
+    }
     return resolved.pluginRoot;
 }
 async function stageAssignmentPluginBundle(input) {
@@ -1127,7 +1199,7 @@ async function stageAssignmentPluginBundle(input) {
         await (0, promises_1.mkdir)(node_path_1.default.dirname(destination), { recursive: true });
         await (0, promises_1.writeFile)(destination, Buffer.from(content));
     }
-    return await stageAgentBundleWorkspaceFiles(pluginRoot, input.workspaceDir);
+    return await stageAgentBundleWorkspaceFiles(pluginRoot, input.workspaceDir, input.taskKind);
 }
 function resolveDevPluginWorkingTree(input) {
     const workingTree = input.workingTree?.trim();
@@ -1946,8 +2018,22 @@ async function runCodex(input) {
             env: pluginEnv,
         });
     }
+    if (input.enablePlaywrightMcp) {
+        const server = (0, runtime_1.buildPlaywrightMcpCommand)(input.instrumentSurface);
+        await execFileAsync('codex', ['mcp', 'add', 'playwright', '--', server.command, ...server.args], {
+            cwd: input.workspaceDir,
+            env: {
+                ...node_process_1.default.env,
+                HOME: homeDir,
+                CODEX_HOME: codexHomeDir,
+            },
+        });
+    }
     let observedCodexThreadId = null;
     let codexThreadProbe = '';
+    const screenshotCollector = input.enablePlaywrightMcp
+        ? (0, instrument_evidence_1.createWorkerInstrumentScreenshotCollector)(input.workspaceDir)
+        : null;
     const result = await (0, runtime_1.runLoggedProcess)({
         command: 'codex',
         args: (0, runtime_1.buildCodexExecArgs)({
@@ -1981,9 +2067,13 @@ async function runCodex(input) {
             }
             await input.onTranscriptChunks(chunks);
         },
+        ...(screenshotCollector
+            ? { onStdoutText: (text) => screenshotCollector.push(text) > 0 }
+            : {}),
         transcriptFlushIntervalMs: runtime_1.DEFAULT_TRANSCRIPT_FLUSH_INTERVAL_MS,
         onChild: input.onChild,
     });
+    screenshotCollector?.finish();
     observedCodexThreadId = observedCodexThreadId
         ?? (0, runtime_1.extractCodexThreadId)(`${result.stdout}\n${result.stderr}\n${result.outputTail}`);
     if (!observedCodexThreadId) {
@@ -2026,7 +2116,7 @@ async function runClaude(input) {
     if (input.enablePlaywrightMcp) {
         playwrightMcpConfigPath = node_path_1.default.join(input.workspaceDir, '.playdrop', 'claude-run', 'playwright-mcp.json');
         (0, node_fs_1.mkdirSync)(node_path_1.default.dirname(playwrightMcpConfigPath), { recursive: true });
-        (0, node_fs_1.writeFileSync)(playwrightMcpConfigPath, `${JSON.stringify((0, runtime_1.buildPlaywrightMcpServerConfig)(), null, 2)}\n`, 'utf8');
+        (0, node_fs_1.writeFileSync)(playwrightMcpConfigPath, `${JSON.stringify((0, runtime_1.buildPlaywrightMcpServerConfig)(input.instrumentSurface), null, 2)}\n`, 'utf8');
     }
     const result = await (0, runtime_1.runLoggedProcess)({
         command: 'claude',
@@ -3381,21 +3471,26 @@ async function writeManagedWorkerLaunchAgent(input) {
 </dict>
 </plist>
 `;
+    const previousPlist = (0, node_fs_1.existsSync)(plistPath) ? (0, node_fs_1.readFileSync)(plistPath, 'utf8') : null;
+    const registrationChanged = previousPlist !== plist;
     await (0, promises_1.writeFile)(plistPath, plist, 'utf8');
-    return { label, plistPath };
+    return { label, plistPath, registrationChanged };
 }
-function launchManagedWorker(label, plistPath) {
-    const uid = typeof node_process_1.default.getuid === 'function' ? node_process_1.default.getuid() : null;
+function launchManagedWorker(label, plistPath, options) {
+    const uid = options.uid ?? (typeof node_process_1.default.getuid === 'function' ? node_process_1.default.getuid() : null);
     if (uid === null) {
         throw new Error('worker_setup_launchagent_uid_unavailable');
     }
+    const runCommand = options.runCommand ?? shellProbe_1.runShell;
     const domain = `gui/${uid}`;
-    (0, shellProbe_1.runShell)(`launchctl bootout ${shellQuote(`${domain}/${label}`)}`);
-    const bootstrap = (0, shellProbe_1.runShell)(`launchctl bootstrap ${shellQuote(domain)} ${shellQuote(plistPath)}`);
-    if (bootstrap.exitCode !== 0) {
-        throw new Error(`worker_setup_launchagent_start_failed: launchctl bootstrap exited with code ${bootstrap.exitCode}. ${bootstrap.output.slice(0, 300)}`);
+    if (options.registrationChanged) {
+        runCommand(`launchctl bootout ${shellQuote(`${domain}/${label}`)}`);
+        const bootstrap = runCommand(`launchctl bootstrap ${shellQuote(domain)} ${shellQuote(plistPath)}`);
+        if (bootstrap.exitCode !== 0) {
+            throw new Error(`worker_setup_launchagent_start_failed: launchctl bootstrap exited with code ${bootstrap.exitCode}. ${bootstrap.output.slice(0, 300)}`);
+        }
     }
-    const kickstart = (0, shellProbe_1.runShell)(`launchctl kickstart -k ${shellQuote(`${domain}/${label}`)}`);
+    const kickstart = runCommand(`launchctl kickstart -k ${shellQuote(`${domain}/${label}`)}`);
     if (kickstart.exitCode !== 0) {
         throw new Error(`worker_setup_launchagent_start_failed: launchctl kickstart exited with code ${kickstart.exitCode}. ${kickstart.output.slice(0, 300)}`);
     }
@@ -3532,7 +3627,7 @@ async function setupWorker(options = {}) {
         }
         verifyNpmGlobalInstallPreconditions();
         const { wrapperPath, policyFile } = await writeManagedWorkerWrapper({ env, workerName, workerKey });
-        const { label, plistPath } = await writeManagedWorkerLaunchAgent({ env, workerName, wrapperPath });
+        const { label, plistPath, registrationChanged } = await writeManagedWorkerLaunchAgent({ env, workerName, wrapperPath });
         const status = await resolveWorkerStatusPayload({ env });
         const activeTaskCount = status.server.worker?.activeTaskCount ?? 0;
         const shouldStart = options.start !== false;
@@ -3550,7 +3645,7 @@ async function setupWorker(options = {}) {
             return;
         }
         if (shouldStart || options.restart) {
-            launchManagedWorker(label, plistPath);
+            launchManagedWorker(label, plistPath, { registrationChanged });
         }
         (0, output_1.printSuccess)('Managed worker setup complete.', [
             `Wrapper: ${wrapperPath}`,
@@ -4027,11 +4122,12 @@ async function startWorker(options = {}) {
                     };
                     await stageAssignmentWorkspaceV2(workspaceDir, assignment.workspace);
                     const assignmentPluginRoot = devPluginWorkingTree
-                        ? await stageAgentBundleWorkspaceFiles(devPluginWorkingTree, workspaceDir)
+                        ? await stageAgentBundleWorkspaceFiles(devPluginWorkingTree, workspaceDir, task.kind)
                         : assignment.plugin
                             ? await stageAssignmentPluginBundle({
                                 workspaceDir,
                                 pluginBundle: assignment.plugin,
+                                taskKind: task.kind,
                             })
                             : null;
                     availableSkillPaths = listPluginSkillPaths(assignmentPluginRoot);
@@ -4118,6 +4214,8 @@ async function startWorker(options = {}) {
                             devPort,
                             codexModel: codexModel ?? resolveCodexModel(assignment.agent.model),
                             taskPluginRoot: assignmentPluginRoot,
+                            enablePlaywrightMcp: assignment.agent.browser === 'PLAYWRIGHT',
+                            instrumentSurface: resolveWorkerInstrumentSurface(taskContext),
                             imagePaths: imageAttachments.map((attachment) => attachment.path),
                             onTranscriptChunks: async (chunks) => {
                                 await appendTranscriptChunks(chunks);
@@ -4135,6 +4233,7 @@ async function startWorker(options = {}) {
                             prompt,
                             enableChrome: assignment.agent.browser === 'CHROME',
                             enablePlaywrightMcp: assignment.agent.browser === 'PLAYWRIGHT',
+                            instrumentSurface: resolveWorkerInstrumentSurface(taskContext),
                             envName: env,
                             workerUsername: username,
                             taskId: task.id,

package/dist/index.js

@@ -1021,12 +1021,14 @@ project
     .option('--timeout <seconds>', 'Load-check timeout in seconds')
     .option('--screenshot <path>', 'Screenshot output path')
     .option('--actions <path>', 'JSON action script to dispatch after the game frame is ready')
+    .option('--tape <surface>', 'Run matched idle and catalogue playtest-tape captures on a declared surface')
     .action(async (target, opts = {}) => {
     await (0, check_1.check)(target, {
         app: opts.app,
         timeout: opts.timeout,
         screenshot: opts.screenshot,
         actions: opts.actions,
+        tape: opts.tape,
     });
 });
 const projectCapture = project.command('capture').description('Record game media with the native macOS recorder');

package/node_modules/@playdrop/config/client-meta.json

@@ -1,7 +1,7 @@
 {
-  "version": "0.12.37",
+  "version": "0.12.39",
   "build": 1,
-  "runtimeSdkVersion": "0.12.37",
+  "runtimeSdkVersion": "0.12.39",
   "runtimeSdkBuild": 1,
   "clients": {
     "all": {