ima2-gen 3.24.1 → 3.25.0

package/.env.example

@@ -17,6 +17,10 @@
 # IMA2_OAUTH_PROXY_PORT=10531   # that endpoint's port on 127.0.0.1; also accepted: OAUTH_PORT
 # IMA2_OAUTH_STATUS_TIMEOUT_MS=3000
 # IMA2_OAUTH_RESTART_DELAY_MS=5000
+# IMA2_OAUTH_RATE_RETRY_MAX=5         # retries per job (plan + renders) after a per-minute GPT OAuth rate limit (0 disables)
+# IMA2_OAUTH_RATE_RETRY_BASE_MS=8000   # wait = base x attempt (+-20% jitter) unless the reply says "try again in Ns"
+# IMA2_OAUTH_RATE_RETRY_MAX_MS=45000   # cap for any single wait; a wordless 429 whose Retry-After exceeds it is not retried
+# IMA2_OAUTH_RATE_RETRY_TOTAL_MS=120000  # cap for all waits of one job; no wait runs past the generation timeout
 # IMA2_RESEARCH_SUFFIX="..."    # appended to every image prompt
 
 # ── Paths ──────────────────────────────────────────────────────────────

package/CHANGELOG.md

@@ -7,11 +7,26 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [3.25.0] - 2026-09-30
+
+### Added
+
+- **Masked edits keep everything outside the mask** — after a masked edit the server restores the source wherever the mask is opaque and blends soft mask edges, so the model can no longer redraw the area you kept. Transparent source pixels stay transparent, and a result that comes back at another size is fitted to the source first. On by default; turn it off with `IMA2_PRESERVE_OUTSIDE_MASK=0` or `ima2 config set features.preserveOutsideMask false`. Composites run one at a time and sources above 4096 × 4096 keep the provider result; the sidecar records `maskOutsidePreserved` when the lock ran. (#340, thanks @ree9622)
+- **GPT OAuth waits out per-minute rate limits** — a transient 429 ("rate limit reached … try again in Ns") on the planner or a render now waits and retries the same request with jitter, while usage, quota and billing limits still fail at once. Each job has one budget shared by the plan and every render: `IMA2_OAUTH_RATE_RETRY_MAX` (5 retries), `IMA2_OAUTH_RATE_RETRY_BASE_MS` (8000), `IMA2_OAUTH_RATE_RETRY_MAX_MS` (45000 per wait), `IMA2_OAUTH_RATE_RETRY_TOTAL_MS` (120000 in total), and no wait runs past the job's generation timeout. A job canceled during a rate limit ends as `499 GENERATION_CANCELED`. (#339, thanks @ree9622)
+
+### Changed
+
+- Tests retry temp-directory cleanup on Windows file locks and give media events 30 seconds (#350).
+
+## [3.24.1] - 2026-09-29
+
 ### Changed
 
 - **Releases finish on their own** — a PR merged into dev during a release no longer fails it: the stable publish requires the tag to match and main, dev and preview to contain the release, and the tag job lands the release on dev by fast-forward or merge. `npm run release` pushes the admin-only `desktop-v` tag as soon as the release tag lands, which starts the desktop build.
 - **`npm run release -- resume X.Y.Z`** finishes an already-tagged release (dev landing, desktop tag and build, stable publish, Pages) and skips what already landed. `--yes` now answers every prompt.
 - Release waits only follow the publish run for their own ref and give a dispatch ten minutes to appear.
+- The release dispatches publish.yml on the ref it publishes (`--ref vX.Y.Z`, `--ref preview`), so the package smoke compares the tarball with the release commit even when main has moved on; the smoke reads `PUBLISH_SHA`.
+- **Resume finishes an untagged cut** — when a release stops after main and the npm preview proof but before the tag, `npm run release -- resume X.Y.Z` finds the version commit on main, re-checks the preview proof and mints the tag. The npm registry proof window grows from 15 to 35 minutes (publish verify steps 51, release waits 130), since a preview took longer than 15 minutes to appear.
 - **Site: the desktop app comes right after the hero** — a new "Desktop app" section under the unchanged hero offers a one-click download for the visitor's OS (resolved from the latest desktop release, with a releases-page fallback), explains what the app adds (bundled server, tray, CLI attach/takeover, macOS updates) with a tray menu built from the real labels, and the header gains a Download link. The download blocks share one mounter.
 
 ## [3.24.0] - 2026-09-29

package/README.md

@@ -362,6 +362,7 @@ Config priority is `environment variables > ~/.ima2/config.json > built-in defau
 | `IMA2_GROK_VIDEO_MODEL_DEFAULT` | `grok-imagine-video-1.5` | Default Grok video model |
 | `IMA2_GROK_GENERATION_TIMEOUT_MS` | `300000` | Timeout for the final Grok Images API call |
 | `IMA2_OAUTH_MASKED_EDIT_ENABLED` | `false` | Opt-in feature flag for masked-edit requests on the OAuth path (#31, groundwork only) |
+| `IMA2_PRESERVE_OUTSIDE_MASK` | `true` | Restore source pixels wherever an edit mask is opaque, so masked edits cannot redraw the kept area (`0` keeps the raw provider result) |
 | `GEMINI_API_KEY` | — | API key for `provider: "gemini-api"` direct Generative Language API path |
 | `VERTEX_SERVICE_ACCOUNT_JSON` | — | Google service account JSON for Vertex AI auth with `provider: "gemini-api"`; takes priority over `GEMINI_API_KEY` when both are set |
 | `IMA2_AGY_BIN` | `agy` on PATH | Explicit path to the Antigravity CLI binary for `provider: "agy"` |

package/config.js

@@ -179,6 +179,15 @@ export const config = {
         statusTimeoutMs: pickInt(env.IMA2_OAUTH_STATUS_TIMEOUT_MS, fileCfg.oauth?.statusTimeoutMs, 3000),
         generationTimeoutMs: pickInt(env.IMA2_OAUTH_GENERATION_TIMEOUT_MS, fileCfg.oauth?.generationTimeoutMs, 400 * 1000),
         restartDelayMs: pickInt(env.IMA2_OAUTH_RESTART_DELAY_MS, fileCfg.oauth?.restartDelayMs, 5000),
+        // Backoff for per-minute rate limits (HTTP 429 "... per min", "try again in Ns"); usage caps
+        // and quotas are never retried. See lib/oauthRateLimit.ts.
+        rateLimitRetry: {
+            maxRetries: pickInt(env.IMA2_OAUTH_RATE_RETRY_MAX, fileCfg.oauth?.rateLimitRetry?.maxRetries, 5),
+            baseDelayMs: pickInt(env.IMA2_OAUTH_RATE_RETRY_BASE_MS, fileCfg.oauth?.rateLimitRetry?.baseDelayMs, 8000),
+            maxDelayMs: pickInt(env.IMA2_OAUTH_RATE_RETRY_MAX_MS, fileCfg.oauth?.rateLimitRetry?.maxDelayMs, 45_000),
+            // Retries and this total wait are one budget per job (plan + renders), inside generationTimeoutMs.
+            maxTotalWaitMs: pickInt(env.IMA2_OAUTH_RATE_RETRY_TOTAL_MS, fileCfg.oauth?.rateLimitRetry?.maxTotalWaitMs, 120_000),
+        },
         // Provider-backed masked edit is off until upstream STEP-0 verification is recorded.
         maskedEditEnabled: pickBool(env.IMA2_OAUTH_MASKED_EDIT_ENABLED, fileCfg.oauth?.maskedEditEnabled, false),
         forceImageToolChoice: pickBool(env.IMA2_OAUTH_FORCE_IMAGE_TOOL_CHOICE, fileCfg.oauth?.forceImageToolChoice, true),
@@ -321,6 +330,10 @@ export const config = {
     },
     features: {
         cardNews: pickBool(env.IMA2_CARD_NEWS, fileCfg.features?.cardNews, env.IMA2_DEV === "1"),
+        // Masked edits restore the source wherever the mask is opaque, because GPT Image
+        // treats the mask as guidance and may redraw the kept area. Opt out with
+        // IMA2_PRESERVE_OUTSIDE_MASK=0 to keep the raw provider result.
+        preserveOutsideMask: pickBool(env.IMA2_PRESERVE_OUTSIDE_MASK, fileCfg.features?.preserveOutsideMask, true),
     },
     cardNewsPlanner: {
         enabled: pickBool(env.IMA2_CARD_NEWS_PLANNER, fileCfg.cardNewsPlanner?.enabled, true),

package/docs/API.md

@@ -70,7 +70,7 @@ Image generation supports OAuth, API-key, Grok, and Gemini (`agy` and `gemini-ap
 - API-key generation covers classic generate, edit, mask-guided edit, multimode, and node generation.
 - If `provider: "api"` is requested without an API key, routes fail before upstream with `401` and `API_KEY_REQUIRED`.
 - Grok generation maps `size` to xAI `aspect_ratio` and `resolution`; it does not send an OpenAI-style `size` field upstream. Grok edit uses xAI `/v1/images/edits`; Grok mask edit remains unsupported and returns `GROK_MASK_UNSUPPORTED`.
-- Mask edits are mask/selection guided edits, not pixel-perfect inpaint guarantees.
+- Mask edits are mask/selection guided edits. The model may redraw outside the mask, so the edit route restores source pixels wherever the mask is opaque before saving (`features.preserveOutsideMask`, env `IMA2_PRESERVE_OUTSIDE_MASK`, default on; the sidecar records `maskOutsidePreserved: true`). The output keeps the source dimensions. When the provider returns a different aspect ratio, the result is stretched to the source size before compositing, so the edited area may look stretched or squeezed. Transparent source pixels in the kept area stay transparent. Composites run one at a time and refuse sources above 4096 × 4096 pixels. If compositing fails or the source is above that bound, the provider result is saved unchanged and `maskOutsidePreserved` is omitted.
 
 Grok video generation uses `POST /api/video/generate` (SSE). See the Video
 Generation section below for the full endpoint specification.
@@ -406,7 +406,7 @@ Custom sizes are reduced to the closest xAI-supported aspect ratio and use
 
 Image edit / image-to-image generation.
 
-The request includes a prompt and image payload. `provider: "api"` sends the prompt and image through the shared Responses image adapter. Optional masks are forwarded as mask guidance, not a pixel-perfect edit guarantee.
+The request includes a prompt and image payload. `provider: "api"` sends the prompt and image through the shared Responses image adapter. Optional masks are forwarded as mask guidance; after the provider returns, pixels where the mask is opaque are restored from the source image (see `IMA2_PRESERVE_OUTSIDE_MASK`).
 
 With `provider: "grok"`, edit requests are sent to xAI `/v1/images/edits`
 with the stored OAuth session. Masked Grok edits are rejected before

package/docs/README.ja.md

@@ -361,6 +361,7 @@ Full reference: [CLI.md](CLI.md).
 | `IMA2_GROK_VIDEO_MODEL_DEFAULT` | `grok-imagine-video-1.5` | Default Grok video model |
 | `IMA2_GROK_GENERATION_TIMEOUT_MS` | `300000` | Timeout for the final Grok Images API call |
 | `IMA2_OAUTH_MASKED_EDIT_ENABLED` | `false` | Opt-in feature flag for masked-edit requests on the OAuth path (#31, groundwork only) |
+| `IMA2_PRESERVE_OUTSIDE_MASK` | `true` | Restore source pixels wherever an edit mask is opaque, so masked edits cannot redraw the kept area (`0` keeps the raw provider result) |
 | `GEMINI_API_KEY` | — | API key for `provider: "gemini-api"` direct Generative Language API path |
 | `VERTEX_SERVICE_ACCOUNT_JSON` | — | Google service account JSON for Vertex AI auth with `provider: "gemini-api"`; takes priority over `GEMINI_API_KEY` when both are set |
 | `IMA2_AGY_BIN` | `agy` on PATH | Explicit path to the Antigravity CLI binary for `provider: "agy"` |

package/docs/README.ko.md

@@ -361,6 +361,7 @@ Full reference: [CLI.md](CLI.md).
 | `IMA2_GROK_VIDEO_MODEL_DEFAULT` | `grok-imagine-video-1.5` | Default Grok video model |
 | `IMA2_GROK_GENERATION_TIMEOUT_MS` | `300000` | Timeout for the final Grok Images API call |
 | `IMA2_OAUTH_MASKED_EDIT_ENABLED` | `false` | Opt-in feature flag for masked-edit requests on the OAuth path (#31, groundwork only) |
+| `IMA2_PRESERVE_OUTSIDE_MASK` | `true` | Restore source pixels wherever an edit mask is opaque, so masked edits cannot redraw the kept area (`0` keeps the raw provider result) |
 | `GEMINI_API_KEY` | — | API key for `provider: "gemini-api"` direct Generative Language API path |
 | `VERTEX_SERVICE_ACCOUNT_JSON` | — | Google service account JSON for Vertex AI auth with `provider: "gemini-api"`; takes priority over `GEMINI_API_KEY` when both are set |
 | `IMA2_AGY_BIN` | `agy` on PATH | Explicit path to the Antigravity CLI binary for `provider: "agy"` |

package/docs/README.zh-CN.md

@@ -361,6 +361,7 @@ Full reference: [docs/CLI.md](CLI.md).
 | `IMA2_GROK_VIDEO_MODEL_DEFAULT` | `grok-imagine-video-1.5` | Default Grok video model |
 | `IMA2_GROK_GENERATION_TIMEOUT_MS` | `300000` | Timeout for the final Grok Images API call |
 | `IMA2_OAUTH_MASKED_EDIT_ENABLED` | `false` | Opt-in feature flag for masked-edit requests on the OAuth path (#31, groundwork only) |
+| `IMA2_PRESERVE_OUTSIDE_MASK` | `true` | Restore source pixels wherever an edit mask is opaque, so masked edits cannot redraw the kept area (`0` keeps the raw provider result) |
 | `GEMINI_API_KEY` | — | API key for `provider: "gemini-api"` direct Generative Language API path |
 | `VERTEX_SERVICE_ACCOUNT_JSON` | — | Google service account JSON for Vertex AI auth with `provider: "gemini-api"`; takes priority over `GEMINI_API_KEY` when both are set |
 | `IMA2_AGY_BIN` | `agy` on PATH | Explicit path to the Antigravity CLI binary for `provider: "agy"` |

package/docs/README.zh-TW.md

@@ -361,6 +361,7 @@ Full reference: [docs/CLI.md](CLI.md).
 | `IMA2_GROK_VIDEO_MODEL_DEFAULT` | `grok-imagine-video-1.5` | Default Grok video model |
 | `IMA2_GROK_GENERATION_TIMEOUT_MS` | `300000` | Timeout for the final Grok Images API call |
 | `IMA2_OAUTH_MASKED_EDIT_ENABLED` | `false` | Opt-in feature flag for masked-edit requests on the OAuth path (#31, groundwork only) |
+| `IMA2_PRESERVE_OUTSIDE_MASK` | `true` | Restore source pixels wherever an edit mask is opaque, so masked edits cannot redraw the kept area (`0` keeps the raw provider result) |
 | `GEMINI_API_KEY` | — | API key for `provider: "gemini-api"` direct Generative Language API path |
 | `VERTEX_SERVICE_ACCOUNT_JSON` | — | Google service account JSON for Vertex AI auth with `provider: "gemini-api"`; takes priority over `GEMINI_API_KEY` when both are set |
 | `IMA2_AGY_BIN` | `agy` on PATH | Explicit path to the Antigravity CLI binary for `provider: "agy"` |

package/docs/migration/runtime-test-inventory.md

@@ -4,7 +4,7 @@ Generated by `npm run test:inventory` (script: `scripts/classify-tests.mjs`).
 
 _Tests considered "runtime-importing" if they import from `../lib/`, `../routes/`, `../bin/`, `../server`, or `../config`._
 
-Total: 532 (runtime: 239, contract: 293)
+Total: 536 (runtime: 243, contract: 293)
 
 ## Runtime-importing tests
 - `tests/advertise-payload-contract.test.ts`
@@ -49,6 +49,7 @@ Total: 532 (runtime: 239, contract: 293)
 - `tests/card-news-template.test.ts`
 - `tests/chatgpt-auth-contract.test.ts`
 - `tests/classic-generate-async.test.ts`
+- `tests/cli-config-keys-contract.test.ts`
 - `tests/cli-error-hints.test.ts`
 - `tests/cli-lan-auth.test.ts`
 - `tests/cli-lib.test.ts`
@@ -116,6 +117,7 @@ Total: 532 (runtime: 239, contract: 293)
 - `tests/local-import-contract.test.ts`
 - `tests/local-lan-policy.test.ts`
 - `tests/logging.test.ts`
+- `tests/masked-edit-composite.test.ts`
 - `tests/mcp-character-route.test.ts`
 - `tests/mcp-connection-manager.test.ts`
 - `tests/mcp-connection-routes.test.ts`
@@ -162,6 +164,8 @@ Total: 532 (runtime: 239, contract: 293)
 - `tests/oauth-cli-dependencies.test.ts`
 - `tests/oauth-normalize.test.ts`
 - `tests/oauth-proxy-error-safety.test.ts`
+- `tests/oauth-rate-limit-lane.test.ts`
+- `tests/oauth-rate-limit-retry.test.ts`
 - `tests/open-directory.test.ts`
 - `tests/openai-execution-parity.test.ts`
 - `tests/openai-transport-parity.test.ts`
@@ -314,7 +318,6 @@ Total: 532 (runtime: 239, contract: 293)
 - `tests/cli-capabilities-contract.test.ts`
 - `tests/cli-character-contract.test.ts`
 - `tests/cli-commands.test.ts`
-- `tests/cli-config-keys-contract.test.ts`
 - `tests/cli-default-output-dir-contract.test.ts`
 - `tests/cli-defaults-command-contract.test.ts`
 - `tests/cli-destructive-safety-contract.test.ts`
@@ -515,6 +518,7 @@ Total: 532 (runtime: 239, contract: 293)
 - `tests/style-feature-removal-contract.test.ts`
 - `tests/subprocess-deadline-contract.test.ts`
 - `tests/test-runner-invocation.test.ts`
+- `tests/test-temp-cleanup-contract.test.ts`
 - `tests/toast-stack-contract.test.ts`
 - `tests/tools-cli-contract.test.ts`
 - `tests/transparent-background-ui-contract.test.ts`

package/lib/configKeys.js

@@ -8,6 +8,7 @@ export const WRITABLE_CONFIG_KEYS = new Set([
     "apiProvider.defaultReasoningEffort",
     "log.level",
     "features.cardNews",
+    "features.preserveOutsideMask",
     "cardNewsPlanner.enabled",
     "cardNewsPlanner.model",
     "cardNewsPlanner.timeoutMs",
@@ -48,6 +49,7 @@ export const KEY_TO_ENV = {
     "apiProvider.defaultReasoningEffort": "IMA2_API_REASONING_EFFORT",
     "log.level": "IMA2_LOG_LEVEL",
     "features.cardNews": "IMA2_CARD_NEWS",
+    "features.preserveOutsideMask": "IMA2_PRESERVE_OUTSIDE_MASK",
     "server.port": "IMA2_PORT",
     "server.host": "IMA2_HOST",
     "server.publicOrigins": "IMA2_PUBLIC_ORIGINS",

package/lib/grokUpstreamRetry.js

@@ -45,7 +45,8 @@ export function isConnectionResetError(err) {
         || msg.includes("connection reset by peer")
         || msg.includes("socket hang up");
 }
-function retryAfterDelayMs(headers) {
+/** Retry-After (seconds or HTTP date) in ms; also used by lib/oauthRateLimit.ts. */
+export function retryAfterDelayMs(headers) {
     const raw = headers.get("retry-after")?.trim();
     if (!raw)
         return undefined;
@@ -62,7 +63,11 @@ export function retryBackoffDelayMs(attempt, opts) {
     if (retryAfter !== undefined)
         return Math.min(retryAfter, opts.maxDelayMs);
     const exp = Math.min(opts.baseDelayMs * (2 ** attempt), opts.maxDelayMs);
-    return Math.floor(exp * (0.8 + Math.random() * 0.4));
+    return jitterDelayMs(exp);
+}
+/** Spread a wait by ±20% so callers blocked in the same instant do not retry in lockstep. */
+export function jitterDelayMs(ms, random = Math.random) {
+    return Math.floor(ms * (0.8 + random() * 0.4));
 }
 function abortError(signal) {
     return signal?.reason ?? new DOMException("The operation was aborted", "AbortError");

package/lib/maskedEditComposite.js

@@ -0,0 +1,84 @@
+/**
+ * Deterministic pixel lock for masked edits.
+ *
+ * GPT Image models receive the edit mask as guidance, not as a pixel lock, so
+ * they often redraw the area the user meant to keep. After the provider
+ * returns, restore the source wherever the submitted mask is opaque (the
+ * OpenAI mask contract: alpha 0 = editable, alpha 255 = keep). Partial alpha
+ * blends source and result proportionally, so a soft mask edge stays soft.
+ *
+ * The blend covers all four RGBA channels, so a transparent source pixel in
+ * the kept area stays transparent instead of letting the result show through.
+ *
+ * The output keeps the source dimensions. When the backend returns a
+ * different size, the result is resized to the source first so the kept area
+ * stays byte-identical to the source instead of being resampled.
+ *
+ * Memory is bounded twice: every decode refuses inputs above
+ * MASKED_EDIT_MAX_PIXELS, and composites run one at a time, so at most one set
+ * of full-size raw buffers exists however many edits run in parallel. A
+ * refused input throws; the edit route then keeps the provider bytes.
+ */
+import sharp from "sharp";
+/** 4096 x 4096: one composite then holds about 4 raw buffers of 64 MiB. */
+export const MASKED_EDIT_MAX_PIXELS = 4096 * 4096;
+function decode(input) {
+    return sharp(input, { limitInputPixels: MASKED_EDIT_MAX_PIXELS });
+}
+function encode(pipeline, format, quality) {
+    const q = Math.max(1, Math.min(100, Math.round(quality) || 100));
+    if (format === "jpeg")
+        return pipeline.jpeg({ quality: q });
+    if (format === "webp")
+        return pipeline.webp({ quality: q });
+    return pipeline.png();
+}
+function rgbaAt(input, width, height) {
+    return decode(input).resize(width, height, { fit: "fill" }).ensureAlpha().raw().toBuffer();
+}
+function maskAlphaAt(mask, width, height) {
+    return decode(mask).resize(width, height, { fit: "fill" }).ensureAlpha().extractChannel("alpha").raw().toBuffer();
+}
+/**
+ * result = source * keep + result * (1 - keep) per channel, keep = mask alpha / 255.
+ * Returns whether any output pixel is not fully opaque.
+ */
+function blendInto(result, source, keep) {
+    let translucent = false;
+    for (let pixel = 0, base = 0; pixel < keep.length; pixel += 1, base += 4) {
+        const k = keep[pixel];
+        if (k === 255)
+            source.copy(result, base, base, base + 4);
+        else if (k !== 0) {
+            for (let c = 0; c < 4; c += 1) {
+                result[base + c] = Math.round((source[base + c] * k + result[base + c] * (255 - k)) / 255);
+            }
+        }
+        if (result[base + 3] < 255)
+            translucent = true;
+    }
+    return translucent;
+}
+async function composite(input) {
+    const { width, height } = await decode(input.source).metadata();
+    if (!width || !height)
+        throw new Error("masked edit source dimensions are unavailable");
+    if (width * height > MASKED_EDIT_MAX_PIXELS)
+        throw new Error("masked edit source exceeds the composite pixel limit");
+    const source = await rgbaAt(input.source, width, height);
+    const result = await rgbaAt(input.result, width, height);
+    const keep = await maskAlphaAt(input.mask, width, height);
+    const translucent = blendInto(result, source, keep);
+    // An all-opaque output is saved without an alpha channel, so alphaVerified
+    // keeps meaning "some pixel is actually transparent".
+    const pipeline = sharp(result, { raw: { width, height, channels: 4 } });
+    const output = translucent ? pipeline : pipeline.removeAlpha();
+    return encode(output, input.format ?? "png", input.quality ?? 100).toBuffer();
+}
+let queueTail = Promise.resolve();
+/** Composites run one at a time; see the memory note above. */
+export function preserveOutsideMask(input) {
+    const run = queueTail.then(() => composite(input));
+    queueTail = run.catch(() => undefined);
+    return run;
+}

package/lib/oauthImages.js

@@ -13,6 +13,7 @@
  */
 import { logEvent } from "./logger.js";
 import { postOAuthImages, postResponses } from "./responsesTransport.js";
+import { createOAuthRateLimitBudget, oauthRateLimitRetryConfig, withOAuthRateLimitRetry, } from "./oauthRateLimit.js";
 export const OAUTH_IMAGE_TOOL = "image_gen";
 export const OAUTH_RENDER_MODEL = "gpt-image-2";
 /** The ChatGPT images edit endpoint accepts at most five input images. */
@@ -128,7 +129,27 @@ export function renderFields(job) {
 function extensionFor(mime) {
     return mime === "image/jpeg" ? "jpg" : mime === "image/webp" ? "webp" : "png";
 }
-async function renderOne(job, prompt) {
+/**
+ * One retry budget per job: the plan and every render draw from the same retry count and total
+ * wait, and no wait may run past the job's generation timeout.
+ */
+function rateLimitBudgetFor(job) {
+    return createOAuthRateLimitBudget(job.ctx?.config?.oauth?.generationTimeoutMs ?? 400 * 1000);
+}
+/** Replay a call the backend rejected with a per-minute rate limit; log every wait. */
+function withRateLimitBackoff(job, budget, stage, request) {
+    return withOAuthRateLimitRetry(request, {
+        config: oauthRateLimitRetryConfig(job.ctx?.config?.oauth?.rateLimitRetry),
+        budget,
+        signal: job.signal,
+        onRetry: (info) => logEvent(job.scope, "rate_limit_retry", { requestId: job.requestId, stage, ...info }),
+        onExhausted: (info) => logEvent(job.scope, "rate_limit_exhausted", { requestId: job.requestId, stage, ...info }),
+    });
+}
+async function renderOne(job, budget, prompt) {
+    return withRateLimitBackoff(job, budget, "render", () => renderOnce(job, prompt));
+}
+async function renderOnce(job, prompt) {
     const fields = renderFields(job);
     if (!job.images.length) {
         return postOAuthImages({
@@ -174,18 +195,18 @@ function emptyDiagnostics() {
         outputTextChars: 0,
     };
 }
-async function plan(job) {
-    let result = await postResponses({
+async function plan(job, budget) {
+    let result = await withRateLimitBackoff(job, budget, "plan", () => postResponses({
         ctx: job.ctx, provider: "oauth", scope: `${job.scope}-plan`, requestId: job.requestId,
         signal: job.signal, maxImages: 0, payload: buildPlannerPayload(job),
-    });
+    }));
     let prompts = promptsFromCalls(result.functionCalls, job.maxImages);
     if (!prompts.length) {
         logEvent(job.scope, "plan_retry", { requestId: job.requestId, events: result.eventCount });
-        result = await postResponses({
+        result = await withRateLimitBackoff(job, budget, "plan", () => postResponses({
             ctx: job.ctx, provider: "oauth", scope: `${job.scope}-plan`, requestId: job.requestId,
             signal: job.signal, maxImages: 0, payload: buildPlannerPayload(job, true),
-        });
+        }));
         prompts = promptsFromCalls(result.functionCalls, job.maxImages);
     }
     return { result, prompts };
@@ -195,9 +216,10 @@ export async function runOAuthImageJob(job) {
     // prompt per stage, so it goes through the planner (its user text already carries the
     // sequence instructions and the Direct fidelity rule).
     const direct = job.mode === "direct" && job.maxImages <= 1;
+    const budget = rateLimitBudgetFor(job);
     const planned = direct
         ? { result: null, prompts: Array.from({ length: Math.max(1, job.maxImages) }, () => job.directPrompt) }
-        : await plan(job);
+        : await plan(job, budget);
     const base = planned.result;
     const usage = {};
     addUsage(usage, base?.usage);
@@ -215,7 +237,7 @@ export async function runOAuthImageJob(job) {
         while (cursor < planned.prompts.length) {
             const index = cursor++;
             try {
-                slots[index]?.resolve({ status: "done", value: await renderOne(job, planned.prompts[index]) });
+                slots[index]?.resolve({ status: "done", value: await renderOne(job, budget, planned.prompts[index]) });
             }
             catch (error) {
                 slots[index]?.resolve({ status: "failed", error });

package/lib/oauthRateLimit.js

@@ -0,0 +1,154 @@
+/**
+ * Backoff for GPT OAuth per-minute rate limits.
+ *
+ * The ChatGPT backend rejects a burst with HTTP 429 and a message such as
+ * "Rate limit reached for gpt-image-2-codex ... on input-images per min: Limit 4000,
+ * Used 4000. Please try again in 7.5s". That bucket refills within the minute, so waiting
+ * and sending the same request again succeeds. A usage cap (the 5-hour or weekly plan
+ * limit, `usage_limit_reached`, an exhausted quota or billing limit) does not refill in
+ * seconds and must fail fast, so it is excluded before any per-minute wording is matched.
+ *
+ * A 429 is a rejection before any work starts, so replaying the request cannot bill the
+ * user twice (unlike the pre-response retries in lib/grokUpstreamRetry.ts).
+ *
+ * One job (a plan plus its renders) spends one retry budget: a retry count, a total wait and
+ * the job's generation deadline, so a burst never stretches a job past its timeout.
+ *
+ * MUST stay a leaf module: it only borrows the abortable sleep, jitter and Retry-After parsing.
+ */
+import { jitterDelayMs, retryAfterDelayMs, sleepWithAbort } from "./grokUpstreamRetry.js";
+/**
+ * Caps that no short wait can clear. Checked first so mixed wording never retries. A bare
+ * "billing" or "credit" is not matched: per-minute messages can link to the billing page or
+ * mention credits, so only an exhausted credit balance counts.
+ */
+const PERMANENT_LIMIT_RE = /usage[ _]?limit|usage cap|quota|billing[ _](?:hard[ _])?limit|hard limit|spending|insufficient[_ ]credits?|credits? (?:exhausted|depleted|balance)|out of credits|plan limit|monthly|weekly|daily|per day|\b5[- ]?hours?\b/i;
+const TRANSIENT_LIMIT_RE = /rate[ _]?limit(?:ed| reached|_exceeded)|(?:requests|tokens|images|input-images) per min|per minute|try again in/i;
+const PER_WINDOW_RE = /per min|per minute|try again in/i;
+export const DEFAULT_OAUTH_RATE_LIMIT_RETRY = Object.freeze({
+    maxRetries: 5,
+    baseDelayMs: 8_000,
+    maxDelayMs: 45_000,
+    maxTotalWaitMs: 120_000,
+});
+/** `null` means "not a rate limit this module recognizes"; only "transient" is retried. */
+export function classifyOAuthRateLimit({ status, text, retryAfterMs, maxDelayMs }) {
+    if (status === 401 || status === 403)
+        return null;
+    const s = String(text ?? "");
+    if (PERMANENT_LIMIT_RE.test(s))
+        return status === 429 || TRANSIENT_LIMIT_RE.test(s) ? "permanent" : null;
+    if (TRANSIENT_LIMIT_RE.test(s) && (status === 429 || PER_WINDOW_RE.test(s)))
+        return "transient";
+    // A wordless 429 with only Retry-After is a per-window bucket only when the wait fits one
+    // retry; a longer wait points at a cap the text did not name, so it surfaces unclassified.
+    if (status === 429 && retryAfterMs !== undefined) {
+        return retryAfterMs <= (maxDelayMs ?? DEFAULT_OAUTH_RATE_LIMIT_RETRY.maxDelayMs) ? "transient" : null;
+    }
+    return null;
+}
+/** "Please try again in 7.5s" / "in 820ms" / "in 2 seconds" → milliseconds. */
+export function parseRetryHintMs(text) {
+    const match = String(text ?? "").match(/try again in\s*([\d.]+)\s*(ms|milliseconds?|s|secs?|seconds?)\b/i);
+    if (!match)
+        return undefined;
+    const value = Number.parseFloat(match[1]);
+    if (!Number.isFinite(value) || value < 0)
+        return undefined;
+    return /^m/i.test(match[2]) ? value : value * 1000;
+}
+/** Fields the transport attaches to a rejected OAuth request. */
+export function oauthRateLimitFields(status, text, headers, maxDelayMs) {
+    const headerMs = headers ? retryAfterDelayMs(headers) : undefined;
+    const kind = classifyOAuthRateLimit({ status, text, retryAfterMs: headerMs, maxDelayMs });
+    if (!kind)
+        return {};
+    const retryAfterMs = parseRetryHintMs(text) ?? headerMs;
+    return { rateLimit: kind, ...(kind === "transient" && retryAfterMs !== undefined ? { retryAfterMs } : {}) };
+}
+function nonNegativeInt(value, fallback) {
+    const n = Number(value);
+    return Number.isFinite(n) && n >= 0 ? Math.floor(n) : fallback;
+}
+export function oauthRateLimitRetryConfig(raw) {
+    const d = DEFAULT_OAUTH_RATE_LIMIT_RETRY;
+    const maxRetries = Math.min(nonNegativeInt(raw?.maxRetries, d.maxRetries), 20);
+    const baseDelayMs = nonNegativeInt(raw?.baseDelayMs, d.baseDelayMs);
+    const maxDelayMs = Math.max(baseDelayMs, nonNegativeInt(raw?.maxDelayMs, d.maxDelayMs));
+    const maxTotalWaitMs = nonNegativeInt(raw?.maxTotalWaitMs, d.maxTotalWaitMs);
+    return { maxRetries, baseDelayMs, maxDelayMs, maxTotalWaitMs };
+}
+/**
+ * The upstream hint wins when it is a real wait (≥ 1s); sub-second hints are unrealistic for a
+ * per-minute bucket, so the linear backoff (base × attempt) applies. The backoff is spread ±20%
+ * like lib/grokUpstreamRetry.ts; a hint only moves later (0 to +20%) so no retry lands before
+ * the bucket refills. Both are capped at `maxDelayMs`.
+ */
+export function oauthRateLimitDelayMs(attempt, hintMs, config, random = Math.random) {
+    if (hintMs !== undefined && hintMs >= 1000)
+        return Math.min(Math.ceil(hintMs * (1 + random() * 0.2)), config.maxDelayMs);
+    return Math.min(jitterDelayMs(config.baseDelayMs * Math.max(1, attempt), random), config.maxDelayMs);
+}
+export function isTransientOAuthRateLimit(error) {
+    return Boolean(error && typeof error === "object" && error.rateLimit === "transient");
+}
+function retryAfterOf(error) {
+    const value = error?.retryAfterMs;
+    return typeof value === "number" && Number.isFinite(value) ? value : undefined;
+}
+function canceledError(cause) {
+    return Object.assign(new Error("Generation canceled"), { status: 499, code: "GENERATION_CANCELED", cause });
+}
+export function createOAuthRateLimitBudget(timeoutMs, now = Date.now) {
+    const bounded = typeof timeoutMs === "number" && Number.isFinite(timeoutMs) && timeoutMs > 0;
+    return { retries: 0, totalWaitMs: 0, deadlineAt: bounded ? now() + timeoutMs : undefined };
+}
+/** Why the budget cannot pay for `waitMs`, or null when it can. */
+function budgetShortfall(budget, config, waitMs, now) {
+    if (budget.retries >= config.maxRetries)
+        return "retries";
+    if (budget.totalWaitMs + waitMs > config.maxTotalWaitMs)
+        return "total_wait";
+    if (budget.deadlineAt !== undefined && now + waitMs >= budget.deadlineAt)
+        return "deadline";
+    return null;
+}
+/** Run `request`, replaying it after a transient rate limit. Any other error surfaces as is. */
+export async function withOAuthRateLimitRetry(request, options = {}) {
+    const config = options.config ?? DEFAULT_OAUTH_RATE_LIMIT_RETRY;
+    const budget = options.budget ?? createOAuthRateLimitBudget();
+    const sleep = options.sleep ?? sleepWithAbort;
+    const now = options.now ?? Date.now;
+    const signal = options.signal ?? undefined;
+    for (let attempt = 1;; attempt++) {
+        try {
+            return await request();
+        }
+        catch (error) {
+            if (!isTransientOAuthRateLimit(error))
+                throw error;
+            // A job canceled while its request was being rate limited ends as a cancel, not a 429.
+            if (signal?.aborted)
+                throw canceledError(signal.reason ?? error);
+            const waitMs = oauthRateLimitDelayMs(attempt, retryAfterOf(error), config, options.random);
+            const reason = budgetShortfall(budget, config, waitMs, now());
+            if (reason) {
+                options.onExhausted?.({ retries: budget.retries, totalWaitMs: budget.totalWaitMs, reason });
+                throw error;
+            }
+            budget.retries++;
+            budget.totalWaitMs += waitMs;
+            options.onRetry?.({ attempt: budget.retries, maxRetries: config.maxRetries, waitMs, totalWaitMs: budget.totalWaitMs });
+            try {
+                await sleep(waitMs, signal);
+            }
+            catch (sleepError) {
+                if (signal?.aborted)
+                    throw canceledError(sleepError);
+                throw sleepError;
+            }
+            if (signal?.aborted)
+                throw canceledError(signal.reason);
+        }
+    }
+}

package/lib/responsesTransport.js

@@ -5,6 +5,7 @@ import { setJobPhase } from "./inflight.js";
 import { parseJson, parseStream, safeDiagnosticLabel, } from "./responsesParse.js";
 import { waitForOAuthReady } from "./oauthProxy.js";
 import { oauthFetch } from "./codexBackend/index.js";
+import { oauthRateLimitFields, oauthRateLimitRetryConfig } from "./oauthRateLimit.js";
 const RESPONSES_ERROR_MARKER = "ima2ResponsesError";
 function makeError(message, { status = 500, code = "RESPONSES_IMAGE_ERROR", cause, ...rest } = {}) {
     const err = new Error(message);
@@ -63,6 +64,15 @@ function safeUpstreamClientMessage(upstream, status) {
         return "OpenAI rate limited the image request.";
     return "OpenAI rejected the image request.";
 }
+/**
+ * Rate-limit kind and wait hint for a rejected GPT OAuth call, read from the raw upstream text
+ * before the client message is redacted. Only the kind and a number leave this function.
+ */
+function rateLimitFieldsOf(ctx, res, upstream, text) {
+    const raw = upstream ? [upstream.message, upstream.code, upstream.type].filter(Boolean).join(" ") : text.slice(0, 2000);
+    const { maxDelayMs } = oauthRateLimitRetryConfig(ctx?.config?.oauth?.rateLimitRetry);
+    return oauthRateLimitFields(res.status, raw, res.headers, maxDelayMs);
+}
 function apiAuthorizationHeader(apiKey) {
     const key = typeof apiKey === "string" ? apiKey.trim() : "";
     if (!key) {
@@ -138,6 +148,7 @@ export async function postResponses({ ctx, provider, scope, payload, requestId,
         if (!res.ok) {
             const text = await res.text();
             const upstream = parseOpenAIErrorBody(text);
+            const rateLimit = provider === "api" ? {} : rateLimitFieldsOf(ctx, res, upstream, text);
             if (res.status >= 400 && res.status < 500 && upstream?.message) {
                 throw makeError(safeUpstreamClientMessage(upstream, res.status), {
                     status: res.status,
@@ -147,11 +158,13 @@ export async function postResponses({ ctx, provider, scope, payload, requestId,
                     upstreamType: upstream.type,
                     upstreamParam: upstream.param,
                     upstreamMessageRedacted: true,
+                    ...rateLimit,
                 });
             }
             throw makeError(`${provider === "api" ? "OpenAI API" : "OAuth proxy"} returned ${res.status}`, {
                 status: res.status,
                 upstreamBodyChars: text.length,
+                ...rateLimit,
             });
         }
         if (requestId)
@@ -207,6 +220,7 @@ export async function postOAuthImages({ ctx, scope, kind, json, form, requestId,
         const text = await res.text();
         if (!res.ok) {
             const upstream = parseOpenAIErrorBody(text);
+            const rateLimit = rateLimitFieldsOf(ctx, res, upstream, text);
             if (res.status >= 400 && res.status < 500 && upstream?.message) {
                 throw makeError(safeUpstreamClientMessage(upstream, res.status), {
                     status: res.status,
@@ -216,9 +230,10 @@ export async function postOAuthImages({ ctx, scope, kind, json, form, requestId,
                     upstreamType: upstream.type,
                     upstreamParam: upstream.param,
                     upstreamMessageRedacted: true,
+                    ...rateLimit,
                 });
             }
-            throw makeError(`GPT OAuth returned ${res.status}`, { status: res.status, upstreamBodyChars: text.length });
+            throw makeError(`GPT OAuth returned ${res.status}`, { status: res.status, upstreamBodyChars: text.length, ...rateLimit });
         }
         let parsed;
         try {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ima2-gen",
-  "version": "3.24.1",
+  "version": "3.25.0",
   "packageManager": "npm@11.18.0",
   "description": "Local-first visual generation runtime and studio for people and coding agents, with reproducible image and video workflows across multiple providers.",
   "type": "module",
@@ -131,5 +131,5 @@
     "typescript-eslint": "8.70.0",
     "yaml": "2.9.1"
   },
-  "gitHead": "d71f73cbb68fff662a1802154a5c9e6fb0b9c82f"
+  "gitHead": "057de2c0639cd451c65bff6f484ae397e86d7447"
 }

package/routes/edit.js

@@ -12,7 +12,7 @@ import { checkImageExecutionAdmission } from "../lib/providers/execution/admissi
 import { resolveGrokQualityModel } from "../lib/imageModels.js";
 import { startJob, finishJob, registerJobAbortController, isJobCanceled, isStartJobFailure, INFLIGHT_RETRY_AFTER_SECONDS } from "../lib/inflight.js";
 import { isGenerationCanceledError, makeGenerationCanceledError, throwIfJobCanceled, } from "../lib/generationCancel.js";
-import { logEvent, logError } from "../lib/logger.js";
+import { logEvent, logError, logWarn } from "../lib/logger.js";
 import { hasPngAlphaChannel, parsePngInfo } from "../lib/pngInfo.js";
 import { verifyBufferAlpha } from "../lib/imageBackgroundParam.js";
 import { decodeRawForAlpha } from "../lib/alphaDecode.js";
@@ -22,6 +22,7 @@ import { requireRuntimeContext } from "../lib/runtimeContext.js";
 import { errorEnvelopeFields } from "../lib/errors/envelope.js";
 import { upstreamLabelFields } from "../lib/diagnosticLabel.js";
 import { getProviderSurfaceSupport } from "../lib/providers/derive.js";
+import { preserveOutsideMask } from "../lib/maskedEditComposite.js";
 function validateModeration(ctx, moderation) {
     if (typeof moderation !== "string" || !ctx.config.oauth.validModeration.has(moderation)) {
         return { error: "moderation must be one of: auto, low" };
@@ -72,12 +73,12 @@ function validateEditMask(imageB64, mask) {
         return { error: "mask PNG must include an alpha channel", code: "EDIT_MASK_NO_ALPHA" };
     }
     const imageCheck = decodePngDataUrl(imageB64, "INVALID_EDIT_IMAGE_BASE64", "INVALID_EDIT_IMAGE_PNG");
-    if (imageCheck.error || !imageCheck.info)
+    if (imageCheck.error || !imageCheck.buffer || !imageCheck.info)
         return imageCheck;
     if (imageCheck.info.width !== maskCheck.info.width || imageCheck.info.height !== maskCheck.info.height) {
         return { error: "mask dimensions must match image dimensions", code: "EDIT_MASK_DIMENSION_MISMATCH" };
     }
-    return { mask: maskCheck.b64, maskBytes: maskCheck.buffer.length };
+    return { mask: maskCheck.b64, maskBytes: maskCheck.buffer.length, maskBuffer: maskCheck.buffer, sourceBuffer: imageCheck.buffer };
 }
 export function registerEditRoutes(app, ctxRaw) {
     const ctx = requireRuntimeContext(ctxRaw);
@@ -240,7 +241,29 @@ export function registerEditRoutes(app, ctxRaw) {
                 ? (resultMimeFromProvider || detectImageMimeFromB64(resultB64) || "image/png")
                 : "image/png";
             const editExt = activeProvider === "grok" || activeProvider === "agy" || activeProvider === "grok-api" || activeProvider === "gemini-api" || activeProvider === "atlascloud" || activeProvider === "minimax" || activeProvider === "nai" ? imageFormatFromMime(editMime) : "png";
-            const editBuffer = Buffer.from(resultB64, "base64");
+            const providerBuffer = Buffer.from(resultB64, "base64");
+            // Masks are guidance for GPT Image models; restore the source wherever the
+            // mask is opaque so a masked edit cannot redraw the area the user kept.
+            const { maskBuffer, sourceBuffer } = maskCheck;
+            const kept = ctx.config.features?.preserveOutsideMask !== false && maskBuffer && sourceBuffer
+                ? { mask: maskBuffer, source: sourceBuffer }
+                : null;
+            // The provider call is already paid for, so a failed composite falls back
+            // to the provider bytes instead of discarding the result with a 500.
+            let editBuffer = providerBuffer;
+            let maskOutsidePreserved = false;
+            if (kept) {
+                try {
+                    editBuffer = await preserveOutsideMask({ ...kept, result: providerBuffer, format: editExt });
+                    maskOutsidePreserved = true;
+                }
+                catch (compositeErr) {
+                    const message = compositeErr instanceof Error ? compositeErr.message : String(compositeErr);
+                    logWarn("edit", "mask_preserve_failed", { requestId, errorMessage: message.slice(0, 200) });
+                }
+            }
+            const editB64 = maskOutsidePreserved ? editBuffer.toString("base64") : resultB64;
+            throwIfJobCanceled(requestId);
             const createdAt = Date.now();
             // Semantic alpha verification: at least one pixel with alpha < 255.
             // Never trust provider mime for transparency claims (same doctrine as
@@ -289,19 +312,20 @@ export function registerEditRoutes(app, ctxRaw) {
                 webSearchCalls,
                 webSearchEnabled,
                 ...(providerUrl ? { providerUrl } : {}),
+                ...(maskOutsidePreserved ? { maskOutsidePreserved: true } : {}),
             };
             await safeWriteSidecar(join(ctx.config.storage.generatedDir, filename + ".json"), meta);
             invalidateHistoryIndex();
             finishHttpStatus = 200;
-            finishMeta = { filename, imageChars: resultB64.length };
+            finishMeta = { filename, imageChars: editB64.length };
             logEvent("edit", "saved", {
                 requestId,
                 filename,
-                imageChars: resultB64.length,
+                imageChars: editB64.length,
                 elapsedMs: Date.now() - startTime,
             });
             res.json({
-                image: `data:${editMime};base64,${resultB64}`,
+                image: `data:${editMime};base64,${editB64}`,
                 elapsed,
                 reasoningEffort,
                 filename,