@playdrop/playdrop-cli 0.13.16 → 0.14.0

package/dist/commands/worker.js

@@ -7,6 +7,7 @@ exports.WORKER_TASK_WORKSPACE_RETENTION = exports.WORKER_CONTEXT_COMMAND_NOT_ALL
 exports.usesCreatorRecovery = usesCreatorRecovery;
 exports.buildCreatorRecoveryPrompt = buildCreatorRecoveryPrompt;
 exports.buildGameEvalRetryPrompt = buildGameEvalRetryPrompt;
+exports.resolveInitialCreatorProgress = resolveInitialCreatorProgress;
 exports.allocateWorkerDevPort = allocateWorkerDevPort;
 exports.isWorkerContextCommandAllowed = isWorkerContextCommandAllowed;
 exports.resolveWorkerExecutionTargetFromRole = resolveWorkerExecutionTargetFromRole;
@@ -50,6 +51,7 @@ exports.removeAgentRunCredentials = removeAgentRunCredentials;
 exports.removeStaleAgentRunCredentials = removeStaleAgentRunCredentials;
 exports.mergeCreatorRecoveryResults = mergeCreatorRecoveryResults;
 exports.buildAgentFailureCode = buildAgentFailureCode;
+exports.classifyAgentAvailabilityFailureReason = classifyAgentAvailabilityFailureReason;
 exports.describeAgentFailureForEvent = describeAgentFailureForEvent;
 exports.createLocalPlaydropShim = createLocalPlaydropShim;
 exports.parseCodexModelCatalog = parseCodexModelCatalog;
@@ -80,6 +82,8 @@ exports.assignmentRequiresRegisteredBundle = assignmentRequiresRegisteredBundle;
 exports.startWorker = startWorker;
 exports.reportTask = reportTask;
 exports.showTaskContext = showTaskContext;
+exports.assertTaskAssetMaterialIsTransparentPng = assertTaskAssetMaterialIsTransparentPng;
+exports.materialTask = materialTask;
 exports.reportCatalogueTask = reportCatalogueTask;
 exports.uploadTask = uploadTask;
 exports.claimSlugTask = claimSlugTask;
@@ -101,6 +105,7 @@ const node_os_1 = __importDefault(require("node:os"));
 const node_path_1 = __importDefault(require("node:path"));
 const node_process_1 = __importDefault(require("node:process"));
 const node_util_1 = require("node:util");
+const sharp_1 = __importDefault(require("sharp"));
 const apiClient_1 = require("../apiClient");
 const clientInfo_1 = require("../clientInfo");
 const commandContext_1 = require("../commandContext");
@@ -196,6 +201,7 @@ const WORKER_CONTEXT_ALLOWED_COMMANDS = [
     ['task', 'context'],
     ['task', 'help'],
     ['task', 'report'],
+    ['task', 'material'],
     ['task', 'report-catalogue'],
     ['task', 'claim-slug'],
     ['task', 'upload'],
@@ -227,6 +233,33 @@ const WORKER_CONTEXT_ALLOWED_COMMANDS = [
     ['ai', 'generations'],
 ];
 exports.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.';
+function resolveInitialCreatorProgress(kind, creationRecovery = false) {
+    if (creationRecovery) {
+        return null;
+    }
+    if (kind === 'NEW_GAME') {
+        return {
+            kind: 'progress',
+            phase: 'setup',
+            current: 'Reviewing your game idea',
+        };
+    }
+    if (kind === 'REMIX_GAME') {
+        return {
+            kind: 'progress',
+            phase: 'setup',
+            current: 'Reviewing the source game and your idea',
+        };
+    }
+    if (kind === 'GAME_UPDATE') {
+        return {
+            kind: 'progress',
+            phase: 'setup',
+            current: 'Reviewing your game and requested change',
+        };
+    }
+    return null;
+}
 function allocateWorkerDevPort(input) {
     const basePort = input.basePort ?? DEFAULT_WORKER_DEV_PORT_BASE;
     const maxParallelTasks = input.maxParallelTasks ?? DEFAULT_WORKER_MAX_PARALLEL_TASKS;
@@ -591,6 +624,13 @@ function buildWorkerTaskContext(input) {
     const outputAppName = typeof output?.appName === 'string' && output.appName.trim()
         ? output.appName.trim()
         : null;
+    const outputDisplayName = typeof output?.displayName === 'string' && output.displayName.trim()
+        ? output.displayName.trim()
+        : null;
+    const outputSubtitle = typeof output?.subtitle === 'string' && output.subtitle.trim()
+        ? output.subtitle.trim()
+        : null;
+    const outputPrimarySurface = normalizeWorkerInstrumentSurface(output?.primarySurface);
     if (!creatorUsername || !outputVersion) {
         throw new Error('agent_task_context_invalid');
     }
@@ -621,6 +661,9 @@ function buildWorkerTaskContext(input) {
         creatorRequest: input.prompt,
         target: input.target,
         outputAppName,
+        outputDisplayName,
+        outputSubtitle,
+        outputPrimarySurface,
         outputVersion,
         remixSourceRef,
         allowedTemplateKeys,
@@ -703,6 +746,9 @@ function workerTaskContextPath(workspaceDir) {
 function workerTaskUploadResultPath(workspaceDir) {
     return node_path_1.default.join(workspaceDir, '.playdrop', 'task-upload-result.json');
 }
+function workerTaskMaterialsPath(workspaceDir) {
+    return node_path_1.default.join(workspaceDir, '.playdrop', 'task-materials.json');
+}
 function serializeWorkerTaskContext(taskContext) {
     const playdrop = taskContext.metadata.playdrop;
     if (!playdrop || typeof playdrop !== 'object' || Array.isArray(playdrop)) {
@@ -720,6 +766,9 @@ function serializeWorkerTaskContext(taskContext) {
             output: {
                 ...output,
                 appName: taskContext.outputAppName,
+                displayName: taskContext.outputDisplayName,
+                subtitle: taskContext.outputSubtitle,
+                primarySurface: taskContext.outputPrimarySurface,
             },
         },
     };
@@ -887,6 +936,28 @@ function normalizeTaskClaimSlugDisplayName(value) {
     }
     return displayName;
 }
+function normalizeTaskClaimSlugSubtitle(value) {
+    if (value === undefined) {
+        return null;
+    }
+    const subtitle = typeof value === 'string' ? value.trim() : '';
+    if (!subtitle || subtitle.length > 120) {
+        throw new Error('invalid_app_subtitle');
+    }
+    return subtitle;
+}
+function normalizeTaskClaimSlugPrimarySurface(value) {
+    if (value === undefined) {
+        return null;
+    }
+    const primarySurface = typeof value === 'string' ? value.trim().toUpperCase() : '';
+    if (primarySurface !== 'DESKTOP'
+        && primarySurface !== 'MOBILE_LANDSCAPE'
+        && primarySurface !== 'MOBILE_PORTRAIT') {
+        throw new Error('invalid_primary_surface');
+    }
+    return primarySurface;
+}
 function readTaskNextStepsFile(filePath) {
     const normalizedPath = typeof filePath === 'string' ? filePath.trim() : '';
     if (!normalizedPath) {
@@ -1447,11 +1518,7 @@ function resolveWorkerEventQueueDir() {
     const eventDir = node_process_1.default.env.PLAYDROP_WORKER_EVENT_DIR?.trim();
     return eventDir || null;
 }
-function enqueueWorkerContextEvent(event) {
-    const eventDir = resolveWorkerEventQueueDir();
-    if (!eventDir) {
-        throw new Error('task_context_event_queue_missing');
-    }
+function enqueueWorkerEvent(eventDir, event) {
     (0, node_fs_1.mkdirSync)(eventDir, { recursive: true });
     const eventId = `${Date.now()}-${crypto.randomUUID()}`;
     const tmpPath = node_path_1.default.join(eventDir, `${eventId}.tmp`);
@@ -1459,6 +1526,13 @@ function enqueueWorkerContextEvent(event) {
     (0, node_fs_1.writeFileSync)(tmpPath, JSON.stringify(event), 'utf8');
     (0, node_fs_1.renameSync)(tmpPath, finalPath);
 }
+function enqueueWorkerContextEvent(event) {
+    const eventDir = resolveWorkerEventQueueDir();
+    if (!eventDir) {
+        throw new Error('task_context_event_queue_missing');
+    }
+    enqueueWorkerEvent(eventDir, event);
+}
 function resolveWorkerTaskStateForWrite() {
     const state = readWorkerTaskState();
     if (!state) {
@@ -1838,6 +1912,9 @@ function buildCataloguePreviewPayload(cataloguePath, workspaceDir = node_path_1.
     const displayName = normalizePreviewString(app.displayName);
     if (displayName)
         catalogue.displayName = displayName;
+    const subtitle = normalizePreviewString(app.subtitle);
+    if (subtitle)
+        catalogue.subtitle = subtitle;
     const description = normalizePreviewString(app.description);
     if (description)
         catalogue.description = description;
@@ -1850,6 +1927,9 @@ function buildCataloguePreviewPayload(cataloguePath, workspaceDir = node_path_1.
     const version = normalizePreviewString(app.version);
     if (version)
         catalogue.version = version;
+    const primarySurface = normalizePreviewString(app.primarySurface);
+    if (primarySurface)
+        catalogue.primarySurface = primarySurface;
     const releaseNotes = normalizePreviewString(app.releaseNotes);
     if (releaseNotes)
         catalogue.releaseNotes = releaseNotes;
@@ -2486,18 +2566,36 @@ function buildAgentFailureCode(agent, result, request) {
     if (combinedOutput.includes('agent_task_creation_recovery_timeout')) {
         return `agent_task_creation_recovery_timeout:${provider}`;
     }
+    const providerStatus = extractProviderStatusCode(combinedOutput);
+    if (/\b(?:usage|spending|token|credit)?\s*(?:limit|quota)\s+(?:has been |was )?(?:reached|exceeded|exhausted)\b/i.test(combinedOutput)
+        || /\byou(?:'ve| have) hit your (?:usage )?limit\b/i.test(combinedOutput)
+        || /\binsufficient_quota\b/i.test(combinedOutput)) {
+        return `agent_provider_quota_exhausted:${provider}`;
+    }
+    if (/\b(?:not logged in|authentication required|please (?:run|use) (?:the )?(?:login|\/login)|oauth token expired)\b/i.test(combinedOutput)
+        || /\b(?:401|403)\s+(?:unauthorized|forbidden)\b/i.test(combinedOutput)) {
+        return `agent_provider_not_authenticated:${provider}`;
+    }
     if (request
         && (/\b(?:unknown|invalid|unsupported)\s+(?:model|effort)\b/i.test(combinedOutput)
             || /\b(?:model|effort)\b.{0,80}\b(?:not found|not available|does not exist|is unavailable|is not supported)\b/i.test(combinedOutput))) {
         return `requested_model_unavailable:${agent}:${request.model}:${request.reasoningEffort ?? ''}`;
     }
-    const providerStatus = extractProviderStatusCode(combinedOutput);
     if (providerStatus === 529 || (/\b529\b/.test(combinedOutput) && /\boverloaded?\b/i.test(combinedOutput))) {
         return `agent_provider_overloaded:${provider}:529`;
     }
-    if (/\boverloaded?\b/i.test(combinedOutput)) {
+    if (/\boverloaded?\b/i.test(combinedOutput)
+        || /\b(?:selected\s+)?model\s+is\s+at\s+capacity\b/i.test(combinedOutput)) {
         return `agent_provider_overloaded:${provider}`;
     }
+    if (providerStatus === 429
+        || providerStatus === 502
+        || providerStatus === 503
+        || providerStatus === 504
+        || /\b(?:service|provider|api)\s+(?:is\s+)?(?:temporarily\s+)?unavailable\b/i.test(combinedOutput)
+        || /\btoo many requests\b/i.test(combinedOutput)) {
+        return `agent_provider_temporarily_unavailable:${provider}${providerStatus ? `:${providerStatus}` : ''}`;
+    }
     if (result.timedOut) {
         return `agent_provider_timeout:${provider}`;
     }
@@ -2509,6 +2607,22 @@ function buildAgentFailureCode(agent, result, request) {
     }
     return `agent_unknown_exit:${provider}`;
 }
+function classifyAgentAvailabilityFailureReason(errorCode) {
+    if (errorCode.startsWith('agent_provider_not_authenticated:')) {
+        return 'agent_not_authenticated';
+    }
+    if (errorCode.startsWith('agent_provider_quota_exhausted:')) {
+        return 'agent_quota_exhausted';
+    }
+    if (errorCode.startsWith('agent_provider_overloaded:')
+        || errorCode.startsWith('agent_provider_temporarily_unavailable:')) {
+        return 'agent_temporarily_unavailable';
+    }
+    if (errorCode.startsWith('requested_model_unavailable:')) {
+        return 'agent_model_unsupported';
+    }
+    return null;
+}
 function describeAgentFailureForEvent(errorCode) {
     const [code, provider, detail] = errorCode.split(':');
     if (code === 'requested_model_unavailable') {
@@ -2517,8 +2631,19 @@ function describeAgentFailureForEvent(errorCode) {
     const providerLabel = provider === 'claude' ? 'Claude' : provider === 'codex' ? 'Codex' : 'The agent provider';
     if (code === 'agent_provider_overloaded') {
         return detail
-            ? `${providerLabel} is overloaded (API ${detail}). Retry this task in a few minutes.`
-            : `${providerLabel} is overloaded. Retry this task in a few minutes.`;
+            ? `${providerLabel} is overloaded (API ${detail}). Reporting provider unavailability to the server.`
+            : `${providerLabel} is overloaded. Reporting provider unavailability to the server.`;
+    }
+    if (code === 'agent_provider_quota_exhausted') {
+        return `${providerLabel} has reached its usage limit. Reporting provider unavailability to the server.`;
+    }
+    if (code === 'agent_provider_not_authenticated') {
+        return `${providerLabel} is not authenticated on this worker. Reporting provider unavailability to the server.`;
+    }
+    if (code === 'agent_provider_temporarily_unavailable') {
+        return detail
+            ? `${providerLabel} is temporarily unavailable (API ${detail}). Reporting provider unavailability to the server.`
+            : `${providerLabel} is temporarily unavailable. Reporting provider unavailability to the server.`;
     }
     if (code === 'agent_provider_timeout') {
         return `${providerLabel} timed out before completing the task. Retry this task when the provider is healthy.`;
@@ -4496,6 +4621,27 @@ async function startWorker(options = {}) {
                     if (shuttingDown) {
                         throw new Error('worker_shutdown');
                     }
+                    let initialCreatorProgressAttempted = false;
+                    const handleAgentChild = (controls) => {
+                        activeTerminators.set(task.id, controls.terminate);
+                        if (initialCreatorProgressAttempted) {
+                            return;
+                        }
+                        initialCreatorProgressAttempted = true;
+                        const initialProgress = resolveInitialCreatorProgress(task.kind, startsInCreationRecovery);
+                        if (!initialProgress) {
+                            return;
+                        }
+                        try {
+                            enqueueWorkerEvent(eventDir, initialProgress);
+                            queueEventDrain().catch((error) => {
+                                handleEventDrainFailure(error);
+                            });
+                        }
+                        catch (error) {
+                            console.error(`Warning: initial creator progress was not queued: ${error instanceof Error ? error.message : String(error)}`);
+                        }
+                    };
                     const runAssignedAgent = async (input) => {
                         if (assignment.agent.runtime === 'CODEX') {
                             return runCodex({
@@ -4518,9 +4664,7 @@ async function startWorker(options = {}) {
                                 onTranscriptChunks: async (chunks) => {
                                     await appendTranscriptChunks(chunks);
                                 },
-                                onChild: (controls) => {
-                                    activeTerminators.set(task.id, controls.terminate);
-                                },
+                                onChild: handleAgentChild,
                                 cleanRoom,
                                 timeoutMs: input.timeoutMs,
                                 resumeSessionId: input.resumeSessionId,
@@ -4548,9 +4692,7 @@ async function startWorker(options = {}) {
                                 onTranscriptChunks: async (chunks) => {
                                     await appendTranscriptChunks(chunks);
                                 },
-                                onChild: (controls) => {
-                                    activeTerminators.set(task.id, controls.terminate);
-                                },
+                                onChild: handleAgentChild,
                                 cleanRoom,
                                 timeoutMs: input.timeoutMs,
                                 resumeSessionId: input.resumeSessionId,
@@ -4560,7 +4702,6 @@ async function startWorker(options = {}) {
                             await client.workerRecordAgentTaskAttemptUnavailable(task.id, {
                                 workerKey,
                                 leaseToken,
-                                attemptIndex: 0,
                                 reason: 'unavailable_runtime',
                                 message: 'Cursor Composer noninteractive worker execution is not configured on this worker.',
                             });
@@ -4686,6 +4827,7 @@ async function startWorker(options = {}) {
                                 model: assignment.agent.model,
                                 reasoningEffort,
                             });
+                            const availabilityReason = classifyAgentAvailabilityFailureReason(failureCode);
                             await client.workerCreateAgentTaskEvent(task.id, {
                                 workerKey,
                                 leaseToken,
@@ -4695,14 +4837,32 @@ async function startWorker(options = {}) {
                                 pct: null,
                                 payload: { error: failureCode },
                             });
-                            await failTaskWithRetry(client, task.id, {
-                                workerKey,
-                                leaseToken,
-                                error: failureCode,
-                                terminalReason: (0, types_1.classifyAgentTaskTerminalReason)(agentFailureRawError(completedAgentResult), 'agent'),
-                                result: agentRunResult,
-                            });
-                            await reportTelemetry('FAILED');
+                            if (availabilityReason) {
+                                retainWorkspace = false;
+                                await reportTelemetry('FAILED').catch((error) => {
+                                    console.error(`Agent task ${task.id} telemetry failed before provider handoff: ${error instanceof Error ? error.message : String(error)}`);
+                                });
+                                const unavailable = await client.workerRecordAgentTaskAttemptUnavailable(task.id, {
+                                    workerKey,
+                                    leaseToken,
+                                    reason: availabilityReason,
+                                    message: failureCode,
+                                });
+                                fenced = true;
+                                console.error(unavailable.requeued
+                                    ? `Agent task ${task.id} reported ${availabilityReason}; the server queued the next approved attempt.`
+                                    : `Agent task ${task.id} reported ${availabilityReason}; no approved attempts remain.`);
+                            }
+                            else {
+                                await failTaskWithRetry(client, task.id, {
+                                    workerKey,
+                                    leaseToken,
+                                    error: failureCode,
+                                    terminalReason: (0, types_1.classifyAgentTaskTerminalReason)(failureCode, 'agent'),
+                                    result: agentRunResult,
+                                });
+                                await reportTelemetry('FAILED');
+                            }
                         }
                     }
                     else {
@@ -5114,7 +5274,7 @@ async function reportTask(options) {
     const done = options.done?.trim() || null;
     const current = options.current?.trim() || null;
     if (!message && !done && !current) {
-        (0, messages_1.printErrorWithHelp)('Task report requires a message, done, or current value.', ['Example: playdrop task report --phase build --done "Built the first loop" --current "Tuning controls"'], { command: 'task report' });
+        (0, messages_1.printErrorWithHelp)('Task report requires a message, done, or current value.', ['Example: playdrop task report --phase greybox-core-loop --done "Built the first loop" --current "Tuning controls"'], { command: 'task report' });
         node_process_1.default.exitCode = 1;
         return;
     }
@@ -5150,6 +5310,131 @@ function showTaskContext() {
         },
     }, null, 2));
 }
+function readWorkerTaskMaterialReceipts(workspaceDir) {
+    const receiptPath = workerTaskMaterialsPath(workspaceDir);
+    if (!(0, node_fs_1.existsSync)(receiptPath)) {
+        return [];
+    }
+    const parsed = JSON.parse((0, node_fs_1.readFileSync)(receiptPath, 'utf8'));
+    if (!Array.isArray(parsed)) {
+        throw new Error('task_material_receipts_invalid');
+    }
+    return parsed.map((entry) => {
+        if (!entry || typeof entry !== 'object' || Array.isArray(entry)) {
+            throw new Error('task_material_receipts_invalid');
+        }
+        const candidate = entry;
+        const filePath = typeof candidate.filePath === 'string' ? candidate.filePath.trim() : '';
+        const sha256 = typeof candidate.sha256 === 'string' ? candidate.sha256.trim() : '';
+        const presentation = candidate.presentation;
+        const title = typeof candidate.title === 'string' ? candidate.title.trim() : '';
+        if (!node_path_1.default.isAbsolute(filePath)
+            || !/^[a-f0-9]{64}$/.test(sha256)
+            || (presentation !== 'frame' && presentation !== 'asset')
+            || !title) {
+            throw new Error('task_material_receipts_invalid');
+        }
+        return { filePath, sha256, presentation, title };
+    });
+}
+function recordWorkerTaskMaterialReceipt(workspaceDir, receipt) {
+    const receipts = readWorkerTaskMaterialReceipts(workspaceDir);
+    const retained = receipts.filter((entry) => (entry.filePath !== receipt.filePath
+        || entry.presentation !== receipt.presentation));
+    retained.push(receipt);
+    (0, node_fs_1.writeFileSync)(workerTaskMaterialsPath(workspaceDir), `${JSON.stringify(retained, null, 2)}\n`, 'utf8');
+}
+async function assertTaskAssetMaterialIsTransparentPng(filePath) {
+    let metadata;
+    let stats;
+    try {
+        metadata = await (0, sharp_1.default)(filePath, { failOn: 'error' }).metadata();
+        stats = await (0, sharp_1.default)(filePath, { failOn: 'error' }).stats();
+    }
+    catch {
+        throw new Error(`task_material_asset_decode_failed:${filePath}`);
+    }
+    if (metadata.format !== 'png') {
+        throw new Error(`task_material_asset_must_be_png:${filePath}`);
+    }
+    if (metadata.hasAlpha !== true || stats.isOpaque) {
+        throw new Error(`task_material_asset_background_not_removed:${filePath}`);
+    }
+}
+async function materialTask(options) {
+    try {
+        const fileOption = options.file?.trim() ?? '';
+        const title = options.title?.trim() ?? '';
+        if (!fileOption || !title || title.length > 60 || title.split(/\s+/).length > 3) {
+            throw new Error('task_material_file_and_title_required');
+        }
+        const filePath = node_path_1.default.resolve(fileOption);
+        if (!(0, node_fs_1.existsSync)(filePath) || !(0, node_fs_1.statSync)(filePath).isFile()) {
+            throw new Error(`task_material_file_not_found:${fileOption}`);
+        }
+        const posterOption = options.poster?.trim() ?? '';
+        const posterPath = posterOption ? node_path_1.default.resolve(posterOption) : null;
+        if (posterPath && (!(0, node_fs_1.existsSync)(posterPath) || !(0, node_fs_1.statSync)(posterPath).isFile())) {
+            throw new Error(`task_material_poster_not_found:${posterOption}`);
+        }
+        const presentation = options.asset ? 'asset' : 'frame';
+        if (presentation === 'asset') {
+            if (posterPath) {
+                throw new Error('task_material_asset_poster_not_allowed');
+            }
+            await assertTaskAssetMaterialIsTransparentPng(filePath);
+        }
+        const taskContext = readTaskContextFile();
+        const ctx = await resolveTaskCommandContext('task material', options.env, taskContext);
+        if (!ctx) {
+            throw new Error('task_material_context_unavailable');
+        }
+        const fileBuffer = (0, node_fs_1.readFileSync)(filePath);
+        const posterBuffer = posterPath ? (0, node_fs_1.readFileSync)(posterPath) : null;
+        const clientKey = (0, node_crypto_1.createHash)('sha256')
+            .update([
+            String(taskContext.taskId),
+            String(taskContext.attempt),
+            node_path_1.default.relative(node_process_1.default.cwd(), filePath),
+            (0, node_crypto_1.createHash)('sha256').update(fileBuffer).digest('hex'),
+            title,
+            posterBuffer ? (0, node_crypto_1.createHash)('sha256').update(posterBuffer).digest('hex') : '',
+            presentation,
+        ].join(':'))
+            .digest('hex')
+            .slice(0, 40);
+        await ctx.client.workerUploadAgentTaskMaterial(taskContext.taskId, {
+            file: new Blob([new Uint8Array(fileBuffer)]),
+            fileName: node_path_1.default.basename(filePath),
+            title,
+            clientKey,
+            presentation,
+            phase: options.phase?.trim() || undefined,
+            taskToken: taskContext.taskToken,
+            ...(posterBuffer && posterPath
+                ? {
+                    poster: new Blob([new Uint8Array(posterBuffer)]),
+                    posterFileName: node_path_1.default.basename(posterPath),
+                }
+                : {}),
+        });
+        recordWorkerTaskMaterialReceipt(resolveTaskWorkspaceDir(), {
+            filePath,
+            sha256: (0, node_crypto_1.createHash)('sha256').update(fileBuffer).digest('hex'),
+            presentation,
+            title,
+        });
+        (0, output_1.printSuccess)(`Task material shared: ${title}`);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        const suggestion = message.startsWith('task_material_asset_background_not_removed:')
+            ? ' Remove the background and retry with --asset, or omit --asset if the image is honestly useful as a full frame.'
+            : '';
+        console.warn(`Warning: task material was not shared: ${message}.${suggestion}`);
+        node_process_1.default.exitCode = 0;
+    }
+}
 async function reportCatalogueTask(options) {
     const message = options.message?.trim();
     if (!message) {
@@ -5216,6 +5501,38 @@ async function uploadTask(options = {}) {
     }
     const uploadKind = taskContext.kind;
     const workspaceDir = resolveTaskWorkspaceDir();
+    if (options.preflightOnly) {
+        const ctx = await resolveTaskCommandContext('task upload --preflight-only', options.env, taskContext);
+        if (!ctx) {
+            return;
+        }
+        const projectDir = discoverWorkerProjectRoot(node_process_1.default.cwd());
+        const result = await (0, upload_1.preflightWorkerAppProject)({
+            client: ctx.client,
+            taskId: taskContext.taskId,
+            taskToken: taskContext.taskToken,
+            kind: uploadKind,
+            executionTarget: taskContext.target,
+            expectedAppName: taskContext.outputAppName ?? undefined,
+            expectedDisplayName: taskContext.outputDisplayName,
+            expectedSubtitle: taskContext.outputSubtitle,
+            expectedPrimarySurface: taskContext.outputPrimarySurface,
+            remixSourceRef: taskContext.remixSourceRef ?? null,
+            playdropAssetRequirement: (0, upload_1.resolveWorkerPlaydropAssetRequirement)(taskContext.creatorRequest),
+            creatorRequest: taskContext.creatorRequest,
+            projectDir,
+            creatorUsername: taskContext.creatorUsername,
+            apiBase: ctx.envConfig.apiBase,
+            webBase: ctx.envConfig.webBase ?? null,
+            token: ctx.token,
+            user: ctx.user,
+        });
+        for (const warning of result.warnings) {
+            console.error(`Preflight warning: ${warning}`);
+        }
+        (0, output_1.printSuccess)(`Task upload preflight passed for ${result.creatorUsername}/${result.appName}. Final capture can start.`);
+        return;
+    }
     if ((0, node_fs_1.existsSync)(workerTaskUploadResultPath(workspaceDir))) {
         const existingResult = readTaskUploadResultFile(workspaceDir);
         assertTaskUploadResultMatchesContext({
@@ -5238,6 +5555,9 @@ async function uploadTask(options = {}) {
             kind: uploadKind,
             executionTarget: taskContext.target,
             expectedAppName: taskContext.outputAppName ?? undefined,
+            expectedDisplayName: taskContext.outputDisplayName,
+            expectedSubtitle: taskContext.outputSubtitle,
+            expectedPrimarySurface: taskContext.outputPrimarySurface,
             remixSourceRef: taskContext.remixSourceRef ?? null,
             playdropAssetRequirement: (0, upload_1.resolveWorkerPlaydropAssetRequirement)(taskContext.creatorRequest),
             creatorRequest: taskContext.creatorRequest,
@@ -5271,26 +5591,55 @@ async function claimSlugTask(options) {
     }
     const appName = normalizeTaskClaimSlugAppName(options.appName);
     const displayName = normalizeTaskClaimSlugDisplayName(options.displayName);
+    const subtitle = normalizeTaskClaimSlugSubtitle(options.subtitle);
+    const primarySurface = normalizeTaskClaimSlugPrimarySurface(options.primarySurface);
     const ctx = await resolveTaskCommandContext('task claim-slug', options.env, taskContext);
     if (!ctx) {
         return;
     }
-    const response = await ctx.client.workerClaimAgentTaskSlug(taskContext.taskId, {
+    const request = {
         appName,
         displayName,
-    });
+        ...(subtitle ? { subtitle } : {}),
+        ...(primarySurface ? { primarySurface } : {}),
+    };
+    const response = await ctx.client.workerClaimAgentTaskSlug(taskContext.taskId, request);
     const claimedAppName = typeof response.appName === 'string' && response.appName.trim()
         ? response.appName.trim()
         : '';
     if (claimedAppName !== appName) {
         throw new Error('task_claim_slug_response_mismatch');
     }
+    const hasResponseDisplayName = Object.prototype.hasOwnProperty.call(response, 'displayName');
+    const responseDisplayName = typeof response.displayName === 'string' && response.displayName.trim()
+        ? response.displayName.trim()
+        : '';
+    if (hasResponseDisplayName && responseDisplayName !== displayName) {
+        throw new Error('task_claim_identity_response_mismatch');
+    }
+    const hasResponseSubtitle = Object.prototype.hasOwnProperty.call(response, 'subtitle');
+    const responseSubtitle = typeof response.subtitle === 'string' && response.subtitle.trim()
+        ? response.subtitle.trim()
+        : null;
+    const hasResponsePrimarySurface = Object.prototype.hasOwnProperty.call(response, 'primarySurface');
+    const responsePrimarySurface = normalizeWorkerInstrumentSurface(response.primarySurface);
+    if ((subtitle && hasResponseSubtitle && responseSubtitle !== subtitle)
+        || (primarySurface && hasResponsePrimarySurface && responsePrimarySurface !== primarySurface)) {
+        throw new Error('task_claim_identity_response_mismatch');
+    }
+    const claimedSubtitle = subtitle ?? responseSubtitle ?? taskContext.outputSubtitle;
+    const claimedPrimarySurface = primarySurface ?? responsePrimarySurface ?? taskContext.outputPrimarySurface;
     const workspaceDir = resolveTaskWorkspaceDir();
     await writeWorkerTaskContextFile(workspaceDir, {
         ...taskContext,
         outputAppName: claimedAppName,
+        outputDisplayName: displayName,
+        outputSubtitle: claimedSubtitle,
+        outputPrimarySurface: claimedPrimarySurface,
     });
-    (0, output_1.printSuccess)(`Claimed app slug "${claimedAppName}" for ${displayName}.`);
+    (0, output_1.printSuccess)(claimedPrimarySurface
+        ? `Claimed "${displayName}" (${claimedAppName}) for ${claimedPrimarySurface}.`
+        : `Claimed app slug "${claimedAppName}" for ${displayName}.`);
 }
 async function completeTask(options) {
     const taskContext = readTaskContextFile();
@@ -5298,9 +5647,12 @@ async function completeTask(options) {
         throw new Error('task_done_not_allowed_for_game_review');
     }
     const summary = typeof options.summary === 'string' ? options.summary.trim() : '';
-    if (!summary || summary.length > 200 || /[\r\n]/.test(summary)) {
+    if (!summary || /[\r\n]/.test(summary)) {
         throw new Error('task_done_summary_required');
     }
+    if (summary.length > 200) {
+        throw new Error('task_done_summary_too_long:max_200_characters');
+    }
     const ctx = await resolveTaskCommandContext('task done', options.env, taskContext);
     if (!ctx) {
         return;