@sapiom/harness 0.5.1 → 0.7.0

package/CHANGELOG.md

@@ -1,5 +1,157 @@
 # @sapiom/harness
 
+## 0.7.0
+
+### Minor Changes
+
+- 3cbe957: Command palette: a proper fuzzy finder, redesigned as Command Search
+
+  The Cmd+K palette is rebuilt around the reported search failures ("cannot find
+  this simple agent"): short queries no longer "match" characters scattered
+  across absolute paths, duplicate past sessions no longer flood the list, and
+  what you search is what the rail shows.
+
+  - **Boundary-gated matcher** (`web/src/lib/fuzzy.ts`): every matched character
+    must be contiguous with the previous one or sit at a word/segment boundary,
+    with a substring fallback for mid-word fragments. Scattered-noise matches are
+    rejected outright, not merely down-ranked. Multi-term queries AND across
+    whitespace.
+  - **Ranking model** (`web/src/lib/palette.ts`, new): rows carry display names
+    (`displayAgentName`, `sessionDisplayName` — user renames are searchable);
+    same-title same-folder past sessions collapse to the newest; sections order
+    by their best hit with per-section caps (lifted when only one kind matches);
+    recency is a bounded score bonus that never lifts a path-only match over a
+    name match.
+  - **Command Search surface** (per the design-eng widget): a search bar with a
+    clear button, filter tabs — All / Sessions / Agents / Templates / Docs /
+    Files / Actions — cycled with Tab/Shift+Tab, and a shortcut-bar footer. App
+    verbs (browse templates, toggle theme, panel toggles, new session here) are
+    injected actions; the Templates tab lists the catalog and opens the gallery
+    focused on a template; the Docs tab searches a short list of docs pages with
+    the docs site as the footer destination.
+  - The active session is badged "current", demoted from the unqueried top spot,
+    and never the default selection; matched characters render on an
+    accent-tinted cap that stays legible on selected rows in both themes.
+
+- f21f6a6: Windows: sessions create and deliver their prompt, the canvas refreshes, and nothing pops a console window
+
+  The desktop app was unusable on Windows — every `POST /api/sessions` answered
+  `500 {"error":"internal error"}`, and when a session did start, its first
+  prompt never reached the agent. Root-caused on a real machine and fixed
+  end to end.
+
+  - **Sessions.** Claude Code's own native auto-updater had renamed the running
+    `claude.exe` to `claude.exe.old.<ts>` inside the app-managed npm prefix and
+    never written the replacement, so every spawn failed while `doctor` (which
+    shells `where`) still reported the agent present. Boot now verifies the
+    agent actually spawns, repairs the managed install when it doesn't, and sets
+    `DISABLE_AUTOUPDATER` for installs the app owns. The refusal itself names
+    the situation instead of "target could not be determined".
+  - **The first prompt.** It is held until the session reports ready, which only
+    happens when the generated `SessionStart` hook POSTs back — and Claude Code
+    runs hooks through Git Bash on Windows, which cannot resolve a `.cmd`, so
+    the desktop's `node.cmd`-only shims meant the hook never ran. The host now
+    ships npm's extensionless sh shim too, a 20s hook-timeout fallback rescues a
+    session whose hook chain is broken (gated on Claude's blocking-prompt
+    screens so it can never answer a trust dialog), `emit.cjs` gets budgets a
+    cold loopback survives (SessionStart only — the other hooks block the
+    agent), and multi-line prompts are paste-wrapped under ConPTY, which hides
+    the bracketed-paste announcement.
+  - **Console windows.** The `sapiom-dev` MCP server was launched via `npx`,
+    whose `cmd.exe` sat on screen as a persistent blank window; closing it
+    killed the server and every later tool call hung. The app now installs
+    `@sapiom/mcp` into its own prefix and launches it through the app binary
+    (GUI subsystem — no console can exist), and every `child_process` call
+    across the harness, agent-core, the MCP and the desktop passes
+    `windowsHide`.
+  - **Canvas.** `fs.watch` reports native separators, so the watcher's
+    POSIX-literal comparison never matched on Windows and `canvas.reload` was
+    never published — every canvas hot-reload was silently dead there (the
+    "Preparing your agent" placeholder outliving a finished install was the
+    visible symptom).
+  - **Diagnosis.** 500s now carry the real message (and errno) instead of
+    "internal error", the desktop tees its main-process log to
+    `<userData>/logs/main.log`, and spawn failures map to actionable 4xx.
+  - **Also:** Git is provisioned from git-for-windows' checksum-pinned MinGit
+    when a Windows machine has none (template clone and deploy shell out to a
+    real `git`); client-supplied `cwd` is normalized server-side and the SPA's
+    path helpers understand both separators; gateway requests time out instead
+    of hanging an MCP tool call for minutes; and the updater falls back to
+    HTTP/1.1, names a GitHub 429 for what it is, and bounds every path that can
+    reach GitHub.
+
+### Patch Changes
+
+- 4edcbf5: Update the bottom toast to the design-system widget spec: the tone now lives in a leading icon — a green circled check for success, a neutral ⓘ for information, a red ⚠ for errors — instead of a red edge stripe on every toast (which error-coded even "Path copied."). The card itself is the shared floating surface every popover uses. Toasts default to the error tone; positive results (copy confirmations, deploy success, describe finished, agents found, up-to-date/downloaded update checks) opt into success, and neutral status (deploy progress, editor hand-offs, empty scans) opts into info. Also: spring entrance and a short exit animation, the auto-dismiss timer pauses while hovered or focused, and the dismiss control is the shared 22px icon button.
+- Updated dependencies [f21f6a6]
+  - @sapiom/agent-core@0.10.7
+  - @sapiom/mcp@0.12.5
+
+## 0.6.0
+
+### Minor Changes
+
+- 928a639: Studio: a new agent's workspace folder now appears in the rail the instant you
+  start creating it — from the composer or a template — as an optimistic
+  "Creating agent…" row, pinned to the top and focusable. It stays put through
+  session-landing and the clone, and across the brief window after the session
+  binds but before its `sapiom.json` is registered, so switching sessions
+  mid-creation can never strand the in-progress agent.
+
+  Also fixes two rail/canvas issues:
+
+  - **Canvas no longer clips the terminal step.** A revise loop (a step pointing
+    back to an earlier one) left a gap in the layer numbering; the SVG height was
+    derived from the layer _count_ while nodes were positioned by their raw layer
+    _index_, so the deepest node (a terminal like `deliver`) fell below the
+    viewBox and was drawn off-screen with a dangling edge. Rows are now compacted
+    to consecutive positions, which also removes the empty band the gap produced.
+  - **Cloned agents show a short name in the rail.** The row now reads
+    `newsletter-autopilot` rather than the full package name
+    `@sapiom/example-newsletter-autopilot` (npm scope and a leading `example-`
+    stripped for display only — the full name is on hover, and the raw name still
+    keys testids and lookups).
+
+- 5c0c646: Rail footer: live plan & balance card, and an "Update now" card for a downloaded desktop update
+
+  The rail's footer gains two shaded cards above the account row.
+
+  - **Plan & balance card** (both hosts): the harness server relays core reads at
+    `GET /api/account/plan` — the API key never reaches the page — showing the
+    org's plan name and one honest money line: daily spend against the org's
+    spend-limit rule (the same "$used / $cap" pair the dashboard renders),
+    falling back to the prepaid available balance, else nothing. An Upgrade pill
+    and a ⋮ menu deep-link to billing/usage on the dashboard (checkout is
+    dashboard-session-only). Signed-out or unreachable hides the card — it never
+    invents a number.
+  - **"Update now" card** (desktop only): when an update has finished
+    downloading, the main process pushes state over a new receive-only
+    `onUpdateState` bridge member (re-pushed on page load, buffered in the
+    preload so a reload can't drop it) and the card appears with the target
+    version. Clicking it goes through the existing `checkForUpdates()` — the
+    pending branch re-raises the update window — so there is still no
+    page-reachable install channel. It outlives "Later"; "Skip this version"
+    suppresses and retracts it (and now also disarms auto-install-on-quit for a
+    skipped build that was already staged).
+
+### Patch Changes
+
+- 651c407: Canvas extraction failures now name the project directory they bundled. The Canvas is the only `check()` caller whose directory the user never typed — it comes from the bound workflow row — so a report of "check, run_local and deploy succeed but the Canvas fails on the same project" was unfalsifiable from the panel alone; esbuild's own paths are printed relative to the invoking package, which reads like the bundler resolving `node_modules` from the wrong root.
+- 7bef8b2: Stop the empty-board auto-collapse from closing a canvas pane the user just opened. The collapse fires once per (session, binding), which was meant to make a redundant "still empty" probe harmless — but the pane's expand control is most often used right after starting a session on an agent, i.e. _before_ `activeSessionId` exists, so the probe that follows arrives under a different key and slams the pane shut a beat after the click (measured: 3–5 of 12 runs of the action-bar e2e, on `main`). A manual expand now claims the session, and a claim made while none is active adopts the one that reports next; switching sessions still re-arms the collapse.
+- 95241fb: Give the rail toggle a resting surface while the app window is blurred: macOS hides the traffic lights it sits beside, so the bare glyph read as a gap on the left of the header.
+- 21bb3f0: Let "Open in editor" target the editor you actually use.
+
+  The session menu hardcoded `vscode://file…`, so on a machine with Cursor (or
+  Windsurf, Zed, VS Code Insiders) and no VS Code the item silently did nothing —
+  the OS resolves the scheme and never reports back, so an unhandled scheme is
+  indistinguishable from a working one. Settings now carries an editor picker
+  (`HarnessSettings.editor`, `PATCH /api/settings`), the menu item names the
+  chosen editor ("Open in Cursor"), and a toast says where the folder was sent.
+  Windows paths are normalized to the `/C:/…` shape the handlers expect.
+
+- Updated dependencies [651c407]
+  - @sapiom/agent-core@0.10.6
+
 ## 0.5.1
 
 ### Patch Changes

package/dist/cli/doctor.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"doctor.d.ts","sourceRoot":"","sources":["../../src/cli/doctor.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAyDnE;;8CAE8C;AAC9C,eAAO,MAAM,sBAAsB,uCAAuC,CAAC;AAC3E,eAAO,MAAM,qBAAqB,2BAA2B,CAAC;AAE9D;;;;GAIG;AACH,MAAM,WAAW,YAAY;IAC3B,MAAM,EAAE,WAAW,EAAE,CAAC;IACtB,EAAE,EAAE,OAAO,CAAC;IACZ;8DAC0D;IAC1D,kBAAkB,EAAE,WAAW,EAAE,CAAC;CACnC;AAED,wBAAsB,SAAS,IAAI,OAAO,CAAC,YAAY,CAAC,CA4BvD;AAED;;;;yBAIyB;AACzB,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,YAAY,GAAG,WAAW,CAEpE;AAED,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,YAAY,GAAG,IAAI,CAM5D"}
+{"version":3,"file":"doctor.d.ts","sourceRoot":"","sources":["../../src/cli/doctor.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AA2DnE;;8CAE8C;AAC9C,eAAO,MAAM,sBAAsB,uCAAuC,CAAC;AAC3E,eAAO,MAAM,qBAAqB,2BAA2B,CAAC;AAE9D;;;;GAIG;AACH,MAAM,WAAW,YAAY;IAC3B,MAAM,EAAE,WAAW,EAAE,CAAC;IACtB,EAAE,EAAE,OAAO,CAAC;IACZ;8DAC0D;IAC1D,kBAAkB,EAAE,WAAW,EAAE,CAAC;CACnC;AAED,wBAAsB,SAAS,IAAI,OAAO,CAAC,YAAY,CAAC,CA4BvD;AAED;;;;yBAIyB;AACzB,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,YAAY,GAAG,WAAW,CAEpE;AAED,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,YAAY,GAAG,IAAI,CAM5D"}

package/dist/cli/doctor.js

@@ -6,7 +6,9 @@ async function which(bin) {
     try {
         const { stdout } = await execFileAsync(process.platform === "win32" ? "where" : "which", [
             bin,
-        ]);
+            // windowsHide: a console child of the console-less desktop host would
+            // otherwise open a visible window (no-op on POSIX and in a real terminal).
+        ], { windowsHide: true });
         return stdout.trim().split("\n")[0] ?? null;
     }
     catch {
@@ -15,7 +17,7 @@ async function which(bin) {
 }
 async function version(bin, args = ["--version"]) {
     try {
-        const { stdout } = await execFileAsync(bin, args);
+        const { stdout } = await execFileAsync(bin, args, { windowsHide: true });
         return stdout.trim().split("\n")[0] ?? null;
     }
     catch {

package/dist/cli/doctor.js.map

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

package/dist/core/account-plan.d.ts

@@ -0,0 +1,51 @@
+/**
+ * account-plan — the rail's plan card, read from the Sapiom CORE surface so it
+ * can never disagree with the dashboard's own billing views.
+ *
+ * Three reads, folded into one `AccountPlanView`:
+ *
+ *  - `GET /v1/dashboard/plan`                        → plan name + status
+ *  - `GET /v1/spending-rules/spend-limit-summary`    → today's settled spend vs
+ *    the org's spend-limit rule — the exact "$used / $cap" pair the dashboard's
+ *    balance card renders (JSON:API envelope; all-null attributes when no rule)
+ *  - `GET /v1/accounts/spend`                        → `availableBalanceUsd`,
+ *    the prepaid fallback when no limit rule exists
+ *
+ * Same auth contract as template-catalog.ts (and verified there): core takes
+ * `Authorization: Bearer`, NOT the agents surface's `x-sapiom-api-key`, and
+ * every path is prefixed `/v1`. The key stays server-side; a 401/403 triggers
+ * exactly one credential refresh + retry.
+ *
+ * These endpoints are excluded from core's public OpenAPI surface, so their
+ * shapes are contracts by observation, not by document. Every field is
+ * narrowed defensively and any drift degrades the readout to `none` (or the
+ * whole view to `fallback`) rather than throwing — a broken billing read must
+ * never take the rail down.
+ */
+import type { AccountPlanView } from "../shared/types.js";
+import { type ApiKeyProvider } from "./api-key-provider.js";
+export interface AccountPlanReader {
+    /** The assembled card view. Never throws: signed-out and unreachable both
+     *  come back as `source: "fallback"` with an honest empty readout. */
+    view(): Promise<AccountPlanView>;
+}
+/** `{ data: { plan: { name, status } | null } }` → the card's plan line. */
+export declare function extractPlan(body: unknown): AccountPlanView["plan"];
+/** JSON:API `{ data: { attributes: { limitUsd, windowSpendUsd } } }` → the
+ *  "$used / $cap" pair, or null when no qualifying rule exists (all-null
+ *  attributes is that endpoint's documented "no rule" answer, not an error). */
+export declare function extractLimit(body: unknown): {
+    usedUsd: number;
+    limitUsd: number;
+} | null;
+/** `{ data: { availableBalanceUsd } }` → the prepaid balance, or null. */
+export declare function extractBalance(body: unknown): number | null;
+export declare function createAccountPlanReader(opts: {
+    /** Accepts a provider (preferred — enables refresh-on-401) or a bare key. */
+    apiKey: string | null | ApiKeyProvider;
+    /** Override the core base URL (resolved from env by default). Test seam. */
+    baseUrl?: string;
+    /** Injectable fetch. Test seam. */
+    fetchImpl?: typeof fetch;
+}): AccountPlanReader;
+//# sourceMappingURL=account-plan.d.ts.map

package/dist/core/account-plan.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"account-plan.d.ts","sourceRoot":"","sources":["../../src/core/account-plan.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAC1D,OAAO,EACL,KAAK,cAAc,EAEpB,MAAM,uBAAuB,CAAC;AAa/B,MAAM,WAAW,iBAAiB;IAChC;0EACsE;IACtE,IAAI,IAAI,OAAO,CAAC,eAAe,CAAC,CAAC;CAClC;AAsBD,4EAA4E;AAC5E,wBAAgB,WAAW,CAAC,IAAI,EAAE,OAAO,GAAG,eAAe,CAAC,MAAM,CAAC,CAIlE;AAED;;gFAEgF;AAChF,wBAAgB,YAAY,CAC1B,IAAI,EAAE,OAAO,GACZ;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAO9C;AAED,0EAA0E;AAC1E,wBAAgB,cAAc,CAAC,IAAI,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI,CAE3D;AAED,wBAAgB,uBAAuB,CAAC,IAAI,EAAE;IAC5C,6EAA6E;IAC7E,MAAM,EAAE,MAAM,GAAG,IAAI,GAAG,cAAc,CAAC;IACvC,4EAA4E;IAC5E,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,mCAAmC;IACnC,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;CAC1B,GAAG,iBAAiB,CA0GpB"}

package/dist/core/account-plan.js

@@ -0,0 +1,174 @@
+/**
+ * account-plan — the rail's plan card, read from the Sapiom CORE surface so it
+ * can never disagree with the dashboard's own billing views.
+ *
+ * Three reads, folded into one `AccountPlanView`:
+ *
+ *  - `GET /v1/dashboard/plan`                        → plan name + status
+ *  - `GET /v1/spending-rules/spend-limit-summary`    → today's settled spend vs
+ *    the org's spend-limit rule — the exact "$used / $cap" pair the dashboard's
+ *    balance card renders (JSON:API envelope; all-null attributes when no rule)
+ *  - `GET /v1/accounts/spend`                        → `availableBalanceUsd`,
+ *    the prepaid fallback when no limit rule exists
+ *
+ * Same auth contract as template-catalog.ts (and verified there): core takes
+ * `Authorization: Bearer`, NOT the agents surface's `x-sapiom-api-key`, and
+ * every path is prefixed `/v1`. The key stays server-side; a 401/403 triggers
+ * exactly one credential refresh + retry.
+ *
+ * These endpoints are excluded from core's public OpenAPI surface, so their
+ * shapes are contracts by observation, not by document. Every field is
+ * narrowed defensively and any drift degrades the readout to `none` (or the
+ * whole view to `fallback`) rather than throwing — a broken billing read must
+ * never take the rail down.
+ */
+import { staticApiKeyProvider, } from "./api-key-provider.js";
+import { resolveCoreBaseUrl } from "./definition-slug-resolver.js";
+/** Mirrors template-catalog.ts: statuses worth one refresh + retry. */
+function isAuthRejection(status) {
+    return status === 401 || status === 403;
+}
+/** How long a successful view is reused. Spend moves on the order of runs, not
+ *  keystrokes; the dashboard's own hooks poll at 30–60s, and the SPA re-asks on
+ *  its own cadence — a short TTL just absorbs bursts (mount + auth flip). */
+const CACHE_TTL_MS = 60000;
+function asObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value)
+        ? value
+        : null;
+}
+/** A finite number, from a JSON number or a decimal string (the ledger returns
+ *  decimal(36,18) strings; the spend read model returns numbers). */
+function usd(value) {
+    if (typeof value === "number")
+        return Number.isFinite(value) ? value : null;
+    if (typeof value === "string" && value.trim() !== "") {
+        const parsed = Number(value);
+        return Number.isFinite(parsed) ? parsed : null;
+    }
+    return null;
+}
+/** `{ data: { plan: { name, status } | null } }` → the card's plan line. */
+export function extractPlan(body) {
+    const plan = asObject(asObject(asObject(body)?.data)?.plan);
+    if (!plan || typeof plan.name !== "string" || plan.name === "")
+        return null;
+    return { name: plan.name, status: plan.status === "active" ? "active" : "inactive" };
+}
+/** JSON:API `{ data: { attributes: { limitUsd, windowSpendUsd } } }` → the
+ *  "$used / $cap" pair, or null when no qualifying rule exists (all-null
+ *  attributes is that endpoint's documented "no rule" answer, not an error). */
+export function extractLimit(body) {
+    const attrs = asObject(asObject(asObject(body)?.data)?.attributes);
+    if (!attrs)
+        return null;
+    const limitUsd = usd(attrs.limitUsd);
+    const usedUsd = usd(attrs.windowSpendUsd);
+    if (limitUsd === null || usedUsd === null)
+        return null;
+    return { usedUsd, limitUsd };
+}
+/** `{ data: { availableBalanceUsd } }` → the prepaid balance, or null. */
+export function extractBalance(body) {
+    return usd(asObject(asObject(body)?.data)?.availableBalanceUsd);
+}
+export function createAccountPlanReader(opts) {
+    const provider = opts.apiKey !== null && typeof opts.apiKey === "object"
+        ? opts.apiKey
+        : staticApiKeyProvider(opts.apiKey);
+    const baseUrl = opts.baseUrl ?? resolveCoreBaseUrl();
+    const fetchImpl = opts.fetchImpl ?? fetch;
+    let cache = null;
+    // One line per distinct failure reason, not per poll — the SPA re-asks every
+    // minute and a persistent misconfiguration shouldn't flood the log.
+    const logged = new Set();
+    const warnOnce = (reason) => {
+        if (logged.has(reason))
+            return;
+        logged.add(reason);
+        console.error(`[harness] account plan unavailable from ${baseUrl} (${reason}); ` +
+            "the rail hides the plan card — check the harness is signed in " +
+            "and SAPIOM_CORE_URL points at a reachable Sapiom API");
+    };
+    /**
+     * GET `path` from the core surface with the held key, refreshing + retrying
+     * once on an auth rejection. Returns the parsed body, or null on any failure.
+     */
+    const getJson = async (path) => {
+        let apiKey = provider.getKey();
+        if (!apiKey)
+            return null;
+        const attempt = async (key) => {
+            try {
+                return await fetchImpl(`${baseUrl}${path}`, {
+                    // Core (`api.*`) takes a Bearer token — see template-catalog.ts.
+                    headers: { Authorization: `Bearer ${key}` },
+                });
+            }
+            catch (err) {
+                warnOnce(err instanceof Error ? err.message : String(err));
+                return null;
+            }
+        };
+        let response = await attempt(apiKey);
+        if (!response)
+            return null;
+        if (isAuthRejection(response.status)) {
+            const refreshed = await provider.refresh();
+            if (refreshed && refreshed !== apiKey) {
+                apiKey = refreshed;
+                response = await attempt(refreshed);
+                if (!response)
+                    return null;
+            }
+        }
+        if (!response.ok) {
+            warnOnce(`HTTP ${response.status} on ${path}`);
+            return null;
+        }
+        try {
+            return await response.json();
+        }
+        catch {
+            warnOnce("response body was not JSON");
+            return null;
+        }
+    };
+    return {
+        async view() {
+            const fresh = cache && Date.now() - cache.at < CACHE_TTL_MS;
+            if (fresh && cache)
+                return cache.value;
+            // Signed out is an expected state (a harness launched without auth), not
+            // a fault — the card simply doesn't render.
+            if (!provider.getKey()) {
+                return { plan: null, readout: { kind: "none" }, source: "fallback", reason: "signed-out" };
+            }
+            // Three independent reads; each may fail alone. A plan with no numbers
+            // and numbers with no plan are both better than nothing, so partial
+            // success builds a partial view instead of discarding what answered.
+            const [planBody, limitBody, spendBody] = await Promise.all([
+                getJson("/v1/dashboard/plan"),
+                getJson("/v1/spending-rules/spend-limit-summary"),
+                getJson("/v1/accounts/spend"),
+            ]);
+            if (planBody === null && limitBody === null && spendBody === null) {
+                // Nothing answered — unreachable (or every shape drifted). Not cached:
+                // the next poll should get to try again.
+                return { plan: null, readout: { kind: "none" }, source: "fallback", reason: "unreachable" };
+            }
+            const plan = extractPlan(planBody);
+            const limit = extractLimit(limitBody);
+            const balance = extractBalance(spendBody);
+            const readout = limit
+                ? { kind: "limit", ...limit }
+                : balance !== null
+                    ? { kind: "balance", availableUsd: balance }
+                    : { kind: "none" };
+            const value = { plan, readout, source: "live" };
+            cache = { at: Date.now(), value };
+            return value;
+        },
+    };
+}
+//# sourceMappingURL=account-plan.js.map

package/dist/core/account-plan.js.map

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

package/dist/core/adapters/claude-code.d.ts

@@ -96,6 +96,16 @@ export interface ClaudeCodeAdapterOptions {
      *  exact turn count; larger files are read only at head+tail. */
     fullScanMaxBytes?: number;
 }
+/**
+ * Claude Code's known blocking startup screens, matched against stripped-ANSI
+ * scrollback. Exported so the packaged smoke / e2e layers can pin the same
+ * patterns this adapter gates the ready-fallback on (see detectBlockingPrompt).
+ * Wording verified against Claude Code 2.1.x; a future rewording fails SAFE:
+ * an unmatched dialog only means the fallback flips `ready` and the injected
+ * prompt lands in a dialog the user is looking at anyway — the pre-fallback
+ * behaviour was the prompt silently vanishing after ten minutes.
+ */
+export declare const CLAUDE_BLOCKING_PROMPT_PATTERNS: readonly RegExp[];
 export declare class ClaudeCodeAdapter implements HarnessAdapter {
     readonly id: "claude-code";
     readonly eventSource: "hooks";
@@ -103,10 +113,36 @@ export declare class ClaudeCodeAdapter implements HarnessAdapter {
      *  launch/resume path below, so a rehydration brief composed into that file
      *  needs no separate delivery. */
     readonly systemPromptDelivery: "launch-flag";
+    /**
+     * See `HarnessAdapter.readyFallback`. The SessionStart hook stays the
+     * primary signal (isReadyEnough gives claude-code NO immediate scrollback
+     * shortcut); this only lets SessionManager's generously-timed fallback
+     * rescue a session whose hook chain is broken — on Windows the hook runs
+     * `node` through Claude's hook shell, and when that resolution fails the
+     * POST never fires, `ready` never flips, and the held first prompt was
+     * silently dropped.
+     */
+    readonly readyFallback: "hook-timeout";
+    /**
+     * See `HarnessAdapter.assumesBracketedPaste`. Claude Code's Ink input layer
+     * enables mode 2004 in every interactive session — the macOS/Linux paste
+     * detection observing `ESC[?2004h` on real ptys is the in-repo evidence.
+     * Declared so Windows (where ConPTY hides that announcement) still paste-
+     * wraps multi-line prompts instead of submitting at the first newline.
+     */
+    readonly assumesBracketedPaste = true;
     private readonly binary;
     private readonly homeDir;
     private readonly fullScanMaxBytes;
     constructor(options?: ClaudeCodeAdapterOptions);
+    /**
+     * See `HarnessAdapter.detectBlockingPrompt` and `readyFallback` above: this
+     * exists ONLY to gate the hook-timeout fallback (never type a stray Enter
+     * into an unanswered trust dialog) — it deliberately does NOT give
+     * claude-code Codex's immediate scrollback shortcut, because the hook is
+     * reliable wherever the hook chain itself works.
+     */
+    detectBlockingPrompt(scrollback: string): boolean;
     doctor(): Promise<DoctorCheck[]>;
     launch(opts: LaunchOpts): SpawnSpec;
     resume(agentSessionId: string, opts: LaunchOpts): SpawnSpec;

package/dist/core/adapters/claude-code.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"claude-code.d.ts","sourceRoot":"","sources":["../../../src/core/adapters/claude-code.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AASH,OAAO,KAAK,EACV,WAAW,EACX,cAAc,EACd,UAAU,EACV,iBAAiB,EACjB,SAAS,EACV,MAAM,uBAAuB,CAAC;AAE/B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,eAAO,MAAM,uBAAuB,UAAU,CAAC;AAE/C;;;GAGG;AACH,wBAAgB,kBAAkB,CAChC,WAAW,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GACrC,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,GAAG,IAAI,CAGjC;AAED;;;;;;;;GAQG;AACH,wBAAgB,wBAAwB,CAAC,WAAW,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,OAAO,CASxF;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAGrD;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAsB,cAAc,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAMpF;AA4BD,MAAM,WAAW,wBAAwB;IACvC,wFAAwF;IACxF,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,kEAAkE;IAClE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;qEACiE;IACjE,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B;AAwMD,qBAAa,iBAAkB,YAAW,cAAc;IACtD,QAAQ,CAAC,EAAE,EAAG,aAAa,CAAU;IACrC,QAAQ,CAAC,WAAW,EAAG,OAAO,CAAU;IACxC;;sCAEkC;IAClC,QAAQ,CAAC,oBAAoB,EAAG,aAAa,CAAU;IACvD,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAChC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAS;gBAE9B,OAAO,GAAE,wBAA6B;IAM5C,MAAM,IAAI,OAAO,CAAC,WAAW,EAAE,CAAC;IA6BtC,MAAM,CAAC,IAAI,EAAE,UAAU,GAAG,SAAS;IAgBnC,MAAM,CAAC,cAAc,EAAE,MAAM,EAAE,IAAI,EAAE,UAAU,GAAG,SAAS;IAa3D;;;;;;;;;;;;;OAaG;IACH,UAAU,CAAC,IAAI,EAAE,UAAU,GAAG,SAAS;IAmBvC;;;;;;;;;;;;;;;;OAgBG;IACG,SAAS,CAAC,cAAc,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAShE,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,iBAAiB,EAAE,CAAC;CA+ClE;AAcD,wBAAgB,uBAAuB,CAAC,OAAO,CAAC,EAAE,wBAAwB,GAAG,cAAc,CAE1F"}
+{"version":3,"file":"claude-code.d.ts","sourceRoot":"","sources":["../../../src/core/adapters/claude-code.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AASH,OAAO,KAAK,EACV,WAAW,EACX,cAAc,EACd,UAAU,EACV,iBAAiB,EACjB,SAAS,EACV,MAAM,uBAAuB,CAAC;AAG/B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,eAAO,MAAM,uBAAuB,UAAU,CAAC;AAE/C;;;GAGG;AACH,wBAAgB,kBAAkB,CAChC,WAAW,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GACrC,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,GAAG,IAAI,CAGjC;AAED;;;;;;;;GAQG;AACH,wBAAgB,wBAAwB,CAAC,WAAW,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,OAAO,CASxF;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAGrD;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAsB,cAAc,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAMpF;AA4BD,MAAM,WAAW,wBAAwB;IACvC,wFAAwF;IACxF,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,kEAAkE;IAClE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;qEACiE;IACjE,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B;AAwMD;;;;;;;;GAQG;AACH,eAAO,MAAM,+BAA+B,EAAE,SAAS,MAAM,EAO5D,CAAC;AAEF,qBAAa,iBAAkB,YAAW,cAAc;IACtD,QAAQ,CAAC,EAAE,EAAG,aAAa,CAAU;IACrC,QAAQ,CAAC,WAAW,EAAG,OAAO,CAAU;IACxC;;sCAEkC;IAClC,QAAQ,CAAC,oBAAoB,EAAG,aAAa,CAAU;IACvD;;;;;;;;OAQG;IACH,QAAQ,CAAC,aAAa,EAAG,cAAc,CAAU;IACjD;;;;;;OAMG;IACH,QAAQ,CAAC,qBAAqB,QAAQ;IACtC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAChC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAS;gBAE9B,OAAO,GAAE,wBAA6B;IAMlD;;;;;;OAMG;IACH,oBAAoB,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO;IAK3C,MAAM,IAAI,OAAO,CAAC,WAAW,EAAE,CAAC;IA6BtC,MAAM,CAAC,IAAI,EAAE,UAAU,GAAG,SAAS;IAgBnC,MAAM,CAAC,cAAc,EAAE,MAAM,EAAE,IAAI,EAAE,UAAU,GAAG,SAAS;IAa3D;;;;;;;;;;;;;OAaG;IACH,UAAU,CAAC,IAAI,EAAE,UAAU,GAAG,SAAS;IAmBvC;;;;;;;;;;;;;;;;OAgBG;IACG,SAAS,CAAC,cAAc,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAShE,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,iBAAiB,EAAE,CAAC;CA+ClE;AAcD,wBAAgB,uBAAuB,CAAC,OAAO,CAAC,EAAE,wBAAwB,GAAG,cAAc,CAE1F"}

package/dist/core/adapters/claude-code.js

@@ -10,6 +10,7 @@ import { readFile, readdir, realpath, stat, open } from "node:fs/promises";
 import { homedir } from "node:os";
 import { basename, join } from "node:path";
 import { promisify } from "node:util";
+import { stripAnsi } from "../strip-ansi.js";
 /**
  * Minimum `claude` version the harness supports.
  *
@@ -295,6 +296,23 @@ function buildConfigArgs(opts) {
         args.push("--plugin-dir", opts.pluginDir);
     return args;
 }
+/**
+ * Claude Code's known blocking startup screens, matched against stripped-ANSI
+ * scrollback. Exported so the packaged smoke / e2e layers can pin the same
+ * patterns this adapter gates the ready-fallback on (see detectBlockingPrompt).
+ * Wording verified against Claude Code 2.1.x; a future rewording fails SAFE:
+ * an unmatched dialog only means the fallback flips `ready` and the injected
+ * prompt lands in a dialog the user is looking at anyway — the pre-fallback
+ * behaviour was the prompt silently vanishing after ten minutes.
+ */
+export const CLAUDE_BLOCKING_PROMPT_PATTERNS = [
+    // First-run / new-directory trust dialog.
+    /do\s+you\s+trust\s+the\s+files\s+in\s+this\s+(folder|directory)/i,
+    // First-run theme picker.
+    /choose\s+the\s+text\s+style/i,
+    // Signed-out login flow.
+    /select\s+login\s+method|sign\s+in\s+to\s+(use\s+)?claude/i,
+];
 export class ClaudeCodeAdapter {
     constructor(options = {}) {
         this.id = "claude-code";
@@ -303,14 +321,43 @@ export class ClaudeCodeAdapter {
          *  launch/resume path below, so a rehydration brief composed into that file
          *  needs no separate delivery. */
         this.systemPromptDelivery = "launch-flag";
+        /**
+         * See `HarnessAdapter.readyFallback`. The SessionStart hook stays the
+         * primary signal (isReadyEnough gives claude-code NO immediate scrollback
+         * shortcut); this only lets SessionManager's generously-timed fallback
+         * rescue a session whose hook chain is broken — on Windows the hook runs
+         * `node` through Claude's hook shell, and when that resolution fails the
+         * POST never fires, `ready` never flips, and the held first prompt was
+         * silently dropped.
+         */
+        this.readyFallback = "hook-timeout";
+        /**
+         * See `HarnessAdapter.assumesBracketedPaste`. Claude Code's Ink input layer
+         * enables mode 2004 in every interactive session — the macOS/Linux paste
+         * detection observing `ESC[?2004h` on real ptys is the in-repo evidence.
+         * Declared so Windows (where ConPTY hides that announcement) still paste-
+         * wraps multi-line prompts instead of submitting at the first newline.
+         */
+        this.assumesBracketedPaste = true;
         this.binary = options.binary ?? "claude";
         this.homeDir = options.homeDir ?? homedir();
         this.fullScanMaxBytes = options.fullScanMaxBytes ?? DEFAULT_FULL_SCAN_MAX_BYTES;
     }
+    /**
+     * See `HarnessAdapter.detectBlockingPrompt` and `readyFallback` above: this
+     * exists ONLY to gate the hook-timeout fallback (never type a stray Enter
+     * into an unanswered trust dialog) — it deliberately does NOT give
+     * claude-code Codex's immediate scrollback shortcut, because the hook is
+     * reliable wherever the hook chain itself works.
+     */
+    detectBlockingPrompt(scrollback) {
+        const cleaned = stripAnsi(scrollback);
+        return CLAUDE_BLOCKING_PROMPT_PATTERNS.some((pattern) => pattern.test(cleaned));
+    }
     async doctor() {
         let versionLine;
         try {
-            const { stdout } = await execFileAsync(this.binary, ["--version"], { timeout: 5000 });
+            const { stdout } = await execFileAsync(this.binary, ["--version"], { timeout: 5000, windowsHide: true });
             versionLine = stdout.trim();
         }
         catch {