@jinn-network/client 0.1.5 → 0.1.6-canary.107ea271

package/dist/harnesses/cost-estimates.js

@@ -0,0 +1,297 @@
+/**
+ * Per-task cost estimates for paid-API-key harnesses.
+ *
+ * Background — Issue #331 (Run-mode `feat`, P0 tier under release-feedback
+ * umbrella #328). The operator dashboard surfaces a harness/model selection
+ * at SolverNet-join time and again in Settings. Operators routing a paid
+ * API key (Anthropic, OpenAI, OpenRouter, Nous Portal) through the Hermes
+ * harness — or a "raw API key" Claude Code variant if we ever add one —
+ * have **no UI nudge** at join-time about per-task cost. The v0.1.6 dogfood
+ * surfaced the concrete worry: a first-run operator could pick Opus 4.7 +
+ * SWE-rebench v2 and burn $100s/hr before they figure out what Jinn does.
+ *
+ * This module captures the heuristic the SPA uses to render that estimate
+ * and to gate the Save & Join action when the estimate exceeds a
+ * configurable per-task threshold (default $1).
+ *
+ * Heuristic shape per the spec:
+ *   per-1k-token rate × typical task length, by model id.
+ *
+ * Subscription harnesses (Claude Code, Codex) are flagged via
+ * `subscriptionPath: true` on the harness; in that case the surface shows
+ * "Included in subscription, no per-task API cost" and **does not** trigger
+ * the confirmation gate, regardless of the model selected.
+ *
+ * To add a new model: append an entry to `MODEL_COST_TABLE`. The id is the
+ * exact `model` string persisted to `joinedSolverNets[<cid>].model`. To
+ * shape a new harness: append to `HARNESS_BILLING`. Keep the units
+ * consistent: token counts in tokens, rates in USD-per-1k-tokens.
+ *
+ * Units note: Anthropic + OpenAI publish prices per million tokens; we
+ * convert to per-1k-tokens here so the multiplication reads as
+ * `(tokens / 1000) * pricePer1k`. Avoids floating-point surprises when the
+ * dashboard renders cents.
+ *
+ * Pricing references captured at the time of this commit (see PR body):
+ *   - Anthropic Claude Opus 4.7: $15/M input, $75/M output (≈ $0.015 / 1k
+ *     input, $0.075 / 1k output). Typical SWE-rebench v2 task estimated at
+ *     ~50k input + 20k output → ~$2.25/task. Anthropic public pricing.
+ *   - Anthropic Claude Sonnet 4.6: $3/M input, $15/M output.
+ *   - OpenAI GPT-5.4: $1.25/M input, $10/M output (OpenAI public pricing).
+ *   - OpenAI GPT-5.4 Mini: $0.25/M input, $2/M output.
+ *
+ * These are heuristics. Provider-API reconciliation (actual usage) is
+ * deferred to the P1 follow-up tracked in #331.
+ */
+import { CLAUDE_CODE_HARNESS, CODEX_HARNESS, HERMES_AGENT_HARNESS, canonicalHarnessName, } from './names.js';
+/**
+ * Per-model cost entries. Keyed by the exact `model` id persisted to
+ * `joinedSolverNets[<cid>].model`. The dashboard model dropdown in
+ * `claudeModels.ts` is the source of truth for which ids appear here.
+ */
+export const MODEL_COST_TABLE = {
+    // ---------- Anthropic family (direct + via OpenRouter) ----------
+    'claude-opus-4-7': {
+        provider: 'anthropic',
+        inputPer1kTokens: 0.015,
+        outputPer1kTokens: 0.075,
+        typicalInputTokens: 50_000,
+        typicalOutputTokens: 20_000,
+    },
+    'claude-sonnet-4-6': {
+        provider: 'anthropic',
+        inputPer1kTokens: 0.003,
+        outputPer1kTokens: 0.015,
+        typicalInputTokens: 50_000,
+        typicalOutputTokens: 20_000,
+    },
+    'claude-haiku-4-5-20251001': {
+        provider: 'anthropic',
+        inputPer1kTokens: 0.001,
+        outputPer1kTokens: 0.005,
+        typicalInputTokens: 50_000,
+        typicalOutputTokens: 20_000,
+    },
+    // OpenRouter routing of the same families (Hermes harness uses these).
+    'anthropic/claude-opus-4.7': {
+        provider: 'openrouter',
+        inputPer1kTokens: 0.015,
+        outputPer1kTokens: 0.075,
+        typicalInputTokens: 50_000,
+        typicalOutputTokens: 20_000,
+    },
+    'anthropic/claude-sonnet-4.6': {
+        provider: 'openrouter',
+        inputPer1kTokens: 0.003,
+        outputPer1kTokens: 0.015,
+        typicalInputTokens: 50_000,
+        typicalOutputTokens: 20_000,
+    },
+    // ---------- OpenAI family ----------
+    'gpt-5.4': {
+        provider: 'openai',
+        inputPer1kTokens: 0.00125,
+        outputPer1kTokens: 0.01,
+        typicalInputTokens: 50_000,
+        typicalOutputTokens: 20_000,
+    },
+    'gpt-5.4-mini': {
+        provider: 'openai',
+        inputPer1kTokens: 0.00025,
+        outputPer1kTokens: 0.002,
+        typicalInputTokens: 50_000,
+        typicalOutputTokens: 20_000,
+    },
+    'gpt-5.5': {
+        provider: 'openai',
+        // Newer flagship; public pricing not confirmed at heuristic-capture
+        // time, so use Opus-4.7-class rates as a conservative upper bound
+        // until we get a verified figure.
+        inputPer1kTokens: 0.015,
+        outputPer1kTokens: 0.06,
+        typicalInputTokens: 50_000,
+        typicalOutputTokens: 20_000,
+    },
+    'gpt-5.3-codex': {
+        provider: 'openai',
+        inputPer1kTokens: 0.00125,
+        outputPer1kTokens: 0.01,
+        typicalInputTokens: 50_000,
+        typicalOutputTokens: 20_000,
+    },
+    'gpt-5.3-codex-spark': {
+        provider: 'openai',
+        inputPer1kTokens: 0.00125,
+        outputPer1kTokens: 0.01,
+        typicalInputTokens: 50_000,
+        typicalOutputTokens: 20_000,
+    },
+    // ---------- OpenRouter long-tail (Hermes) ----------
+    // These rates are coarse — OpenRouter's effective price depends on the
+    // route picked. We pick the published list-price upper bound so the
+    // estimate biases toward over-warning rather than under-warning.
+    'tencent/hy3-preview': {
+        provider: 'openrouter',
+        inputPer1kTokens: 0.003,
+        outputPer1kTokens: 0.015,
+        typicalInputTokens: 50_000,
+        typicalOutputTokens: 20_000,
+    },
+    'deepseek/deepseek-v4-pro': {
+        provider: 'openrouter',
+        inputPer1kTokens: 0.0014,
+        outputPer1kTokens: 0.0028,
+        typicalInputTokens: 50_000,
+        typicalOutputTokens: 20_000,
+    },
+    'deepseek/deepseek-v4-flash': {
+        provider: 'openrouter',
+        inputPer1kTokens: 0.0001,
+        outputPer1kTokens: 0.0004,
+        typicalInputTokens: 50_000,
+        typicalOutputTokens: 20_000,
+    },
+    'google/gemini-3.1-flash-lite': {
+        provider: 'openrouter',
+        inputPer1kTokens: 0.0001,
+        outputPer1kTokens: 0.0004,
+        typicalInputTokens: 50_000,
+        typicalOutputTokens: 20_000,
+    },
+    'moonshotai/kimi-k2.6': {
+        provider: 'openrouter',
+        inputPer1kTokens: 0.0006,
+        outputPer1kTokens: 0.0025,
+        typicalInputTokens: 50_000,
+        typicalOutputTokens: 20_000,
+    },
+    'openrouter/owl-alpha': {
+        provider: 'openrouter',
+        inputPer1kTokens: 0.002,
+        outputPer1kTokens: 0.008,
+        typicalInputTokens: 50_000,
+        typicalOutputTokens: 20_000,
+    },
+    'minimax/minimax-m2.7': {
+        provider: 'openrouter',
+        inputPer1kTokens: 0.0008,
+        outputPer1kTokens: 0.0032,
+        typicalInputTokens: 50_000,
+        typicalOutputTokens: 20_000,
+    },
+    'nousresearch/hermes-4-405b': {
+        provider: 'nous',
+        inputPer1kTokens: 0.0009,
+        outputPer1kTokens: 0.0009,
+        typicalInputTokens: 50_000,
+        typicalOutputTokens: 20_000,
+    },
+};
+/**
+ * Harness-level billing classification.
+ *
+ * `subscriptionPath: true` means the harness shells out to a
+ * subscription-billed CLI (Claude Code, Codex) and the operator does NOT
+ * incur per-task API charges — the cost surface is suppressed entirely
+ * and the confirmation gate is never triggered.
+ *
+ * `subscriptionPath: false` means the harness routes to a paid API key
+ * (Hermes via OpenRouter / Anthropic API / Nous Portal). The cost surface
+ * is shown and the gate fires above the configured threshold.
+ */
+export const HARNESS_BILLING = {
+    [CLAUDE_CODE_HARNESS]: { subscriptionPath: true },
+    [CODEX_HARNESS]: { subscriptionPath: true },
+    [HERMES_AGENT_HARNESS]: { subscriptionPath: false },
+};
+/** Default per-task USD threshold above which the confirmation gate fires. */
+export const DEFAULT_HIGH_COST_THRESHOLD_USD = 1;
+/**
+ * Compute the per-task cost estimate for a given model id. Returns `null`
+ * when the id has no entry in `MODEL_COST_TABLE` — callers should treat
+ * that as "unknown, don't surface a number" rather than rendering $0.
+ */
+export function estimateModelCost(modelId) {
+    const entry = MODEL_COST_TABLE[modelId];
+    if (!entry)
+        return null;
+    const inputUsd = (entry.typicalInputTokens / 1000) * entry.inputPer1kTokens;
+    const outputUsd = (entry.typicalOutputTokens / 1000) * entry.outputPer1kTokens;
+    return {
+        usd: inputUsd + outputUsd,
+        inputUsd,
+        outputUsd,
+        typicalInputTokens: entry.typicalInputTokens,
+        typicalOutputTokens: entry.typicalOutputTokens,
+        entry,
+    };
+}
+/**
+ * `true` when the harness routes through a paid API key. Subscription
+ * harnesses (Claude Code, Codex) return `false`; unknown harnesses
+ * conservatively return `true` so a misnamed harness doesn't silently
+ * skip the cost surface.
+ */
+export function harnessUsesPaidApiKey(harness) {
+    if (!harness)
+        return false;
+    const canonical = canonicalHarnessName(harness);
+    const billing = HARNESS_BILLING[canonical];
+    if (!billing)
+        return true;
+    return !billing.subscriptionPath;
+}
+/**
+ * Decide what the cost surface should render for a given harness + model
+ * combination, plus whether the confirmation gate fires.
+ *
+ * Defaults:
+ *   - threshold: $1 / task (see DEFAULT_HIGH_COST_THRESHOLD_USD).
+ *   - subscription harness → suppress surface + skip gate.
+ *   - unknown model on a paid harness → show estimate slot (caller may
+ *     render "estimate unavailable") but DO NOT trigger the gate.
+ */
+export function decideCostSurface(harness, modelId, thresholdUsd = DEFAULT_HIGH_COST_THRESHOLD_USD) {
+    if (!harnessUsesPaidApiKey(harness)) {
+        return {
+            showEstimate: false,
+            estimate: null,
+            requiresConfirmation: false,
+            suppressedReason: 'Included in subscription, no per-task API cost.',
+        };
+    }
+    const estimate = modelId ? estimateModelCost(modelId) : null;
+    const modelOverridesSubscription = estimate?.entry.subscriptionPath === true;
+    if (modelOverridesSubscription) {
+        return {
+            showEstimate: false,
+            estimate: null,
+            requiresConfirmation: false,
+            suppressedReason: 'Included in subscription, no per-task API cost.',
+        };
+    }
+    return {
+        showEstimate: true,
+        estimate,
+        requiresConfirmation: estimate !== null && estimate.usd > thresholdUsd,
+        suppressedReason: null,
+    };
+}
+/**
+ * Format a USD amount for compact display in the dashboard. Picks the
+ * smallest fraction count that still distinguishes the value from $0.
+ */
+export function formatUsd(amount) {
+    if (!Number.isFinite(amount))
+        return '—';
+    if (amount === 0)
+        return '$0';
+    if (amount < 0.01)
+        return `<$0.01`;
+    if (amount < 1)
+        return `$${amount.toFixed(2)}`;
+    if (amount < 10)
+        return `$${amount.toFixed(2)}`;
+    return `$${amount.toFixed(2)}`;
+}
+//# sourceMappingURL=cost-estimates.js.map

package/dist/harnesses/cost-estimates.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cost-estimates.js","sourceRoot":"","sources":["../../src/harnesses/cost-estimates.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;AAEH,OAAO,EACL,mBAAmB,EACnB,aAAa,EACb,oBAAoB,EACpB,oBAAoB,GACrB,MAAM,YAAY,CAAC;AAwBpB;;;;GAIG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAA6C;IACxE,mEAAmE;IACnE,iBAAiB,EAAE;QACjB,QAAQ,EAAE,WAAW;QACrB,gBAAgB,EAAE,KAAK;QACvB,iBAAiB,EAAE,KAAK;QACxB,kBAAkB,EAAE,MAAM;QAC1B,mBAAmB,EAAE,MAAM;KAC5B;IACD,mBAAmB,EAAE;QACnB,QAAQ,EAAE,WAAW;QACrB,gBAAgB,EAAE,KAAK;QACvB,iBAAiB,EAAE,KAAK;QACxB,kBAAkB,EAAE,MAAM;QAC1B,mBAAmB,EAAE,MAAM;KAC5B;IACD,2BAA2B,EAAE;QAC3B,QAAQ,EAAE,WAAW;QACrB,gBAAgB,EAAE,KAAK;QACvB,iBAAiB,EAAE,KAAK;QACxB,kBAAkB,EAAE,MAAM;QAC1B,mBAAmB,EAAE,MAAM;KAC5B;IACD,uEAAuE;IACvE,2BAA2B,EAAE;QAC3B,QAAQ,EAAE,YAAY;QACtB,gBAAgB,EAAE,KAAK;QACvB,iBAAiB,EAAE,KAAK;QACxB,kBAAkB,EAAE,MAAM;QAC1B,mBAAmB,EAAE,MAAM;KAC5B;IACD,6BAA6B,EAAE;QAC7B,QAAQ,EAAE,YAAY;QACtB,gBAAgB,EAAE,KAAK;QACvB,iBAAiB,EAAE,KAAK;QACxB,kBAAkB,EAAE,MAAM;QAC1B,mBAAmB,EAAE,MAAM;KAC5B;IAED,sCAAsC;IACtC,SAAS,EAAE;QACT,QAAQ,EAAE,QAAQ;QAClB,gBAAgB,EAAE,OAAO;QACzB,iBAAiB,EAAE,IAAI;QACvB,kBAAkB,EAAE,MAAM;QAC1B,mBAAmB,EAAE,MAAM;KAC5B;IACD,cAAc,EAAE;QACd,QAAQ,EAAE,QAAQ;QAClB,gBAAgB,EAAE,OAAO;QACzB,iBAAiB,EAAE,KAAK;QACxB,kBAAkB,EAAE,MAAM;QAC1B,mBAAmB,EAAE,MAAM;KAC5B;IACD,SAAS,EAAE;QACT,QAAQ,EAAE,QAAQ;QAClB,oEAAoE;QACpE,kEAAkE;QAClE,kCAAkC;QAClC,gBAAgB,EAAE,KAAK;QACvB,iBAAiB,EAAE,IAAI;QACvB,kBAAkB,EAAE,MAAM;QAC1B,mBAAmB,EAAE,MAAM;KAC5B;IACD,eAAe,EAAE;QACf,QAAQ,EAAE,QAAQ;QAClB,gBAAgB,EAAE,OAAO;QACzB,iBAAiB,EAAE,IAAI;QACvB,kBAAkB,EAAE,MAAM;QAC1B,mBAAmB,EAAE,MAAM;KAC5B;IACD,qBAAqB,EAAE;QACrB,QAAQ,EAAE,QAAQ;QAClB,gBAAgB,EAAE,OAAO;QACzB,iBAAiB,EAAE,IAAI;QACvB,kBAAkB,EAAE,MAAM;QAC1B,mBAAmB,EAAE,MAAM;KAC5B;IAED,sDAAsD;IACtD,uEAAuE;IACvE,oEAAoE;IACpE,iEAAiE;IACjE,qBAAqB,EAAE;QACrB,QAAQ,EAAE,YAAY;QACtB,gBAAgB,EAAE,KAAK;QACvB,iBAAiB,EAAE,KAAK;QACxB,kBAAkB,EAAE,MAAM;QAC1B,mBAAmB,EAAE,MAAM;KAC5B;IACD,0BAA0B,EAAE;QAC1B,QAAQ,EAAE,YAAY;QACtB,gBAAgB,EAAE,MAAM;QACxB,iBAAiB,EAAE,MAAM;QACzB,kBAAkB,EAAE,MAAM;QAC1B,mBAAmB,EAAE,MAAM;KAC5B;IACD,4BAA4B,EAAE;QAC5B,QAAQ,EAAE,YAAY;QACtB,gBAAgB,EAAE,MAAM;QACxB,iBAAiB,EAAE,MAAM;QACzB,kBAAkB,EAAE,MAAM;QAC1B,mBAAmB,EAAE,MAAM;KAC5B;IACD,8BAA8B,EAAE;QAC9B,QAAQ,EAAE,YAAY;QACtB,gBAAgB,EAAE,MAAM;QACxB,iBAAiB,EAAE,MAAM;QACzB,kBAAkB,EAAE,MAAM;QAC1B,mBAAmB,EAAE,MAAM;KAC5B;IACD,sBAAsB,EAAE;QACtB,QAAQ,EAAE,YAAY;QACtB,gBAAgB,EAAE,MAAM;QACxB,iBAAiB,EAAE,MAAM;QACzB,kBAAkB,EAAE,MAAM;QAC1B,mBAAmB,EAAE,MAAM;KAC5B;IACD,sBAAsB,EAAE;QACtB,QAAQ,EAAE,YAAY;QACtB,gBAAgB,EAAE,KAAK;QACvB,iBAAiB,EAAE,KAAK;QACxB,kBAAkB,EAAE,MAAM;QAC1B,mBAAmB,EAAE,MAAM;KAC5B;IACD,sBAAsB,EAAE;QACtB,QAAQ,EAAE,YAAY;QACtB,gBAAgB,EAAE,MAAM;QACxB,iBAAiB,EAAE,MAAM;QACzB,kBAAkB,EAAE,MAAM;QAC1B,mBAAmB,EAAE,MAAM;KAC5B;IACD,4BAA4B,EAAE;QAC5B,QAAQ,EAAE,MAAM;QAChB,gBAAgB,EAAE,MAAM;QACxB,iBAAiB,EAAE,MAAM;QACzB,kBAAkB,EAAE,MAAM;QAC1B,mBAAmB,EAAE,MAAM;KAC5B;CACF,CAAC;AAEF;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,MAAM,eAAe,GAA4D;IACtF,CAAC,mBAAmB,CAAC,EAAE,EAAE,gBAAgB,EAAE,IAAI,EAAE;IACjD,CAAC,aAAa,CAAC,EAAE,EAAE,gBAAgB,EAAE,IAAI,EAAE;IAC3C,CAAC,oBAAoB,CAAC,EAAE,EAAE,gBAAgB,EAAE,KAAK,EAAE;CACpD,CAAC;AAEF,8EAA8E;AAC9E,MAAM,CAAC,MAAM,+BAA+B,GAAG,CAAC,CAAC;AAiBjD;;;;GAIG;AACH,MAAM,UAAU,iBAAiB,CAAC,OAAe;IAC/C,MAAM,KAAK,GAAG,gBAAgB,CAAC,OAAO,CAAC,CAAC;IACxC,IAAI,CAAC,KAAK;QAAE,OAAO,IAAI,CAAC;IACxB,MAAM,QAAQ,GAAG,CAAC,KAAK,CAAC,kBAAkB,GAAG,IAAI,CAAC,GAAG,KAAK,CAAC,gBAAgB,CAAC;IAC5E,MAAM,SAAS,GAAG,CAAC,KAAK,CAAC,mBAAmB,GAAG,IAAI,CAAC,GAAG,KAAK,CAAC,iBAAiB,CAAC;IAC/E,OAAO;QACL,GAAG,EAAE,QAAQ,GAAG,SAAS;QACzB,QAAQ;QACR,SAAS;QACT,kBAAkB,EAAE,KAAK,CAAC,kBAAkB;QAC5C,mBAAmB,EAAE,KAAK,CAAC,mBAAmB;QAC9C,KAAK;KACN,CAAC;AACJ,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,qBAAqB,CAAC,OAA2B;IAC/D,IAAI,CAAC,OAAO;QAAE,OAAO,KAAK,CAAC;IAC3B,MAAM,SAAS,GAAG,oBAAoB,CAAC,OAAO,CAAC,CAAC;IAChD,MAAM,OAAO,GAAG,eAAe,CAAC,SAAS,CAAC,CAAC;IAC3C,IAAI,CAAC,OAAO;QAAE,OAAO,IAAI,CAAC;IAC1B,OAAO,CAAC,OAAO,CAAC,gBAAgB,CAAC;AACnC,CAAC;AAiBD;;;;;;;;;GASG;AACH,MAAM,UAAU,iBAAiB,CAC/B,OAA2B,EAC3B,OAA2B,EAC3B,eAAuB,+BAA+B;IAEtD,IAAI,CAAC,qBAAqB,CAAC,OAAO,CAAC,EAAE,CAAC;QACpC,OAAO;YACL,YAAY,EAAE,KAAK;YACnB,QAAQ,EAAE,IAAI;YACd,oBAAoB,EAAE,KAAK;YAC3B,gBAAgB,EAAE,iDAAiD;SACpE,CAAC;IACJ,CAAC;IACD,MAAM,QAAQ,GAAG,OAAO,CAAC,CAAC,CAAC,iBAAiB,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;IAC7D,MAAM,0BAA0B,GAC9B,QAAQ,EAAE,KAAK,CAAC,gBAAgB,KAAK,IAAI,CAAC;IAC5C,IAAI,0BAA0B,EAAE,CAAC;QAC/B,OAAO;YACL,YAAY,EAAE,KAAK;YACnB,QAAQ,EAAE,IAAI;YACd,oBAAoB,EAAE,KAAK;YAC3B,gBAAgB,EAAE,iDAAiD;SACpE,CAAC;IACJ,CAAC;IACD,OAAO;QACL,YAAY,EAAE,IAAI;QAClB,QAAQ;QACR,oBAAoB,EAAE,QAAQ,KAAK,IAAI,IAAI,QAAQ,CAAC,GAAG,GAAG,YAAY;QACtE,gBAAgB,EAAE,IAAI;KACvB,CAAC;AACJ,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,SAAS,CAAC,MAAc;IACtC,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC;QAAE,OAAO,GAAG,CAAC;IACzC,IAAI,MAAM,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IAC9B,IAAI,MAAM,GAAG,IAAI;QAAE,OAAO,QAAQ,CAAC;IACnC,IAAI,MAAM,GAAG,CAAC;QAAE,OAAO,IAAI,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,CAAC;IAC/C,IAAI,MAAM,GAAG,EAAE;QAAE,OAAO,IAAI,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,CAAC;IAChD,OAAO,IAAI,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,CAAC;AACjC,CAAC"}

package/dist/harnesses/engine/engine.d.ts

@@ -8,6 +8,7 @@
  */
 import { TaskRunPersistence, type PersistedTaskRun, type PersistedTaskRunInput } from './persistence.js';
 import type { Store } from '../../store/store.js';
+import { type ReapWorkDirsReport } from './work-dir-reaper.js';
 import { type PackagingDeps } from './packaging.js';
 import { type EnvelopeAssemblyDeps } from './envelope-assembly.js';
 import { type DeliveryDeps } from './delivery.js';
@@ -240,6 +241,28 @@ export interface TaskEngineOptions {
      * Spec: docs/superpowers/specs/2026-05-06-agent-harness-solvernet-design.md §6.3
      */
     harnessMode?: 'train' | 'frozen';
+    /**
+     * Working-directory reaper tuning (issue #320). Each task run provisions a
+     * heavy scratch directory under `paths.workingDirRoot`; without cleanup an
+     * operator accumulates hundreds of dirs / tens of GB. The engine reaps a
+     * task's directory once it reaches a terminal state (COMPLETE / FAILED),
+     * and periodically sweeps the root for crash-orphaned dirs.
+     *
+     * Optional — sensible defaults apply when absent.
+     */
+    workDirReaper?: {
+        /**
+         * Age above which a directory with no DB row (orphaned by a crash or an
+         * older daemon) is removed. Defaults to {@link DEFAULT_ORPHAN_MAX_AGE_MS}
+         * (24h). Set to a large value to keep orphans for forensic inspection.
+         */
+        orphanMaxAgeMs?: number;
+        /**
+         * Disable the reaper entirely (escape hatch for debugging a stuck task).
+         * Defaults to false — the reaper runs.
+         */
+        disabled?: boolean;
+    };
 }
 /** Per-task outcome from a recovery pass. */
 export interface RecoveryReport {
@@ -289,6 +312,11 @@ export declare class TaskEngine {
     private stopped;
     private stopResolve?;
     private readonly stopPromise;
+    /** Working-dir reaper tuning (issue #320). */
+    protected readonly workDirReaperOpts: {
+        orphanMaxAgeMs: number;
+        disabled: boolean;
+    };
     constructor(opts: TaskEngineOptions);
     /**
      * Called when an task is observed from an on-chain event.
@@ -320,6 +348,18 @@ export declare class TaskEngine {
      * Errors from individual tasks are logged but do not stop the loop.
      */
     tick(options?: TickOptions): Promise<void>;
+    /**
+     * Reap on-disk per-task working directories (issue #320).
+     *
+     * Removes the scratch directory of every task in a terminal state
+     * (COMPLETE / FAILED) and any crash-orphaned directory older than the
+     * configured max age. In-flight tasks are never touched. Safe to call at
+     * any time; never throws (filesystem errors are collected into the report).
+     *
+     * Called automatically every `tick()`; also exposed for the one-shot
+     * cleanup script and for tests.
+     */
+    reapWorkDirsNow(): ReapWorkDirsReport;
     /**
      * Drive `tick()` on a fixed interval until `stop()` is called.
      * Errors thrown by tick() itself are logged and do not stop the loop.

package/dist/harnesses/engine/engine.js

@@ -11,6 +11,7 @@ import { createHash, randomUUID } from 'node:crypto';
 import { keccak256, toBytes } from 'viem';
 import { TaskRunPersistence } from './persistence.js';
 import { TaskRunState, MissingEvidenceHashError } from './state.js';
+import { reapWorkDirs, DEFAULT_ORPHAN_MAX_AGE_MS, } from './work-dir-reaper.js';
 import { provisionWorkingDir, provisionImplStateDir, walkArtifacts, uploadArtifacts, } from './packaging.js';
 import { DONATION_ARTIFACT_ENCODING } from './artifact-scrub.js';
 import { assembleAndSignEnvelope, } from './envelope-assembly.js';
@@ -109,6 +110,8 @@ export class TaskEngine {
     stopPromise = new Promise((resolve) => {
         this.stopResolve = resolve;
     });
+    /** Working-dir reaper tuning (issue #320). */
+    workDirReaperOpts;
     constructor(opts) {
         this.persistence = new TaskRunPersistence(opts.store.db);
         this.store = opts.store;
@@ -124,6 +127,10 @@ export class TaskEngine {
         this.reputationFeedback = opts.reputationFeedback;
         this.operatorConfig = opts.operatorConfig;
         this.harnessMode = opts.harnessMode ?? 'train';
+        this.workDirReaperOpts = {
+            orphanMaxAgeMs: opts.workDirReaper?.orphanMaxAgeMs ?? DEFAULT_ORPHAN_MAX_AGE_MS,
+            disabled: opts.workDirReaper?.disabled ?? false,
+        };
     }
     // ── Public API ──────────────────────────────────────────────────────────────
     /**
@@ -186,6 +193,10 @@ export class TaskEngine {
                 void processPromise.then((report) => this.logProcessReport('tick', report));
             }
         }
+        // Reap the working directories of tasks that have reached a terminal
+        // state. Cheap (one readdir + a few rmSync) and idempotent, so it runs
+        // every tick — there is no separate reaper loop to keep alive or crash.
+        this.reapWorkDirsNow();
         if (!wait)
             return;
         const reports = await Promise.all(scheduled);
@@ -193,6 +204,41 @@ export class TaskEngine {
             this.logProcessReport('tick', report);
         }
     }
+    /**
+     * Reap on-disk per-task working directories (issue #320).
+     *
+     * Removes the scratch directory of every task in a terminal state
+     * (COMPLETE / FAILED) and any crash-orphaned directory older than the
+     * configured max age. In-flight tasks are never touched. Safe to call at
+     * any time; never throws (filesystem errors are collected into the report).
+     *
+     * Called automatically every `tick()`; also exposed for the one-shot
+     * cleanup script and for tests.
+     */
+    reapWorkDirsNow() {
+        const empty = { removed: [], protected: [], scanned: 0, errors: [] };
+        if (this.workDirReaperOpts.disabled)
+            return empty;
+        // Read the in-flight / terminal partition as a single atomic snapshot.
+        // Two separate queries would leave a TOCTOU window: a task transitioning
+        // DELIVERING → COMPLETE between the reads could be classified terminal and
+        // have its working directory deleted while deliver() still needs it.
+        const { terminal: terminalRequestIds, inFlight: inFlightRequestIds } = this.persistence.getReaperPartition();
+        const report = reapWorkDirs({
+            workingDirRoot: this.paths.workingDirRoot,
+            terminalRequestIds,
+            inFlightRequestIds,
+            orphanMaxAgeMs: this.workDirReaperOpts.orphanMaxAgeMs,
+        });
+        if (report.removed.length > 0) {
+            console.log(`[harness-engine] work-dir reaper removed ${report.removed.length} ` +
+                `terminal/orphaned task dir(s) under ${this.paths.workingDirRoot}`);
+        }
+        for (const e of report.errors) {
+            console.warn(`[harness-engine] work-dir reaper failed to remove ${e.requestId}: ${e.error}`);
+        }
+        return report;
+    }
     /**
      * Drive `tick()` on a fixed interval until `stop()` is called.
      * Errors thrown by tick() itself are logged and do not stop the loop.
@@ -350,6 +396,7 @@ export class TaskEngine {
         }
         if (current.state === TaskRunState.DISCOVERED) {
             this.persistence.transition(task.requestId, TaskRunState.CLAIMED);
+            console.log(`[harness-engine] ${task.requestId} DISCOVERED → CLAIMED`);
         }
         else {
             console.log(`[harness-engine] ${task.requestId}: claim completed but state is already ${current.state}; skipping CLAIMED transition`);
@@ -818,6 +865,18 @@ export class TaskEngine {
                 console.warn(`[harness-engine] ${task.requestId}: failed to hydrate solutionOutputsJson: ${err instanceof Error ? err.message : err}`);
             }
         }
+        // jinn-mono-4tfq: SkippableError caught in RUNNING leaves a skip-marker
+        // Solution with no payload; short-circuit before envelope assembly.
+        // Runs BEFORE the deps guard — skipping needs nothing wired.
+        const earlyImplOutput = this.solutionOutputs.get(task.requestId);
+        const gatingClaim = earlyImplOutput?.gating;
+        if (gatingClaim?.['skipped'] === true) {
+            const reason = String(gatingClaim['reason'] ?? 'unknown');
+            const detail = String(earlyImplOutput?.informational?.['detail'] ?? '');
+            console.log(`[harness-engine] ${task.requestId}: PACKAGING short-circuited — impl was skipped (${reason})${detail ? `: ${detail}` : ''}`);
+            this.persistence.markFailed(task.requestId, `impl skipped: ${reason}${detail ? ` — ${detail}` : ''}`);
+            return;
+        }
         if (!this.packagingDeps || !this.envelopeDeps) {
             throw new NotImplementedError('pack');
         }
@@ -911,9 +970,9 @@ export class TaskEngine {
         // Record payload so validatePayload does not reject the output.
         const solverType = task.solverType ?? 'legacy.v0';
         // Derive role from Task.role. Evaluator tasks produce 'verdict' envelopes;
-        // all other tasks produce 'restoration' envelopes.
+        // all other tasks produce 'solution' envelopes.
         const isEvaluation = task.taskRole === 'evaluation';
-        const role = isEvaluation ? 'verdict' : 'restoration';
+        const role = isEvaluation ? 'verdict' : 'solution';
         let envelopePayload;
         if (isEvaluation) {
             // ── Verdict envelope payload ──────────────────────────────────────────────
@@ -926,7 +985,7 @@ export class TaskEngine {
             // with a wrong shape — validatePayload will catch schema mismatches.
             //
             // verificationOfRestoration: stubbed — Plan D will connect the real SDK.
-            // restorationEnvelope.sha256: placeholder — Plan D wires real sha256 derivation.
+            // solutionEnvelope.sha256: placeholder — Plan D wires real sha256 derivation.
             const verdictPayload = implOutput?.verdictPayload;
             if (!verdictPayload) {
                 throw new Error(`pack: evaluator impl for ${task.requestId} did not produce verdictPayload on Solution; ` +
@@ -1471,13 +1530,15 @@ export class TaskEngine {
      * throws, the task is marked FAILED with the error message.
      */
     async _runTransition(task, fn) {
-        const oldState = task.state;
+        // Each transition method (claim, takePreSnapshot, runImpl, pack, deliver)
+        // logs its own domain-specific line on success (e.g. with manifestCid,
+        // deliveryTx, impl name). We deliberately don't emit a generic
+        // `oldState → newState` line here: doing so produced duplicate
+        // transition lines in the operator log (jinn-mono-kzan). On failure,
+        // the catch below marks the task FAILED and rethrows so the caller can
+        // surface the error.
         try {
             await fn();
-            const updated = this.persistence.getByRequestId(task.requestId);
-            if (updated && updated.state !== oldState) {
-                console.log(`[harness-engine] ${task.requestId} ${oldState} → ${updated.state}`);
-            }
         }
         catch (err) {
             const reason = err instanceof Error ? err.message : String(err);