@playdrop/playdrop-cli 0.14.6 → 0.14.8

package/config/client-meta.json

@@ -1,7 +1,7 @@
 {
-  "version": "0.14.6",
+  "version": "0.14.8",
   "build": 1,
-  "runtimeSdkVersion": "0.14.6",
+  "runtimeSdkVersion": "0.14.8",
   "runtimeSdkBuild": 1,
   "clients": {
     "all": {

package/dist/apps/upload.js

@@ -245,6 +245,7 @@ async function uploadAppVersion(client, task, artifacts, options) {
         usesPacks: task.uses.packs,
         tags: task.tags,
         design: task.design,
+        tweaks: task.tweaks,
         clearTags: options?.clearTags,
         surfaceTargets: task.surfaceTargets,
         primarySurface: task.primarySurface,

package/dist/catalogue.d.ts

@@ -1,4 +1,4 @@
-import { type AppAchievementCatalogueDefinition, type AppAuthMode, type AppControllerMode, type AppHostingMode, type AppLeaderboardCatalogueDefinition, type AppListingMediaMetadata, type AppMetadataAssetSpecSupport, type AppPlaytestTapes, type AppSurface, type AppType, type AppVersionDesign, type AppVersionVisibility, type AssetSpecContract, type AssetSpecStatus, type AssetSpecValidationKind, type CatalogueTagGroupDefinition, type ContentLicense, type PlayerMetaDefinitionStatus } from '@playdrop/types';
+import { type AppAchievementCatalogueDefinition, type AppAuthMode, type AppControllerMode, type AppHostingMode, type AppLeaderboardCatalogueDefinition, type AppListingMediaMetadata, type AppMetadataAssetSpecSupport, type AppPlaytestTapes, type AppSurface, type AppType, type AppTweaksDeclaration, type AppVersionDesign, type AppVersionVisibility, type AssetSpecContract, type AssetSpecStatus, type AssetSpecValidationKind, type CatalogueTagGroupDefinition, type ContentLicense, type PlayerMetaDefinitionStatus } from '@playdrop/types';
 import { type AssetSpecSupportDeclaration } from './assetSpecs';
 export type CatalogueJson = {
     apps?: Array<Record<string, unknown>>;
@@ -54,6 +54,7 @@ export type AppCatalogueEntry = {
     primarySurface?: string | null;
     playtestTapes?: unknown;
     design?: unknown;
+    tweaks?: unknown;
     version?: string;
     releaseNotes?: string;
     visibility?: string;
@@ -196,6 +197,7 @@ export type AppTask = {
     primarySurface?: AppSurface;
     playtestTapes?: AppPlaytestTapes;
     design?: AppVersionDesign;
+    tweaks?: AppTweaksDeclaration;
     missingMetadata: string[];
     version?: string;
     releaseNotes?: string;

package/dist/catalogue.js

@@ -1375,6 +1375,15 @@ function buildAppTasks(rootDir, catalogues, options) {
                 }
                 design = parsedDesign.value;
             }
+            let tweaks;
+            if (Object.prototype.hasOwnProperty.call(entry, 'tweaks')) {
+                const parsedTweaks = (0, types_1.normalizeAppTweaks)(entry.tweaks);
+                if (!parsedTweaks.ok) {
+                    errors.push(`[${label}] App "${rawName}" ${parsedTweaks.error}`);
+                    continue;
+                }
+                tweaks = parsedTweaks.value;
+            }
             const errorCountBeforeTagMetadata = errors.length;
             const remix = normalizeCatalogueRemixRef(entry.remix, 'app', errors, `[${label}] App "${rawName}"`);
             const tags = normalizeCatalogueTags(entry.tags, errors, `[${label}] App "${rawName}"`);
@@ -1579,6 +1588,7 @@ function buildAppTasks(rootDir, catalogues, options) {
                 primarySurface: metadata.primarySurface,
                 playtestTapes: metadata.playtestTapes,
                 design,
+                tweaks,
                 missingMetadata: metadata.missingFields,
                 // Versioning fields
                 version,

package/dist/commands/dev.js

@@ -16,6 +16,7 @@ const http_1 = require("../http");
 const messages_1 = require("../messages");
 const devRuntimeAssets_1 = require("./devRuntimeAssets");
 const devServer_1 = require("./devServer");
+const tweakStaleness_1 = require("../tweakStaleness");
 const devShared_1 = require("./devShared");
 function formatDevRuntimeAssetManifestFailure(error) {
     const rawMessage = error instanceof Error ? error.message : String(error ?? 'unknown_error');
@@ -301,6 +302,14 @@ async function dev(targetArg, appOption, devOptions = {}) {
         });
         let runtimeAssetManifest = (0, devRuntimeAssets_1.createEmptyDevRuntimeAssetManifest)();
         if (taskLookup.task) {
+            try {
+                await (0, tweakStaleness_1.fetchAndAssertTweakState)(client, currentUsername, taskLookup.task);
+            }
+            catch (error) {
+                (0, messages_1.printErrorWithHelp)(error instanceof Error ? error.message : 'Could not verify the current tweak state.', [], { command: 'project dev' });
+                process.exitCode = 1;
+                return;
+            }
             try {
                 runtimeAssetManifest = await (0, devRuntimeAssets_1.buildDevRuntimeAssetManifest)({
                     client,

package/dist/commands/devRuntimeAssets.d.ts

@@ -1,5 +1,5 @@
 import type { ApiClient } from '@playdrop/api-client';
-import { type AppAuthMode, type AppControllerMode, type AppMetadataAssetSpecSupport, type AppRuntimeAssetsResponse, type AppSurface, type AppType } from '@playdrop/types';
+import { type AppAuthMode, type AppControllerMode, type AppMetadataAssetSpecSupport, type AppRuntimeAssetsResponse, type AppSurface, type AppType, type TweakValues } from '@playdrop/types';
 import type { AppTask } from '../catalogue';
 export type LocalOwnedRuntimeAssetFileRecord = {
     absolutePath: string;
@@ -14,6 +14,7 @@ export type LocalDevAppMetadata = {
     previewable: boolean;
     assetSpecSupport: AppMetadataAssetSpecSupport[];
     version: string | null;
+    tweakValues?: TweakValues;
 };
 export type DevRuntimeAssetsResponse = AppRuntimeAssetsResponse & {
     localAppMetadata: LocalDevAppMetadata;

package/dist/commands/devRuntimeAssets.js

@@ -124,6 +124,9 @@ function buildLocalAppMetadata(task) {
             capabilities: Array.from(entry.capabilities),
         })),
         version: typeof task.version === 'string' && task.version.trim().length > 0 ? task.version.trim() : null,
+        ...(task.tweaks && task.tweaks.removed !== true
+            ? { tweakValues: { ...task.tweaks.defaults } }
+            : {}),
     };
 }
 function assertCustomAssetVersionSupported(task, assetRef, version) {

package/dist/commands/notes.d.ts

@@ -0,0 +1,7 @@
+export declare function browseNotes(rawRef: string | undefined, options?: {
+    json?: boolean;
+    output?: string;
+}): Promise<void>;
+export declare function clearNotes(rawRef: string | undefined, rawIds: string[], options?: {
+    json?: boolean;
+}): Promise<void>;

package/dist/commands/notes.js

@@ -0,0 +1,107 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.browseNotes = browseNotes;
+exports.clearNotes = clearNotes;
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const types_1 = require("@playdrop/types");
+const commandContext_1 = require("../commandContext");
+const errors_1 = require("../errors");
+const messages_1 = require("../messages");
+const output_1 = require("../output");
+function notesApiMessage(error) {
+    if (error.code === 'playtest_notes_changed') {
+        const missingIds = Array.isArray(error.details?.['missingIds']) ? error.details['missingIds'] : [];
+        return {
+            problem: `The note inbox changed before it could be cleared${missingIds.length > 0 ? `: ${missingIds.join(', ')}` : '.'}`,
+            suggestions: ['Run notes browse again, then clear the current IDs.'],
+        };
+    }
+    return { problem: `PlayDrop rejected the notes request: ${error.code ?? error.message} (HTTP ${error.status}).` };
+}
+function parseAppVersionRef(raw, command) {
+    const ref = (0, types_1.parseContentVersionRef)(raw ?? '');
+    if (!ref || ref.kind !== 'app') {
+        (0, messages_1.printErrorWithHelp)('An exact canonical app-version ref is required.', ['Use app:creator/name@x.y.z.', `Example: playdrop ${command} app:olivier/platformer@1.4.0`], { command });
+        process.exitCode = 1;
+        return null;
+    }
+    return ref;
+}
+async function browseNotes(rawRef, options = {}) {
+    const ref = parseAppVersionRef(rawRef, 'notes browse');
+    if (!ref)
+        return;
+    await (0, commandContext_1.withEnvironment)('notes browse', 'Reading playtest notes', async ({ client }) => {
+        try {
+            const response = await client.listPlaytestNotes(ref.creatorUsername, ref.name, ref.version);
+            let output = response;
+            if (options.output) {
+                const outputDirectory = (0, node_path_1.resolve)(options.output);
+                (0, node_fs_1.mkdirSync)(outputDirectory, { recursive: true });
+                const notes = [];
+                for (const note of response.notes) {
+                    if (!note.attachment) {
+                        notes.push(note);
+                        continue;
+                    }
+                    const localPath = (0, node_path_1.resolve)(outputDirectory, `${note.id}-${note.attachment.fileName}`);
+                    const blob = await client.downloadPlaytestNoteAttachment(ref.creatorUsername, ref.name, ref.version, note.id);
+                    (0, node_fs_1.writeFileSync)(localPath, Buffer.from(await blob.arrayBuffer()));
+                    notes.push({ ...note, localPath });
+                }
+                output = { notes };
+                (0, node_fs_1.writeFileSync)((0, node_path_1.resolve)(outputDirectory, 'notes.json'), `${JSON.stringify(output, null, 2)}\n`, 'utf8');
+            }
+            if (options.json) {
+                (0, output_1.printJson)(output);
+                return;
+            }
+            if (options.output) {
+                (0, output_1.printSuccess)(`Materialized ${output.notes.length} playtest notes in ${(0, node_path_1.resolve)(options.output)}.`);
+                return;
+            }
+            if (output.notes.length === 0) {
+                console.log('No pending playtest notes.');
+                return;
+            }
+            for (const note of output.notes) {
+                const summary = note.kind === 'TEXT'
+                    ? note.text
+                    : note.kind === 'ASSET'
+                        ? `${note.assetRef}: ${note.comment}`
+                        : note.attachment?.fileName;
+                console.log(`${note.id}\t${note.kind}\tv${note.authoredVersion}\t${summary ?? ''}`);
+            }
+        }
+        catch (error) {
+            if (!(0, errors_1.handleCommandFailure)(error, 'notes browse', 'Read playtest notes', { apiMessage: notesApiMessage }))
+                throw error;
+        }
+    });
+}
+async function clearNotes(rawRef, rawIds, options = {}) {
+    const ref = parseAppVersionRef(rawRef, 'notes clear');
+    if (!ref)
+        return;
+    const ids = rawIds.map(Number);
+    if (ids.length === 0 || ids.some((id) => !Number.isInteger(id) || id <= 0) || new Set(ids).size !== ids.length) {
+        (0, messages_1.printErrorWithHelp)('One or more explicit note IDs are required.', ['Example: playdrop notes clear app:olivier/platformer@1.4.0 42 43'], { command: 'notes clear' });
+        process.exitCode = 1;
+        return;
+    }
+    await (0, commandContext_1.withEnvironment)('notes clear', 'Clearing playtest notes', async ({ client }) => {
+        try {
+            const result = await client.clearPlaytestNotes(ref.creatorUsername, ref.name, ref.version, ids);
+            if (options.json) {
+                (0, output_1.printJson)(result);
+                return;
+            }
+            (0, output_1.printSuccess)(`Cleared ${result.cleared.length} playtest notes. ${result.count} pending.`);
+        }
+        catch (error) {
+            if (!(0, errors_1.handleCommandFailure)(error, 'notes clear', 'Clear playtest notes', { apiMessage: notesApiMessage }))
+                throw error;
+        }
+    });
+}

package/dist/commands/tweaks.d.ts

@@ -0,0 +1,6 @@
+type TweaksOptions = {
+    json?: boolean;
+};
+export declare function getTweaks(rawRef: string | undefined, options?: TweaksOptions): Promise<void>;
+export declare function replaceTweaks(rawRef: string | undefined, file: string | undefined, options?: TweaksOptions): Promise<void>;
+export {};

package/dist/commands/tweaks.js

@@ -0,0 +1,93 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getTweaks = getTweaks;
+exports.replaceTweaks = replaceTweaks;
+const node_fs_1 = require("node:fs");
+const types_1 = require("@playdrop/types");
+const commandContext_1 = require("../commandContext");
+const errors_1 = require("../errors");
+const messages_1 = require("../messages");
+const output_1 = require("../output");
+function tweakApiMessage(error) {
+    if (error.code === 'creator_latest_private_version_required') {
+        const latestVersion = typeof error.details?.['latestVersion'] === 'string' ? error.details['latestVersion'] : null;
+        const latestId = typeof error.details?.['latestId'] === 'string' ? error.details['latestId'] : null;
+        const latestVisibility = typeof error.details?.['latestVisibility'] === 'string' ? error.details['latestVisibility'] : null;
+        return {
+            problem: latestVersion && latestVisibility === 'PUBLIC'
+                ? `The latest tweak base, ${latestVersion}, is live and cannot be edited.`
+                : latestVersion
+                    ? `Tweaks can only be changed on the latest editable version, ${latestVersion}.`
+                    : 'This app has no editable tweak base version.',
+            suggestions: latestVersion && latestVisibility === 'PUBLIC'
+                ? [`Create a new private version based on ${latestId ?? 'the latest tweak state'}, then tune that version.`]
+                : latestId ? [`Latest tweak state: ${latestId}`] : [],
+        };
+    }
+    return { problem: `PlayDrop rejected the tweak request: ${error.code ?? error.message} (HTTP ${error.status}).` };
+}
+function parseAppVersionRef(raw, command) {
+    const ref = (0, types_1.parseContentVersionRef)(raw ?? '');
+    if (!ref || ref.kind !== 'app') {
+        (0, messages_1.printErrorWithHelp)('An exact canonical app-version ref is required.', ['Use app:creator/name@x.y.z.', `Example: playdrop ${command} app:olivier/platformer@1.4.0`], { command });
+        process.exitCode = 1;
+        return null;
+    }
+    return ref;
+}
+async function getTweaks(rawRef, options = {}) {
+    const ref = parseAppVersionRef(rawRef, 'tweaks get');
+    if (!ref)
+        return;
+    await (0, commandContext_1.withEnvironment)('tweaks get', 'Reading tweaks', async ({ client }) => {
+        try {
+            const snapshot = await client.getAppTweaks(ref.creatorUsername, ref.name, ref.version);
+            if (options.json) {
+                (0, output_1.printJson)(snapshot);
+                return;
+            }
+            console.log(`Tweak state: ${snapshot.id}`);
+            console.log(JSON.stringify(snapshot.values, null, 2));
+        }
+        catch (error) {
+            if (!(0, errors_1.handleCommandFailure)(error, 'tweaks get', 'Read tweaks', { apiMessage: tweakApiMessage }))
+                throw error;
+        }
+    });
+}
+async function replaceTweaks(rawRef, file, options = {}) {
+    const ref = parseAppVersionRef(rawRef, 'tweaks replace');
+    if (!ref)
+        return;
+    if (!file?.trim()) {
+        (0, messages_1.printErrorWithHelp)('A JSON file is required.', ['Pass --file <path>.'], { command: 'tweaks replace' });
+        process.exitCode = 1;
+        return;
+    }
+    let values;
+    try {
+        const parsed = JSON.parse((0, node_fs_1.readFileSync)(file, 'utf8'));
+        if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed))
+            throw new Error('not_object');
+        values = parsed;
+    }
+    catch {
+        (0, messages_1.printErrorWithHelp)(`Could not read a JSON object from ${file}.`, [], { command: 'tweaks replace' });
+        process.exitCode = 1;
+        return;
+    }
+    await (0, commandContext_1.withEnvironment)('tweaks replace', 'Replacing tweaks', async ({ client }) => {
+        try {
+            const snapshot = await client.replaceAppTweaks(ref.creatorUsername, ref.name, ref.version, values);
+            if (options.json) {
+                (0, output_1.printJson)(snapshot);
+                return;
+            }
+            (0, output_1.printSuccess)(`Tweaks replaced. New state: ${snapshot.id}`);
+        }
+        catch (error) {
+            if (!(0, errors_1.handleCommandFailure)(error, 'tweaks replace', 'Replace tweaks', { apiMessage: tweakApiMessage }))
+                throw error;
+        }
+    });
+}

package/dist/commands/validate.js

@@ -9,6 +9,7 @@ const externalAssetPackValidation_1 = require("../externalAssetPackValidation");
 const taskSelection_1 = require("../taskSelection");
 const taskUtils_1 = require("../taskUtils");
 const uploadLog_1 = require("../uploadLog");
+const tweakStaleness_1 = require("../tweakStaleness");
 const listingPreflight_1 = require("../listingPreflight");
 const upload_content_1 = require("./upload-content");
 const upload_1 = require("./upload");
@@ -189,11 +190,24 @@ async function validate(pathOrName, options = {}) {
     const assetSpecTasks = tasks.filter((task) => task.kind === 'asset-spec');
     const assetSpecLookups = buildLocalAssetSpecLookups(assetSpecTasks);
     const sortedTasks = (0, taskUtils_1.sortTasks)(tasks);
+    const tweakValidationContext = await loadAuthenticatedValidationContext(workspacePath, options.env);
     for (const task of sortedTasks) {
         const entityId = task.name;
         try {
             if (task.kind === 'app') {
                 const workerContext = (0, listingPreflight_1.readWorkerUploadPreflightContext)(task.projectDir);
+                if (tweakValidationContext) {
+                    const creatorResult = (0, upload_content_1.getTaskCreatorResult)(task, tweakValidationContext.username, tweakValidationContext.currentUserRole);
+                    if (creatorResult.creatorTargetError)
+                        throw new Error(creatorResult.creatorTargetError);
+                    await (0, tweakStaleness_1.fetchAndAssertTweakState)(tweakValidationContext.client, creatorResult.taskCreator, task, { allowAppNotFound: true });
+                }
+                else if (workerContext?.tweaks) {
+                    (0, tweakStaleness_1.assertTweakStateMatches)(task, workerContext.tweaks);
+                }
+                else if (task.tweaks !== undefined) {
+                    warnings.add(`App "${task.name}" tweak basedOn was validated locally; remote staleness was not checked.`);
+                }
                 if (workerContext) {
                     await (0, upload_1.assertWorkerAppLocalUploadPreflight)({
                         task,

package/dist/commands/worker.d.ts

@@ -346,7 +346,7 @@ type WorkerRuntimeState = {
     target: AgentExecutionTarget;
     startedAt: string;
 };
-export type WorkerSupervisorType = 'app' | 'terminal';
+export type WorkerSupervisorType = 'app' | 'launchagent' | 'terminal';
 export type WorkerSupervisorLockOwner = {
     schemaVersion: 1;
     supervisorType: WorkerSupervisorType;

package/dist/commands/worker.js

@@ -151,7 +151,7 @@ const CLAIM_BACKOFF_JITTER_MS = 500;
 const FAIL_REPORT_RETRY_DELAY_MS = 2000;
 const WORKER_TRANSCRIPT_CHUNK_BATCH_SIZE = 100;
 const SLACK_API_BASE_URL = 'https://slack.com/api';
-const WORKER_WRAPPER_CONTRACT_VERSION = 2;
+const WORKER_WRAPPER_CONTRACT_VERSION = 3;
 const WORKER_SUPPORTED_KINDS = ['NEW_GAME', 'STATIC_GAME', 'REMIX_GAME', 'GAME_UPDATE', 'GAME_REVIEW', 'GAME_EVAL'];
 const GAME_CREATION_TASK_KINDS = new Set(['NEW_GAME', 'STATIC_GAME', 'REMIX_GAME', 'GAME_UPDATE']);
 const AGENT_MANAGED_UPLOAD_TASK_KINDS = new Set(['NEW_GAME', 'REMIX_GAME', 'GAME_UPDATE']);
@@ -3238,8 +3238,8 @@ function resolveWorkerStateDir() {
 }
 function normalizeWorkerSupervisorType(value) {
     const normalized = value?.trim().toLowerCase() || 'terminal';
-    if (normalized !== 'app' && normalized !== 'terminal') {
-        throw new Error(`worker_supervisor_type_invalid: expected app or terminal, received ${value ?? ''}.`);
+    if (normalized !== 'app' && normalized !== 'launchagent' && normalized !== 'terminal') {
+        throw new Error(`worker_supervisor_type_invalid: expected app, launchagent, or terminal, received ${value ?? ''}.`);
     }
     return normalized;
 }
@@ -3299,7 +3299,7 @@ function readWorkerSupervisorLockOwner(file) {
         throw new Error(`worker_supervisor_lock_invalid: ${file} does not contain valid owner metadata.`);
     }
     if (parsed.schemaVersion !== 1
-        || (parsed.supervisorType !== 'app' && parsed.supervisorType !== 'terminal')
+        || (parsed.supervisorType !== 'app' && parsed.supervisorType !== 'launchagent' && parsed.supervisorType !== 'terminal')
         || !Number.isInteger(parsed.pid)
         || (parsed.pid ?? 0) <= 0
         || typeof parsed.processStartIdentity !== 'string'
@@ -3323,7 +3323,11 @@ function workerSupervisorOwnerIsLive(owner) {
     return currentIdentity === owner.processStartIdentity;
 }
 function workerSupervisorHolderDescription(owner) {
-    const supervisor = owner.supervisorType === 'app' ? 'Local Agent app' : 'terminal';
+    const supervisor = owner.supervisorType === 'app'
+        ? 'Local Agent app'
+        : owner.supervisorType === 'launchagent'
+            ? 'LaunchAgent'
+            : 'terminal';
     return `${supervisor} worker "${owner.workerName}" (PID ${owner.pid})`;
 }
 function workerSupervisorOwnersMatch(left, right) {
@@ -3384,7 +3388,12 @@ function acquireWorkerSupervisorLock(input) {
             }
             const holder = readWorkerSupervisorLockOwner(file);
             if (workerSupervisorOwnerIsLive(holder)) {
-                throw new Error(`worker_supervisor_lock_held: ${workerSupervisorHolderDescription(holder)} already owns ${file}. Stop that worker before starting ${input.supervisorType === 'app' ? 'the Local Agent app worker' : 'a terminal worker'}.`);
+                const requestedSupervisor = input.supervisorType === 'app'
+                    ? 'the Local Agent app worker'
+                    : input.supervisorType === 'launchagent'
+                        ? 'the LaunchAgent worker'
+                        : 'a terminal worker';
+                throw new Error(`worker_supervisor_lock_held: ${workerSupervisorHolderDescription(holder)} already owns ${file}. Stop that worker before starting ${requestedSupervisor}.`);
             }
             removeStaleWorkerSupervisorLockIfUnchanged(file, holder);
         }
@@ -3885,7 +3894,7 @@ if [ "$TARGET_UPDATE_FAILED" -eq 0 ]; then
   rm -f "$FAILURE_FILE"
 fi
 
-exec /usr/bin/caffeinate -dimsu playdrop worker start --env ${shellQuote(input.env)} --name ${shellQuote(input.workerName)}
+exec /usr/bin/caffeinate -dimsu playdrop worker start --env ${shellQuote(input.env)} --name ${shellQuote(input.workerName)} --supervisor launchagent
 `;
     await (0, promises_1.writeFile)(wrapperPath, script, 'utf8');
     await (0, promises_1.chmod)(wrapperPath, 0o755);
@@ -4191,6 +4200,19 @@ async function startWorker(options = {}) {
             throw new Error(`worker_update_policy_target_mismatch: expected ${target}, received ${initialWorkerPolicy.executionTarget}.`);
         }
         const workerName = options.name?.trim() || `${username} - ${node_os_1.default.hostname()}`;
+        const workerKey = (0, config_1.getOrCreateWorkerKey)();
+        const runningWrapperVersion = (0, runtime_1.readPositiveEnvInt)('PLAYDROP_WORKER_WRAPPER_CONTRACT_VERSION', WORKER_WRAPPER_CONTRACT_VERSION);
+        if (target === 'FIRST_PARTY'
+            && node_process_1.default.platform === 'darwin'
+            && options.env?.trim()
+            && node_process_1.default.env.PLAYDROP_WORKER_WRAPPER_CONTRACT_VERSION
+            && runningWrapperVersion < WORKER_WRAPPER_CONTRACT_VERSION) {
+            verifyNpmGlobalInstallPreconditions();
+            const { wrapperPath } = await writeManagedWorkerWrapper({ env, workerName, workerKey });
+            await writeManagedWorkerLaunchAgent({ env, workerName, wrapperPath });
+            console.log(`Worker repaired LaunchAgent wrapper contract ${runningWrapperVersion} -> ${WORKER_WRAPPER_CONTRACT_VERSION}. Restarting under LaunchAgent ownership.`);
+            return;
+        }
         const supervisorType = normalizeWorkerSupervisorType(options.supervisor);
         const supervisorLock = acquireWorkerSupervisorLock({ supervisorType, workerName });
         try {
@@ -4221,7 +4243,6 @@ async function startWorker(options = {}) {
                 chromiumInstalled: true,
                 ...(local.playwright.executablePath ? { executablePath: local.playwright.executablePath } : {}),
             };
-            const workerKey = (0, config_1.getOrCreateWorkerKey)();
             const maxParallelTasks = (0, runtime_1.readPositiveEnvInt)('PLAYDROP_WORKER_MAX_PARALLEL_TASKS', DEFAULT_WORKER_MAX_PARALLEL_TASKS);
             let capabilities = local.capabilities;
             let lastCapabilityRefreshAt = Date.now();

package/dist/index.js

@@ -44,6 +44,8 @@ const feedback_1 = require("./commands/feedback");
 const changelog_1 = require("./commands/changelog");
 const publicPages_1 = require("./commands/publicPages");
 const upgrade_1 = require("./commands/upgrade");
+const tweaks_1 = require("./commands/tweaks");
+const notes_1 = require("./commands/notes");
 const worker_1 = require("./commands/worker");
 const messages_1 = require("./messages");
 // Restricted shim: inside a worker task workspace only task-scoped commands,
@@ -177,7 +179,7 @@ worker
     .option('--env <env>', 'Resolve this command against one logged-in environment')
     .option('--once', 'Process at most one task then exit')
     .option('--name <name>', 'Worker display name override')
-    .option('--supervisor <type>', 'Worker supervisor type: app or terminal', 'terminal')
+    .option('--supervisor <type>', 'Worker supervisor type: app, launchagent, or terminal', 'terminal')
     .option('--supervise-stdin', 'Exit with a bounded shutdown when stdin closes')
     .option('--dev-plugin-working-tree <path>', 'DEV ONLY: stage task plugin files from this working tree')
     .action(async (opts) => {
@@ -577,6 +579,43 @@ versions
     .action(async (ref, opts) => {
     await (0, versionsBrowse_1.browseVersions)(ref, opts);
 });
+const tweaks = program.command('tweaks').description('Read and replace version-scoped game tweaks');
+tweaks
+    .command('get')
+    .description('Read the current tweak state for an exact app version')
+    .argument('<ref>', 'Exact ref: app:creator/name@x.y.z')
+    .option('--json', 'Output JSON')
+    .action(async (ref, options) => {
+    await (0, tweaks_1.getTweaks)(ref, options);
+});
+tweaks
+    .command('replace')
+    .description('Replace tweaks on the latest private app version')
+    .argument('<ref>', 'Exact ref: app:creator/name@x.y.z')
+    .requiredOption('--file <path>', 'JSON object containing the complete tweak values')
+    .option('--json', 'Output JSON')
+    .action(async (ref, options) => {
+    await (0, tweaks_1.replaceTweaks)(ref, options.file, options);
+});
+const notes = program.command('notes').description('Read and clear pending creator playtest notes');
+notes
+    .command('browse')
+    .description('Browse pending playtest notes for an app')
+    .argument('<ref>', 'Exact ref: app:creator/name@x.y.z')
+    .option('--json', 'Output JSON')
+    .option('--output <directory>', 'Materialize attachments and a notes.json manifest')
+    .action(async (ref, options) => {
+    await (0, notes_1.browseNotes)(ref, options);
+});
+notes
+    .command('clear')
+    .description('Clear explicit note IDs after incorporating them')
+    .argument('<ref>', 'Exact ref: app:creator/name@x.y.z')
+    .argument('<ids...>', 'One or more note IDs')
+    .option('--json', 'Output JSON')
+    .action(async (ref, ids, options) => {
+    await (0, notes_1.clearNotes)(ref, ids, options);
+});
 const credits = program.command('credits').description('Credit balance and history');
 credits
     .command('balance')

package/dist/listingPreflight.d.ts

@@ -9,6 +9,10 @@ export type WorkerUploadPreflightContext = {
     target: 'FIRST_PARTY' | 'PERSONAL';
     creatorUsername: string;
     creatorRequest: string;
+    tweaks?: {
+        id: string;
+        values: Record<string, string | number | boolean>;
+    };
 };
 export declare function readMediaCaptureProof(input: {
     task: AppTask;

package/dist/listingPreflight.js

@@ -303,6 +303,15 @@ function readWorkerUploadPreflightContext(projectDir) {
             target,
             creatorUsername: typeof playdrop.creatorUsername === 'string' ? playdrop.creatorUsername.trim() : '',
             creatorRequest: typeof request.prompt === 'string' ? request.prompt.trim() : '',
+            ...(playdrop.tweaks
+                && typeof playdrop.tweaks === 'object'
+                && !Array.isArray(playdrop.tweaks)
+                && typeof playdrop.tweaks.id === 'string'
+                && playdrop.tweaks.values
+                && typeof playdrop.tweaks.values === 'object'
+                && !Array.isArray(playdrop.tweaks.values)
+                ? { tweaks: { id: playdrop.tweaks.id, values: playdrop.tweaks.values } }
+                : {}),
         };
     }
     if (parsed?.protocolVersion !== undefined) {
@@ -319,6 +328,14 @@ function readWorkerUploadPreflightContext(projectDir) {
         target: parsed.target,
         creatorUsername: typeof parsed.creatorUsername === 'string' ? parsed.creatorUsername.trim() : '',
         creatorRequest: typeof parsed.creatorRequest === 'string' ? parsed.creatorRequest.trim() : '',
+        ...(parsed.tweaks
+            && typeof parsed.tweaks === 'object'
+            && typeof parsed.tweaks.id === 'string'
+            && parsed.tweaks.values
+            && typeof parsed.tweaks.values === 'object'
+            && !Array.isArray(parsed.tweaks.values)
+            ? { tweaks: parsed.tweaks }
+            : {}),
     };
 }
 function assertAgentGameHeroListingPreflight(task) {

package/dist/tweakStaleness.d.ts

@@ -0,0 +1,7 @@
+import { type AppTweaksSnapshot } from '@playdrop/types';
+import type { ApiClient } from '@playdrop/api-client';
+import type { AppTask } from './catalogue';
+export declare function assertTweakStateMatches(task: AppTask, latest: AppTweaksSnapshot | null): void;
+export declare function fetchAndAssertTweakState(client: ApiClient, creatorUsername: string, task: AppTask, options?: {
+    allowAppNotFound?: boolean;
+}): Promise<void>;

package/dist/tweakStaleness.js

@@ -0,0 +1,36 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.assertTweakStateMatches = assertTweakStateMatches;
+exports.fetchAndAssertTweakState = fetchAndAssertTweakState;
+const types_1 = require("@playdrop/types");
+function assertTweakStateMatches(task, latest) {
+    const basedOn = task.tweaks?.basedOn ?? null;
+    const latestId = latest?.id ?? null;
+    if (task.tweaks === undefined && latestId === null)
+        return;
+    if (task.tweaks !== undefined && basedOn === latestId)
+        return;
+    throw new Error([
+        'Tweak definition is out of date.',
+        '',
+        `Code is based on: ${basedOn ?? 'none'}`,
+        `Latest state is:  ${latestId ?? 'none'}`,
+        '',
+        'Latest values:',
+        JSON.stringify(latest?.values ?? null, null, 2),
+    ].join('\n'));
+}
+async function fetchAndAssertTweakState(client, creatorUsername, task, options = {}) {
+    let latest = null;
+    try {
+        latest = await client.getLatestAppTweaks(creatorUsername, task.name);
+    }
+    catch (error) {
+        if (!(error instanceof types_1.ApiError))
+            throw error;
+        if (error.code !== 'tweaks_not_declared' && !(options.allowAppNotFound && error.code === 'app_not_found')) {
+            throw error;
+        }
+    }
+    assertTweakStateMatches(task, latest);
+}