pi-codex-image-gen 0.1.15 → 0.2.0

package/CHANGELOG.md

@@ -6,6 +6,30 @@ This project follows the spirit of [Keep a Changelog](https://keepachangelog.com
 
 ## [Unreleased]
 
+## [0.2.0] - 2026-10-09
+
+### Documentation
+
+- Record the decision to defer a native Pi image adapter: generic image operations do not preserve the current approval, large-original delivery, save/recovery, and usage contracts.
+- Summarize independent image credentials, absent-only legacy fallback, routing-model semantics, and separately invoked API billing.
+
+### Added
+
+- Add shared `codex_images` namespace discovery and quota/file-effect annotations without changing either entry point's exposure or the artifact-delivery contract.
+- Add `codex_generate_image_artifact` for codemode and other nested workflows, returning structured original-file metadata instead of base64 image payloads.
+- Add branch-local artifact recovery, recent-artifact edits, and `/image-artifacts`; keep completed private temporary originals through script failures and reload.
+
+### Fixed
+
+- Block legacy-account fallback when package-owned image authentication is configured but cannot be resolved, including unsupported stored credential types hidden by Pi's OAuth-only provider.
+- Make inline-delivery `codex_generate_image` model-only so nested calls cannot consume image quota while discarding attachments (#158).
+- Preserve recoverable artifacts when persistent saves fail, report post-generation storage failures without retries, and support explicit codemode display through Pi's image reader.
+- Anchor recovery before generation so cancelled commits that finish after tree navigation or session replacement remain recoverable only from the originating branch and its forks.
+
+### Changed
+
+- Update the shared Pi development and contract-test baseline to 1.1.0; require Node.js >=22.19.0 to match the host runtime. Pi remains a host-supplied peer dependency.
+
 ## [0.1.15] - 2026-10-02
 
 ### Changed

package/CONTRIBUTING.md

@@ -22,7 +22,24 @@ pi install -l /path/to/pi-mono/packages/pi-codex-image-gen
 pi
 ```
 
-With Pi 0.85.1 or later, run `/login codex-images`, complete the ChatGPT browser login, and ask Pi to generate an image. Chat can stay on `openai` OAuth. Neither the Codex app nor Pi's legacy OAuth helpers are required.
+With Pi 1.1.0 or later, run `/login codex-images`, complete the ChatGPT browser login, and ask Pi to generate an image. Chat can stay on `openai` OAuth. Neither the Codex app nor Pi's legacy OAuth helpers are required.
+
+### Image delivery smoke test
+
+The default tests use real Pi sessions with synthetic credentials and mocked SSE;
+they do not consume subscription quota. Test both nested events and the parent
+codemode result. The shared development baseline is Pi 1.1.0 on Node >=22.19.0.
+
+For an explicitly authorized live smoke test, load this package in a disposable
+Pi profile with the existing image-capable OAuth login. Keep credentials out of
+the repository and do not copy them into test fixtures. Generate one image using
+`codex_generate_image_artifact` with `save: "none"`, inspect its original pixels,
+and display it by reading `result.artifact.path` and passing the returned image
+block to `image()`. Report the reader's text note if no image block is returned.
+Run `/image-artifacts`, reload, and recover the same file without regeneration.
+Check that a nested call to `codex_generate_image` is unavailable without making
+another image request. Do not retry an ambiguous connection/quota failure.
+Do not use the separately billed API CLI.
 
 For a one-off run without changing settings:
 

package/README.md

@@ -10,6 +10,7 @@ Create and edit images without leaving [Pi](https://pi.dev).
 - **Edit from references** — transform up to five local or recent conversation images.
 - **Save where work happens** — return images inline or organize them by project, session, or custom directory.
 - **Separate image login** — keep Pi chat on `openai` OAuth while the extension handles image authentication.
+- **Scripted workflows without image payloads** — generate recoverable originals through codemode and load images only for explicit display.
 
 ## Install
 
@@ -54,9 +55,133 @@ The tool reports generation stages and the backend's returned size, quality, bac
 - Prompts: 32,000 characters. References: five regular PNG/JPEG/WebP files or conversation images, at most 20 MiB each and 50 MiB combined.
 - Responses: 100 MiB total, with at most one 32 MiB decoded output image. Base64 and format signatures are checked; this is not a full image decoder. Backend text and revised prompts are limited to 4,000 characters; HTTP error bodies are read only up to 16 KiB and are not displayed.
 - Transient HTTP failures have bounded retries. Quota exhaustion, moderation errors, failed/incomplete streams, connection errors, and deadlines are not automatically retried. Avoid immediately repeating an ambiguous failure: the first generation may have consumed quota.
-- Local save settings are checked before generation. Existing files are never overwritten; a save failure still returns the inline image and a warning.
+- Local save settings are checked before generation. Existing files are never overwritten; a persistent save failure still returns the direct inline image or scripted original artifact and a bounded warning.
 - Cloudflare challenges are reported as connection failures, not as proof that your subscription or image model is unsupported.
 
+### Direct and codemode tools
+
+Use Pi 1.1.0 or newer and Node.js >=22.19.0.
+
+| Tool | Reachability | Delivery |
+| --- | --- | --- |
+| `codex_generate_image` | Model-only; available directly with codemode off, `on`, or `only`. Nested calls are blocked. | Summary and inline image, plus an optional persistent save. |
+| `codex_generate_image_artifact` | Codemode and other nested callers. Not declared directly by default, but explicit activation is supported. | Structured metadata and an original file path; no image payload. |
+
+Pi's `codemode` exposure is not a strict codemode-only restriction. Other tools
+can call the artifact tool through `ctx.executeTool()`. If explicitly activated
+directly, it still returns paths and metadata rather than an image attachment.
+Both tools use the same generation/editing parameters, image login, backend,
+validation, and quota safeguards.
+
+Both definitions share the `codex_images` namespace and advisory hints:
+mutating, non-destructive (no overwrites), non-idempotent, and open-world.
+Generation can consume quota and write files; these hints never grant approval.
+Await `describeNamespace("codex_images")` or
+`searchTools("image artifact", { namespace: "codex_images" })` for the callable
+artifact tool, including with zero inline budget. The inline tool stays
+model-only and receives no new output schema. The artifact schema, delivery,
+recovery, explicit-request policy, and no-automatic-retry rules are unchanged.
+
+```js
+const result = await tools.codex_generate_image_artifact({
+  prompt: "A red fox in watercolor",
+  save: "none"
+});
+text(result); // summary, artifact: {path, mimeType, byteCount}, savedPath?, saveWarning?
+```
+
+For explicit display:
+
+```js
+const preview = await tools.read({ path: result.artifact.path });
+if (preview?.type === "image") image(preview);
+else text(preview); // Pi can omit images it cannot decode or bound.
+text(result.summary);
+```
+
+`read` can resize or omit an image that cannot be decoded within Pi's display
+limits. Check that its result is an image block before calling `image()` when
+handling untrusted outputs. The original file is unchanged. Do not print image
+bytes using `text()`, `console`, or `return`, or store them in codemode's store.
+Large originals (up to 32 MiB) are transported as paths, not base64 through
+codemode's 16,777,216-character output budget. Pi's `image()` also saves a
+temporary display copy.
+
+For chained edits, use `referencedImagePaths: [result.artifact.path]`.
+`numLastImagesToInclude` also reads artifact records from the current session
+branch, including generations that were never displayed. The normal 20 MiB
+per-reference and 50 MiB aggregate limits still apply: a 32 MiB output is
+recoverable but cannot be used as an edit input without first reducing its size.
+Each edit is a new generation request and can consume quota.
+
+#### Artifact storage and recovery
+
+The artifact tool reserves a new private `pi-codex-image-*` directory under the
+OS temporary directory before generating. Original files have user-only
+permissions (directory `0700`, file `0600`) and are never overwritten.
+`save: "none"` means **no persistent user copy** for this tool; it does not
+disable temporary original storage. The direct tool's `none` mode still does
+not write the image to disk.
+
+Completed originals are not automatically deleted by this extension, including
+on script failure/timeout, reload, shutdown, or branch changes. They remain
+until user or OS temporary-file cleanup; there is no guaranteed retention
+period across OS cleanup or reboot. Copy needed assets to persistent storage.
+Only incomplete reservations owned by the current call are cleaned up.
+
+Before generation, a branch-local `codex-image-artifact-reservation` entry
+anchors recovery to the originating branch. On completion, a private, bounded
+JSON manifest beside the reserved original records path, MIME type, byte count,
+and call ID. Normal same-branch completions also append a
+`codex-image-artifact` session entry, without image bytes or prompts. Late
+completions after cancellation do not append records to unrelated branches or
+replacement sessions; the original branch's reservation reads the manifest.
+Run `/image-artifacts` to list the last 20 recorded original paths on the
+current branch without generation or network work. Records survive reload,
+resume, and session forks that preserve the entries; abandoned branches are
+not included. Listing reads validated recovery manifests, not image bytes, and
+does not verify that an original still exists. A missing
+original fails recent-image editing before generation; do not regenerate it
+automatically.
+
+If temporary storage is known to be unavailable, the artifact call fails before
+generation. If writing the original fails after generation, a successful
+requested persistent save becomes the recovery artifact, with a warning. If
+neither file can be saved, the call fails explicitly: **quota may already have
+been consumed and there is no recoverable artifact**. No generation retry is
+made. A failure to persist session recovery metadata is reported with the
+recoverable file path rather than hiding the completed file.
+
+### Native Pi image models
+
+`codex-images` is an **authentication-only provider**, not an image-model
+catalog entry. Pi's `models.generateImages()` and
+`ctx.modelRegistry.generateImages()` do not expose this package's subscription
+backend. Continue using the direct or artifact tool above. OpenRouter image
+models use their own credentials/billing and are not a subscription fallback.
+
+A native adapter is deferred on the Pi 1.1.0 baseline. The generic image
+context provides text/image blocks, not this package's save modes, routing
+override, output-format control, or branch-aware recent-image selection.
+Generic calls also do not inherit the image tools' approval hooks or exclusions.
+Registering an image operation would add another callable surface, not merely
+another discovery label.
+
+Generic codemode image results are held in memory until explicitly displayed.
+An undisplayed image has no automatically saved original or `/image-artifacts`
+record. VM memory or aggregate output limits can reject display after
+generation finishes. A successful `image()` display saves a temporary copy,
+but that is not this package's pre-generation reservation and branch-recovery
+contract. The artifact tool avoids transporting large originals as base64.
+
+The current tools retain backend numeric counters in `details.usage`; these
+are informational, not Pi ledger entries or verified subscription charges.
+Pi aggregates **reported** native image usage on a codemode result, but a raw
+extension `generateImages()` call does not automatically persist it. Neither
+missing usage nor a zero catalog price proves generation is free. A future
+adapter needs an explicit accounting and unknown-cost policy as well as safe
+delivery, recovery, authentication, and approval contracts.
+
 ### Images 2.5 and API fallback
 
 The optional `skills/imagegen/scripts/image_gen.py` API CLI accepts `--model gpt-image-2.5-flare` or `--model gpt-image-2.5-sunburst`, including their `2026-09-08` snapshots. Both accept `--quality xhigh` and `--quality max` in addition to the existing quality settings. The CLI default remains `gpt-image-2`. Both 2.5 models support `--size auto` and custom dimensions such as `1536x864`, under the [documented size constraints](skills/imagegen/references/image-api.md#flexible-sizes-gpt-image-2-and-25). Resolutions above `2560x1440` are experimental.
@@ -69,6 +194,17 @@ In subscription tests on September 11, 2026, the direct endpoint accepted Flare,
 
 ## Authentication
 
+| Credential / route | Model selection | Usage and fallback |
+| --- | --- | --- |
+| `codex-images` OAuth / private Codex Responses | `model` selects a routing model, not an image model | ChatGPT image quota; preferred credential |
+| Legacy Pi `openai-codex` OAuth / same backend | Same routing semantics | Used only when owned image credentials are absent; no switch after an auth/generation failure |
+| Pi `openai` ChatGPT plan-sharing login | Any chat model | Not accepted for image generation; never sent to this backend |
+| OpenAI API key | Explicit standalone Python CLI only | Separate API billing; never an automatic fallback from the Pi tool |
+
+Changing the chat default to GPT-6.1 Sol does not change image authentication
+or certify the image backend's served model. The backend chooses the image
+model; successful inference on another route is not image capability evidence.
+
 The extension owns an image-capable ChatGPT OAuth flow, registered as **Codex Images** (`codex-images`). Pi stores its credentials and handles refresh. Your chat provider can remain `openai`; image authentication is independent.
 
 ```
@@ -77,11 +213,11 @@ The extension owns an image-capable ChatGPT OAuth flow, registered as **Codex Im
 
 Complete the browser login with your ChatGPT account. You can also run `/login` and select **Codex Images (ChatGPT subscription)**. The browser redirects to `http://localhost:1455/auth/callback`. If the callback cannot reach Pi, paste the **full redirect URL** into Pi's login prompt, not into chat. Login expires after ten minutes.
 
-Use Pi 0.85.1 or later. Pi stores the `codex-images` credential in its agent auth store (normally `~/.pi/agent/auth.json`). `/logout codex-images` removes that credential without changing your chat login. No credential files are created by the extension itself.
+Use Pi 1.1.0 or later. Pi stores the `codex-images` credential in its agent auth store (normally `~/.pi/agent/auth.json`). `/logout codex-images` removes that credential without changing your chat login. No credential files are created by the extension itself.
 
 The package implements the Codex-compatible OAuth protocol itself. It neither imports Pi's `openai-codex` OAuth helpers nor requires the Codex app or its credential store. It still depends on OpenAI continuing to accept that public OAuth client and private image endpoint; this is not a new OAuth application registered with OpenAI.
 
-Existing Pi `openai-codex` credentials remain a compatibility fallback when `codex-images` credentials are absent and the legacy provider is available. With both image logins, `codex-images` wins. A selected login that fails to refresh or generate does not switch to another account.
+Existing Pi `openai-codex` credentials remain a compatibility fallback when `codex-images` credentials are absent and the legacy provider is available. With both image logins, `codex-images` wins. A selected login that fails to refresh or generate does not switch to another account. Configured but unusable image credentials also block fallback, including a stored API-key credential that Pi's OAuth-only provider cannot resolve. Re-run `/login codex-images` to repair that login instead of silently using a different account.
 
 Both image logins use `https://chatgpt.com/backend-api/codex/responses`. Pi's new `openai` plan-sharing OAuth grant is different and [does not support image generation](https://developers.openai.com/siwc/token-sharing-open-source/preview-limitations). The extension never sends that chat token to the Codex backend. API keys do **not** enable this tool or API-key billing.
 
@@ -125,13 +261,15 @@ Project config overrides global config only when project trust is active. If pro
 
 | Mode      | Behavior                                                         |
 | --------- | ---------------------------------------------------------------- |
-| `none`    | Image is returned inline but not written to disk.                |
+| `none`    | Direct tool: inline image, no disk save. Artifact tool: private temporary original, no persistent copy. |
 | `project` | Saves to `<project>/.pi/generated-images/<session-id>/`.         |
 | `global`  | Saves to `~/.pi/agent/generated-images/<session-id>/`.           |
 | `custom`  | Saves to a user-specified directory (requires `saveDir` or env). `~` and `~/...` expand to the current user's home directory. |
 
 ## Tool parameters
 
+Both generation entry points accept these parameters.
+
 | Parameter      | Type   | Required | Description                                                        |
 | -------------- | ------ | -------- | ------------------------------------------------------------------ |
 | `prompt`       | string | ✅        | The image generation prompt.                                       |
@@ -149,8 +287,9 @@ Project config overrides global config only when project trust is active. If pro
 3. For edits, attaches the selected local or conversation images to the request.
 4. The backend selects an image model to generate or edit the image.
 5. Parses the SSE stream and strictly validates the returned base64 and image format.
-6. Saves the image according to the active save mode; persistence failures produce a warning without discarding a valid inline image.
-7. Returns the image data inline plus metadata (model, format, path, revised prompt, usage).
+6. For the artifact tool, commits the reserved temporary original and records its branch-local recovery metadata.
+7. Saves a persistent copy according to the active save mode; failures produce a bounded warning without discarding a usable inline image or artifact.
+8. Returns the direct inline image or structured artifact metadata. Codemode displays an image only through an explicit `read` and `image()` operation.
 
 ## Troubleshooting
 

package/SECURITY.md

@@ -21,7 +21,7 @@ The maintainer will acknowledge reports as soon as practical and coordinate disc
 
 `pi-codex-image-gen` is a Pi package. Pi extensions execute with the same permissions as the local user running Pi. Users should review installed Pi packages and only install packages from sources they trust.
 
-The extension implements image-capable ChatGPT OAuth under the provider ID `codex-images`, using the Codex-compatible public OAuth client ID (not a client secret). Pi stores access/refresh tokens in its agent credential store, normally `~/.pi/agent/auth.json`, and coordinates refresh. This is local credential persistence, not encrypted secret storage; protect the agent directory and do not commit it. The extension does not write its own credential files or access the Codex app's credential store. `/logout codex-images` removes only the image login. Existing legacy Pi `openai-codex` OAuth remains a fallback when package-owned credentials are absent; refresh or request failure does not switch accounts.
+The extension implements image-capable ChatGPT OAuth under the provider ID `codex-images`, using the Codex-compatible public OAuth client ID (not a client secret). Pi stores access/refresh tokens in its agent credential store, normally `~/.pi/agent/auth.json`, and coordinates refresh. This is local credential persistence, not encrypted secret storage; protect the agent directory and do not commit it. The extension does not write its own credential files or access the Codex app's credential store. `/logout codex-images` removes only the image login. Existing legacy Pi `openai-codex` OAuth remains a fallback when package-owned credentials are absent; refresh or request failure does not switch accounts. An unresolved owned login also checks Pi's provider-auth configuration status: a configured but unusable credential is an error, not permission to try a different account. This includes a stored API-key credential unsupported by the OAuth-only provider; no credential file is read directly by the extension.
 
 Browser login uses random OAuth state and S256 PKCE. Its callback listener binds only to `127.0.0.1:1455`; the registered redirect URI is `http://localhost:1455/auth/callback`. Loopback HTTP is limited to this local callback. Automatic and pasted callbacks must have the expected origin, path, and state. Pasted input must be the full redirect URL, never a bare authorization code. Invalid callbacks cannot finish login. Listener cleanup runs on success, failure, and cancellation. Login has a ten-minute limit; token requests have a 30-second limit and 64 KiB response bound, with no retries or redirects. Do not paste login URLs into chat or log them.
 
@@ -31,4 +31,52 @@ Network work has a five-minute deadline and a 100 MiB response bound. Output ima
 
 Generated files are created exclusively with user-only permissions. A repeated backend ID or existing destination produces a save warning rather than overwriting that file. Cancellation and stream failures do not trigger automatic generation retries because the remote operation may already have consumed quota.
 
+The inline-delivery tool is `model-only`; Pi blocks nested calls before execution.
+The artifact tool uses `codemode` exposure, not an exclusive codemode permission:
+other nested tools and explicitly activated direct calls can use it. Tool
+discovery does not initiate generation or credential resolution. Both entry
+points preserve the same OAuth and backend limits.
+
+The provider exposes no native image models. A native image operation would
+be separately callable through `models.generateImages()`, without inheriting
+the named tools' approval hooks or exclusions. Such an adapter is deferred;
+the generic API is not an alternate route around these tools' restrictions.
+Backend counters in `details.usage` are informational and do not establish
+metered session usage, remaining quota, or a verified subscription price.
+
+Artifact generation reserves a private random OS temporary directory (`0700`)
+and an exclusively created original file (`0600`) before requesting generation.
+The opened file descriptor is used for writes; a synced, regular file with the
+same inode/device and expected length must remain at the returned path.
+Successful originals are retained through script errors, reload, shutdown, and
+branch changes; only incomplete reservations are deleted by the extension.
+There is no automatic expiry. User/OS cleanup can remove them at any time, so
+temporary paths are not durable project assets. `save: "none"` on the artifact
+tool still writes this temporary original. Protect or explicitly remove
+sensitive images when no longer needed.
+
+The session stores bounded artifact metadata (path, MIME type, byte count, call
+ID), not generated bytes, prompts, or credentials. A pre-generation reservation
+entry anchors the operation to its source branch. A private `0600` JSON
+completion manifest in the reserved directory allows late completions to be
+recovered without appending state to an unrelated current branch/session.
+Forks and resumes that retain the reservation can recover the same original.
+Fallback persistent copies keep the private recovery manifest, but remove any
+incomplete temporary original.
+
+`/image-artifacts` exposes the last 20 current-branch paths without reading
+image bytes or accessing the network. Manifest reads reject symlinks and
+non-regular files, are capped at 8 KiB, and validate the returned metadata and
+its reservation identity. Session metadata is validated before recent-image selection or
+listing. Recent artifact inputs receive the existing regular-file, signature,
+and input-size checks. Explicit display uses Pi's image reader and can resize
+or omit un-decodable images without modifying originals.
+
+A failed persistent copy does not remove a committed temporary original. If
+the temporary write fails after generation, a successful requested persistent
+copy can serve as the artifact; if both are unavailable, the tool reports an
+explicit post-generation failure and possible quota consumption, not success
+or an automatic retry. Disk or session-store failures cannot guarantee recovery.
+Base64 originals do not cross codemode's structured generation-result boundary.
+
 At startup, `@mocito/install-telemetry` sends a best-effort install/update ping to the configured telemetry endpoint once per package version unless CI, Pi offline/telemetry settings, or `enableInstallTelemetry: false` disables it. It contains only the package name/version and parsed platform/runtime/architecture; it does not include prompts, file paths, configuration values, credentials, or provider responses.

package/extensions/index.ts

@@ -1,7 +1,7 @@
 /**
  * Project-local Codex image generation extension.
  *
- * Registers `codex_generate_image`, a tool that uses package-owned
+ * Registers inline and artifact image tools that use package-owned
  * ChatGPT image OAuth or legacy Pi auth to call the Codex Responses backend with the
  * native `image_generation` tool. The backend selects the image model.
  */
@@ -12,11 +12,12 @@ import { mkdir, open, writeFile } from "node:fs/promises";
 import { homedir } from "node:os";
 import { isAbsolute, join, resolve } from "node:path";
 import { StringEnum } from "@earendil-works/pi-ai";
-import { CONFIG_DIR_NAME, type ExtensionAPI, type ExtensionContext, getAgentDir, withFileMutationQueue } from "@earendil-works/pi-coding-agent";
+import { CONFIG_DIR_NAME, type ExtensionAPI, type ExtensionContext, type ExtensionToolContext, type AgentToolUpdateCallback, type AgentToolResult, getAgentDir, withFileMutationQueue } from "@earendil-works/pi-coding-agent";
 import { type Static, Type } from "typebox";
 import { reportInstallTelemetry } from "../src/install-telemetry.js";
 import { extractImageAccountId, imageAuthProvider, IMAGE_AUTH_PROVIDER } from "../src/image-oauth.js";
 import { abortable, httpFailure, MAX_IMAGE_BYTES, parseCodexSse, withRequestDeadline, type ParsedCodexResponse } from "../src/codex-response.js";
+import { ARTIFACT_ENTRY, RESERVATION_ENTRY, artifactRecord, artifactReservation, readArtifactManifest, branchArtifacts, reserveArtifact, type ImageArtifact } from "../src/artifacts.js";
 
 const PACKAGE_NAME = "pi-codex-image-gen";
 const LEGACY_PROVIDER = "openai-codex";
@@ -117,6 +118,17 @@ const TOOL_PARAMS = Type.Object({
 
 type ToolParams = Static<typeof TOOL_PARAMS>;
 
+const ARTIFACT_OUTPUT = Type.Object({
+	summary: Type.String(),
+	artifact: Type.Object({
+		path: Type.String(),
+		mimeType: StringEnum(["image/png", "image/jpeg", "image/webp"]),
+		byteCount: Type.Integer({ minimum: 1, maximum: MAX_IMAGE_BYTES }),
+	}),
+	savedPath: Type.Optional(Type.String()),
+	saveWarning: Type.Optional(Type.String()),
+});
+
 // --- Config types ---
 
 interface ExtensionConfig {
@@ -149,6 +161,13 @@ async function resolveImageAuth(registry: ExtensionContext["modelRegistry"]): Pr
 		try {
 			if (typeof registry.getProviderAuth === "function") {
 				const resolved = await registry.getProviderAuth(provider);
+				// Pi returns undefined for a stored credential whose type this
+				// OAuth-only provider cannot use. That is not an absent login and
+				// must not silently select a different account's legacy OAuth.
+				if (!resolved && provider === IMAGE_AUTH_PROVIDER
+					&& registry.getProviderAuthStatus?.(provider).configured) {
+					throw new Error("Configured image credentials could not be resolved.");
+				}
 				if (resolved && resolved.source !== "OAuth") {
 					throw new Error("Image credentials must use OAuth.");
 				}
@@ -271,15 +290,19 @@ async function saveImage(
 	return filePath;
 }
 
-export function selectRecentImages(messages: unknown[], count: number): InputImage[] {
-	const images: InputImage[] = [];
+type RecentImage = InputImage | { path: string; mimeType: string };
+
+export function selectRecentImages(messages: unknown[], count: number): RecentImage[] {
+	const images: RecentImage[] = [];
 	for (let index = messages.length - 1; index >= 0 && images.length < count; index--) {
 		const message = messages[index] as { content?: unknown };
 		if (!Array.isArray(message?.content)) continue;
 		for (let contentIndex = message.content.length - 1; contentIndex >= 0 && images.length < count; contentIndex--) {
-			const block = message.content[contentIndex] as { type?: unknown; data?: unknown; mimeType?: unknown };
+			const block = message.content[contentIndex] as { type?: unknown; data?: unknown; mimeType?: unknown; path?: unknown };
 			if (block?.type === "image" && typeof block.data === "string" && typeof block.mimeType === "string") {
 				images.push({ data: block.data, mimeType: block.mimeType });
+			} else if (block?.type === "image_artifact" && typeof block.path === "string" && typeof block.mimeType === "string") {
+				images.push({ path: block.path, mimeType: block.mimeType });
 			}
 		}
 	}
@@ -349,12 +372,16 @@ export async function resolveInputImages(
 		if (!Number.isInteger(count) || count < 1 || count > MAX_EDIT_IMAGES) {
 			throw new Error(`numLastImagesToInclude must be between 1 and ${MAX_EDIT_IMAGES}.`);
 		}
-		const images = selectRecentImages(messages, count);
-		if (images.length !== count) {
-			throw new Error(`Requested the last ${count} conversation images, but only ${images.length} were available.`);
+		const recent = selectRecentImages(messages, count);
+		if (recent.length !== count) {
+			throw new Error(`Requested the last ${count} conversation images, but only ${recent.length} were available.`);
 		}
+		const images: InputImage[] = [];
 		let total = 0;
-		for (const image of images) {
+		for (const selected of recent) {
+			const image = "path" in selected
+				? { data: (await readInputImage(selected.path)).toString("base64"), mimeType: selected.mimeType }
+				: selected;
 			if (image.data.length > Math.ceil(MAX_INPUT_IMAGE_BYTES / 3) * 4) throw new Error("Conversation image exceeds 20 MiB.");
 			const format = OUTPUT_FORMATS.find(format => mimeForFormat(format) === image.mimeType);
 			if (!format) throw new Error("Conversation image has an unsupported format.");
@@ -362,6 +389,7 @@ export async function resolveInputImages(
 			if (bytes.length > MAX_INPUT_IMAGE_BYTES) throw new Error("Conversation image exceeds 20 MiB.");
 			total += bytes.length;
 			if (total > MAX_TOTAL_INPUT_BYTES) throw new Error("Conversation images exceed 50 MiB in total.");
+			images.push(image);
 		}
 		return images;
 	}
@@ -464,22 +492,44 @@ export default function codexImageGen(pi: ExtensionAPI) {
 	reportInstallTelemetry();
 	pi.registerProvider(imageAuthProvider);
 
-	pi.registerTool({
-		name: "codex_generate_image",
-		label: "Codex Image",
-		description:
-			"Generate or edit an image with the OpenAI Codex ChatGPT backend built-in image_generation tool. The backend selects the image model. Accepts up to five local or recent conversation images (20 MiB each, 50 MiB total). Requires /login codex-images or existing legacy Pi OAuth credentials; works with openai OAuth chat and does not require the Codex app or an API key. Network deadline: 5 minutes; output image limit: 32 MiB; backend text is limited to 4,000 characters.",
-		promptSnippet: "Generate or edit bitmap images via the OpenAI Codex ChatGPT backend image_generation tool.",
-		promptGuidelines: [
-			"Use codex_generate_image when the user asks to generate or edit a raster image with OpenAI/Codex image generation.",
-			"Do not use codex_generate_image without a clear image-generation request, because it consumes the user's Codex image quota.",
-			"The model parameter selects a Codex routing model, not an image model. Do not pass gpt-image-* IDs.",
-			"Output metadata is backend-reported, not independently verified. Check pixels for dimensions and transparency; do not infer a served model from appearance or a successful request.",
-			"Do not automatically repeat quota, connection, deadline, or incomplete-stream failures. The backend may already have consumed image quota.",
-		],
-		parameters: TOOL_PARAMS,
-		executionMode: "parallel", // #4: safe to run concurrently — no shared state, saves serialized per-path
-		async execute(toolCallId, params: ToolParams, signal, onUpdate, ctx) {
+	const guidelines = [
+		"Generate or edit images only on a clear user request; each call consumes Codex image quota.",
+		"The model parameter selects a Codex routing model, not an image model. Do not pass gpt-image-* IDs.",
+		"Output metadata is backend-reported. Inspect pixels for dimensions and transparency; do not infer a served model.",
+		"Do not automatically repeat quota, connection, deadline, incomplete-stream, or artifact-storage failures. Quota may already have been consumed.",
+	];
+
+	async function recordOriginal(
+		artifact: ImageArtifact, toolCallId: string, reservation: Awaited<ReturnType<typeof reserveArtifact>>,
+		ctx: ExtensionToolContext, sessionId: string, originEntryId: string | null,
+	): Promise<string | undefined> {
+		const record = { artifact, toolCallId: toolCallId.slice(0, 256) };
+		let manifestPublished = false;
+		try {
+			await reservation.publish(record);
+			manifestPublished = true;
+		} catch { /* A completed original must survive a metadata-storage failure. */ }
+		// Do not attach late results to an unrelated branch or a replacement
+		// session. The pre-generation reservation and private manifest preserve
+		// recovery on the originating branch, including its forks and resumes.
+		try {
+			if (ctx.sessionManager.getSessionId() === sessionId && originEntryId
+				&& ctx.sessionManager.getBranch().some(entry => entry.id === originEntryId)) {
+				pi.appendEntry(ARTIFACT_ENTRY, record);
+				return undefined;
+			}
+		} catch { /* The context may be inactive after reload; use the manifest. */ }
+		if (manifestPublished) return undefined;
+		return `Artifact recovery metadata could not be persisted. Recover the image from ${artifact.path}. No generation retry was made.`;
+	}
+
+	async function executeImage(
+		artifactMode: boolean, toolCallId: string, params: ToolParams, signal: AbortSignal | undefined,
+		onUpdate: AgentToolUpdateCallback<unknown> | undefined, ctx: ExtensionToolContext,
+	): Promise<AgentToolResult<unknown>> {
+		let reservation: Awaited<ReturnType<typeof reserveArtifact>> | undefined;
+		let originEntryId: string | null = null;
+		try {
 			if (typeof params.prompt !== "string" || !params.prompt.trim() || params.prompt.length > MAX_PROMPT_CHARS) {
 				throw new Error("Image prompt must contain 1 to 32,000 characters.");
 			}
@@ -496,15 +546,48 @@ export default function codexImageGen(pi: ExtensionAPI) {
 			}
 			const sessionId = ctx.sessionManager.getSessionId();
 			const saveConfig = resolveSaveConfig(params, ctx.cwd, sessionId, config);
-			const auth = await resolveImageAuth(ctx.modelRegistry);
-			const provider = auth.provider;
-			const model = ctx.modelRegistry.find(provider, requestedModel)?.id || requestedModel;
 			const messages: unknown[] = [];
-			for (const entry of ctx.sessionManager.getBranch()) {
+			const branch = ctx.sessionManager.getBranch();
+			const completedPaths = new Set(branch.flatMap(entry => {
+				const record = entry.type === "custom" && entry.customType === ARTIFACT_ENTRY ? artifactRecord(entry.data) : undefined;
+				return record ? [record.artifact.path] : [];
+			}));
+			for (const entry of params.numLastImagesToInclude !== undefined ? branch : []) {
 				if (entry.type === "message") messages.push(entry.message);
 				if (entry.type === "custom_message") messages.push(entry);
+				if (entry.type === "custom" && entry.customType === ARTIFACT_ENTRY) {
+					const record = artifactRecord(entry.data);
+					if (record) messages.push({ content: [{ type: "image_artifact", ...record.artifact }] });
+				}
+				if (entry.type === "custom" && entry.customType === RESERVATION_ENTRY) {
+					const pending = artifactReservation(entry.data);
+					const record = pending ? await readArtifactManifest(pending) : undefined;
+					// Normal completions also have a session entry. Prefer that
+					// later entry and avoid counting the same original twice.
+					if (record && !completedPaths.has(record.artifact.path)) {
+						messages.push({ content: [{ type: "image_artifact", ...record.artifact }] });
+					}
+				}
 			}
 			const inputImages = await resolveInputImages(params, ctx.cwd, messages);
+			signal?.throwIfAborted();
+			if (artifactMode) {
+				try {
+					reservation = await reserveArtifact(extensionForFormat(outputFormat));
+				} catch {
+					throw new Error("Image artifact storage is unavailable. No generation request was made.");
+				}
+				signal?.throwIfAborted();
+				// Attach the recovery anchor synchronously before quota/network
+				// work. A cancelled parent may settle while commit I/O is pending.
+				pi.appendEntry(RESERVATION_ENTRY, {
+					path: reservation.path, mimeType: mimeForFormat(outputFormat), toolCallId: toolCallId.slice(0, 256),
+				});
+				originEntryId = ctx.sessionManager.getLeafId();
+			}
+			const auth = await resolveImageAuth(ctx.modelRegistry);
+			const provider = auth.provider;
+			const model = ctx.modelRegistry.find(provider, requestedModel)?.id || requestedModel;
 
 			onUpdate?.({
 				content: [{ type: "text", text: `Requesting image ${inputImages.length > 0 ? "edit" : "generation"} through ${provider}/${model}...` }],
@@ -528,18 +611,37 @@ export default function codexImageGen(pi: ExtensionAPI) {
 			let savedPath: string | undefined;
 			let attemptedPath: string | undefined;
 			let saveWarning: string | undefined;
+			let artifact: ImageArtifact | undefined;
+			let recoveryWarning: string | undefined;
+			if (reservation) {
+				try {
+					artifact = await reservation.commit(imageBytes, mimeForFormat(outputFormat));
+				} catch {
+					// Attempt the requested persistent copy below, never generation again.
+				}
+				// Persist before callbacks, persistent saves, or parent script output.
+				if (artifact) recoveryWarning = await recordOriginal(artifact, toolCallId, reservation, ctx, sessionId, originEntryId);
+			}
 			if (saveConfig.mode !== "none" && saveConfig.outputDir) {
 				attemptedPath = imagePath(outputFormat, saveConfig.outputDir, parsed.image.id || toolCallId);
 				try {
 					savedPath = await saveImage(imageBytes, outputFormat, saveConfig.outputDir, parsed.image.id || toolCallId);
-					onUpdate?.({
-						content: [{ type: "text", text: `Image saved to ${savedPath}.` }],
-						details: { provider, model, savedPath, byteCount: imageBytes.length },
-					});
 				} catch (error) {
-					saveWarning = `Image generation succeeded, but the image could not be saved to disk: ${error instanceof Error ? error.message : String(error)}`;
+					const reason = (error instanceof Error ? error.message : String(error))
+						.replace(/[\u0000-\u001f\u007f-\u009f]/g, " ").slice(0, 500);
+					saveWarning = `Image generation succeeded, but the image could not be saved to disk: ${reason}`;
+				}
+			}
+			if (artifactMode && !artifact) {
+				if (savedPath) {
+					artifact = { path: savedPath, mimeType: mimeForFormat(outputFormat), byteCount: imageBytes.length };
+					recoveryWarning = await recordOriginal(artifact, toolCallId, reservation!, ctx, sessionId, originEntryId);
+					saveWarning = "Temporary artifact storage failed; recover the original from the persistent saved path. No generation retry was made.";
+				} else {
+					throw new Error("Image generation succeeded, but artifact storage failed and no usable file could be saved. Image quota may have been consumed. No automatic retry was made.");
 				}
 			}
+			saveWarning = [saveWarning, recoveryWarning].filter(Boolean).join(" ") || undefined;
 
 			const summary = [
 				`Generated image via ${provider}/${model} using the backend-selected image model.`,
@@ -548,17 +650,28 @@ export default function codexImageGen(pi: ExtensionAPI) {
 				reportedImage.quality ? `Backend-reported quality: ${reportedImage.quality}.` : undefined,
 				reportedImage.background ? `Backend-reported background: ${reportedImage.background}.` : undefined,
 				parsed.image.revisedPrompt ? `Revised prompt: ${parsed.image.revisedPrompt}` : undefined,
-				savedPath ? `Saved image to: ${savedPath}` : "Image was not saved to disk.",
+				artifact ? `Original image artifact: ${artifact.path}.` : undefined,
+				savedPath ? `Saved image to: ${savedPath}` : artifactMode ? "No persistent image copy was saved." : "Image was not saved to disk.",
 				saveWarning ? `Warning: ${saveWarning}` : undefined,
 			]
 				.filter(Boolean)
 				.join(" ");
 
+			if (savedPath || artifact) onUpdate?.({
+				content: [{ type: "text", text: artifact ? `Original image artifact: ${artifact.path}.` : `Image saved to ${savedPath}.` }],
+				details: { provider, model, savedPath, artifact, byteCount: imageBytes.length },
+			});
+
 			return {
 				content: [
 					{ type: "text", text: summary },
-					{ type: "image", data: parsed.image.result, mimeType: mimeForFormat(outputFormat) },
+					...(!artifactMode ? [{ type: "image" as const, data: parsed.image.result, mimeType: mimeForFormat(outputFormat) }] : []),
 				],
+				...(artifact ? { structuredContent: {
+					summary, artifact: { ...artifact },
+					...(savedPath ? { savedPath } : {}),
+					...(saveWarning ? { saveWarning } : {}),
+				} } : {}),
 				details: {
 					provider,
 					model,
@@ -570,6 +683,7 @@ export default function codexImageGen(pi: ExtensionAPI) {
 					outputFormat,
 					saveMode: saveConfig.mode,
 					savedPath,
+					artifact,
 					attemptedPath,
 					saveWarning,
 					inputImageCount: inputImages.length,
@@ -579,6 +693,61 @@ export default function codexImageGen(pi: ExtensionAPI) {
 					usage: parsed.usage,
 				},
 			};
+		} finally {
+			// Cleanup only reservations made by this call, never completed originals.
+			await reservation?.dispose().catch(() => undefined);
+		}
+	}
+
+	const description = "Generate or edit an image with the OpenAI Codex ChatGPT backend built-in image_generation tool. The backend selects the image model. Accepts up to five local or recent conversation images (20 MiB each, 50 MiB total). Requires /login codex-images or existing legacy Pi OAuth credentials; works with openai OAuth chat and does not require the Codex app or an API key. Network deadline: 5 minutes; output image limit: 32 MiB; backend text is limited to 4,000 characters.";
+	const metadata = {
+		namespace: {
+			name: "codex_images",
+			description: "Quota-consuming image generation and private original artifacts.",
+			instructions: "Generate only on an explicit image request. codex_generate_image is model-only and returns an inline image. Scripts use codex_generate_image_artifact and receive metadata with artifact.path, never base64; read that path and use image(block) only for requested display. Completed originals survive script failures/reload; save=none still creates temporary originals. Calls consume quota and may write files, so do not automatically retry failures. Await each artifact before using it for an edit. Existing OAuth, approval and exposure rules still apply.",
+		},
+		annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true },
+	};
+	pi.registerTool({
+		...metadata,
+		name: "codex_generate_image",
+		label: "Codex Image",
+		exposure: "model-only",
+		description: `${description} Direct model calls only; returns an inline image. For codemode workflows use codex_generate_image_artifact.`,
+		promptSnippet: "Generate or edit bitmap images via the OpenAI Codex ChatGPT backend image_generation tool.",
+		promptGuidelines: guidelines,
+		parameters: TOOL_PARAMS,
+		executionMode: "parallel",
+		execute: (id, params, signal, update, ctx) => executeImage(false, id, params, signal, update, ctx),
+	});
+	pi.registerTool({
+		...metadata,
+		name: "codex_generate_image_artifact",
+		label: "Codex Image Artifact",
+		exposure: "codemode",
+		description: `${description} Returns structured metadata and a private temporary original path, never image bytes. save=none disables persistent copies, not temporary storage. Completed artifacts survive script errors and reload until user/OS cleanup. Read artifact.path and call image(block) only for explicit display. Other nested callers and explicitly activated direct calls are supported. Recover current-branch paths with /image-artifacts.`,
+		promptGuidelines: [
+			...guidelines,
+			"For display read result.artifact.path and call image(block) only if read returns an image block; otherwise report its text note. Do not print image bytes.",
+			"For chained edits pass result.artifact.path through referencedImagePaths; each edit consumes quota.",
+		],
+		parameters: TOOL_PARAMS,
+		outputSchema: ARTIFACT_OUTPUT,
+		executionMode: "parallel",
+		execute: (id, params, signal, update, ctx) => executeImage(true, id, params, signal, update, ctx),
+	});
+	pi.registerCommand("image-artifacts", {
+		description: "List the last 20 generated original artifact paths on the current branch (no generation).",
+		handler: async (_args, ctx) => {
+			const records = (await branchArtifacts(ctx.sessionManager.getBranch())).slice(-20);
+			pi.sendMessage({
+				customType: "codex-image-artifact-list",
+				content: records.length ? records.map(record =>
+					`${record.artifact.path} (${record.artifact.mimeType}, ${record.artifact.byteCount} bytes)`,
+				).join("\n") + "\nTemporary originals may be removed by user/OS cleanup. Copy needed assets to persistent storage."
+					: "No image artifacts recorded on this branch.",
+				display: true,
+			});
 		},
 	});
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-codex-image-gen",
-  "version": "0.1.15",
+  "version": "0.2.0",
   "description": "Image generation and editing for Pi using your ChatGPT Codex login.",
   "type": "module",
   "license": "Apache-2.0",
@@ -58,17 +58,17 @@
     "typebox": "*"
   },
   "devDependencies": {
-    "@earendil-works/pi-ai": "^0.85.1",
-    "@earendil-works/pi-coding-agent": "^0.85.1",
-    "@types/node": "^26.2.0",
-    "typebox": "^1.3.10",
+    "@earendil-works/pi-ai": "1.1.0",
+    "@earendil-works/pi-coding-agent": "1.1.0",
+    "@types/node": "^26.6.3",
+    "typebox": "^1.3.34",
     "typescript": "^7.0.2"
   },
   "publishConfig": {
     "access": "public"
   },
   "engines": {
-    "node": ">=20.6.0"
+    "node": ">=22.19.0"
   },
   "dependencies": {
     "@mocito/install-telemetry": "0.1.1"

package/skills/imagegen/SKILL.md

@@ -26,7 +26,13 @@ Within CLI fallback, the CLI exposes three subcommands:
 
 Rules:
 - Use the Pi `codex_generate_image` tool by default for new image generation requests.
+- `codex_generate_image` is model-only; call it directly, never through codemode. For scripted workflows use `tools.codex_generate_image_artifact(...)`, which returns `{ summary, artifact: { path, mimeType, byteCount }, savedPath?, saveWarning? }` without image bytes. Both tools support the same generation/edit parameters and subscription login. Use Pi >=1.1.0.
+- To display an artifact, call `tools.read({path: result.artifact.path})`, then `image(block)` if the returned value is an image block. Pi can resize or omit an un-decodable display image; the original remains unchanged. Never print or store base64 image bytes. Pass artifact paths directly through `referencedImagePaths` for chained edits.
+- Artifact `save: "none"` still writes a private temporary original; it means no persistent user copy. Completed originals survive script failure/timeout, reload, shutdown, and branch changes until user/OS cleanup. Copy needed project assets to persistent storage. Run `/image-artifacts` to recover current-branch paths without generation. Recent-image selection includes branch-local original artifacts, even if never displayed; reference-size limits still apply.
+- Do not retry artifact-storage failures automatically. Known storage failures reject before generation; failures after backend success can already have consumed quota. A successful requested persistent save can be used as recovery if the temporary write fails. If neither succeeds, the tool explicitly reports that no artifact is recoverable.
 - Image login is separate from chat: use `/login codex-images` and complete the ChatGPT OAuth flow in Pi. The Codex app is not required. Existing legacy Pi `openai-codex` OAuth can be a fallback; new `openai` plan-sharing chat OAuth cannot generate images. Never ask the user to paste login URLs or tokens into chat.
+- Legacy OAuth is used only when owned image credentials are absent. Configured but unusable `codex-images` credentials block fallback; repair that login instead of switching accounts.
+- `codex-images` has no native Pi image-model entry. Do not substitute `models.generateImages()` or an OpenRouter image model for these subscription tools: native image calls do not inherit their approval, save/recovery, output-size, or billing contracts.
 - The tool's `model` parameter selects a Codex routing model, not Flare or Sunburst. Do not claim a specific served image model unless the response reports it. Read `details.reportedImage` for backend-reported output settings, then inspect the actual image; prompt requests for quality, dimensions, or transparency are not guarantees.
 - The default routing model is `gpt-6-astra`. Explicit tool parameters and configuration values override this default.
 - Do not automatically repeat quota, connection, timeout, or incomplete-stream failures. The remote generation may already have consumed quota.
@@ -42,7 +48,7 @@ Rules:
 
 Pi tool save-path policy:
 - In Pi tool mode, generated images are saved under Pi's agent directory by default: `<pi-agent-dir>/generated-images/<pi-session-id>/<image-call-id>.*`. The default Pi agent directory is `~/.pi/agent`, but it can be overridden with `PI_CODING_AGENT_DIR`; use Pi's configured agent directory, not a hardcoded home path.
-- Do not describe or rely on OS temp as the default Pi tool destination.
+- Do not describe OS temp as the default persistent destination. The artifact tool additionally keeps a private temporary original regardless of persistent save mode; its path is not a durable project asset.
 - Use the tool's `save` and `saveDir` controls to choose a save directory. Custom mode appends a session directory; it does not accept an exact output filename. If an exact asset path is needed, copy the generated image there and leave the original in place.
 - Save-path precedence in Pi tool mode:
   1. If the user names a destination, copy the selected output there and leave the original in place.

package/src/artifacts.ts

@@ -0,0 +1,150 @@
+import { constants } from "node:fs";
+import { lstat, mkdtemp, open, rm, type FileHandle } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { isAbsolute, join, resolve } from "node:path";
+
+export const ARTIFACT_ENTRY = "codex-image-artifact";
+export const RESERVATION_ENTRY = "codex-image-artifact-reservation";
+
+export interface ImageArtifact {
+	path: string;
+	mimeType: string;
+	byteCount: number;
+}
+
+export interface ArtifactRecord {
+	artifact: ImageArtifact;
+	toolCallId: string;
+}
+
+export interface ArtifactReservation {
+	path: string;
+	mimeType: string;
+	toolCallId: string;
+}
+
+export function artifactReservation(value: unknown): ArtifactReservation | undefined {
+	if (!value || typeof value !== "object") return undefined;
+	const record = value as ArtifactReservation;
+	// Reuse the path/MIME/call-ID validation without accepting a completed image.
+	const validated = artifactRecord({
+		artifact: { path: record.path, mimeType: record.mimeType, byteCount: 1 },
+		toolCallId: record.toolCallId,
+	});
+	return validated ? { path: validated.artifact.path, mimeType: validated.artifact.mimeType, toolCallId: validated.toolCallId } : undefined;
+}
+
+// Read metadata, never image bytes, from the current branch. Session files can
+// be edited externally, so do not blindly spread their data into tool results.
+export function artifactRecord(value: unknown): ArtifactRecord | undefined {
+	if (!value || typeof value !== "object") return undefined;
+	const record = value as Partial<ArtifactRecord>;
+	const artifact = record.artifact;
+	if (!artifact || typeof artifact.path !== "string" || artifact.path.length > 4096
+		|| !isAbsolute(artifact.path) || /[\u0000-\u001f\u007f]/.test(artifact.path)
+		|| !["image/png", "image/jpeg", "image/webp"].includes(artifact.mimeType)
+		|| !Number.isInteger(artifact.byteCount) || artifact.byteCount <= 0 || artifact.byteCount > 32 * 1024 * 1024
+		|| typeof record.toolCallId !== "string" || record.toolCallId.length > 256) return undefined;
+	return {
+		artifact: { path: artifact.path, mimeType: artifact.mimeType, byteCount: artifact.byteCount },
+		toolCallId: record.toolCallId,
+	};
+}
+
+/** Only a published, bounded manifest marks a reservation ready. The branch
+ * reservation is written before generation, so late completions need not
+ * mutate whichever branch/session the user is viewing after cancellation. */
+export async function readArtifactManifest(reservation: ArtifactReservation): Promise<ArtifactRecord | undefined> {
+	let file: FileHandle | undefined;
+	try {
+		file = await open(`${reservation.path}.json`, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0) | (constants.O_NONBLOCK ?? 0));
+		const info = await file.stat();
+		const visible = await lstat(`${reservation.path}.json`);
+		if (!info.isFile() || !visible.isFile() || info.ino !== visible.ino || info.dev !== visible.dev || info.size > 8192) return undefined;
+		const buffer = Buffer.alloc(8193);
+		let total = 0;
+		while (total < buffer.length) {
+			const { bytesRead } = await file.read(buffer, total, buffer.length - total, null);
+			if (!bytesRead) break;
+			total += bytesRead;
+		}
+		if (total > 8192) return undefined;
+		const record = artifactRecord(JSON.parse(buffer.subarray(0, total).toString("utf8")));
+		return record?.toolCallId === reservation.toolCallId && record.artifact.mimeType === reservation.mimeType ? record : undefined;
+	} catch {
+		return undefined;
+	} finally {
+		await file?.close().catch(() => undefined);
+	}
+}
+
+export async function branchArtifacts(entries: readonly { type: string; customType?: string; data?: unknown }[]): Promise<ArtifactRecord[]> {
+	const records = new Map<string, ArtifactRecord>();
+	for (const entry of entries) {
+		const reservation = entry.type === "custom" && entry.customType === RESERVATION_ENTRY ? artifactReservation(entry.data) : undefined;
+		const record = reservation ? await readArtifactManifest(reservation)
+			: entry.type === "custom" && entry.customType === ARTIFACT_ENTRY ? artifactRecord(entry.data) : undefined;
+		if (record) {
+			records.delete(record.artifact.path);
+			records.set(record.artifact.path, record);
+		}
+	}
+	return [...records.values()];
+}
+
+/** Reserve private storage before spending quota. Keep completed files until
+ * user/OS cleanup; reload, shutdown, and branch changes must not remove them. */
+export async function reserveArtifact(extension: string, root = tmpdir()) {
+	if (!["png", "jpg", "webp"].includes(extension)) throw new Error("Unsupported artifact format.");
+	const absoluteRoot = resolve(root);
+	if (absoluteRoot.length > 4000 || /[\u0000-\u001f\u007f]/.test(absoluteRoot)) {
+		throw new Error("Image artifact storage path is unsupported. No generation request was made.");
+	}
+	const dir = await mkdtemp(join(absoluteRoot, "pi-codex-image-"));
+	const path = join(dir, `original.${extension}`);
+	let file: FileHandle | undefined;
+	let committed = false;
+	try {
+		file = await open(path, constants.O_CREAT | constants.O_EXCL | constants.O_RDWR | (constants.O_NOFOLLOW ?? 0), 0o600);
+	} catch {
+		await rm(dir, { recursive: true, force: true });
+		throw new Error("Image artifact storage is unavailable. No generation request was made.");
+	}
+	const handle = file;
+	return {
+		path,
+		async commit(bytes: Buffer, mimeType: string): Promise<ImageArtifact> {
+			await handle.writeFile(bytes);
+			await handle.sync();
+			const info = await handle.stat();
+			const visible = await lstat(path);
+			if (!visible.isFile() || info.ino !== visible.ino || info.dev !== visible.dev || visible.size !== bytes.length) {
+				throw new Error("Image artifact is no longer available at its reserved path.");
+			}
+			committed = true;
+			return { path, mimeType, byteCount: bytes.length };
+		},
+		async publish(record: ArtifactRecord) {
+			const validated = artifactRecord(record);
+			if (!validated) throw new Error("Invalid artifact recovery metadata.");
+			const json = JSON.stringify(validated);
+			if (Buffer.byteLength(json) > 8192) throw new Error("Artifact recovery metadata exceeds the size limit.");
+			const manifest = await open(`${path}.json`, constants.O_CREAT | constants.O_EXCL | constants.O_WRONLY | (constants.O_NOFOLLOW ?? 0), 0o600);
+			try {
+				await manifest.writeFile(json);
+				await manifest.sync();
+			} finally {
+				await manifest.close();
+			}
+			if (record.artifact.path !== path) await rm(path, { force: true });
+			committed = true; // Retain fallback manifests too, never incomplete originals.
+		},
+		async dispose() {
+			try {
+				await handle.close();
+			} finally {
+				if (!committed) await rm(dir, { recursive: true, force: true });
+			}
+		},
+	};
+}