@12ui/design 0.2.76 → 0.2.78

package/dist/workspace-runner-stop.d.ts

@@ -0,0 +1,25 @@
+/**
+ * `12ui workspace runner stop`: the person's way to end the workspace runners on this Mac. Each live runner gets
+ * SIGTERM (it claims nothing more, finishes the drawing in hand, says goodbye, deletes its token and exits); a folder
+ * whose runner is gone has its leftover token deleted; and every Codex call a killed runner left running is stopped.
+ */
+export type StopScope = {
+    all: true;
+} | {
+    all: false;
+    origin: string;
+    workspace: string | null;
+};
+export type StopReport = {
+    stopped: Array<{
+        workspace: string;
+        pid: number;
+    }>;
+    codexStopped: number[];
+};
+export declare const stopWorkspaceRunners: (args: {
+    dataRoot: string;
+    scope: StopScope;
+}) => Promise<StopReport>;
+export declare const stopMessage: (report: StopReport) => string;
+//# sourceMappingURL=workspace-runner-stop.d.ts.map

package/dist/workspace-runner-stop.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"workspace-runner-stop.d.ts","sourceRoot":"","sources":["../src/workspace-runner-stop.ts"],"names":[],"mappings":"AAKA;;;;GAIG;AAEH,MAAM,MAAM,SAAS,GAAG;IAAE,GAAG,EAAE,IAAI,CAAA;CAAE,GAAG;IAAE,GAAG,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,CAAC;AAEjG,MAAM,MAAM,UAAU,GAAG;IACvB,OAAO,EAAE,KAAK,CAAC;QAAE,SAAS,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACnD,YAAY,EAAE,MAAM,EAAE,CAAC;CACxB,CAAC;AASF,eAAO,MAAM,oBAAoB,GAAU,MAAM;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,SAAS,CAAA;CAAE,KAAG,OAAO,CAAC,UAAU,CAmB3G,CAAC;AAIF,eAAO,MAAM,WAAW,GAAI,QAAQ,UAAU,KAAG,MAKhD,CAAC"}

package/dist/workspace-runner-stop.js

@@ -0,0 +1,44 @@
+import { existsSync } from 'node:fs';
+import { reapCodexChildren } from './workspace-runner-children.js';
+import { listRunnerDirs, liveRunnerHolder, removeRunnerToken, runnerDirOf } from './workspace-runner-store.js';
+const folders = async (dataRoot, scope) => {
+    if (scope.all)
+        return await listRunnerDirs(dataRoot, null);
+    if (scope.workspace === null)
+        return await listRunnerDirs(dataRoot, scope.origin);
+    const dir = runnerDirOf(dataRoot, scope.origin, scope.workspace);
+    return existsSync(dir) ? [{ dir, workspace: scope.workspace }] : [];
+};
+export const stopWorkspaceRunners = async (args) => {
+    const report = { stopped: [], codexStopped: [] };
+    for (const { dir, workspace } of await folders(args.dataRoot, args.scope)) {
+        const holder = await liveRunnerHolder(dir);
+        if (holder) {
+            try {
+                process.kill(holder.pid, 'SIGTERM');
+                report.stopped.push({ workspace, pid: holder.pid });
+            }
+            catch (error) {
+                if (error.code !== 'ESRCH')
+                    throw error;
+            }
+        }
+        else {
+            await removeRunnerToken(dir);
+        }
+        // A live runner finishes its own calls; a call whose runner is gone was left behind by a killed one.
+        const reaped = await reapCodexChildren(dir);
+        report.codexStopped.push(...reaped.filter((entry) => entry.outcome === 'stopped').map((entry) => entry.pgid));
+    }
+    return report;
+};
+const plural = (count, word) => `${count} ${word}${count === 1 ? '' : 's'}`;
+export const stopMessage = (report) => {
+    const parts = [];
+    if (report.stopped.length > 0)
+        parts.push(`Stopped ${plural(report.stopped.length, 'workspace runner')}; each finishes the drawing in hand, then exits.`);
+    if (report.codexStopped.length > 0)
+        parts.push(`Stopped ${plural(report.codexStopped.length, 'Codex call')} a killed runner left behind.`);
+    return parts.length > 0 ? parts.join(' ') : 'No workspace runner is running on this Mac.';
+};
+//# sourceMappingURL=workspace-runner-stop.js.map

package/dist/workspace-runner-stop.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"workspace-runner-stop.js","sourceRoot":"","sources":["../src/workspace-runner-stop.ts"],"names":[],"mappings":"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"}

package/dist/workspace-runner-store.d.ts

@@ -0,0 +1,26 @@
+import { type LockHolder } from './slate-lock.js';
+/** A workspace's public key as the plan names it (`wk_` and 8 hex on design.12ui.com): path-safe by construction. */
+export declare const WORKSPACE_KEY_PATTERN: RegExp;
+/** The origin is part of the key, so a local proof server and design.12ui.com never share a runner. */
+export declare const runnerDirOf: (dataRoot: string, origin: string, workspace: string) => string;
+/** Every runner folder on this Mac, or only those of one origin: `{dir, workspace}`. */
+export declare const listRunnerDirs: (dataRoot: string, origin: string | null) => Promise<Array<{
+    dir: string;
+    workspace: string;
+}>>;
+export declare const runnerLockFile: (dir: string) => string;
+export declare const ensureRunnerDir: (dir: string) => Promise<void>;
+/** Replace the token atomically (0600): a reader sees the old token or the new one, never half of either. */
+export declare const writeRunnerToken: (dir: string, token: string) => Promise<void>;
+/** The stored token, or null when it is missing or not a token. */
+export declare const readRunnerToken: (dir: string) => Promise<string | null>;
+/** When the stored token was written (its mtime), or null when there is none. */
+export declare const runnerTokenWrittenAtMs: (dir: string) => Promise<number | null>;
+/** The runner deletes the token when it exits, so no live credential is left on disk without a runner. */
+export declare const removeRunnerToken: (dir: string) => Promise<void>;
+/** The live runner's holder, or null when none holds the lock (absent, its PID gone, or its heartbeat lapsed). */
+export declare const liveRunnerHolder: (dir: string) => Promise<LockHolder | null>;
+/** One JSON line in `runner.log`. Diagnostics only: a failed write never stops the runner. */
+export declare const createRunnerLog: (dir: string, clock?: () => Date) => (entry: Record<string, unknown>) => Promise<void>;
+export type RunnerLog = ReturnType<typeof createRunnerLog>;
+//# sourceMappingURL=workspace-runner-store.d.ts.map

package/dist/workspace-runner-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"workspace-runner-store.d.ts","sourceRoot":"","sources":["../src/workspace-runner-store.ts"],"names":[],"mappings":"AAIA,OAAO,EAAyC,KAAK,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAgBzF,qHAAqH;AACrH,eAAO,MAAM,qBAAqB,QAA4B,CAAC;AAQ/D,uGAAuG;AACvG,eAAO,MAAM,WAAW,GAAI,UAAU,MAAM,EAAE,QAAQ,MAAM,EAAE,WAAW,MAAM,KAAG,MAGjF,CAAC;AAEF,wFAAwF;AACxF,eAAO,MAAM,cAAc,GAAU,UAAU,MAAM,EAAE,QAAQ,MAAM,GAAG,IAAI,KAAG,OAAO,CAAC,KAAK,CAAC;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,CAAC,CAa/H,CAAC;AAEF,eAAO,MAAM,cAAc,GAAI,KAAK,MAAM,KAAG,MAAgC,CAAC;AAI9E,eAAO,MAAM,eAAe,GAAU,KAAK,MAAM,KAAG,OAAO,CAAC,IAAI,CAG/D,CAAC;AAEF,6GAA6G;AAC7G,eAAO,MAAM,gBAAgB,GAAU,KAAK,MAAM,EAAE,OAAO,MAAM,KAAG,OAAO,CAAC,IAAI,CAU/E,CAAC;AAEF,mEAAmE;AACnE,eAAO,MAAM,eAAe,GAAU,KAAK,MAAM,KAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAQxE,CAAC;AAEF,iFAAiF;AACjF,eAAO,MAAM,sBAAsB,GAAU,KAAK,MAAM,KAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAO/E,CAAC;AAEF,0GAA0G;AAC1G,eAAO,MAAM,iBAAiB,GAAU,KAAK,MAAM,KAAG,OAAO,CAAC,IAAI,CAEjE,CAAC;AAEF,kHAAkH;AAClH,eAAO,MAAM,gBAAgB,GAAU,KAAK,MAAM,KAAG,OAAO,CAAC,UAAU,GAAG,IAAI,CAG7E,CAAC;AAEF,8FAA8F;AAC9F,eAAO,MAAM,eAAe,GAAI,KAAK,MAAM,EAAE,QAAO,MAAM,IAAuB,MAAY,OAAO,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAG,OAAO,CAAC,IAAI,CAUzI,CAAC;AAEF,MAAM,MAAM,SAAS,GAAG,UAAU,CAAC,OAAO,eAAe,CAAC,CAAC"}

package/dist/workspace-runner-store.js

@@ -0,0 +1,114 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { appendFile, chmod, mkdir, readdir, readFile, rename, rm, stat, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { holderState, staleWhenHeartbeatLapsed } from './slate-lock.js';
+/**
+ * Where the workspace runner keeps its state on this Mac: `<data root>/workspace-runner/<origin key>-<workspace>/`,
+ * a folder only this user can read (0700), holding
+ *  - `lock`: the single-instance lock (alive while the runner's PID is and its heartbeat, the mtime, is fresh);
+ *  - `token`: the workspace's newest upload token (0600), written by every `12ui workspace draw` for that workspace
+ *    and re-read by the runner before each heartbeat, so a fresher token reaches a running runner without a restart;
+ *    its mtime is when it was written, and the runner deletes it when it exits;
+ *  - `codex/<pgid>.json`: each Codex image call the runner has running, by its process group, so a call a killed
+ *    runner left behind can be found and stopped (workspace-runner-children.ts);
+ *  - `runner.log`: what it did, JSON lines, rotated at 1 MiB (its stdio goes nowhere).
+ * The token is never put on a command line or in the environment of the detached process.
+ */
+const TOKEN_PATTERN = /^wp_[0-9A-Za-z]{22}$/u;
+/** A workspace's public key as the plan names it (`wk_` and 8 hex on design.12ui.com): path-safe by construction. */
+export const WORKSPACE_KEY_PATTERN = /^wk_[0-9A-Za-z]{1,32}$/u;
+const LOG_LIMIT_BYTES = 1024 * 1024;
+const sha256 = (value) => createHash('sha256').update(value).digest('hex');
+const runnersRoot = (dataRoot) => path.join(dataRoot, 'workspace-runner');
+const originKey = (origin) => sha256(origin).slice(0, 12);
+/** The origin is part of the key, so a local proof server and design.12ui.com never share a runner. */
+export const runnerDirOf = (dataRoot, origin, workspace) => {
+    if (!WORKSPACE_KEY_PATTERN.test(workspace))
+        throw new Error(`${JSON.stringify(workspace)} is not a workspace key.`);
+    return path.join(runnersRoot(dataRoot), `${originKey(origin)}-${workspace}`);
+};
+/** Every runner folder on this Mac, or only those of one origin: `{dir, workspace}`. */
+export const listRunnerDirs = async (dataRoot, origin) => {
+    let names;
+    try {
+        names = await readdir(runnersRoot(dataRoot));
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return [];
+        throw error;
+    }
+    return names.flatMap((name) => {
+        const match = /^([0-9a-f]{12})-(wk_[0-9A-Za-z]{1,32})$/u.exec(name);
+        if (!match || (origin !== null && match[1] !== originKey(origin)))
+            return [];
+        return [{ dir: path.join(runnersRoot(dataRoot), name), workspace: match[2] }];
+    }).sort((a, b) => a.dir.localeCompare(b.dir));
+};
+export const runnerLockFile = (dir) => path.join(dir, 'lock');
+const tokenFile = (dir) => path.join(dir, 'token');
+const logFile = (dir) => path.join(dir, 'runner.log');
+export const ensureRunnerDir = async (dir) => {
+    await mkdir(dir, { recursive: true, mode: 0o700 });
+    await chmod(dir, 0o700);
+};
+/** Replace the token atomically (0600): a reader sees the old token or the new one, never half of either. */
+export const writeRunnerToken = async (dir, token) => {
+    if (!TOKEN_PATTERN.test(token))
+        throw new Error('Refusing to store something that is not an upload token.');
+    const file = tokenFile(dir);
+    const temporary = `${file}.${randomUUID()}.tmp`;
+    try {
+        await writeFile(temporary, `${token}\n`, { flag: 'wx', mode: 0o600 });
+        await rename(temporary, file);
+    }
+    finally {
+        await rm(temporary, { force: true });
+    }
+};
+/** The stored token, or null when it is missing or not a token. */
+export const readRunnerToken = async (dir) => {
+    try {
+        const value = (await readFile(tokenFile(dir), 'utf8')).trim();
+        return TOKEN_PATTERN.test(value) ? value : null;
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return null;
+        throw error;
+    }
+};
+/** When the stored token was written (its mtime), or null when there is none. */
+export const runnerTokenWrittenAtMs = async (dir) => {
+    try {
+        return (await stat(tokenFile(dir))).mtimeMs;
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return null;
+        throw error;
+    }
+};
+/** The runner deletes the token when it exits, so no live credential is left on disk without a runner. */
+export const removeRunnerToken = async (dir) => {
+    await rm(tokenFile(dir), { force: true });
+};
+/** The live runner's holder, or null when none holds the lock (absent, its PID gone, or its heartbeat lapsed). */
+export const liveRunnerHolder = async (dir) => {
+    const state = await holderState(runnerLockFile(dir), staleWhenHeartbeatLapsed);
+    return state.state === 'live' ? state.holder ?? null : null;
+};
+/** One JSON line in `runner.log`. Diagnostics only: a failed write never stops the runner. */
+export const createRunnerLog = (dir, clock = () => new Date()) => async (entry) => {
+    const file = logFile(dir);
+    try {
+        const size = await stat(file).then((info) => info.size, () => 0);
+        if (size > LOG_LIMIT_BYTES) {
+            await rm(`${file}.1`, { force: true });
+            await rename(file, `${file}.1`);
+        }
+        await appendFile(file, `${JSON.stringify({ at: clock().toISOString(), pid: process.pid, ...entry })}\n`, { mode: 0o600 });
+    }
+    catch { /* the log is diagnostics only */ }
+};
+//# sourceMappingURL=workspace-runner-store.js.map

package/dist/workspace-runner-store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"workspace-runner-store.js","sourceRoot":"","sources":["../src/workspace-runner-store.ts"],"names":[],"mappings":"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"}

package/open-design.json

@@ -3,7 +3,7 @@
   "specVersion": "1.0.0",
   "name": "12ui-design",
   "title": "12UI Design",
-  "version": "0.2.76",
+  "version": "0.2.78",
   "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.76",
+            "@12ui/design@0.2.78",
             "mcp"
           ]
         }

package/package.json

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

package/runtime/codex-conversion/src/images/native-frame.mjs

@@ -0,0 +1,103 @@
+import sharp from 'sharp';
+
+// How a native image that came back in another shape than its frame meets the frame without distortion (one module
+// for the policy, CLAUDE.md item 9). The Design workspace's options use it (`aspect-preserving-lanczos3`); conversion
+// keeps the exact stretch, whose geometry must map onto its source frame.
+//
+// Never stretch: the image is scaled by one factor on both axes. Cutting it to the frame's shape (cover) loses what
+// the cut strips hold, so it is chosen only with proof that they hold nothing: every pixel of every strip within
+// `BLANK_DELTA` of its strip's median colour on every channel. One ink pixel is no proof (CLAUDE.md item 8): a share of
+// stray pixels let a 69 px strip holding 12 pixels of a heart button's faint outline count as blank (0.2.78 gate,
+// 1606x979 into 1536x1024). Without that proof the whole image is kept (contain) and the frame's spare side is filled
+// with the colour of the image's own edge there, so nothing drawn is lost.
+
+/** A channel difference from a strip's median colour beyond which a pixel is ink. */
+export const BLANK_DELTA = 24;
+/** How many pixels deep an edge is sampled for the colour of the spare side. */
+const EDGE_DEPTH = 2;
+
+const rgbOf = async (image, region) => {
+  const {data, info} = await sharp(image).extract(region).removeAlpha().raw().toBuffer({resolveWithObject: true});
+  return {data, channels: info.channels, count: info.width * info.height};
+};
+
+/** The per-channel median colour of the pixels in `region`. */
+const medianColour = ({data, channels, count}) => {
+  const colour = [];
+  for (let channel = 0; channel < 3; channel += 1) {
+    const histogram = new Uint32Array(256);
+    for (let index = 0; index < count; index += 1) histogram[data[index * channels + Math.min(channel, channels - 1)]] += 1;
+    let seen = 0, value = 0;
+    while (value < 255 && seen + histogram[value] <= count / 2) { seen += histogram[value]; value += 1; }
+    colour.push(value);
+  }
+  return colour;
+};
+
+/** Whether a strip holds nothing: every pixel within `BLANK_DELTA` of its median colour. Any ink pixel vetoes the cut. */
+export const stripIsBlank = async (image, region) => {
+  if (region.width <= 0 || region.height <= 0) return true;
+  const pixels = await rgbOf(image, region);
+  const [r, g, b] = medianColour(pixels);
+  for (let index = 0; index < pixels.count; index += 1) {
+    const at = index * pixels.channels;
+    const c = (offset) => pixels.data[at + Math.min(offset, pixels.channels - 1)];
+    if (Math.abs(c(0) - r) > BLANK_DELTA || Math.abs(c(1) - g) > BLANK_DELTA || Math.abs(c(2) - b) > BLANK_DELTA) return false;
+  }
+  return true;
+};
+
+const hex = (colour) => `#${colour.map((value) => value.toString(16).padStart(2, '0')).join('')}`;
+
+/**
+ * The cover window: the largest part of the image in the frame's shape, centred, and the strips outside it (in the
+ * image's own pixels). An image already in the frame's shape to within a pixel has no strips.
+ */
+export const coverWindow = (actual, expected) => {
+  const {width: aw, height: ah} = actual, {width: fw, height: fh} = expected;
+  if (aw * fh > ah * fw) {
+    const kw = Math.min(aw, Math.round(ah * fw / fh)), left = Math.floor((aw - kw) / 2);
+    return {window: {left, top: 0, width: kw, height: ah}, strips: [{left: 0, top: 0, width: left, height: ah}, {left: left + kw, top: 0, width: aw - left - kw, height: ah}], axis: 'x'};
+  }
+  const kh = Math.min(ah, Math.round(aw * fh / fw)), top = Math.floor((ah - kh) / 2);
+  return {window: {left: 0, top, width: aw, height: kh}, strips: [{left: 0, top: 0, width: aw, height: top}, {left: 0, top: top + kh, width: aw, height: ah - top - kh}], axis: 'y'};
+};
+
+/**
+ * Fit `original` (PNG bytes) to `expected` without distortion: the uniform scale when its shape is the frame's (to
+ * within a pixel), the cover crop when every cut strip is blank, else the contain fit padded with the edge colours.
+ * Returns the PNG and the record of what was done.
+ */
+export async function fitToFrame(original, expected) {
+  const meta = await sharp(original).metadata();
+  const actual = {width: meta.width, height: meta.height};
+  const {window, strips, axis} = coverWindow(actual, expected);
+  /** @type {import('sharp').ResizeOptions} */
+  const resize = {fit: 'fill', kernel: 'lanczos3'};
+  if (strips.every((strip) => strip.width <= 0 || strip.height <= 0)) {
+    const png = await sharp(original).resize(expected.width, expected.height, resize).png().toBuffer();
+    return {png, normalization: {name: 'uniform-scale', kernel: 'lanczos3', output: expected, scale: expected.width / actual.width}};
+  }
+  const blank = [];
+  for (const strip of strips) blank.push(await stripIsBlank(original, strip));
+  if (blank.every(Boolean)) {
+    const png = await sharp(original).extract(window).resize(expected.width, expected.height, resize).png().toBuffer();
+    return {png, normalization: {name: 'cover-crop', kernel: 'lanczos3', output: expected, scale: expected.width / window.width, crop: window}};
+  }
+  // Contain: the whole image at one scale, the spare side filled with the colour of the image's own edge beside it.
+  const scale = Math.min(expected.width / actual.width, expected.height / actual.height);
+  const width = Math.min(expected.width, Math.max(1, Math.round(actual.width * scale)));
+  const height = Math.min(expected.height, Math.max(1, Math.round(actual.height * scale)));
+  const spare = axis === 'y' ? expected.width - width : expected.height - height;
+  const before = Math.floor(spare / 2), after = spare - before;
+  const edges = axis === 'y'
+    ? [{left: 0, top: 0, width: Math.min(EDGE_DEPTH, actual.width), height: actual.height}, {left: Math.max(0, actual.width - EDGE_DEPTH), top: 0, width: Math.min(EDGE_DEPTH, actual.width), height: actual.height}]
+    : [{left: 0, top: 0, width: actual.width, height: Math.min(EDGE_DEPTH, actual.height)}, {left: 0, top: Math.max(0, actual.height - EDGE_DEPTH), width: actual.width, height: Math.min(EDGE_DEPTH, actual.height)}];
+  const [first, second] = await Promise.all(edges.map(async (edge) => medianColour(await rgbOf(original, edge))));
+  const fill = (colour) => ({r: colour[0], g: colour[1], b: colour[2], alpha: 1});
+  const pad = axis === 'y' ? {left: before, right: after, top: 0, bottom: 0} : {left: 0, right: 0, top: before, bottom: after};
+  let png = await sharp(original).resize(width, height, resize).png().toBuffer();
+  if (before > 0) png = await sharp(png).extend(axis === 'y' ? {left: before, background: fill(first)} : {top: before, background: fill(first)}).png().toBuffer();
+  if (after > 0) png = await sharp(png).extend(axis === 'y' ? {right: after, background: fill(second)} : {bottom: after, background: fill(second)}).png().toBuffer();
+  return {png, normalization: {name: 'contain-pad', kernel: 'lanczos3', output: expected, scale, pad, colours: [hex(first), hex(second)]}};
+}

package/runtime/codex-conversion/src/images/native-invoke.mjs

@@ -8,13 +8,26 @@ import {filesUnder} from './native-files.mjs';
 import {collectNative,packNativeReceipt} from './native-collect.mjs';
 
 // Based on the successful C-N03 study invocation; separate from the no-tool planner.
+// The call is unattended (`-a never`) and its prompt carries text from outside (a person's typed edit, a plan built
+// from a source image), so its sandbox is read-only: the model may read the attached images and call the image tool,
+// whose output Codex itself records in the rollout and its own home, but any command it is talked into cannot write.
+// Proven with real Codex 0.159.3 (docs/slate-remote.md, "Image calls are read-only").
+export const NATIVE_SANDBOX = 'read-only';
 export function nativeArgv(spec, finalPath) {
   return ['-a', 'never', 'exec', '--ignore-user-config', '--ignore-rules', '--strict-config', '-C', spec.workDir,
-    '--skip-git-repo-check', '-s', 'danger-full-access', '-m', 'gpt-6-astra', '-c', 'model_reasoning_effort="medium"',
+    '--skip-git-repo-check', '-s', NATIVE_SANDBOX, '-m', 'gpt-6-astra', '-c', 'model_reasoning_effort="medium"',
     '-c', 'model_provider="openai"', '-c', 'forced_login_method="chatgpt"', '-c', 'project_doc_max_bytes=0',
     '--enable', 'skip_host_skill_discovery', '--json', '--color', 'never', '--output-last-message', finalPath,
     ...(spec.referencePaths ?? [spec.referencePath]).flatMap(file => ['--image', file]), '-'];
 }
+/**
+ * One native image call: `codex exec` in its own process group, its prompt on stdin, its events and stderr kept in the
+ * call directory. Optional in `spec`:
+ *  - `interruptOnSignal` (default true): a SIGINT or SIGTERM of this process stops the call. A caller that finishes its
+ *    calls on a signal itself (the Design workspace runner) passes false, so the call runs to its own end or timeout.
+ *  - `onSpawn({pgid, callDir})` / `onExit({pgid})`: told the child's process group (it leads its own) once it runs and
+ *    once it is gone, so a caller can find a call it left behind. A failing hook never fails the call.
+ */
 export async function invokeNative(spec, {callDir, persistMetadata}) {
   await fs.mkdir(spec.workDir, {recursive: true});
   const auth = spec.auth;
@@ -27,15 +40,21 @@ export async function invokeNative(spec, {callDir, persistMetadata}) {
   const prompt = spec.prompt;
   let timedOut = false, killTimer;
   const child = spawn(spec.binary, argv, {cwd: spec.workDir, env: subscriptionEnv(auth.home), detached: true, stdio: ['pipe', 'pipe', 'pipe']});
-  const stop = signal => { if (child.pid) try { process.kill(-child.pid, signal); } catch (error) { if (error.code !== 'ESRCH') throw error; } };
+  // ESRCH: the group is gone. EPERM: macOS answers so for a group whose members are all zombies.
+  const stop = signal => { if (child.pid) try { process.kill(-child.pid, signal); } catch (error) { if (error.code !== 'ESRCH' && error.code !== 'EPERM') throw error; } };
   const terminate = () => { stop('SIGTERM'); killTimer = setTimeout(() => stop('SIGKILL'), 5000); };
+  const hook = async (name, value) => { try { await spec[name]?.(value); } catch { /* the caller's bookkeeping only */ } };
+  const closed = new Promise(resolve => { child.once('error', error => resolve({spawnError: String(error)})); child.once('close', (exitCode, signal) => resolve({exitCode, signal})); });
   child.stdout.pipe(stdout); child.stderr.pipe(stderr); child.stdin.on('error', () => {}); child.stdin.end(prompt);
   const timer = setTimeout(() => { timedOut = true; terminate(); }, spec.timeoutMs);
+  const interruptible = spec.interruptOnSignal !== false;
   const interrupted = () => terminate();
-  process.once('SIGINT', interrupted); process.once('SIGTERM', interrupted);
-  const result = await new Promise(resolve => { child.once('error', error => resolve({spawnError: String(error)})); child.once('close', (exitCode, signal) => resolve({exitCode, signal})); });
+  if (interruptible) { process.once('SIGINT', interrupted); process.once('SIGTERM', interrupted); }
+  if (child.pid) await hook('onSpawn', {pgid: child.pid, callDir});
+  const result = await closed;
   clearTimeout(timer); clearTimeout(killTimer); stop('SIGTERM');
-  process.removeListener('SIGINT', interrupted); process.removeListener('SIGTERM', interrupted);
+  if (interruptible) { process.removeListener('SIGINT', interrupted); process.removeListener('SIGTERM', interrupted); }
+  if (child.pid) await hook('onExit', {pgid: child.pid});
   await Promise.all([finished(stdout), finished(stderr)]);
   const events=(await fs.readFile(path.join(callDir,'events.jsonl'),'utf8')).split('\n').filter(Boolean).flatMap(line=>{try{return [JSON.parse(line)];}catch{return [{type:'malformed-event'}];}});
   const diagnostics=events.filter(event=>['error','turn.failed','malformed-event'].includes(event.type));

package/runtime/codex-conversion/src/images/native.mjs

@@ -7,18 +7,27 @@ import {invokeNative} from './native-invoke.mjs';
 import {collectNative,packNativeReceipt} from './native-collect.mjs';
 import {filesUnder,inputFileNames} from './native-files.mjs';
 import {sha256,pngDimensions,parseNativeRecords} from './native-records.mjs';
+import {fitToFrame} from './native-frame.mjs';
 
-export async function decodeNativeResponse(bytes) {
+/** How a native image meets its frame: conversion's exact stretch (the default), or the aspect-preserving fit (native-frame.mjs). */
+export const NATIVE_NORMALIZATIONS=Object.freeze({stretch:'exact-stretch-lanczos3',preserveAspect:'aspect-preserving-lanczos3'});
+/** @typedef {typeof NATIVE_NORMALIZATIONS[keyof typeof NATIVE_NORMALIZATIONS]} NativeNormalization */
+/** @param {Buffer} bytes @param {{normalization?: NativeNormalization}} [options] */
+export async function decodeNativeResponse(bytes,{normalization=NATIVE_NORMALIZATIONS.stretch}={}) {
+  if(!Object.values(NATIVE_NORMALIZATIONS).includes(normalization)) throw Error('Unknown native normalization: '+normalization);
   const receipt=JSON.parse(bytes.toString('utf8'));
   if(!['exact-size-pass','size-mismatch'].includes(receipt.state)||receipt.outputs.length!==1) throw Error('Native image call requires inspection: '+receipt.state);
   if(receipt.model!=='gpt-6-astra'||receipt.effort!=='medium')throw Error('Native coordinator model/effort does not match requested execution');
   const original=Buffer.from(receipt.outputs[0].base64,'base64');
   if(sha256(original)!==receipt.outputs[0].sha256) throw Error('Native original custody mismatch');
   const actual=pngDimensions(original), expected=receipt.geometry.raw.expected;
-  const png=await sharp(original).resize(expected.width,expected.height,{fit:'fill',kernel:'lanczos3'}).png().toBuffer();
-  return {png,usage:{codexTokens:receipt.tokenUsage??[],imageUsage:null},revisedPrompt:receipt.generations[0].revisedPrompt??null,native:{originalPath:receipt.outputs[0].path,originalSha256:sha256(original),originalDimensions:actual,normalization:{name:'exact-stretch',kernel:'lanczos3',output:expected,scaleX:expected.width/actual.width,scaleY:expected.height/actual.height},model:receipt.model,effort:receipt.effort,imageModel:null,invocationCount:receipt.invocationCount}};
+  const fitted=normalization===NATIVE_NORMALIZATIONS.preserveAspect
+    ?await fitToFrame(original,expected)
+    :{png:await sharp(original).resize(expected.width,expected.height,{fit:'fill',kernel:'lanczos3'}).png().toBuffer(),normalization:{name:'exact-stretch',kernel:'lanczos3',output:expected,scaleX:expected.width/actual.width,scaleY:expected.height/actual.height}};
+  return {png:fitted.png,usage:{codexTokens:receipt.tokenUsage??[],imageUsage:null},revisedPrompt:receipt.generations[0].revisedPrompt??null,native:{originalPath:receipt.outputs[0].path,originalSha256:sha256(original),originalDimensions:actual,normalization:fitted.normalization,model:receipt.model,effort:receipt.effort,imageModel:null,invocationCount:receipt.invocationCount}};
 }
-export async function executeNativeCall({request,input,callId,store,codexBinary='codex',codexHome,timeoutMs=1800000}) {
+/** `processOptions` reaches the call's `codex exec` child: `interruptOnSignal`, `onSpawn`, `onExit` (native-invoke.mjs). */
+export async function executeNativeCall({request,input,callId,store,codexBinary='codex',codexHome,timeoutMs=1800000,processOptions={}}) {
   let auth;
   return store.runCall(callId,request,async({callDir,persistMetadata})=>{
     // One reference is the conversion case; a list attaches every image in order (design workspace edits and variations).
@@ -29,7 +38,7 @@ export async function executeNativeCall({request,input,callId,store,codexBinary=
     const referencePath=referencePaths[0];
     const inspect=referencePaths.length===1?`Use tools.view_image once to inspect ${referencePath}.`:`Use tools.view_image once for each of these files, in this order: ${referencePaths.join(', ')}.`;
     const prompt=`This is an asset-execution task. ${inspect} Then invoke tools.image_gen__imagegen exactly once with referenced_image_paths=[${referencePaths.map(file=>JSON.stringify(file)).join(', ')}] and the following prompt copied verbatim. Do not use shell, web, apps, other image providers, or image-editing code. No retries, extra calls, HTML work, or visual repair. If unavailable or unsuccessful, report failure. Emit the native image result with generatedImage and finish. Do not print base64.\n\nIMAGE PROMPT:\n${request.prompt}\n`;
-    return invokeNative({auth,binary:codexBinary,workDir:path.join(callDir,'work'),referencePath,referencePaths,prompt,timeoutMs,expected:request.expected},{callDir,persistMetadata});
+    return invokeNative({...processOptions,auth,binary:codexBinary,workDir:path.join(callDir,'work'),referencePath,referencePaths,prompt,timeoutMs,expected:request.expected},{callDir,persistMetadata});
   },{prepare:async({callDir})=>{
     const authHome=codexHome??process.env.CODEX_HOME??path.join(os.homedir(),'.codex');
     auth=await prepareHome({authHome,binary:codexBinary,runDir:callDir});

package/runtime/codex-conversion/src/run-store.mjs

@@ -3,7 +3,7 @@ import { hostname } from 'node:os';
 import { join, dirname } from 'node:path';
 import { randomUUID } from 'node:crypto';
 import { canonical, hash, readJson, writeJson, writeBytes, syncDirectory } from './run-store-io.mjs';
-export { hash, readJson, writeJson } from './run-store-io.mjs';
+export { canonical, hash, readJson, writeJson } from './run-store-io.mjs';
 /** @typedef {{bytes: Buffer, metadata?: any}} Response */
 /** @param {string} message @param {string} code */
 function failure(message, code) { return Object.assign(new Error(message), { code }); }
@@ -77,6 +77,26 @@ export function createStore(runDir) {
     },
   };
 }
+/**
+ * The response a call id already received, read back with the request it was received for, when its custody is
+ * intact (the checks `runCall` makes before it reuses one); null when the id received nothing. It only reads: a caller
+ * whose own request differs (`REQUEST_CHANGED`) decides whether that paid response serves it, and `runCall` keeps the
+ * id's identity as it is.
+ * @param {string} runDir @param {string} id
+ * @returns {Promise<{callDir: string, request: any, requestHash: string, bytes: Buffer, metadata: any} | null>}
+ */
+export async function readReceived(runDir, id) {
+  const callDir = join(runDir, 'calls', hash(id));
+  const state = await readJson(join(callDir, 'state.json'));
+  if (!state || state.id !== id || state.status === 'prepared') return null;
+  const [request, custody] = await Promise.all([readJson(join(callDir, 'request.json')), readJson(join(callDir, 'custody.json'))]);
+  let bytes = null;
+  try { bytes = await readFile(join(callDir, 'response.bin')); }
+  catch (error) { if (/** @type {NodeJS.ErrnoException} */ (error).code !== 'ENOENT') throw error; }
+  if (!bytes || !request || hash(canonical(request)) !== state.requestHash) return null;
+  if (custody?.requestHash !== state.requestHash || custody.length !== bytes.length || custody.responseHash !== hash(bytes)) return null;
+  return { callDir, request, requestHash: state.requestHash, bytes, metadata: custody.metadata };
+}
 /** @template T @param {string} runDir @param {() => Promise<T>} callback @returns {Promise<T>} */
 export async function withRunLock(runDir, callback) {
   await mkdir(runDir, { recursive: true });