clauderipple 0.12.6 → 0.12.7

package/CHANGELOG.md

@@ -1,5 +1,20 @@
 # Changelog
 
+## 0.12.7 — 2026-10-22
+
+### Fixed
+
+- **A GPT main session knows it can make images.** How to call `/api/image` was written only into
+  generated worker files, so a session running GPT as its own model said it had no image tool and
+  drew an SVG. The same lines now end its instructions; subagent turns are unchanged.
+- **A relay's 402 for a downed model no longer parks the whole account.** OpenCode Go answered 402
+  while one model's endpoint was down, which read as billing exhaustion and rested the account for
+  30 minutes, DeepSeek included. A refusal whose body says the upstream failed is now transient.
+- **A failed hotspot join is tried again within seconds** (10 s, 20 s, 30 s … up to a minute)
+  instead of waiting out the once-a-minute switch rule.
+- **`ripple:auto` asks for a bare task description,** so the Claude app's running-agent row no
+  longer shows another worker's model name copied into the title.
+
 ## 0.12.6 — 2026-10-22
 
 ### Fixed

package/dist/app/package.json

@@ -1,5 +1,5 @@
 {
   "private": true,
-  "version": "0.12.6",
+  "version": "0.12.7",
   "type": "commonjs"
 }

package/dist/mod/hooks/workers.ts

@@ -7,7 +7,11 @@ import { kindOf, parseEffortVerdict, verdictObject } from './judge'
 import { claudeChoices, rungAbove, rungOf, tickedChoices } from './ladder'
 
 /** The one agent the main chat delegates to; the judge picks the worker (docs/specs/2026-10-12-worker-tiers.md). */
+// The description line: a chat that had seen other workers' "Sol·high · " titles wrote one here
+// too, and the app's running-agent row showed "Sol·high" while Sonnet ran (2026-10-22). The row
+// shows the call as written; only the task list gets the mod's corrected title.
 export const AUTO_DESCRIPTION = 'Delegate any task here; ClaudeRipple picks the model. If a worker fails or returns nothing usable, delegate again here once and say the earlier attempt failed. ' +
+  'Write the Agent description as the task alone, with no model or effort in front: ClaudeRipple puts the model it picks there. ' +
   'If you know how hard the task is, put [[ripple: light]], [[ripple: standard]], [[ripple: hard]] or [[ripple: max]] on the prompt\'s first line: ' +
   'light = lookups, mechanical edits, one small fix; standard = carry out a designed change (even across several files), research, summarize, read-only review; ' +
   'hard = subtle debugging, security review, or work where a wrong call is costly; max = planning, design or architecture where the deliverable is the decision itself. ' +

package/dist/router/src/agents.js

@@ -45,9 +45,10 @@ const BODY = [
 /**
  * Added to the body when a ChatGPT provider is configured: how a worker makes an image. A worker has
  * no image tool, and `clauderipple` is not on PATH for everyone (a checkout runs from source), so
- * the instruction is the admin endpoint itself, which curl reaches on every platform.
+ * the instruction is the admin endpoint itself, which curl reaches on every platform. A GPT main
+ * session gets the same lines in its instructions (proxy.ts).
  */
-function imageLine(port) {
+export function imageLine(port) {
     return [
         "이미지가 필요하면 ChatGPT 구독으로 만든다(한 장 30초~수 분):",
         `\`curl -sS --fail-with-body -o <절대경로>.png -H 'content-type: application/json' -d '{"prompt":"…"}' http://127.0.0.1:${port}/api/image\``,

package/dist/router/src/health.js

@@ -12,6 +12,7 @@
 // A check that cannot run (no curl) exits as before: the documented fix stays the default.
 import path from "node:path";
 import { PROBE_URLS } from "./tether.js";
+import { RELAY_UPSTREAM_FAILED } from "./pool.js";
 /** Only definite billing/quota exhaustion, never a bare rate limit or RESOURCE_EXHAUSTED.
  * 402 is already `exhausted` in pool.ts; Codex's usage_limit_reached is named in
  * providers/chatgpt/translate.ts. Other vendors share the explicit billing vocabulary.
@@ -20,6 +21,9 @@ import { PROBE_URLS } from "./tether.js";
 export function providerExhaustion(status, body = "", retryMs, now = Date.now()) {
     if (status !== 402 && status !== 429)
         return undefined;
+    // A relay's 402 for its upstream being down is not about money (pool.ts, RELAY_UPSTREAM_FAILED).
+    if (RELAY_UPSTREAM_FAILED.test(body))
+        return undefined;
     const balance = /\b(?:insufficient[_ -]+(?:balance|credits?|funds)|(?:balance|credits?)[_ -]+(?:insufficient|exhausted|depleted))\b/i.test(body);
     const billing = /\bbilling[_ -]+(?:hard[_ -]+)?(?:limit|exhausted|quota)|\b(?:exhausted|exceeded|insufficient)[_ -]+billing\b/i.test(body);
     const quota = /\b(?:insufficient_quota|usage_limit_reached|quota[_ -]+exhausted|exhausted[_ -]+quota)\b/i.test(body);

package/dist/router/src/pool.js

@@ -26,6 +26,8 @@
 const DEFAULT_RATE_LIMIT_MS = 60_000;
 const TRANSIENT_MS = 10_000;
 const EXHAUSTED_MS = 30 * 60_000;
+/** A relay passing on its upstream's failure; whatever status it chose, the credential did nothing. */
+export const RELAY_UPSTREAM_FAILED = /upstream (request )?failed/i;
 /** A `Retry-After` beyond this is treated as "not within this session"; the credential is parked. */
 const MAX_COOLDOWN_MS = 6 * 60 * 60_000;
 /**
@@ -48,13 +50,19 @@ export function classify(status, retryAfterMs, body = "") {
         // held for no time at all rather than for a shorter time — any cooldown at all would move the
         // conversation to another credential and take the prompt cache with it (§4). `bounded` is
         // bypassed deliberately: its one-second floor is exactly the cache cost this avoids.
-        if (/upstream (request )?failed/i.test(body)) {
+        if (RELAY_UPSTREAM_FAILED.test(body)) {
             return { retryable: true, kind: "transient", cooldownMs: 0, quarantine: false };
         }
         return { retryable: true, kind: "auth", cooldownMs: bounded(retryAfterMs ?? DEFAULT_RATE_LIMIT_MS), quarantine: false };
     }
     if (status === 429)
         return { retryable: true, kind: "rate-limit", cooldownMs: bounded(retryAfterMs ?? DEFAULT_RATE_LIMIT_MS), quarantine: false };
+    // The same relay answers 402 for a model whose own endpoint is down ("server_error … Upstream
+    // request failed: Endpoint is unavailable", OpenCode Go for minimax-m3.1-flash-free, 2026-10-22).
+    // That is no statement about money: read as exhaustion it parked the whole account for half an
+    // hour and its other models with it.
+    if (status === 402 && RELAY_UPSTREAM_FAILED.test(body))
+        return { retryable: true, kind: "transient", cooldownMs: 0, quarantine: false };
     if (status === 402)
         return { retryable: true, kind: "exhausted", cooldownMs: bounded(retryAfterMs ?? EXHAUSTED_MS), quarantine: false };
     // 408 and 425 are the server saying "ask again"; 5xx is the server being broken. Both may work

package/dist/router/src/providers/chatgpt/index.js

@@ -984,12 +984,13 @@ export class ChatGptAdapter {
      * `subagent` is the one bit about the caller the tier needs: Claude Code names the agent in the
      * `x-claude-code-agent-id` header, and only a subagent's request carries it.
      */
-    responsesOptions(carried, model, effort, replay = true, subagent = false) {
+    responsesOptions(carried, model, effort, replay = true, subagent = false, imageHint) {
         return {
             model,
             effort: effort ?? this.cfg.defaultEffort ?? "high",
             identity: this.cfg.identity ?? true,
             ...(this.cfg.instructionsAppend ? { instructionsAppend: this.cfg.instructionsAppend } : {}),
+            ...(imageHint ? { imageHint } : {}),
             replay,
             // The envelope names this provider and this model, and the request builder refuses anything
             // else: reasoning outlives the turn that made it, and a conversation moved to another model
@@ -1006,7 +1007,7 @@ export class ChatGptAdapter {
      * Handle a fully-read Messages request. `model`/`effort` already resolved by routing.
      *
      * `options.subagent` says the turn was made inside a subagent, which is what the provider's
-     * `fast.subagent` switch is about.
+     * `fast.subagent` switch is about. `options.imageHint` is how the session makes an image (translate.ts).
      */
     async handle(req, res, path, json, model, effort, options) {
         if (path.startsWith("/v1/messages/count_tokens")) {
@@ -1021,7 +1022,7 @@ export class ChatGptAdapter {
             this.log.warn(`chatgpt ${this.name}: dropped server tools for ${model}: ${[...serverTools].join(", ")} (Anthropic runs these; this provider cannot)`);
         const carried = { replayed: 0, undecodable: 0 };
         const subagent = options?.subagent === true;
-        let upstreamReq = toResponsesRequest(json, this.responsesOptions(carried, model, effort, true, subagent));
+        let upstreamReq = toResponsesRequest(json, this.responsesOptions(carried, model, effort, true, subagent, options?.imageHint));
         let body = JSON.stringify(upstreamReq);
         const cacheKey = upstreamReq.prompt_cache_key;
         // Input estimate for message_start: a conversation only grows, so the last measured total is a floor.
@@ -1062,7 +1063,7 @@ export class ChatGptAdapter {
         // must never be the reason a user's turn fails (reasoning.ts).
         if (carried.replayed > 0 && sent.kind === "refused" && refusesReplayedReasoning(sent.status, sent.text)) {
             this.log.warn(`chatgpt ${this.name}: upstream ${sent.status} refused ${carried.replayed} replayed reasoning item(s) for ${model}; asking again without them: ${sent.text.slice(0, 200)}`);
-            upstreamReq = toResponsesRequest(json, this.responsesOptions({ replayed: 0, undecodable: 0 }, model, effort, false, subagent));
+            upstreamReq = toResponsesRequest(json, this.responsesOptions({ replayed: 0, undecodable: 0 }, model, effort, false, subagent, options?.imageHint));
             body = JSON.stringify(upstreamReq);
             carried.replayed = 0;
             sent = await ask();

package/dist/router/src/providers/chatgpt/translate.js

@@ -233,6 +233,8 @@ export function toResponsesRequest(req, opts) {
         parts.push(sys);
     if (opts.instructionsAppend)
         parts.push(opts.instructionsAppend);
+    if (opts.imageHint && opts.subagent !== true)
+        parts.push(opts.imageHint);
     const input = [];
     // Claude Code sends side queries whose history starts with a bare tool_result (e.g. summarising a
     // large tool output). Anthropic tolerates the orphan; the Responses API rejects a function_call_output

package/dist/router/src/proxy.js

@@ -21,7 +21,7 @@ import zlib from "node:zlib";
 import { ProviderHealth, providerExhaustion, UpstreamHealth } from "./health.js";
 import { BOOTSTRAP_PATH, injectBootstrap } from "./bootstrap.js";
 import { THREAD_UNSUPPORTED, effortOf, isAutoModeClassifier, resolve, rewriteBody, stripThreadFields, threadDecision, unroutableReason } from "./routing.js";
-import { defaultAgentDir, withAgentAliases } from "./agents.js";
+import { defaultAgentDir, imageLine, withAgentAliases } from "./agents.js";
 import { forwardCompatibleHeader, resolveCompatibleCaps, sanitizeForCompatible } from "./compat.js";
 import { applyIdentityToAnthropicBody } from "./identity.js";
 import { anthropicServerToolBackend, webPluginBackend, webSearchBlocks, webSearchErrorBlocks, webSearchMessage, webSearchQuery, webSearchSse } from "./websearch.js";
@@ -33,7 +33,7 @@ import { GoogleAdapter } from "./providers/google/index.js";
 import { OpenCodeUsage, isOpenCodeGo } from "./providers/opencode-usage.js";
 import { GrokAdapter } from "./providers/grok/index.js";
 import { conversationKey } from "./providers/chatgpt/translate.js";
-import { providerFor, searchProviderFor, terminateHosts } from "./config.js";
+import { adminPort, providerFor, searchProviderFor, terminateHosts } from "./config.js";
 import { chatPickerModels, injectPickerModels, isBootstrapPath } from "./picker.js";
 import { effortLevels, effortLevelsForModel } from "./admin.js";
 import { isWebFetchRequest } from "./webfetch.js";
@@ -989,7 +989,7 @@ export class Proxy {
                         try {
                             // The adapter reports each account's outcome to the shared pool itself, so a slot pointing
                             // here fails over once every account is out (chooseTarget asks the adapter).
-                            const o = await this.chatgpt(route.provider, provider).handle(req, res, path, json, route.model, effortOf(json), { subagent });
+                            const o = await this.chatgpt(route.provider, provider).handle(req, res, path, json, route.model, effortOf(json), { subagent, imageHint: imageLine(adminPort(cfg)) });
                             if (!path.startsWith("/v1/messages/count_tokens"))
                                 this.providerHealth.observe(route.provider, o.status, o.exhaustion);
                             finish(String(o.status), o.bytes, o.note, o.status >= 400, { ...o, ...(searchAttempted ? { upstreamCalled: undefined } : {}) });

package/dist/router/src/tether.js

@@ -66,6 +66,13 @@ export const PROBE_URLS = {
 };
 export const PROBE_TIMEOUT_MS = 4_000;
 export const MIN_SWITCH_INTERVAL_MS = 60_000;
+/**
+ * After a join that failed, the next try comes this much later per failure in a row (10, 20, 30 s…)
+ * up to MIN_SWITCH_INTERVAL_MS. A failed join switched nothing, so the once-a-minute rule against
+ * flapping does not apply: walking out of the office, the first join failed as the hotspot was only
+ * just coming into range, and the Mac sat offline for the rest of the minute (2026-10-22).
+ */
+export const JOIN_RETRY_MS = 10_000;
 /** How long a scan that saw a known Wi-Fi stands for a return still waiting on busy calls. */
 export const KNOWN_VISIBLE_TRUST_MS = 60_000;
 export const RETURN_PROBE_MS = 20_000;
@@ -96,6 +103,8 @@ export const RETURN_HOLD_FAILSAFE_MS = RETURN_DRAIN_WAIT_MS + 3 * 60_000;
 const JOIN_SETTLE_MS = 15_000;
 /** States that say why the last join failed; they stay (with their hint) until the next attempt. */
 const JOIN_FAILURES = new Set(["hotspot-not-visible", "join-failed", "needs-setup", "no-hotspot-profile", "needs-location"]);
+/** Failures a moment later can cure (the phone coming into range); setup problems wait the full minute. */
+const RETRIABLE_JOIN = new Set(["hotspot-not-visible", "join-failed"]);
 // ---- Pure helpers -------------------------------------------------------------------------------
 /** The Wi-Fi device from `networksetup -listallhardwareports` ("Hardware Port: Wi-Fi\nDevice: en0"). */
 export function parseWifiDevice(text) {
@@ -336,6 +345,8 @@ export class TetherController {
     state = "off";
     pinned = false;
     lastSwitchAt = 0;
+    /** Hotspot joins that failed in a row; the retry gap grows with it (JOIN_RETRY_MS). */
+    joinFailures = 0;
     /** When a scan last saw a known Wi-Fi other than the hotspot. */
     knownVisibleAt = -Infinity;
     lastSwitch = null;
@@ -486,6 +497,7 @@ export class TetherController {
         }
         if (this.network === "hotspot") {
             // Landed here by our own failover or by hand: either way, plan the way back from here.
+            this.joinFailures = 0;
             if (this.landedOnHotspotAt === null) {
                 this.landedOnHotspotAt = this.now();
                 this.nextReturnAt = nextReturnPoint(this.landedOnHotspotAt, this.now());
@@ -500,6 +512,8 @@ export class TetherController {
         // On Wi-Fi (or none): the way back is no longer pending, and landing again starts the schedule over.
         this.landedOnHotspotAt = null;
         if (!this.window.outage()) {
+            if (this.network === "wifi")
+                this.joinFailures = 0;
             this.state = this.network === "wifi" ? "watching" : "no-wifi";
             if (this.network === "wifi")
                 this.decide(`watching Wi-Fi (${5 - this.window.failures()}/5 recent probes ok)`);
@@ -517,11 +531,13 @@ export class TetherController {
             return;
         }
         const since = this.now() - this.lastSwitchAt;
-        if (since < MIN_SWITCH_INTERVAL_MS) {
+        const retrying = this.joinFailures > 0 && RETRIABLE_JOIN.has(this.state);
+        const gap = retrying ? Math.min(MIN_SWITCH_INTERVAL_MS, JOIN_RETRY_MS * this.joinFailures) : MIN_SWITCH_INTERVAL_MS;
+        if (since < gap) {
             // A failed join keeps saying why (and its hint) until the next attempt.
             if (!JOIN_FAILURES.has(this.state))
                 this.state = "outage";
-            this.decide(`${why}; waiting ${Math.ceil((MIN_SWITCH_INTERVAL_MS - since) / 1000)}s (at most one switch per minute)`);
+            this.decide(`${why}; waiting ${Math.ceil((gap - since) / 1000)}s (${retrying ? "trying the hotspot again" : "at most one switch per minute"})`);
             return;
         }
         // A call in flight on a dead network cannot finish anyway; give it a short chance, no more.
@@ -533,6 +549,7 @@ export class TetherController {
         this.decide(`${why}: joining hotspot "${settings.hotspotSsid}"`);
         const outcome = await this.join(settings.hotspotSsid);
         this.recordSwitch("hotspot", outcome === "joined", outcome === "joined" ? why : outcome);
+        this.joinFailures = outcome === "joined" ? 0 : this.joinFailures + 1;
         if (outcome === "joined" && !this.onHotspot(this.currentIp())) {
             // Joined, but on a network that could not be remembered (see learn()): it reads as Wi-Fi.
             this.window.reset();

package/dist/router/src/version.js

@@ -5,4 +5,4 @@
 // from the manifests. Until 0.1.1 the router and the CLI each carried their own literal, and both
 // still said "0.1.0" in the 0.1.1 release: after an update nobody could tell which router was
 // running, and the tray app had nothing to compare (2026-09-15, reported from a Windows install).
-export const VERSION = "0.12.6";
+export const VERSION = "0.12.7";

package/docs/ARCHITECTURE.md

@@ -427,7 +427,10 @@ must preserve **Data: Artificial Analysis (artificialanalysis.ai)** attribution.
   reason. With a chatgpt provider configured the body also tells a worker how to
   make an image: `POST /api/image` on the admin port, which runs one Codex
   Responses turn with the hosted `image_generation` tool required and answers
-  with the image bytes (`clauderipple image` is the same call). Measured
+  with the image bytes (`clauderipple image` is the same call). A GPT main session
+  gets the same lines at the end of its instructions (not a subagent's turns, whose
+  agent file has them): without them a GPT session told the operator it could not
+  make images and drew an SVG (2026-10-22). Measured
   2026-09-29 on a subscription: the image is the `image_generation_call` output
   item's base64 `result`, about 30 s; `output_format` and `background` are
   honoured, `size` and `quality` are accepted and ignored (even "999x1" and
@@ -1647,6 +1650,7 @@ plan unless marked otherwise.
 | Blind returns repeatedly cut the only connection while travelling with the lid closed (2026-10-21 18:40–19:08 KST, owner-reported router.log): at each point, "trying to go back to Wi-Fi: leaving the hotspot so macOS joins the best known network", then "no network was joined", "networksetup said: Failed to join network PBJ" → `join-failed`. No known Wi-Fi was in range, and an idle iPhone stops advertising; with the lid closed macOS did not reliably rejoin it. The owner pinned the network as a stopgap. | Never leave the hotspot speculatively. Before either quiet return or the hold gate, a read-only backend check must prove another saved Wi-Fi is visible (on Windows, also an automatic profile). No match → "staying on the hotspot: no known Wi-Fi in range", once per point, then the next point on the unchanged schedule. Scan/list failure, unsupported response or Location refusal → stay and log why; never hold calls or disconnect on unknown visibility. macOS: preferred SSIDs + directed CoreWLAN JXA scans, Windows: saved profile SSIDs intersected with `netsh wlan show networks` (§8, measurements 2026-10-21). |
 | Android hotspot never recognised (2026-10-20, found by reading the code for an owner with Windows laptops and Android phones in mind): "on the hotspot" was the iPhone range 172.20.10.0/28 alone, on macOS and Windows. An Android hotspot hands out 192.168.43.x (≤ Android 10) or a random /24 (Android 11+; 192.168/16, 172.16/12, 10/8 by Android 14), so after our own failover `join()` saw no hotspot address and reported `join-failed`/`hotspot-not-visible`, while on the phone the controller read Wi-Fi and never planned the way back, and a by-hand join was never recognised | The product does not assume an iPhone. After our own join of the configured SSID is accepted by the OS, a new, non-link-local address within the settle time is the join, and its subnet (address + netmask from `os.networkInterfaces()`: no Location, no elevation) is kept in `<home>/tether.json` for that hotspot name; "on the hotspot" = iPhone range OR that network (§8). Only our own join replaces it, and a subnet equal to the Wi-Fi watched before is not remembered (logged as ambiguous) so home Wi-Fi is never read as the hotspot. Hints name both phones where the step differs. Not yet run with a real Android phone. |
 | An expired Claude login on the Mac wrote `[desktop state] …로그인이 만료되었습니다…` every few seconds per Claude app session and read the keychain (a synchronous child process) for every request, while phones learned of it only by a failed send (2026-10-15) | A login problem is one host state: logged when it starts and ends, sent to phones as `HostInfo.desktopProblem` (a banner), and the keychain is reread at most every 30 s while expired or after a 401. Per-session Remote Control errors log once per change. The host never refreshes the login itself. |
+| OpenCode Go answered **402** for `minimax-m3.1-flash-free` while that model's endpoint was down (`server_error … Upstream request failed: Endpoint is unavailable`); read as billing exhaustion, it parked the whole `opencode-go` account for 30 minutes, DeepSeek with it, and delegated work fell back to Opus while the account had credit (2026-10-22) | A relay's refusal whose body says its upstream failed (`RELAY_UPSTREAM_FAILED`, `pool.ts`) is transient whatever status it carries — 402 as well as 403 — and never a provider exhaustion (`health.ts`). A plain 402 or a body naming balance, billing or quota still is. |
 
 ### Router-owned automatic updates (2026-10-21)
 
@@ -1802,7 +1806,11 @@ before; a Wi-Fi elsewhere that happens to use the learned /24 reads as the hotsp
 can drop it only when another saved SSID is visible (visibility guard, 2026-10-21, below);
 `tether.pin` stops switching entirely. Failover (on Wi-Fi or no
 address, outage): wait at most 30s for an in-flight call, then `sudo -n networksetup
--setairportnetwork <dev> <NAME>` (macOS takes the password from the System keychain). The probe window
+-setairportnetwork <dev> <NAME>` (macOS takes the password from the System keychain). Switches are at
+least a minute apart, but a join that failed ("Failed to join network", or not visible) switched
+nothing, so it is tried again 10 s, 20 s, 30 s … later up to that minute: walking out of the office
+the first join came as the hotspot was only just in range, failed, and the Mac stayed offline for the
+rest of the minute (2026-10-22). Setup failures (sudo, profile, Location) still wait the minute. The probe window
 lives in the process, so it only works if the router is not restarted every few seconds while the
 machine is offline (§5, health self-exit refined 2026-10-20). networksetup
 reports failure on stdout and may exit 0, so its text decides: "Could not find network" →

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "clauderipple",
-  "version": "0.12.6",
+  "version": "0.12.7",
   "description": "Use GPT (any ChatGPT plan with Codex), DeepSeek and 400+ other models in the Claude Desktop Code tab and Claude Code while staying signed in to your Claude subscription — no third-party gateway mode. Several ChatGPT accounts that take over when one runs out, in Codex too.",
   "license": "GPL-3.0-only",
   "workspaces": [