@12ui/design 0.2.67 → 0.2.68

package/SKILL.md

@@ -28,7 +28,7 @@ dispatch paid work when it is absent, rejected, or times out.
 Use `12ui` when it is available on `PATH`. Otherwise invoke the pinned CLI that
 the plugin's `open-design.json` MCP entry uses:
 
-    npx -y @12ui/design@0.2.67 <command> ...
+    npx -y @12ui/design@0.2.68 <command> ...
 
 Run `12ui auth status --json` (or its pinned `npx` equivalent) before the paid
 preflight. A desktop user can authenticate with `12ui auth login`; a headless

package/open-design.json

@@ -3,7 +3,7 @@
   "specVersion": "1.0.0",
   "name": "12ui-design",
   "title": "12UI Design",
-  "version": "0.2.67",
+  "version": "0.2.68",
   "description": "Explore corpus-grounded interface directions, choose one, and convert it into production-ready responsive or native artifacts with 12UI.",
   "author": {
     "name": "Just Every",
@@ -49,7 +49,7 @@
           "command": "npx",
           "args": [
             "-y",
-            "@12ui/design@0.2.67",
+            "@12ui/design@0.2.68",
             "mcp"
           ]
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@12ui/design",
-  "version": "0.2.67",
+  "version": "0.2.68",
   "type": "module",
   "description": "The canonical 12ui CLI, SDK, MCP server, and visual interface design skills",
   "main": "dist/index.js",

package/runtime/bootstrap.mjs

@@ -0,0 +1,131 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { cp, mkdir, readFile, readdir, realpath, rename, rm, stat, writeFile } from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { spawn } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import { parseArgs } from 'node:util';
+
+async function files(root, relative = '') {
+  const entries = await readdir(path.join(root, relative), { withFileTypes: true });
+  const result = [];
+  for (const entry of entries.sort((a, b) => a.name.localeCompare(b.name))) {
+    const name = path.join(relative, entry.name);
+    if (entry.isSymbolicLink()) throw new Error(`Runtime payload must not contain symlinks: ${name}`);
+    if (entry.isDirectory()) result.push(...await files(root, name));
+    else result.push(name);
+  }
+  return result;
+}
+
+function execute(command, args, options = {}) {
+  return new Promise((resolve, reject) => {
+    const child = spawn(command, args, { stdio: 'inherit', ...options });
+    child.on('error', reject);
+    child.on('exit', (code, signal) => {
+      if (code === 0) resolve();
+      else reject(new Error(`${command} failed (${signal ?? code})`));
+    });
+  });
+}
+
+const payloadEntries = ['bin', 'src', 'templates', 'package.json', 'npm-shrinkwrap.json', 'README.md'];
+
+async function runtimeKey(payload) {
+  if (Number(process.versions.node.split('.')[0]) < 22) throw new Error('12ui Codex conversion requires Node.js 22 or newer.');
+  const hash = createHash('sha256');
+  hash.update(`${process.platform}/${process.arch}/node-${process.versions.node.split('.')[0]}\0`);
+  const names = [];
+  for (const entry of payloadEntries) {
+    if ((await stat(path.join(payload, entry))).isDirectory()) names.push(...await files(payload, entry));
+    else names.push(entry);
+  }
+  for (const file of names.sort()) {
+    hash.update(file).update('\0').update(await readFile(path.join(payload, file))).update('\0');
+  }
+  return hash.digest('hex');
+}
+
+export async function prepareRuntime(payload, cacheBase) {
+  const key = await runtimeKey(payload);
+  const root = path.join(cacheBase, key);
+  const ready = async () => {
+    try { return (await readFile(path.join(root, '.12ui-ready'), 'utf8')) === key; }
+    catch (error) { if (error.code === 'ENOENT') return false; throw error; }
+  };
+  if (await ready()) return { root, key };
+  await mkdir(cacheBase, { recursive: true });
+  const staging = path.join(cacheBase, `.${key}-${randomUUID()}`);
+  try {
+    await cp(payload, staging, { recursive: true, errorOnExist: true });
+    // npm runs only against the content-keyed user cache, never the installed skill.
+    await execute(process.platform === 'win32' ? 'npm.cmd' : 'npm', ['ci', '--omit=dev', '--no-audit', '--no-fund'], { cwd: staging, stdio: ['inherit', 2, 2] });
+    await writeFile(path.join(staging, '.12ui-ready'), key);
+    try { await rename(staging, root); }
+    catch (error) { if (!(await ready())) throw error; }
+    return { root, key };
+  } finally {
+    await rm(staging, { recursive: true, force: true });
+  }
+}
+
+export function parseRunInvocation(command, args) {
+  if (!['convert', 'improve'].includes(command)) return {};
+  const names = command === 'convert'
+    ? ['source', 'run-dir', 'auth-home', 'clean-assets', 'image-backend', 'reasoning', 'codex-bin', 'timeout-ms']
+    : ['project', 'target', 'source-capture', 'instructions', 'run-dir', 'auth-home', 'codex-bin', 'width', 'height'];
+  const options = Object.fromEntries(names.map(name => [name, { type: 'string' }]));
+  options.help = { type: 'boolean' };
+  const { values, positionals } = parseArgs({ args, options, allowPositionals: true });
+  const mode = positionals[0] ?? (command === 'improve' ? 'improve' : undefined);
+  const allowed = command === 'convert' ? ['convert', 'resume'] : ['improve', 'prepare', 'apply', 'resume'];
+  if (!values.help && (!allowed.includes(mode) || positionals.length > 1 || !values['run-dir'])) {
+    throw new Error(`Expected ${allowed.join('/')} and --run-dir; use --help`);
+  }
+  return { runDir: values['run-dir'] ? path.resolve(values['run-dir']) : undefined,
+    createsRun: ['convert', 'prepare', 'improve'].includes(mode), help: values.help };
+}
+
+export async function launch(command, args = process.argv.slice(2)) {
+  if (!['convert', 'export', 'finish', 'improve'].includes(command)) throw new Error(`Unknown runtime command: ${command}`);
+  const payload = fileURLToPath(new URL('./codex-conversion/', import.meta.url));
+  const cacheBase = process.env.TWELVE_UI_CODEX_RUNTIME_CACHE
+    ?? path.join(os.homedir(), '.cache', '12ui', 'codex-conversion');
+  const cache = path.resolve(cacheBase);
+  const { runDir, createsRun, help } = parseRunInvocation(command, args);
+  const pinPath = runDir ? path.join(runDir, '.12ui-runtime.json') : undefined;
+  let runExisted = false;
+  if (runDir) {
+    try { await stat(runDir); runExisted = true; }
+    catch (error) { if (error.code !== 'ENOENT') throw error; }
+  }
+  let runtime;
+  if (pinPath && !createsRun && !help) {
+    let pin;
+    try { pin = JSON.parse(await readFile(pinPath, 'utf8')); }
+    catch (error) { throw new Error(`Run has no valid runtime pin: ${pinPath}. Resume it with its original preserved skill/runtime; no new implementation was run.`); }
+    if (!/^[a-f0-9]{64}$/.test(pin.key)) throw new Error('Invalid run runtime key.');
+    const root = path.join(cache, pin.key);
+    if (await runtimeKey(root) !== pin.key) throw new Error(`Pinned runtime is missing or changed: ${root}. Restore the preserved runtime before resuming.`);
+    if (await readFile(path.join(root, '.12ui-ready'), 'utf8') !== pin.key) throw new Error(`Pinned runtime is not ready: ${root}`);
+    runtime = { root, key: pin.key };
+  } else runtime = await prepareRuntime(payload, cache);
+  const { root, key } = runtime;
+  const entry = await realpath(path.join(root, 'bin', `${command}.mjs`));
+  try {
+    await execute(process.execPath, [entry, ...args], {
+      env: { ...process.env, TWELVE_UI_CODEX_RUNTIME_KEY: key, TWELVE_UI_CODEX_RUNTIME_ROOT: root },
+    });
+  } finally {
+    if (pinPath && createsRun && !runExisted) {
+      try {
+        await writeFile(pinPath, JSON.stringify({ schemaVersion: 1, key }) + '\n', { flag: 'wx' });
+      } catch (error) { if (!['ENOENT', 'EEXIST'].includes(error.code)) throw error; }
+    }
+  }
+}
+
+if (process.argv[1] && await realpath(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  try { await launch(process.argv[2], process.argv.slice(3)); }
+  catch (error) { console.error(error.message); process.exitCode = 1; }
+}

package/runtime/codex-conversion/README.md

@@ -0,0 +1,75 @@
+# Codex conversion
+
+Node 22+ CLI for the demonstrated A workflow: one schema-constrained Astra ChatGPT planner response (low by default), followed by parallel image requests. The default external backend uses **OpenAI image API** requests with `gpt-image-2.5-flare` high; `--image-backend native` selects Codex-native image execution. It returns HTML/CSS and independent image files. It does not return native LayerDoc. External image calls require separate API credentials.
+
+Install this package and an authenticated Codex CLI supporting the preserved invocation flags. Pass the existing Codex authentication directory explicitly; it must contain `auth.json` and `models_cache.json` with the selected Astra reasoning effort available. Credentials remain outside the run directory. The isolated planner environment excludes API keys; external images use `OPENAI_API_KEY` from the calling environment.
+
+```sh
+12ui-convert convert --source design.png --run-dir ./new-run --auth-home /path/to/codex-home
+12ui-convert resume --run-dir ./new-run --auth-home /path/to/codex-home
+```
+
+`--reasoning low|medium` selects initial planner reasoning (default low); bounded contract repair remains medium. `--image-backend external|native` selects image execution (default external). All selectors are frozen for resume; conflicting explicit values are rejected.
+
+`--codex-bin` selects the installed binary; `--timeout-ms` sets the per-call planner wall cap (1–1800000, default 1800000). `CODEX_CONVERSION_IMAGE_ENDPOINT` explicitly overrides the image endpoint and is frozen in the run configuration. Do not put credentials in that URL. Stdout contains one JSON result; progress goes to stderr. Exit code is zero only for completion.
+
+Validation normalizes recoverable representation differences first, including exact integer strings, enum formatting, redundant omissions, a single JSON code fence and incompatible request grouping. Valid responses take the original fast path. When source or document issues remain unresolved, one additional Astra medium call repairs the saved response using the source and explicit issues. The original request is never repeated. Both responses, normalization changes and unresolved issues remain inspectable; exhausted repair returns those issues when no usable artifact can be produced. This contract repair is distinct from optional visual correction experiments; it does not automatically judge appearance or substitute images.
+
+Each conversion needs a new directory. Source bytes, dimensions, prompt/schema hashes, implementation hash, model configuration and image endpoint are immutable. Resume rejects changed source or implementation; it can rebuild local output from previously received planner/provider bytes without credentials. A run can move to another directory, and its `output/` directory can be copied independently. The manifest records relative file paths, content hashes, source ownership and external dependencies, including allowed Google Fonts; those fonts still require network access.
+
+Paid calls use durable `prepared`, `dispatched`, and `received` states. A response whose complete bytes and hash are in custody is reused. A planner final also recovers from its verified completion receipt. An interrupted dispatch without proven response custody returns `needs-reconciliation` and is never automatically submitted again. Keep the run directory for investigation; do not delete it and treat a fresh run as a free retry. An exclusive process lock prevents concurrent resumes. Dead local process locks can be reclaimed; locks from other hosts require investigation.
+
+`result.json` separates initial planner, contract-repair and external image provider usage; these are usage records, not complete dollar accounting. `output/manifest.json` describes the portable artifact. `calls/` holds immutable request identities, response bytes, public metadata, planner event output and receipt hashes. Transport completion is recorded independently of payload syntax so a completed malformed response can be normalized or repaired. Never share the run directory without inspecting model and provider output for source content.
+
+Validation: `pnpm test` and `pnpm typecheck` from this package. Tests use test-only provider/planner doubles and real filesystem/process interruption boundaries; real account behavior and visual quality require the separate frozen study.
+
+## Install as a reusable Codex skill
+
+Run `node bin/install-skill.mjs` from the installed package, or pass `--destination /absolute/skills/codex-convert`. The default destination is `${CODEX_HOME:-~/.codex}/skills/codex-convert`. Installation copies the bundled runtime and installs its production dependencies; an existing destination is rejected.
+
+The source skill lives in `skill/codex-convert`. Its installed `scripts/convert.mjs` wrapper accepts the same conversion and resume arguments as the CLI.
+
+### Native image custody and geometry
+
+The native backend launches a separate Codex session with the native image tool enabled,
+using Astra medium as coordinator. The underlying image model is not exposed. It uses
+ChatGPT authentication from `--auth-home`, then `CODEX_HOME`, then `~/.codex`; no
+`OPENAI_API_KEY` is required for native artwork. The local Codex CLI must support the
+native image tool and the strict invocation flags used by this package.
+
+Each group permits exactly one image generation. The durable call response retains the
+original PNG bytes, original dimensions, tool audit, and quota observations. Native image
+sizes can differ from the frozen frame: an explicit Lanczos3 exact-stretch derivative
+maps the complete native image into that frame before taking the unchanged source-owner
+crops. Receipts name the transform and scale factors; originals are never overwritten.
+Six prior native study calls supported this treatment at rendered size, with fine detail
+variation and no demonstrated quality advantage over the external route.
+
+Completed calls replay without authentication or inference. Interrupted calls collect
+existing completion records only; uncertain calls require reconciliation and are never
+redispatched. Account quota snapshots are not per-image cost measurements.
+
+Run the optional real-byte geometry/resume check against a retained native study directory:
+`NATIVE_IMAGE_EVIDENCE=/absolute/path/to/native-v1 node --test test/native-images.test.mjs`.
+
+## Original source crops
+
+`--clean-assets crop|enhance` selects the requested treatment of clean opaque artwork (default `enhance`) and is frozen for resume. `crop` asks the planner to declare `crop-source` only for owners needing no removal, transparency or new detail. These original-pixel crops execute locally at native dimensions, with no AI call or implicit 2x scaling. Other owners still use the selected image backend. `preserve-source` retains its original AI enhancement meaning. Contradictory declarations remain explicit repair issues.
+
+## Export and inspection
+
+After rendering and inspecting the output, `node bin/export.mjs --source RUN/output --destination NEW_DIR --target assets|png|jpg|webp|pdf|react [--width PIXELS --height PIXELS]` creates deterministic derivatives without inference. PNG/JPG/WebP and browser PDF require Chromium (`npx playwright install chromium`). Omitted viewport dimensions use the source dimensions saved in the manifest, or a documented 1440×1000 viewport when no valid source geometry exists. PDF uses one full-content page by default; explicit `--height` selects paginated browser output. Raster metadata records actual rendered dimensions separately from the viewport. PDF is not a native LayerDoc export. React produces editable JSX with preserved document-global CSS and assets, suitable for one full page per document. It is not an isolated widget or application behavior implementation. `npm install && npm run build` in its output rebuilds edits. Source scripts/handlers are reported as unresolved actions.
+
+For focused HTML/CSS corrections after parent Codex inspection, read the skill's `references/finishing.md`. `node bin/finish.mjs --source-dir RUN/output --patch PATCH.json --output-dir NEW_DIR` applies uniquely anchored replacements without inference. Both helpers require new destinations, preserve originals, and write manifests with actual derivative hashes. Keep the old installed runtime when upgrading: immutable old runs must resume with their original implementation. The installer rejects an existing destination; install the candidate to a separate path.
+
+### Source-boundary grid normalization
+
+Previously legal image frames and requests are unchanged. When an exact source boundary cannot fit the external provider's output grid, the executor preserves the complete original input and owner coordinates, requests a legal rounded canvas, then records a Lanczos3 mapping to the exact 2x delivery frame before cropping. Original provider bytes/PNG and the mapped frame remain separate. Unsupported size or aspect constraints still return explicit issues; this mapping does not invent padding, trim owners, or spend a planner repair call on that representational grid mismatch.
+
+## Approved redesigns in existing projects
+
+`12ui-improve improve --project /absolute/project --target /absolute/approved.png --source-capture /absolute/current.png --instructions /absolute/brief.md --run-dir /absolute/new-run --auth-home /absolute/codex-home` prepares and invokes one Astra low turn on the actual application. The brief supplies applicable project instructions, runtime/build commands, desired changes and behavior checks. `--codex-bin` selects the executable; `--width` and `--height` select the viewport (otherwise target dimensions). PNG/JPEG/WebP inputs are supported.
+
+Use `prepare` with those inputs to freeze and inspect without dispatch, `apply --run-dir RUN --auth-home HOME` to start the prepared run once, and `resume --run-dir RUN` to reconcile saved work without dispatch. Preserve the current source capture, target, project content and durable records. Inspect actual code and browser behavior after execution; a completed call is not a visual-quality verdict. The standalone skill exposes the same commands through `scripts/improve.mjs`.
+
+The Codex-specific 12ui-design skill coordinates draft/corpus/branch imagery through 12ui, single-image conversion through this package, and approved redesigns through local project edits. The shared API skill for other clients remains separate. Full hosted branch prototype assembly and native LayerDoc/SVG/PSD/PPTX/Sketch outputs remain explicit API features; a failed local run does not trigger them automatically. React export produces full-page JSX, not an application's data or behavior.

package/runtime/codex-conversion/bin/convert.mjs

@@ -0,0 +1,21 @@
+#!/usr/bin/env node
+import { parseArgs } from 'node:util';
+import { convert, resume } from '../src/run.mjs';
+
+try {
+  const { values, positionals } = parseArgs({ allowPositionals: true, options: {
+    source: { type: 'string' }, 'run-dir': { type: 'string' }, 'auth-home': { type: 'string' },
+    'clean-assets': { type: 'string' }, 'image-backend': { type: 'string' }, reasoning: { type: 'string' }, 'codex-bin': { type: 'string' }, 'timeout-ms': { type: 'string' }, help: { type: 'boolean' },
+  } });
+  if (values.help) {
+    console.log(JSON.stringify({ usage: '12ui-convert convert --source IMAGE --run-dir NEW_DIR --auth-home CODEX_HOME [--reasoning low|medium] [--clean-assets crop|enhance] [--image-backend external|native] | 12ui-convert resume --run-dir DIR [--auth-home CODEX_HOME]', imageCredentials: { external: 'OPENAI_API_KEY', native: 'Codex account via --auth-home' }, format: 'html-css', defaultImageBackend: 'external', defaultReasoning: 'low' }));
+  } else {
+    if (!values['run-dir'] || !['convert', 'resume'].includes(positionals[0]) || positionals.length !== 1) throw new Error('Expected convert or resume and --run-dir');
+    const options = { cleanAssets: values['clean-assets'], imageBackend: values['image-backend'], reasoning: values.reasoning, source: values.source, runDir: values['run-dir'], authHome: values['auth-home'], binary: values['codex-bin'], timeoutMs: values['timeout-ms'] ? Number(values['timeout-ms']) : undefined, progress: message => process.stderr.write(message + '\n') };
+    const result = await (positionals[0] === 'convert' ? convert(options) : resume(options));
+    console.log(JSON.stringify(result)); if (result.status !== 'complete') process.exitCode = 1;
+  }
+} catch (error) {
+  console.log(JSON.stringify({ schemaVersion: 1, status: 'failed', error: { message: error.message } }));
+  process.exitCode = 1;
+}

package/runtime/codex-conversion/bin/export.mjs

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+import {parseArgs} from 'node:util';
+import {exportOutput} from '../src/exports/index.mjs';
+try{const {values}=parseArgs({options:{source:{type:'string'},destination:{type:'string'},target:{type:'string'},width:{type:'string'},height:{type:'string'},help:{type:'boolean'}}});if(values.help)console.log('export --source OUTPUT_DIR --destination NEW_DIR --target assets|png|jpg|webp|pdf|react [--width PIXELS --height PIXELS]. Omitted dimensions use the saved source, or 1440x1000 without source geometry. PDF uses one full-content page unless --height requests pagination. Raster/PDF require: npx playwright install chromium');else{if(!values.source||!values.destination||!values.target)throw Error('source, destination and target required');console.log(JSON.stringify(await exportOutput({sourceDir:values.source,outputDir:values.destination,target:values.target,width:values.width?Number(values.width):undefined,height:values.height?Number(values.height):undefined})));}}catch(error){console.error(error.message);process.exitCode=1;}

package/runtime/codex-conversion/bin/finish.mjs

@@ -0,0 +1,11 @@
+#!/usr/bin/env node
+import {parseArgs} from 'node:util';
+import {finishOutput} from '../src/finish/index.mjs';
+export async function main(args = process.argv.slice(2)) {
+  const {values} = parseArgs({args, options: {'source-dir': {type:'string'}, patch: {type:'string'}, 'output-dir': {type:'string'}}});
+  if (!values['source-dir'] || !values.patch || !values['output-dir']) throw Error('Expected --source-dir DIR --patch FILE --output-dir NEW_DIR');
+  const result = await finishOutput({sourceDir: values['source-dir'], patchFile: values.patch, outputDir: values['output-dir']});
+  console.log(JSON.stringify(result));
+  return result;
+}
+if (process.argv[1] === import.meta.filename) main().catch(error => {console.log(JSON.stringify({status:'failed', error: error.message})); process.exitCode = 1;});

package/runtime/codex-conversion/bin/improve.mjs

@@ -0,0 +1,12 @@
+#!/usr/bin/env node
+import {parseArgs} from 'node:util';
+import {prepareProject,applyProject,resumeProject,improveProject} from '../src/project/run.mjs';
+try {
+ const {values:v,positionals}=parseArgs({allowPositionals:true,options:{project:{type:'string'},target:{type:'string'},'source-capture':{type:'string'},instructions:{type:'string'},'run-dir':{type:'string'},'auth-home':{type:'string'},'codex-bin':{type:'string'},width:{type:'string'},height:{type:'string'},help:{type:'boolean'}}});
+ if(v.help)console.log('12ui-improve improve|prepare --project ABS --target IMAGE --source-capture IMAGE --instructions FILE --run-dir NEW [--auth-home HOME] [--codex-bin BIN] [--width N --height N]\n12ui-improve apply --run-dir RUN --auth-home HOME [--codex-bin BIN]\n12ui-improve resume --run-dir RUN\nImprove prepares and invokes one tool-enabled Astra low turn. Prepare makes no call. Apply starts a prepared run once. Resume only reconciles saved work and never dispatches. Images: PNG/JPEG/WebP; viewport defaults to target dimensions. Project instructions must include applicable rules, runtime/build and behavior checks.');
+ else {
+  const mode=positionals[0]??'improve';if(positionals.length>1||!['improve','prepare','apply','resume'].includes(mode)||!v['run-dir'])throw Error('Expected improve/prepare/apply/resume and --run-dir; use --help');
+  const options={project:v.project,target:v.target,sourceCapture:v['source-capture'],instructions:v.instructions,runDir:v['run-dir'],authHome:v['auth-home'],binary:v['codex-bin'],width:v.width===undefined?undefined:Number(v.width),height:v.height===undefined?undefined:Number(v.height)};
+  const result=await ({improve:improveProject,prepare:prepareProject,apply:applyProject,resume:resumeProject}[mode])(options);console.log(JSON.stringify(result));if(!['complete','prepared'].includes(result.status))process.exitCode=1;
+ }
+}catch(error){console.error(JSON.stringify({status:'failed',error:{message:error.message}}));process.exitCode=1;}

package/runtime/codex-conversion/bin/install-skill.mjs

@@ -0,0 +1,36 @@
+#!/usr/bin/env node
+import { cp, mkdir, readFile, rm, access } from 'node:fs/promises';
+import { dirname, resolve, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { homedir } from 'node:os';
+import { parseArgs } from 'node:util';
+import { spawnSync } from 'node:child_process';
+
+const root = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+const { values } = parseArgs({ options: { destination: { type: 'string' }, help: { type: 'boolean' } } });
+if (values.help) {
+  console.log('node bin/install-skill.mjs [--destination /absolute/skills/codex-convert]\nInstalls a self-contained local skill and its npm production dependencies. Existing destinations are never replaced.');
+} else {
+  const destination = resolve(values.destination ?? join(process.env.CODEX_HOME || join(homedir(), '.codex'), 'skills/codex-convert'));
+  let created = false;
+  try {
+    const manifest = JSON.parse(await readFile(join(root, 'package.json'), 'utf8'));
+    await access(join(root, 'skill/codex-convert/SKILL.md'));
+    await mkdir(dirname(destination), { recursive: true });
+    await mkdir(destination);
+    created = true;
+    await cp(join(root, 'skill/codex-convert'), destination, { recursive: true });
+    const runtime = join(destination, 'runtime');
+    await mkdir(runtime);
+    for (const file of ['bin', 'src', 'templates', 'README.md', 'package.json', 'npm-shrinkwrap.json']) {
+      await cp(join(root, file), join(runtime, file), { recursive: true });
+    }
+    const child = spawnSync(process.platform === 'win32' ? 'npm.cmd' : 'npm', ['ci', '--omit=dev', '--no-audit', '--no-fund'], { cwd: runtime, stdio: 'inherit' });
+    if (child.error || child.status !== 0) throw child.error ?? new Error(`Dependency installation exited ${child.status}`);
+    console.log(JSON.stringify({ skill: 'codex-convert', version: manifest.version, destination, invoke: `node ${join(destination, 'scripts/convert.mjs')} --help` }));
+  } catch (error) {
+    if (created) await rm(destination, { recursive: true, force: true });
+    console.error(`Skill installation failed: ${error.message}`);
+    process.exitCode = 1;
+  }
+}

package/runtime/codex-conversion/bin/recover-image.mjs

@@ -0,0 +1,11 @@
+#!/usr/bin/env node
+import {parseArgs} from 'node:util';
+import {recoverImage} from './recovery/run.mjs';
+try {
+  const {values:v,positionals}=parseArgs({allowPositionals:true,options:{'original-run':{type:'string'},group:{type:'string'},'run-dir':{type:'string'},help:{type:'boolean'}}});
+  if(v.help)console.log(JSON.stringify({usage:'recover-image.mjs recover --original-run RUN --group group-NN --run-dir NEW_DIR | recover-image.mjs resume --run-dir RECOVERY_DIR',condition:'External Flare only; verified received HTTP500 JSON error with no image data; one new attempt, never unknown dispatch or completed images',credential:'OPENAI_API_KEY for a new request only'}));
+  else {
+    const mode=positionals[0];if(positionals.length!==1||!['recover','resume'].includes(mode)||!v['run-dir']||mode==='recover'&&(!v['original-run']||!v.group))throw Error('Expected recover/resume and required inputs; use --help');
+    const result=await recoverImage({originalRun:v['original-run'],group:v.group,runDir:v['run-dir']},{resume:mode==='resume'});console.log(JSON.stringify(result));if(result.status!=='complete')process.exitCode=1;
+  }
+}catch(error){console.log(JSON.stringify({schemaVersion:1,status:error.code==='NEEDS_RECONCILIATION'?'needs-reconciliation':'failed',error:{message:error.message}}));process.exitCode=1;}

package/runtime/codex-conversion/bin/recovery/prepare.mjs

@@ -0,0 +1,68 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import {hash,readJson,writeJson} from '../../src/run-store.mjs';
+import {canonical} from '../../src/run-store-io.mjs';
+import {assessContract} from '../../src/contract-repair.mjs';
+import {prepareReference} from '../../src/images/geometry.mjs';
+import {operationPrompt} from '../../src/images/prompt.mjs';
+
+export async function readReceivedCall(root,id,folder='calls') {
+  const dir=path.join(root,folder,hash(id));
+  const state=await readJson(path.join(dir,'state.json'));
+  if(state?.status!=='received')throw Object.assign(Error(`Call ${id} is not confirmed received; reconcile without redispatch`),{code:'NEEDS_RECONCILIATION'});
+  const [custody,request,bytes]=await Promise.all([readJson(path.join(dir,'custody.json')),readJson(path.join(dir,'request.json')),fs.readFile(path.join(dir,'response.bin'))]);
+  const requestHash=hash(canonical(request)),responseHash=hash(bytes);
+  if(state?.id!==id||state.status!=='received'||state.requestHash!==requestHash||custody?.requestHash!==requestHash||state.responseHash!==responseHash||custody.responseHash!==responseHash||custody.length!==bytes.length||canonical(state.metadata)!==canonical(custody.metadata))throw Error(`Unverified received custody for ${id}; reconcile without redispatch`);
+  return {id,request,bytes,metadata:state.metadata,requestHash,responseHash};
+}
+
+export async function assertSameRequest(source,target,request) {
+  const current={endpoint:request.endpoint,model:'gpt-image-2.5-flare',quality:'high',size:`${target.frame.output.width}x${target.frame.output.height}`,background:target.background,prompt:operationPrompt(target),inputSha256:hash(await prepareReference(source,target))};
+  if(canonical(current)!==canonical(request))throw Error('Current executor request differs from the original; no new request dispatched');
+}
+
+export function requireFailed500(call) {
+  let payload;try{payload=JSON.parse(call.bytes);}catch{throw Error('Failed response is not complete JSON; reconcile without redispatch');}
+  if(call.metadata?.status!==500||typeof payload?.error?.message!=='string'||payload.data!=null||payload.output!=null||payload.b64_json!=null)throw Error('Recovery requires a verified HTTP500 error with no image data; completed or unknown work is not retried');
+  if(call.request.backend||call.request.model!=='gpt-image-2.5-flare')throw Error('This recovery operation supports the external Flare transport only');
+  return payload.error;
+}
+
+export async function prepareRecovery({originalRun,group,runDir}) {
+  originalRun=path.resolve(originalRun);runDir=path.resolve(runDir);
+  if(!/^group-\d+$/.test(group))throw Error('Expected exact group-NN id');
+  const identity=await readJson(path.join(originalRun,'run.json'));
+  const source=await fs.readFile(path.join(originalRun,identity.source.path));
+  if(hash(source)!==identity.source.sha256)throw Error('Original source identity changed');
+  const plan=await readJson(path.join(originalRun,'plan.json')),target=plan.groups.find(g=>g.id===group);
+  if(!target)throw Error('Requested group is absent from saved plan');
+  const failed=await readReceivedCall(originalRun,'image-'+group),error=requireFailed500(failed);
+  await assertSameRequest(source,target,failed.request);
+  let plannerId='planner';
+  if(await readJson(path.join(originalRun,'contract-repair.json')))plannerId='contract-repair-1';
+  const planner=await readReceivedCall(originalRun,plannerId),assessment=assessContract(planner.bytes,identity.source);
+  if(!assessment.ok||canonical(assessment.plan.assets)!==canonical(plan.assets)||canonical(assessment.plan.groups)!==canonical(plan.groups))throw Error('Saved planner and plan do not agree; no new request dispatched');
+  const inheritedCalls=[];
+  for(const g of plan.groups.filter(g=>g.id!==group)){
+    const c=await readReceivedCall(originalRun,'image-'+g.id);
+    if(c.metadata?.status<200||c.metadata?.status>=300)throw Error('Another image group is not complete; recovery requires all other groups received successfully');
+    inheritedCalls.push({id:c.id,requestHash:c.requestHash,responseHash:c.responseHash,metadata:c.metadata});
+  }
+  const inheritedAssets=[];
+  const targetIds=new Set(target.members.map(a=>a.id));
+  for(const asset of plan.assets.filter(a=>!targetIds.has(a.id))){
+    const receipt=await readJson(path.join(originalRun,asset.id+'-delivery.json')),bytes=await fs.readFile(path.join(originalRun,receipt.path));
+    if(hash(bytes)!==receipt.sha256)throw Error('Completed asset identity changed');
+    inheritedAssets.push({receipt,bytes});
+  }
+  await fs.mkdir(runDir);
+  await fs.writeFile(path.join(runDir,identity.source.path),source);
+  await fs.cp(path.join(originalRun,'calls'),path.join(runDir,'inherited-calls'),{recursive:true});
+  await fs.copyFile(path.join(originalRun,'result.json'),path.join(runDir,'original-result.json'));
+  await writeJson(path.join(runDir,'run.json'),{...identity,kind:'confirmed-http500-recovery',originalRun,createdAt:new Date().toISOString()});
+  await writeJson(path.join(runDir,'plan.json'),plan);
+  for(const a of inheritedAssets){await fs.writeFile(path.join(runDir,a.receipt.path),a.bytes);await writeJson(path.join(runDir,a.receipt.id+'-delivery.json'),a.receipt);}
+  const record={schemaVersion:1,originalRun,group,plannerId,source:identity.source,plannedHtmlSha256:hash(assessment.normalized.html),planSha256:hash(canonical(plan)),originalResultSha256:hash(await fs.readFile(path.join(runDir,'original-result.json'))),failedCall:{id:failed.id,request:failed.request,requestHash:failed.requestHash,responseHash:failed.responseHash,metadata:failed.metadata,error},inheritedCalls,inheritedAssets:inheritedAssets.map(a=>a.receipt),maximumNewAttempts:1,createdAt:new Date().toISOString()};
+  await writeJson(path.join(runDir,'recovery.json'),record);
+  return record;
+}

package/runtime/codex-conversion/bin/recovery/run.mjs

@@ -0,0 +1,37 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import {createStore,withRunLock,hash,readJson,writeJson} from '../../src/run-store.mjs';
+import {canonical} from '../../src/run-store-io.mjs';
+import {assessContract} from '../../src/contract-repair.mjs';
+import {executeImages} from '../../src/images/execute.mjs';
+import {publishOutput} from '../../src/output.mjs';
+import {prepareRecovery,readReceivedCall,requireFailed500,assertSameRequest} from './prepare.mjs';
+
+export async function recoverImage(options,{resume=false}={}) {
+  const runDir=path.resolve(options.runDir);
+  if(!resume)await prepareRecovery({...options,runDir});
+  return withRunLock(runDir,async()=>{
+    const started=Date.now(),startedAt=new Date().toISOString();
+    try {
+      const record=await readJson(path.join(runDir,'recovery.json'));
+      if(!record||record.maximumNewAttempts!==1)throw Error('No supported recovery identity');
+      if(options.group&&options.group!==record.group||options.originalRun&&path.resolve(options.originalRun)!==record.originalRun)throw Error('Recovery input differs from recorded identity');
+      const sourcePath=path.join(runDir,record.source.path),source=await fs.readFile(sourcePath),plan=await readJson(path.join(runDir,'plan.json'));
+      if(hash(source)!==record.source.sha256||hash(canonical(plan))!==record.planSha256)throw Error('Recovery source or plan changed');
+      const failed=await readReceivedCall(runDir,record.failedCall.id,'inherited-calls');requireFailed500(failed);
+      if(failed.requestHash!==record.failedCall.requestHash||failed.responseHash!==record.failedCall.responseHash)throw Error('Original failed call changed');
+      const target=plan.groups.find(g=>g.id===record.group);await assertSameRequest(source,target,failed.request);
+      const planner=await readReceivedCall(runDir,record.plannerId,'inherited-calls'),assessment=assessContract(planner.bytes,record.source);
+      if(!assessment.ok||hash(assessment.normalized.html)!==record.plannedHtmlSha256)throw Error('Original planned HTML changed');
+      for(const asset of record.inheritedAssets)if(hash(await fs.readFile(path.join(runDir,asset.path)))!==asset.sha256)throw Error('Inherited asset changed');
+      const env={...(options.env??process.env),CODEX_CONVERSION_IMAGE_ENDPOINT:failed.request.endpoint};
+      const images=await executeImages({plan:{...plan,assets:target.members,groups:[target]},sourcePath,runDir,store:createStore(runDir),env,progress:undefined,imageBackend:'external',...(options.fetchImpl?{fetchImpl:options.fetchImpl}:{})});
+      const output=await publishOutput({runDir,normalized:assessment.normalized,assets:[...record.inheritedAssets,...images.assets],source:record.source,plan});
+      const unchangedAssets=[];
+      for(const a of record.inheritedAssets){const bytes=await fs.readFile(path.join(runDir,'output',a.id+'.png'));if(hash(bytes)!==a.sha256)throw Error('Published inherited asset changed');unchangedAssets.push({id:a.id,sha256:a.sha256});}
+      if(hash(await fs.readFile(path.join(runDir,'output/index.html')))!==record.plannedHtmlSha256)throw Error('Published planned HTML changed');
+      const result={schemaVersion:1,status:'complete',kind:'confirmed-provider-failure-recovery',output,originalRun:record.originalRun,receipts:'calls/',inheritedReceipts:'inherited-calls/',timing:{startedAt,completedAt:new Date().toISOString(),thisResumeMs:Date.now()-started,elapsedSinceRecoveryCreationMs:Date.now()-Date.parse(record.createdAt)},usage:{newCodexCalls:0,newImageCalls:images.usage.filter(g=>!g.reused).length,externalImages:images.usage},unchangedAssets,htmlSha256:record.plannedHtmlSha256,uncertainties:plan.uncertainties};
+      await writeJson(path.join(runDir,'result.json'),result);return result;
+    }catch(error){const result={schemaVersion:1,status:error.code==='NEEDS_RECONCILIATION'?'needs-reconciliation':'failed',error:{message:error.message},receipts:'calls/',inheritedReceipts:'inherited-calls/',timing:{startedAt,completedAt:new Date().toISOString(),thisResumeMs:Date.now()-started}};await writeJson(path.join(runDir,'result.json'),result);return result;}
+  });
+}