codex-orchestrator 0.1.51 → 2.0.0

package/internal-skills/acceptance-proof/SKILL.md

@@ -0,0 +1,14 @@
+---
+name: acceptance-proof
+description: Independently prove a checked change against frozen acceptance criteria and return a typed proof report.
+---
+
+# Acceptance Proof
+
+Independently prove the checked change against every frozen acceptance criterion. Inspect the issue snapshot, actual diff, configured check receipts, and available repository evidence. Classify each criterion as non-visual or visual from the criterion and changed behavior, preserve every frozen criterion ID, and require concrete evidence for every declared surface.
+
+For a browser surface, read and follow [references/browser.md](references/browser.md). For Android, follow [references/android.md](references/android.md) and use only `tools/android-lease.mjs`. For iOS, follow [references/ios.md](references/ios.md) and use only `tools/ios-lease.mjs`. Resolve every reference/helper from this exact immutable skill snapshot and use only the proof-bound arguments supplied by the runner. Apply the selected platform procedure's real-workflow, state capture, diagnostics, freshness, analysis, and artifact-classification requirements.
+
+Do not edit product code, repair the implementation, change lifecycle state, or perform publication. Do not commit, push, open or edit a pull request, mutate GitHub labels/comments, publish packages, deploy, or use external credentials. Do not copy or print credential bytes or auth/secret paths. Report a typed external blocker only when proof genuinely depends on unavailable external authority.
+
+Return only the JSON object required by the exact output schema supplied by the runner. Do not add prose around the report and do not independently restate or modify its fields.

package/internal-skills/acceptance-proof/references/android.md

@@ -0,0 +1,14 @@
+# Android Proof Procedure
+
+Use Android proof only when a frozen criterion describes user-visible Android behavior or the checked diff changes that behavior. Keep the exact frozen criterion IDs and declare `decision.mode: visual`, target `android`, and an `android` surface for each applicable criterion.
+
+1. Discover current Android and Flutter ownership before mutation. Require exactly one online emulator, no physical device, and no live process for the selected application ID. If a user-owned app or runtime is present, return a typed tool blocker and do not install, launch, stop, replace, or clear it.
+2. Acquire the runner lease before installing or launching the app by invoking the exact immutable `tools/android-lease.mjs` path and lease arguments supplied by the runner. Keep its token private. If acquisition is blocked, do not bypass it with direct `adb` commands.
+3. Install and launch only the selected application ID on the leased emulator. Resolve the actual application PID and bind it with the same helper, proof ID, token, lease root, and lease artifact path before interacting with the app.
+4. Complete the real workflow through its final interaction. Use an accessibility/UI hierarchy dump to locate controls and derive interaction coordinates; do not guess coordinates. Recheck that the exact leased application PID is still live after the final interaction.
+5. After the final interaction, capture a fresh PNG screenshot, a fresh UI hierarchy XML, and a device log scoped to the exact application PID. Verify the lease again after all captures. The screenshot and hierarchy must prove the same final state.
+6. Review spacing, padding, clipping, overlap, alignment, and the specific visual complaint. Separately review visible user-facing copy against the frozen criterion. Link both reviews to exact evidence IDs.
+7. Write every artifact below the runner-provided proof directory. Mark the UI hierarchy, device log, and lease record `publishable: false`. Mark a screenshot publishable only when it contains no credential, secret, private user path, or unrelated account data. Never place serials, application IDs, PIDs, lease tokens, local paths, credential bytes, authorization data, environment values, or user-owned device data in the publishable receipt.
+8. Build the exact generated Proof Report. Each Android criterion must reference both screenshot and hierarchy evidence. Visual evidence must include workflow entrypoint/steps/final state, Android capture dimensions, device-log ref, lease ref, `capturedAfterFinalInteraction: true`, and evidence-linked layout/copy reviews.
+
+The runner releases the lease after terminal proof settlement. Do not release it early. A screenshot alone, missing hierarchy/log/lease, stale evidence, changed application PID, guessed interaction, rewritten criterion, unanalysed image, or secret-bearing artifact cannot pass. Return `needs-rework` for product defects and a typed `external-block` only for genuinely unavailable emulator/tool/service authority.

package/internal-skills/acceptance-proof/references/browser.md

@@ -0,0 +1,13 @@
+# Browser Proof Procedure
+
+Use browser proof only when at least one frozen criterion describes user-visible web behavior or when the checked diff changes that behavior. Keep the exact frozen criterion IDs and declare `decision.mode: visual`, target `browser`, and a `browser` surface for each applicable criterion.
+
+1. Identify the real local application or fixture entrypoint and the complete user workflow required by the criterion. Do not substitute a nearby route, first reachable screen, static file, or unrelated demo.
+2. Launch a real browser against HTTP(S). Complete the workflow through its final interaction and assert the requested final state from live DOM text/state.
+3. Repeat the final workflow at one desktop width of at least 1024 pixels and one narrow responsive width of at most 480 pixels. Capture a fresh screenshot and DOM-state JSON after the last interaction at each viewport.
+4. Record browser console errors and failed network requests in separate JSON files even when both lists are empty.
+5. Review spacing, padding, clipping, overlap, alignment, responsive reflow, and the specific visual complaint. Separately review visible user-facing copy against the frozen criterion. Link each finding to the exact evidence IDs used.
+6. Write every artifact below the runner-provided proof directory. Mark screenshots publishable only when they contain no credential, secret, private user path, or unrelated account data. Mark DOM, console, and network artifacts `publishable: false`. Never include credential bytes, authorization headers, environment values, cookies, storage state, or local auth paths.
+7. Build the exact generated Proof Report. Each browser criterion must reference both screenshot and DOM evidence at every required viewport. The visual evidence must include workflow entrypoint/steps/final state, viewport captures, console/network refs, `capturedAfterFinalInteraction: true`, and evidence-linked layout/copy reviews.
+
+A screenshot by itself, stale file, one viewport, missing DOM/diagnostics, irrelevant route, rewritten criterion, unanalysed image, or secret-bearing artifact cannot pass. Return `needs-rework` for product behavior defects and a typed `external-block` only for genuinely unavailable browser tooling or service authority.

package/internal-skills/acceptance-proof/references/ios.md

@@ -0,0 +1,14 @@
+# iOS Proof Procedure
+
+Use iOS proof only when a frozen criterion describes user-visible iOS behavior or the checked diff changes that behavior. Keep exact criterion IDs and declare `decision.mode: visual`, target `ios`, and an `ios` surface for each applicable criterion.
+
+1. Perform read-only Xcode/Simulator discovery. If any Simulator is already booted or Flutter, VM Service, XCTest, Simulator UI, or IDE ownership is ambiguous, return a typed tool blocker without mutation.
+2. Acquire the lease with the exact immutable helper, lease root, artifact, proof ID, bundle ID, owner PID, xcrun path, runtime ID, and device-type ID supplied by the runner. The helper creates a new proof-bound Simulator after durable intent. Never select, boot, install into, or delete an existing device; never use the `booted` alias.
+3. Boot, build, install, and launch only through the returned UDID. Bind the exact bundle/process with the helper before accepting evidence. Every later `simctl` or test command must contain that literal UDID.
+4. Complete the workflow with XCUITest or an equivalent accessibility driver. Select controls by accessibility identity or hierarchy, never guessed coordinates. Capture pre/final accessibility hierarchy and prove the requested final state from live accessibility text/state.
+5. While the exact final app process remains live, capture a fresh Simulator PNG and process-scoped Simulator log, then verify the same lease/app/process again. Broad logs are forbidden.
+6. Review spacing, padding, clipping, overlap, alignment, and the specific visual complaint. Separately review visible copy against the frozen criterion and link both reviews to exact evidence IDs.
+7. Write artifacts only below the proof directory. Keep hierarchy, logs, and lease local-only. A screenshot may be publishable only when it contains no credential, secret, private path, or unrelated account data. Keep UDID, bundle/process identity, lease token, raw logs, and local paths out of publishable results.
+8. Emit the exact generated Proof Report with screenshot plus hierarchy linked to every iOS criterion, process-log and lease refs, workflow/final state, post-interaction freshness, and evidence-linked layout/copy reviews.
+
+The runner reconciles shutdown/delete and releases the lease after terminal proof settlement. Do not release early. Screenshot-only, stale, unleased, target-drifted, guessed-interaction, broad-log, rewritten-criterion, or secret-bearing evidence cannot pass.

package/internal-skills/acceptance-proof/tools/android-lease.mjs

@@ -0,0 +1,280 @@
+#!/usr/bin/env node
+
+import { execFile } from 'node:child_process';
+import { randomUUID } from 'node:crypto';
+import { lstat, mkdir, open, readFile, rename, rm } from 'node:fs/promises';
+import { dirname, join, resolve } from 'node:path';
+import { promisify } from 'node:util';
+
+const execFileAsync = promisify(execFile);
+const LEASE_FILE = 'android.json';
+const LEASE_MS = 15 * 60 * 1000;
+
+class Blocked extends Error {}
+
+try {
+  const [command, ...argv] = process.argv.slice(2);
+  const args = parseArgs(argv);
+  const result = await execute(command, args);
+  process.stdout.write(`${JSON.stringify(result)}\n`);
+} catch (error) {
+  const blocked = error instanceof Blocked;
+  process.stdout.write(`${JSON.stringify({
+    status: blocked ? 'blocked' : 'internal-error',
+    reason: blocked ? error.message : 'Android lease helper failed internally.',
+  })}\n`);
+  process.exitCode = blocked ? 20 : 70;
+}
+
+async function execute(command, args) {
+  const leaseRoot = requiredPath(args['lease-root'], 'lease root');
+  const artifactPath = requiredPath(args.artifact, 'lease artifact');
+  const proofId = requiredString(args['proof-id'], 'proof ID');
+  const adb = args.adb
+    ? requiredPath(args.adb, 'adb path')
+    : process.env.ANDROID_ADB || join(process.env.HOME || '', 'Library', 'Android', 'sdk', 'platform-tools', 'adb');
+  const now = parseNow();
+  await ensureDirectDirectory(leaseRoot);
+  await ensureDirectDirectory(dirname(artifactPath));
+  const leasePath = join(leaseRoot, LEASE_FILE);
+
+  if (command === 'acquire') {
+    const appId = requiredAppId(args['app-id']);
+    const ownerPid = requiredPid(args['owner-pid']);
+    const target = await selectEmulator(adb);
+    const existing = await readLease(leasePath);
+    if (existing) {
+      if (existing.proofId === proofId && existing.appId === appId && existing.ownerPid === ownerPid) {
+        await verifyTarget(adb, existing, false);
+        return publicResult('reused', existing);
+      }
+      if (!(Date.parse(existing.expiresAt) < now.getTime() && !pidAlive(existing.ownerPid))) {
+        throw new Blocked('An active foreign Android lease already exists.');
+      }
+      if (existing.serial !== target.serial || existing.appId !== appId) {
+        throw new Blocked('A stale Android lease does not match the requested target identity.');
+      }
+      await rm(leasePath);
+    }
+    const livePid = await appPid(adb, target.serial, appId);
+    if (livePid !== undefined) throw new Blocked('The requested Android app already has a user-owned live process.');
+    const lease = {
+      schema: 'codex-orchestrator.android-lease',
+      version: 1,
+      status: 'active',
+      proofId,
+      token: randomUUID(),
+      serial: target.serial,
+      appId,
+      ownerPid,
+      appPid: null,
+      acquiredAt: now.toISOString(),
+      expiresAt: new Date(now.getTime() + LEASE_MS).toISOString(),
+      updatedAt: now.toISOString(),
+    };
+    await createExclusiveJson(leasePath, lease);
+    await writeAtomicJson(artifactPath, lease);
+    return publicResult('acquired', lease);
+  }
+
+  const token = requiredString(args.token, 'lease token');
+  const lease = await requireOwnedLease(leasePath, proofId, token, now);
+  if (command === 'bind') {
+    await verifyTarget(adb, lease, false, true);
+    const pid = await appPid(adb, lease.serial, lease.appId);
+    if (pid === undefined) throw new Blocked('The leased Android app is not running.');
+    const bound = { ...lease, appPid: pid, updatedAt: now.toISOString() };
+    await replaceJson(leasePath, bound);
+    await writeAtomicJson(artifactPath, bound);
+    return publicResult('bound', bound);
+  }
+  if (command === 'verify') {
+    await verifyTarget(adb, lease, true);
+    await writeAtomicJson(artifactPath, { ...lease, updatedAt: now.toISOString() });
+    return publicResult('verified', lease);
+  }
+  if (command === 'release') {
+    await verifyTarget(adb, lease, Number.isSafeInteger(lease.appPid));
+    const released = { ...lease, status: 'released', updatedAt: now.toISOString() };
+    await writeAtomicJson(artifactPath, released);
+    await rm(leasePath);
+    await syncDirectory(dirname(leasePath));
+    return publicResult('released', released);
+  }
+  throw new Blocked('Unknown Android lease command.');
+}
+
+async function selectEmulator(adb) {
+  const output = await adbCommand(adb, ['devices', '-l']);
+  const rows = output.stdout.split(/\r?\n/u).slice(1).map((line) => line.trim()).filter(Boolean).map((line) => {
+    const [serial, state] = line.split(/\s+/u);
+    return { serial, state };
+  });
+  if (rows.some((row) => !row.serial.startsWith('emulator-'))) throw new Blocked('Physical Android devices are not eligible for runner leases.');
+  if (rows.length !== 1 || rows[0].state !== 'device') throw new Blocked('Exactly one online Android emulator is required.');
+  const boot = await adbCommand(adb, ['-s', rows[0].serial, 'shell', 'getprop', 'sys.boot_completed']);
+  if (boot.stdout.trim() !== '1') throw new Blocked('The Android emulator has not completed boot.');
+  return rows[0];
+}
+
+async function verifyTarget(adb, lease, requireBoundApp, allowUnboundLive = false) {
+  const target = await selectEmulator(adb);
+  if (target.serial !== lease.serial) throw new Blocked('The leased Android emulator identity changed.');
+  const currentPid = await appPid(adb, lease.serial, lease.appId);
+  if (requireBoundApp) {
+    if (!Number.isSafeInteger(lease.appPid) || currentPid !== lease.appPid) {
+      throw new Blocked('The leased Android app PID changed or disappeared.');
+    }
+  } else if (!allowUnboundLive && lease.appPid === null && currentPid !== undefined) {
+    throw new Blocked('The leased Android app became live before runner binding.');
+  }
+}
+
+async function appPid(adb, serial, appId) {
+  const result = await adbCommand(adb, ['-s', serial, 'shell', 'pidof', '-s', appId], true);
+  const value = result.stdout.trim();
+  if (!value) return undefined;
+  const pid = Number(value);
+  if (!Number.isSafeInteger(pid) || pid < 1) throw new Blocked('Android app PID observation is invalid.');
+  return pid;
+}
+
+async function adbCommand(adb, args, allowFailure = false) {
+  try {
+    return await execFileAsync(adb, args, { timeout: 15_000, maxBuffer: 1024 * 1024, env: process.env });
+  } catch (error) {
+    if (allowFailure && typeof error === 'object' && error !== null && 'stdout' in error) {
+      return { stdout: String(error.stdout || ''), stderr: String(error.stderr || '') };
+    }
+    throw new Blocked('Android tooling did not return a usable target observation.');
+  }
+}
+
+function parseArgs(argv) {
+  const result = {};
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index];
+    if (!arg.startsWith('--')) throw new Blocked('Android lease arguments are invalid.');
+    const equals = arg.indexOf('=');
+    if (equals > 2) {
+      result[arg.slice(2, equals)] = arg.slice(equals + 1);
+      continue;
+    }
+    const value = argv[++index];
+    if (!value || value.startsWith('--')) throw new Blocked('Android lease argument value is missing.');
+    result[arg.slice(2)] = value;
+  }
+  return result;
+}
+
+function parseNow() {
+  const value = process.env.CODEX_ORCHESTRATOR_NOW || new Date().toISOString();
+  const date = new Date(value);
+  if (Number.isNaN(date.getTime()) || date.toISOString() !== value) throw new Error('invalid lease clock');
+  return date;
+}
+
+async function requireOwnedLease(path, proofId, token, now) {
+  const lease = await readLease(path);
+  if (!lease || lease.proofId !== proofId || lease.token !== token) throw new Blocked('Android lease ownership does not match.');
+  if (lease.status !== 'active' || Date.parse(lease.expiresAt) < now.getTime()) throw new Blocked('Android lease is not active.');
+  return lease;
+}
+
+async function readLease(path) {
+  try {
+    return validateLease(JSON.parse(await readFile(path, 'utf8')));
+  } catch (error) {
+    if (typeof error === 'object' && error !== null && 'code' in error && error.code === 'ENOENT') return undefined;
+    throw new Blocked('Android lease state is malformed.');
+  }
+}
+
+function validateLease(value) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) throw new Error('invalid lease');
+  const keys = ['schema', 'version', 'status', 'proofId', 'token', 'serial', 'appId', 'ownerPid', 'appPid', 'acquiredAt', 'expiresAt', 'updatedAt'].sort();
+  const actual = Object.keys(value).sort();
+  if (actual.length !== keys.length || actual.some((key, index) => key !== keys[index])) throw new Error('invalid lease keys');
+  if (value.schema !== 'codex-orchestrator.android-lease' || value.version !== 1 || !['active', 'released'].includes(value.status)) throw new Error('invalid lease schema');
+  requiredString(value.proofId, 'proof ID');
+  requiredString(value.token, 'token');
+  if (!/^emulator-[0-9]+$/u.test(value.serial)) throw new Error('invalid serial');
+  requiredAppId(value.appId);
+  requiredPid(value.ownerPid);
+  if (value.appPid !== null) requiredPid(value.appPid);
+  for (const field of ['acquiredAt', 'expiresAt', 'updatedAt']) {
+    if (new Date(value[field]).toISOString() !== value[field]) throw new Error('invalid lease timestamp');
+  }
+  return value;
+}
+
+async function ensureDirectDirectory(path) {
+  const absolute = resolve(path);
+  await mkdir(absolute, { recursive: true, mode: 0o700 });
+  const info = await lstat(absolute);
+  if (!info.isDirectory() || info.isSymbolicLink()) throw new Error('unsafe lease directory');
+}
+
+async function createExclusiveJson(path, value) {
+  const handle = await open(path, 'wx', 0o600);
+  try {
+    await handle.writeFile(`${JSON.stringify(value)}\n`);
+    await handle.sync();
+  } finally {
+    await handle.close();
+  }
+  await syncDirectory(dirname(path));
+}
+
+async function replaceJson(path, value) {
+  await writeAtomicJson(path, value);
+}
+
+async function writeAtomicJson(path, value) {
+  const temp = `${path}.tmp-${process.pid}-${randomUUID()}`;
+  const handle = await open(temp, 'wx', 0o600);
+  try {
+    await handle.writeFile(`${JSON.stringify(value)}\n`);
+    await handle.sync();
+  } finally {
+    await handle.close();
+  }
+  await rename(temp, path);
+  await syncDirectory(dirname(path));
+}
+
+async function syncDirectory(path) {
+  const handle = await open(path, 'r');
+  try { await handle.sync(); } finally { await handle.close(); }
+}
+
+function publicResult(status, lease) {
+  return { status, proofId: lease.proofId, token: lease.token, serial: lease.serial, appId: lease.appId, appPid: lease.appPid, expiresAt: lease.expiresAt };
+}
+
+function requiredPath(value, field) {
+  const text = requiredString(value, field);
+  if (!text.startsWith('/')) throw new Blocked(`${field} must be absolute.`);
+  return resolve(text);
+}
+
+function requiredString(value, field) {
+  if (typeof value !== 'string' || value.length === 0 || value.length > 4096) throw new Blocked(`${field} is invalid.`);
+  return value;
+}
+
+function requiredAppId(value) {
+  const text = requiredString(value, 'app ID');
+  if (!/^[A-Za-z][A-Za-z0-9_]*(?:\.[A-Za-z][A-Za-z0-9_]*)+$/u.test(text)) throw new Blocked('Android app ID is invalid.');
+  return text;
+}
+
+function requiredPid(value) {
+  const pid = Number(value);
+  if (!Number.isSafeInteger(pid) || pid < 1) throw new Blocked('Android owner PID is invalid.');
+  return pid;
+}
+
+function pidAlive(pid) {
+  try { process.kill(pid, 0); return true; } catch (error) { return error?.code === 'EPERM'; }
+}

package/internal-skills/acceptance-proof/tools/ios-lease.mjs

@@ -0,0 +1,288 @@
+#!/usr/bin/env node
+
+import { execFile } from 'node:child_process';
+import { randomUUID } from 'node:crypto';
+import { lstat, mkdir, open, readFile, rename, rm } from 'node:fs/promises';
+import { dirname, join, resolve } from 'node:path';
+import { promisify } from 'node:util';
+
+const execFileAsync = promisify(execFile);
+const LEASE_FILE = 'ios.json';
+const LEASE_MS = 20 * 60 * 1000;
+const UDID_PATTERN = /^[0-9A-F]{8}-[0-9A-F]{4}-4[0-9A-F]{3}-[89AB][0-9A-F]{3}-[0-9A-F]{12}$/iu;
+
+class Blocked extends Error {}
+
+try {
+  const [command, ...argv] = process.argv.slice(2);
+  const args = parseArgs(argv);
+  const result = await execute(command, args);
+  process.stdout.write(`${JSON.stringify(result)}\n`);
+} catch (error) {
+  const blocked = error instanceof Blocked;
+  process.stdout.write(`${JSON.stringify({
+    status: blocked ? 'blocked' : 'internal-error',
+    reason: blocked ? error.message : 'iOS lease helper failed internally.',
+  })}\n`);
+  process.exitCode = blocked ? 20 : 70;
+}
+
+async function execute(command, args) {
+  const leaseRoot = requiredPath(args['lease-root'], 'lease root');
+  const artifactPath = requiredPath(args.artifact, 'lease artifact');
+  const proofId = requiredString(args['proof-id'], 'proof ID');
+  const xcrun = requiredPath(args.xcrun || '/usr/bin/xcrun', 'xcrun path');
+  const now = parseNow();
+  await ensureDirectDirectory(leaseRoot);
+  await ensureDirectDirectory(dirname(artifactPath));
+  const leasePath = join(leaseRoot, LEASE_FILE);
+
+  if (command === 'acquire') {
+    const bundleId = requiredBundleId(args['bundle-id']);
+    const ownerPid = requiredPid(args['owner-pid']);
+    const runtimeId = requiredIdentifier(args.runtime, 'runtime ID', 'com.apple.CoreSimulator.SimRuntime.');
+    const deviceTypeId = requiredIdentifier(args['device-type'], 'device type ID', 'com.apple.CoreSimulator.SimDeviceType.');
+    const existing = await readLease(leasePath);
+    const booted = await listDevices(xcrun, 'booted');
+    if (booted.some((device) => device.udid !== existing?.udid)) {
+      throw new Blocked('A user-owned booted Simulator session already exists.');
+    }
+    if (existing) {
+      if (existing.status === 'active' && existing.proofId === proofId && existing.bundleId === bundleId
+        && existing.ownerPid === ownerPid && Date.parse(existing.expiresAt) >= now.getTime()) {
+        await requireRecordedTarget(xcrun, existing, false);
+        return publicResult('reused', existing);
+      }
+      if (!(Date.parse(existing.expiresAt) < now.getTime() && !pidAlive(existing.ownerPid))) {
+        throw new Blocked('An active foreign iOS lease already exists.');
+      }
+      await cleanupRecordedTarget(xcrun, existing);
+      await rm(leasePath);
+      await syncDirectory(dirname(leasePath));
+    }
+    if (booted.length !== 0) throw new Blocked('A booted Simulator appeared before lease acquisition.');
+
+    const deviceName = `Codex ${proofId}`;
+    const preparing = {
+      schema: 'codex-orchestrator.ios-lease', version: 1, status: 'preparing', proofId, token: randomUUID(),
+      udid: null, deviceName, bundleId, ownerPid, appPid: null, runtimeId, deviceTypeId, runnerCreated: true,
+      acquiredAt: now.toISOString(), expiresAt: new Date(now.getTime() + LEASE_MS).toISOString(), updatedAt: now.toISOString(),
+    };
+    await createExclusiveJson(leasePath, preparing);
+    let createdUdid;
+    try {
+      const created = await simctl(xcrun, ['create', deviceName, deviceTypeId, runtimeId]);
+      createdUdid = created.stdout.trim();
+      if (!UDID_PATTERN.test(createdUdid)) throw new Blocked('simctl create returned an invalid Simulator identity.');
+      const active = { ...preparing, status: 'active', udid: createdUdid, updatedAt: now.toISOString() };
+      await replaceJson(leasePath, active);
+      await writeAtomicJson(artifactPath, active);
+      return publicResult('acquired', active);
+    } catch (error) {
+      if (createdUdid && UDID_PATTERN.test(createdUdid)) await simctl(xcrun, ['delete', createdUdid], true);
+      await rm(leasePath, { force: true });
+      await syncDirectory(dirname(leasePath));
+      throw error;
+    }
+  }
+
+  const token = requiredString(args.token, 'lease token');
+  const lease = await requireOwnedLease(leasePath, proofId, token, now);
+  if (command === 'bind') {
+    const appPid = requiredPid(args['app-pid']);
+    await verifyAppTarget(xcrun, lease, appPid);
+    const bound = { ...lease, appPid, updatedAt: now.toISOString() };
+    await replaceJson(leasePath, bound);
+    await writeAtomicJson(artifactPath, bound);
+    return publicResult('bound', bound);
+  }
+  if (command === 'verify') {
+    if (!Number.isSafeInteger(lease.appPid)) throw new Blocked('The iOS lease is not bound to an app process.');
+    await verifyAppTarget(xcrun, lease, lease.appPid);
+    await writeAtomicJson(artifactPath, { ...lease, updatedAt: now.toISOString() });
+    return publicResult('verified', lease);
+  }
+  if (command === 'release') {
+    await cleanupRecordedTarget(xcrun, lease, true);
+    const released = { ...lease, status: 'released', updatedAt: now.toISOString() };
+    await writeAtomicJson(artifactPath, released);
+    await rm(leasePath);
+    await syncDirectory(dirname(leasePath));
+    return publicResult('released', released);
+  }
+  throw new Blocked('Unknown iOS lease command.');
+}
+
+async function listDevices(xcrun, scope = 'all') {
+  const args = scope === 'booted' ? ['list', 'devices', 'booted', '-j'] : ['list', 'devices', '-j'];
+  const result = await simctl(xcrun, args);
+  let parsed;
+  try { parsed = JSON.parse(result.stdout); } catch { throw new Blocked('simctl device inventory is malformed.'); }
+  return Object.values(parsed.devices || {}).flat().filter((device) => device && device.isAvailable !== false).map((device) => ({
+    udid: device.udid, name: device.name, state: device.state,
+  }));
+}
+
+async function requireRecordedTarget(xcrun, lease, requireBooted) {
+  if (!lease.runnerCreated || !UDID_PATTERN.test(String(lease.udid))) throw new Blocked('The iOS lease lacks a runner-created target.');
+  const matches = (await listDevices(xcrun)).filter((device) => device.udid === lease.udid);
+  if (matches.length !== 1) throw new Blocked('The leased Simulator identity is absent or ambiguous.');
+  if (requireBooted && matches[0].state !== 'Booted') throw new Blocked('The leased Simulator is not booted.');
+  return matches[0];
+}
+
+async function verifyAppTarget(xcrun, lease, appPid) {
+  await requireRecordedTarget(xcrun, lease, true);
+  const container = (await simctl(xcrun, ['get_app_container', lease.udid, lease.bundleId, 'app'])).stdout.trim();
+  if (!container.endsWith('.app') || container.includes('\n')) throw new Blocked('The leased iOS app container is invalid.');
+  const services = (await simctl(xcrun, ['spawn', lease.udid, 'launchctl', 'list'])).stdout;
+  const matches = services.split(/\r?\n/u).map((line) => /^\s*(\d+)\s+\S+\s+UIKitApplication:([^[]+)\[/u.exec(line))
+    .filter((match) => match && match[2] === lease.bundleId);
+  if (matches.length !== 1 || Number(matches[0][1]) !== appPid) {
+    throw new Blocked('The leased iOS app PID changed or does not match its bundle container.');
+  }
+}
+
+async function cleanupRecordedTarget(xcrun, lease, allowAbsent = false) {
+  if (!lease.runnerCreated) throw new Blocked('Only runner-created Simulators may be released.');
+  const devices = await listDevices(xcrun);
+  let matches = lease.udid
+    ? devices.filter((device) => device.udid === lease.udid)
+    : devices.filter((device) => device.name === lease.deviceName);
+  if (matches.length === 0 && allowAbsent) return;
+  if (matches.length !== 1 || !UDID_PATTERN.test(matches[0].udid)) throw new Blocked('Runner-created Simulator cleanup identity is absent or ambiguous.');
+  if (matches[0].state === 'Booted') await simctl(xcrun, ['shutdown', matches[0].udid]);
+  await simctl(xcrun, ['delete', matches[0].udid]);
+  matches = (await listDevices(xcrun)).filter((device) => device.udid === matches[0].udid);
+  if (matches.length !== 0) throw new Blocked('Runner-created Simulator deletion was not confirmed.');
+}
+
+async function simctl(xcrun, args, allowFailure = false) {
+  try {
+    return await execFileAsync(xcrun, ['simctl', ...args], { timeout: 20_000, maxBuffer: 1024 * 1024, env: process.env });
+  } catch (error) {
+    if (allowFailure) return { stdout: '', stderr: '' };
+    throw new Blocked('iOS Simulator tooling did not return a usable target observation.');
+  }
+}
+
+function parseArgs(argv) {
+  const result = {};
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index];
+    if (!arg.startsWith('--')) throw new Blocked('iOS lease arguments are invalid.');
+    const equals = arg.indexOf('=');
+    if (equals > 2) { result[arg.slice(2, equals)] = arg.slice(equals + 1); continue; }
+    const value = argv[++index];
+    if (!value || value.startsWith('--')) throw new Blocked('iOS lease argument value is missing.');
+    result[arg.slice(2)] = value;
+  }
+  return result;
+}
+
+function parseNow() {
+  const value = process.env.CODEX_ORCHESTRATOR_NOW || new Date().toISOString();
+  const date = new Date(value);
+  if (Number.isNaN(date.getTime()) || date.toISOString() !== value) throw new Error('invalid lease clock');
+  return date;
+}
+
+async function requireOwnedLease(path, proofId, token, now) {
+  const lease = await readLease(path);
+  if (!lease || lease.status !== 'active' || lease.proofId !== proofId || lease.token !== token) throw new Blocked('iOS lease ownership does not match.');
+  if (Date.parse(lease.expiresAt) < now.getTime()) throw new Blocked('iOS lease is not active.');
+  return lease;
+}
+
+async function readLease(path) {
+  try { return validateLease(JSON.parse(await readFile(path, 'utf8'))); }
+  catch (error) {
+    if (error?.code === 'ENOENT') return undefined;
+    throw new Blocked('iOS lease state is malformed.');
+  }
+}
+
+function validateLease(value) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) throw new Error('invalid lease');
+  const keys = ['schema', 'version', 'status', 'proofId', 'token', 'udid', 'deviceName', 'bundleId', 'ownerPid', 'appPid', 'runtimeId', 'deviceTypeId', 'runnerCreated', 'acquiredAt', 'expiresAt', 'updatedAt'].sort();
+  const actual = Object.keys(value).sort();
+  if (actual.length !== keys.length || actual.some((key, index) => key !== keys[index])) throw new Error('invalid lease keys');
+  if (value.schema !== 'codex-orchestrator.ios-lease' || value.version !== 1 || !['preparing', 'active', 'released'].includes(value.status)) throw new Error('invalid lease schema');
+  requiredString(value.proofId, 'proof ID');
+  requiredString(value.token, 'token');
+  requiredString(value.deviceName, 'device name');
+  requiredBundleId(value.bundleId);
+  requiredPid(value.ownerPid);
+  if (value.appPid !== null) requiredPid(value.appPid);
+  requiredIdentifier(value.runtimeId, 'runtime ID', 'com.apple.CoreSimulator.SimRuntime.');
+  requiredIdentifier(value.deviceTypeId, 'device type ID', 'com.apple.CoreSimulator.SimDeviceType.');
+  if (value.runnerCreated !== true) throw new Error('invalid runner ownership');
+  if (value.status === 'preparing' ? value.udid !== null : !UDID_PATTERN.test(String(value.udid))) throw new Error('invalid UDID');
+  for (const field of ['acquiredAt', 'expiresAt', 'updatedAt']) if (new Date(value[field]).toISOString() !== value[field]) throw new Error('invalid timestamp');
+  return value;
+}
+
+async function ensureDirectDirectory(path) {
+  const absolute = resolve(path);
+  await mkdir(absolute, { recursive: true, mode: 0o700 });
+  const info = await lstat(absolute);
+  if (!info.isDirectory() || info.isSymbolicLink()) throw new Error('unsafe lease directory');
+}
+
+async function createExclusiveJson(path, value) {
+  const handle = await open(path, 'wx', 0o600);
+  try { await handle.writeFile(`${JSON.stringify(value)}\n`); await handle.sync(); } finally { await handle.close(); }
+  await syncDirectory(dirname(path));
+}
+
+async function replaceJson(path, value) { await writeAtomicJson(path, value); }
+
+async function writeAtomicJson(path, value) {
+  const temp = `${path}.tmp-${process.pid}-${randomUUID()}`;
+  const handle = await open(temp, 'wx', 0o600);
+  try { await handle.writeFile(`${JSON.stringify(value)}\n`); await handle.sync(); } finally { await handle.close(); }
+  await rename(temp, path);
+  await syncDirectory(dirname(path));
+}
+
+async function syncDirectory(path) {
+  const handle = await open(path, 'r');
+  try { await handle.sync(); } finally { await handle.close(); }
+}
+
+function publicResult(status, lease) {
+  return { status, proofId: lease.proofId, token: lease.token, udid: lease.udid, bundleId: lease.bundleId, appPid: lease.appPid, expiresAt: lease.expiresAt };
+}
+
+function requiredPath(value, field) {
+  const text = requiredString(value, field);
+  if (!text.startsWith('/')) throw new Blocked(`${field} must be absolute.`);
+  return resolve(text);
+}
+
+function requiredString(value, field) {
+  if (typeof value !== 'string' || value.length === 0 || value.length > 4096) throw new Blocked(`${field} is invalid.`);
+  return value;
+}
+
+function requiredIdentifier(value, field, prefix) {
+  const text = requiredString(value, field);
+  if (!text.startsWith(prefix) || !/^[A-Za-z0-9.-]+$/u.test(text)) throw new Blocked(`${field} is invalid.`);
+  return text;
+}
+
+function requiredBundleId(value) {
+  const text = requiredString(value, 'bundle ID');
+  if (!/^[A-Za-z][A-Za-z0-9_]*(?:\.[A-Za-z][A-Za-z0-9_]*)+$/u.test(text)) throw new Blocked('iOS bundle ID is invalid.');
+  return text;
+}
+
+function requiredPid(value) {
+  const pid = Number(value);
+  if (!Number.isSafeInteger(pid) || pid < 1) throw new Blocked('iOS process ID is invalid.');
+  return pid;
+}
+
+function pidAlive(pid) {
+  try { process.kill(pid, 0); return true; } catch (error) { return error?.code === 'EPERM'; }
+}

package/internal-skills/agent-auto/SKILL.md

@@ -0,0 +1,14 @@
+---
+name: agent-auto
+description: Implement one prepared GitHub issue inside the runner-owned worktree and return a typed implementation report.
+---
+
+# Agent Auto
+
+Implement one issue end to end inside the prepared worktree. Treat the supplied issue snapshot, frozen acceptance criteria, repository instructions, and runner-provided output schema as authoritative.
+
+Inspect the repository, choose the smallest complete strategy, and use native Codex subagents when useful. Apply TDD for behavior changes, run focused validation, repair failures that are within the issue scope, and leave the worktree ready for independent acceptance proof.
+
+The runner owns authorization and every external effect. Do not commit, push, open or edit a pull request, mutate GitHub labels/comments, publish packages, deploy, or use external credentials. Do not copy or print credential bytes or auth/secret paths. If completion depends on a credential, unavailable tool/service, or product decision, return the typed external blocker instead of widening authority.
+
+Return only the JSON object required by the exact output schema supplied by the runner. Do not add prose around the report and do not independently restate or modify its fields.