codehere 0.5.0-alpha.5 → 0.6.0-alpha.1

package/dist/infrastructure/hooks/pre-prompt-scan.js

@@ -0,0 +1,122 @@
+/**
+ * Pre-prompt safety scan — cross-vendor parity, task #110.
+ *
+ * The substrate the FAQ landing claims for v0.5.x → v0.6: "per-tool
+ * blocking parity for Codex / Aider / OpenCode / Gemini." Today, only
+ * Claude Code has a per-tool PreToolUse hook. The other 4 adapters
+ * spawn raw — every Bash/Edit they make goes unscanned.
+ *
+ * Closing that gap fully needs per-adapter pre-tool intercepts (huge
+ * scope per-adapter — different IPC + lifecycle for each CLI). This
+ * module ships the FIRST cross-vendor slice: scan the user's PROMPT
+ * before spawn. Catches the prompt-side leaks (API key in prompt,
+ * injection-pattern poisoning, credential paste) for ALL 5 adapters
+ * with one piece of code.
+ *
+ * Posture follows getHookMode():
+ *   block    → high+ severity findings refuse spawn (throw)
+ *   advisory → findings logged + warning event, spawn proceeds
+ *   log-only → findings logged, spawn proceeds, no warning
+ *   off      → no scan, spawn proceeds
+ *
+ * Every scan writes one audit-log entry with synthetic toolName
+ * 'pre_prompt' so the existing /history feed + hash chain pick it up
+ * without surface changes.
+ */
+import { scanPayload, calculateRiskScore, appendAuditLog, } from './claude-sdk-hook.js';
+import { getHookMode } from './hook-mode.js';
+import { filterAllowed } from '../security/permissions-config.js';
+/**
+ * Scan a user prompt before spawn. Always writes one audit-log entry.
+ * Returns allowed=false ONLY when mode === 'block' AND there's a
+ * high-or-critical finding. Other modes always allow but still log.
+ */
+export function scanPromptBeforeSpawn(input) {
+    const rawFindings = scanPayload(input.prompt);
+    // P18 slice 1 — filter against the cwd's permissions.yaml allow-list.
+    // Allow-listed findings are dropped from the BLOCK calculation but
+    // still recorded in the audit-log allowed-list field so a forensic
+    // reviewer can see what was suppressed and why.
+    const { surviving, allowed } = input.cwd
+        ? filterAllowed(rawFindings, input.cwd)
+        : { surviving: rawFindings, allowed: [] };
+    const findings = surviving;
+    const riskScore = calculateRiskScore(findings);
+    const mode = (() => {
+        try {
+            return getHookMode();
+        }
+        catch {
+            return 'off';
+        }
+    })();
+    // Severity gate: only critical/high findings can refuse a spawn.
+    // Medium/low findings get logged but never block — they're flagged
+    // for visibility, not enforcement. Matches the per-tool hook's
+    // existing severity-to-action policy.
+    const hardFindings = findings.filter((f) => f.severity === 'critical' || f.severity === 'high');
+    const wouldBlock = hardFindings.length > 0;
+    const blocked = mode === 'block' && wouldBlock;
+    // Audit entry — written for every scan, regardless of mode. Synthetic
+    // toolName 'pre_prompt' lets /history filter chips group these
+    // separately from per-tool entries (existing chip filters on tool).
+    const entry = {
+        timestamp: new Date().toISOString(),
+        sessionId: input.sessionId,
+        toolName: 'pre_prompt',
+        // Truncate the prompt for the audit record — full prompts can be
+        // 10K+ chars and we don't want the audit log to balloon.
+        toolInput: JSON.stringify({
+            agent: input.agent,
+            prompt: input.prompt.length > 500 ? input.prompt.slice(0, 500) + '…' : input.prompt,
+            cwd: input.cwd ?? null,
+            promptLength: input.prompt.length,
+            // P18 slice 1 — record what got allow-listed for forensic audit.
+            // Empty array when no permissions.yaml exists in the cwd.
+            ...(allowed.length > 0
+                ? {
+                    allowedByPermissions: allowed.map((a) => ({
+                        category: a.finding.category,
+                        matched: a.finding.matched,
+                        reason: a.entry.reason ?? '(no reason given)',
+                    })),
+                }
+                : {}),
+        }),
+        riskScore,
+        blocked,
+        findings: findings.length,
+        criticalFindings: findings.filter((f) => f.severity === 'critical').length,
+        // Mode-driven override marker so the audit reader knows WHY a
+        // would-block finding wasn't enforced. Reuses the existing
+        // OverrideReason 'log_only_mode' for log-only AND advisory + off
+        // (all three skip the block; 'log_only_mode' is the closest
+        // shared semantic — the entry's mode field can be added as a new
+        // OverrideReason later without breaking the audit chain).
+        ...(wouldBlock && !blocked ? { overrideReason: 'log_only_mode' } : {}),
+    };
+    try {
+        appendAuditLog(entry);
+    }
+    catch {
+        // Audit-write failure should NOT itself block a spawn — that would
+        // be a denial-of-service vector (fill the log dir → no spawns).
+        // The audit infra has its own failure-mode logging.
+    }
+    // Compose a block reason from the worst findings. Used by the
+    // session-manager to throw an actionable error.
+    let blockReason = '';
+    if (blocked) {
+        const top = hardFindings.slice(0, 3);
+        const summary = top.map((f) => `[${f.severity}] ${f.description}`).join('; ');
+        blockReason = `pre-prompt scan blocked: ${summary}`;
+    }
+    return {
+        allowed: !blocked,
+        blocked,
+        riskScore,
+        findings,
+        blockReason,
+    };
+}
+//# sourceMappingURL=pre-prompt-scan.js.map

package/dist/infrastructure/orchestration/aider-adapter.js

@@ -17,6 +17,7 @@ import { EventEmitter } from 'events';
 import { randomUUID } from 'crypto';
 import { ProgressAggregator } from './progress-aggregator.js';
 import { applyMemoryPrefix } from './memory-injector.js';
+import { mirrorToolCallToAudit } from '../hooks/mirror-tool-call-to-audit.js';
 import { snapshotCwd, extractArtifacts } from './artifacts-extractor.js';
 const HEADLESS_FLAGS = [
     '--yes-always', // auto-accept all file-edit confirmations
@@ -99,6 +100,32 @@ export function spawnAider(prompt, options = {}) {
         if (event.type === 'stdout' && event.data?.line) {
             const line = String(event.data.line);
             textAccum += line + '\n';
+            // #110 slice 3 — mirror aider tool calls to the audit log. Match
+            // the same stdout patterns the aggregator parses (per
+            // learning_aider.md): "Running <cmd>" → Bash, "Applied edit to
+            // <path>" → Edit, "Creating empty file <path>" → Write.
+            // Strip ANSI as defense-in-depth (HEADLESS_FLAGS already includes
+            // --no-pretty but extraArgs could override).
+            const stripAnsi = (s) => s.replace(/\[[0-9;]*m/g, '');
+            const clean = stripAnsi(line).trim();
+            let toolName = '';
+            let input = '';
+            let mirrorMatch;
+            if ((mirrorMatch = clean.match(/^Running\s+(.+)$/))) {
+                toolName = 'Bash';
+                input = mirrorMatch[1];
+            }
+            else if ((mirrorMatch = clean.match(/^Applied edit to\s+(.+)$/))) {
+                toolName = 'Edit';
+                input = mirrorMatch[1];
+            }
+            else if ((mirrorMatch = clean.match(/^Creating empty file\s+(.+)$/))) {
+                toolName = 'Write';
+                input = mirrorMatch[1];
+            }
+            if (toolName && input) {
+                mirrorToolCallToAudit({ sessionId, agent: 'aider', toolName, toolInput: input, cwd });
+            }
             // Aider emits a cost summary like:
             //   "Tokens: 1.2k sent, 412 received. Cost: $0.01 request, $0.01 session."
             const m = line.match(/Tokens:\s*([\d.]+)([kM]?)\s*sent,\s*([\d.]+)([kM]?)\s*received/i);
@@ -330,6 +357,7 @@ export function spawnAider(prompt, options = {}) {
 export const AiderAdapter = {
     id: 'aider',
     label: 'Aider',
+    description: 'Best when you already know which file to change and what to change in it. Tight, focused edits — no plan-then-explore phase.',
     processPattern: /(?:^|\/)aider(?:\s|$)/,
     isInstalled() {
         try {

package/dist/infrastructure/orchestration/artifacts-extractor.js

@@ -9,11 +9,81 @@
  *
  * Agent-agnostic on purpose. Both Claude and Codex mutate the filesystem;
  * git tells the truth regardless of which tool did the write.
+ *
+ * v0.6.x: dirty-baseline subtraction. Without it, files the user had
+ * uncommitted at spawn time would falsely appear in artifacts even though
+ * the agent never touched them — git diff vs spawn-HEAD includes EVERYTHING
+ * dirty in the working tree, not just what changed during the session.
+ * Now snapshotCwd captures `git status --porcelain` + per-file mtime/size at
+ * spawn time. extractArtifacts filters out files whose stat is unchanged
+ * since spawn — they were dirty before, not by this session. Files that were
+ * dirty at spawn AND further modified during the session still appear.
+ *
+ * Limitation: cannot distinguish concurrent human writes from agent writes
+ * during the session window. True PID-level attribution would require
+ * fanotify/audit subsystem. The dirty-baseline filter eliminates the most
+ * common false-positive (pre-existing uncommitted work) without that.
  */
 import { execFileSync } from 'child_process';
 import { existsSync, readFileSync, statSync } from 'fs';
 import { join, isAbsolute } from 'path';
 import { scoreFile } from '../security/trust-scorer.js';
+/** Capture mtime + size for a single path. Returns null if stat fails. */
+function statBaseline(fullPath) {
+    try {
+        const st = statSync(fullPath);
+        return { mtimeMs: st.mtimeMs, size: st.size };
+    }
+    catch {
+        return null;
+    }
+}
+/** Read `git status --porcelain` and stat every dirty path. Best-effort.
+ *  Paths are git-relative (i.e. relative to repoRoot, not cwd). */
+function captureDirtyBaseline(cwd, repoRoot) {
+    const baseline = new Map();
+    try {
+        const out = execFileSync('git', ['status', '--porcelain', '-z'], {
+            cwd,
+            encoding: 'utf-8',
+            timeout: 5000,
+            stdio: ['ignore', 'pipe', 'ignore'],
+        });
+        // Porcelain -z separates entries by NUL. First two chars are status, then space, then path.
+        // Renames have an extra NUL-separated old path which we don't need here.
+        for (const entry of out.split('\0')) {
+            if (!entry)
+                continue;
+            // Strip the 2-char status prefix + 1 separator (3 chars total)
+            const path = entry.slice(3);
+            if (!path)
+                continue;
+            const full = isAbsolute(path) ? path : join(repoRoot, path);
+            const b = statBaseline(full);
+            if (b)
+                baseline.set(path, b);
+        }
+    }
+    catch {
+        /* best-effort — empty baseline means no filtering, status-quo behavior */
+    }
+    return baseline;
+}
+/** Get repo root via `git rev-parse --show-toplevel`. Returns null if not in a repo. */
+function getRepoRoot(cwd) {
+    try {
+        const out = execFileSync('git', ['rev-parse', '--show-toplevel'], {
+            cwd,
+            encoding: 'utf-8',
+            timeout: 2000,
+            stdio: ['ignore', 'pipe', 'ignore'],
+        }).trim();
+        return out.length > 0 ? out : null;
+    }
+    catch {
+        return null;
+    }
+}
 /** Take a baseline so Layer 3 can diff against it on exit. Cheap; ~5ms. */
 export function snapshotCwd(cwd) {
     const spawnedAtMs = Date.now();
@@ -24,10 +94,26 @@ export function snapshotCwd(cwd) {
             timeout: 2000,
             stdio: ['ignore', 'pipe', 'ignore'],
         }).trim();
-        return { cwd, head: out, isGitRepo: out.length > 0, spawnedAtMs };
+        const isGitRepo = out.length > 0;
+        const repoRoot = isGitRepo ? (getRepoRoot(cwd) ?? cwd) : cwd;
+        return {
+            cwd,
+            head: out,
+            isGitRepo,
+            spawnedAtMs,
+            repoRoot,
+            dirtyBaseline: isGitRepo ? captureDirtyBaseline(cwd, repoRoot) : new Map(),
+        };
     }
     catch {
-        return { cwd, head: null, isGitRepo: false, spawnedAtMs };
+        return {
+            cwd,
+            head: null,
+            isGitRepo: false,
+            spawnedAtMs,
+            repoRoot: cwd,
+            dirtyBaseline: new Map(),
+        };
     }
 }
 /** Collect {path, +, -} from git diff (numstat) + untracked files (wc -l). */
@@ -69,9 +155,10 @@ function changedFiles(snap) {
         for (const rel of untracked.split('\n')) {
             if (!rel.trim())
                 continue;
-            // Count lines in the new file
+            // Count lines in the new file. Untracked paths come from git relative
+            // to repoRoot — must join with repoRoot, not cwd, when cwd is a subdir.
             try {
-                const full = isAbsolute(rel) ? rel : join(snap.cwd, rel);
+                const full = isAbsolute(rel) ? rel : join(snap.repoRoot, rel);
                 if (!existsSync(full))
                     continue;
                 const size = statSync(full).size;
@@ -125,7 +212,9 @@ function parseTestSummary(stdout) {
 function annotateTrust(snap, files) {
     return files.map((f) => {
         try {
-            const full = isAbsolute(f.path) ? f.path : join(snap.cwd, f.path);
+            // Git-relative path: join with repoRoot, not cwd (matters when cwd is
+            // a subdirectory of the repo).
+            const full = isAbsolute(f.path) ? f.path : join(snap.repoRoot, f.path);
             if (!existsSync(full))
                 return f;
             const size = statSync(full).size;
@@ -154,7 +243,8 @@ function filterByMtime(snap, files) {
     const grace = 1000; // ms; allow clock skew between git's touch and our Date.now()
     return files.filter((f) => {
         try {
-            const full = isAbsolute(f.path) ? f.path : join(snap.cwd, f.path);
+            // Git-relative path: join with repoRoot, not cwd.
+            const full = isAbsolute(f.path) ? f.path : join(snap.repoRoot, f.path);
             if (!existsSync(full))
                 return true; // file was deleted — keep it
             const { mtimeMs } = statSync(full);
@@ -165,10 +255,40 @@ function filterByMtime(snap, files) {
         }
     });
 }
+/**
+ * Drop files that were dirty at spawn time and have NOT been further modified
+ * since. The git-diff-vs-spawn-HEAD path picks up the user's pre-existing
+ * uncommitted changes; without this filter, those files get mis-attributed to
+ * the agent's task. A file is considered "further modified" if its mtime OR
+ * size changed since the spawn snapshot — content-level tampering with same
+ * mtime/size is rare enough to ignore.
+ */
+function filterBySpawnBaseline(snap, files) {
+    if (snap.dirtyBaseline.size === 0)
+        return files;
+    return files.filter((f) => {
+        const baseline = snap.dirtyBaseline.get(f.path);
+        if (!baseline)
+            return true; // wasn't dirty at spawn — definitely a session change
+        try {
+            // Git-relative path: join with repoRoot, not cwd.
+            const full = isAbsolute(f.path) ? f.path : join(snap.repoRoot, f.path);
+            if (!existsSync(full))
+                return true; // deleted during session — that's a change
+            const { mtimeMs, size } = statSync(full);
+            // Further-modified if either mtime advanced or size differs from baseline.
+            return mtimeMs > baseline.mtimeMs || size !== baseline.size;
+        }
+        catch {
+            return true; // stat failed — be permissive (don't drop files we can't verify)
+        }
+    });
+}
 export function extractArtifacts(snap, collectedStdout) {
     const raw = changedFiles(snap);
-    const mine = filterByMtime(snap, raw);
-    const files = annotateTrust(snap, mine);
+    const sessionScoped = filterByMtime(snap, raw);
+    const agentLikely = filterBySpawnBaseline(snap, sessionScoped);
+    const files = annotateTrust(snap, agentLikely);
     const tests = parseTestSummary(collectedStdout);
     return { files, tests };
 }

package/dist/infrastructure/orchestration/claude-code-adapter.js

@@ -407,6 +407,7 @@ export function spawnClaudeCode(prompt, options = {}) {
 export const ClaudeCodeAdapter = {
     id: 'claude-code',
     label: 'Claude Code',
+    description: 'Good default for editing code, running tests, and shell commands. Strongest safety net: codehere can stop risky actions before they run, not just record them after.',
     processPattern: /(?:^|\/)claude(?:\s|$)/,
     isInstalled() {
         try {

package/dist/infrastructure/orchestration/codex-adapter.js

@@ -19,6 +19,7 @@ import { randomUUID } from 'crypto';
 import { ProgressAggregator } from './progress-aggregator.js';
 import { snapshotCwd, extractArtifacts } from './artifacts-extractor.js';
 import { applyMemoryPrefix } from './memory-injector.js';
+import { mirrorToolCallToAudit } from '../hooks/mirror-tool-call-to-audit.js';
 const HEADLESS_FLAGS = [
     'exec',
     '--json',
@@ -103,6 +104,18 @@ export function spawnCodex(prompt, options = {}) {
                 textAccum += item.aggregated_output + '\n';
             if (item?.type === 'agent_message' && item.text)
                 textAccum += item.text + '\n';
+            // #110 slice 2 — mirror tool calls to the audit log so codex
+            // gets the same audit-trail surface as Claude's per-tool hook.
+            // Post-hoc only (no block); pre-tool intercept is a future slice.
+            if (item?.type === 'command_execution' && typeof item.command === 'string' && item.command) {
+                mirrorToolCallToAudit({
+                    sessionId,
+                    agent: 'codex',
+                    toolName: 'Bash',
+                    toolInput: item.command,
+                    cwd,
+                });
+            }
         }
         // Accumulate token usage across all turns (one turn.completed per turn).
         if (event.type === 'turn.completed') {
@@ -358,6 +371,7 @@ export function spawnCodex(prompt, options = {}) {
 export const CodexAdapter = {
     id: 'codex',
     label: 'Codex',
+    description: 'OpenAI\'s coding agent. Good when the task needs reading a lot of code first, then changing several files together.',
     processPattern: /(?:^|\/)codex(?:\s|$)/,
     isInstalled() {
         try {

package/dist/infrastructure/orchestration/failover-classifier.js

@@ -0,0 +1,151 @@
+/**
+ * Failover classifier — v0.6.x rate-limit fail-over wedge (Slice A).
+ *
+ * Interprets adapter error codes to decide whether fail-over to a different
+ * adapter should be offered to the user. Pure function — no I/O, no adapter
+ * spawning. Adapters already detect rate-limit / quota errors via their
+ * ERROR_PATTERNS arrays and emit `codehere:error` events with codes:
+ *   - 'rate_limit'      — Anthropic / OpenAI / Google 429s
+ *   - 'quota_exceeded'  — credit balance / quota exhausted
+ *   - 'auth_invalid'    — NOT failover-eligible (different fix)
+ *   - other codes       — NOT failover-eligible (specific to provider)
+ *
+ * This module's job: take an emitted error code, return either a FailoverSignal
+ * (caller should ask user "switch to Codex?") or null (don't offer failover).
+ *
+ * Per `feedback_research_sharpens_not_pivots.md` — this sharpens what already
+ * ships (per-adapter error patterns) rather than introducing a new detection
+ * mechanism. Per claim_market_position v4 — the fail-over capability is the
+ * v0.6 outward proof point that demonstrates codehere's vendor-neutral value
+ * (only a vendor-neutral layer can switch you off Claude when Claude refuses).
+ *
+ * Slice A scope (this commit): the pure classifier + retry-after parser +
+ * tests. Slices B-F wire policy resolution, user consent, mid-task hand-off,
+ * UI surfacing, and end-to-end integration.
+ */
+/**
+ * Error codes that should trigger a fail-over offer. Keep tight — false
+ * positives waste user attention with "switch?" prompts they don't want.
+ *
+ * Verified against current adapter ERROR_PATTERNS (May 2026):
+ *   - 'rate_limit'      — emitted by all 5 adapters on 429s
+ *   - 'quota_exceeded'  — emitted by codex-adapter, gemini-adapter
+ *   - 'credit_low'      — emitted by claude-code-adapter, aider-adapter
+ *                         when API credit balance is exhausted
+ *
+ * NOT included (and why):
+ *   - 'auth_invalid' — fixing the wrong adapter doesn't help; switching to
+ *     a different agent that ALSO needs auth doesn't fix anything
+ *   - generic errors — no signal that another adapter would do better
+ *   - timeouts — could be transient on either side
+ */
+const FAILOVER_TRIGGER_CODES = new Set(['rate_limit', 'quota_exceeded', 'credit_low']);
+/**
+ * Returns a FailoverSignal if the error code suggests we should offer
+ * fail-over to a different adapter, null otherwise. Pure function — no
+ * side effects. Caller decides how to surface the offer (CLI prompt,
+ * web UI banner, programmatic auto-failover).
+ *
+ * @param fromAgent  Adapter id of the agent that hit the error
+ * @param errorCode  Code from the adapter's ERROR_PATTERNS classification
+ * @param errorMessage  Original error text (used to extract retry-after)
+ */
+export function classifyFailoverEligibility(fromAgent, errorCode, errorMessage) {
+    if (!FAILOVER_TRIGGER_CODES.has(errorCode))
+        return null;
+    if (!fromAgent)
+        return null;
+    const retryAfterMs = parseRetryAfterMs(errorMessage);
+    const signal = {
+        fromAgent,
+        errorCode,
+        reason: errorMessage || `${fromAgent} hit ${errorCode}`,
+    };
+    if (retryAfterMs !== undefined)
+        signal.retryAfterMs = retryAfterMs;
+    return signal;
+}
+/**
+ * Best-effort extraction of retry-after from common error message shapes.
+ * Returns milliseconds or undefined. Conservative — only matches patterns
+ * we've seen in real provider responses; unknown shapes return undefined
+ * (caller treats as "unknown — show indefinite wait").
+ *
+ * Patterns recognized:
+ *   - "Retry-After: 60"
+ *   - "retry after 60s"
+ *   - "retry after 60 seconds"
+ *   - "try again in 2 minutes"
+ *   - "wait 5 min"
+ *   - "wait 90 seconds"
+ *   - "in 2m 30s" (rare, treat as 2 minutes)
+ *
+ * NOT matched (intentionally — too ambiguous):
+ *   - bare numbers ("60") — could be anything
+ *   - "wait a moment" — no quantity
+ */
+export function parseRetryAfterMs(message) {
+    if (!message)
+        return undefined;
+    // "Retry-After: <N> <unit>" — HTTP header style with EXPLICIT unit.
+    // Per RFC 7231, default unit is seconds; we also accept explicit unit
+    // suffix (some providers add one for clarity, e.g. "Retry-After: 5 minutes").
+    // Must NOT match HTTP-date forms ("Retry-After: Wed, 21 Oct ...").
+    const headerWithUnitMatch = message.match(/retry-?after[:\s]+(\d+)\s*(seconds?|secs?|s\b|minutes?|mins?|m\b|hours?|hrs?|h\b)/i);
+    if (headerWithUnitMatch) {
+        const n = Number(headerWithUnitMatch[1]);
+        const unit = headerWithUnitMatch[2].toLowerCase();
+        if (Number.isFinite(n) && n > 0)
+            return convertToMs(n, unit);
+    }
+    // "Retry-After: 60" — bare header with no unit, defaults to seconds per RFC.
+    // Negative lookahead rejects HTTP-date forms (alphabetic chars after the digits).
+    const headerBareMatch = message.match(/retry-?after[:\s]+(\d+)(?!\s*[A-Za-z])/i);
+    if (headerBareMatch) {
+        const sec = Number(headerBareMatch[1]);
+        if (Number.isFinite(sec) && sec > 0)
+            return sec * 1000;
+    }
+    // Order matters: try LARGER units first so compound durations like
+    // "2m 30s" or "1h 45m" don't get misread as the smaller unit. Without
+    // this, "try again in 2m 30s" would match the seconds pattern on "30s"
+    // and return 30 seconds instead of ~2 minutes.
+    //
+    // Each pattern accepts a fractional value (e.g. OpenAI's "try again in 1.23s")
+    // — bare-int regex would have matched "23s" and missed the "1." prefix,
+    // returning 23 seconds instead of ~1.23 seconds. Capture group is "\d+(?:\.\d+)?".
+    // "in 2 hours" / "try again in 1 hour" — common for daily / weekly limits
+    const naturalHoursMatch = message.match(/(?:retry|try again|in|wait|reset).*?(\d+(?:\.\d+)?)\s*hours?\b/i);
+    if (naturalHoursMatch) {
+        const hr = Number(naturalHoursMatch[1]);
+        if (Number.isFinite(hr) && hr > 0)
+            return Math.round(hr * 60 * 60 * 1000);
+    }
+    // "retry after 2 minutes" / "try again in 5 min" / "wait 5 min" / "in 2m 30s"
+    const naturalMinutesMatch = message.match(/(?:retry|try again|wait).*?(\d+(?:\.\d+)?)\s*(?:minutes?|mins?|m\b)/i);
+    if (naturalMinutesMatch) {
+        const min = Number(naturalMinutesMatch[1]);
+        if (Number.isFinite(min) && min > 0)
+            return Math.round(min * 60 * 1000);
+    }
+    // "retry after 60s" / "try again in 60s" / "wait 60s" / "try again in 1.23s"
+    // (OpenAI returns fractional seconds for sub-2-second rate-limit windows).
+    // Last because compound durations like "2m 30s" should be read as minutes.
+    const naturalSecondsMatch = message.match(/(?:retry|try again|wait).*?(\d+(?:\.\d+)?)\s*(?:seconds?|secs?|s\b)/i);
+    if (naturalSecondsMatch) {
+        const sec = Number(naturalSecondsMatch[1]);
+        if (Number.isFinite(sec) && sec > 0)
+            return Math.round(sec * 1000);
+    }
+    return undefined;
+}
+/** Convert a number + unit string to milliseconds. Unit is one of the regex
+ *  alternatives in the header-with-unit pattern above. */
+function convertToMs(n, unit) {
+    if (/^h/i.test(unit))
+        return n * 60 * 60 * 1000;
+    if (/^m/i.test(unit))
+        return n * 60 * 1000;
+    return n * 1000; // seconds (default)
+}
+//# sourceMappingURL=failover-classifier.js.map

package/dist/infrastructure/orchestration/failover-policy.js

@@ -0,0 +1,106 @@
+/**
+ * Failover policy — v0.6.x rate-limit fail-over wedge (Slice B).
+ *
+ * Given: an adapter that hit a fail-over-eligible error (per Slice A's
+ * `classifyFailoverEligibility`), a user-configured preference chain, and
+ * the set of currently-available adapters on this machine.
+ * Returns: the next adapter to try, or null if no fail-over target is
+ * available.
+ *
+ * Pure function — no I/O, no spawning. Caller (session-manager, Slice D)
+ * uses the resolver output to drive the user-consent flow (Slice C) and
+ * the mid-task hand-off.
+ *
+ * Default chain rationale:
+ *   claude-code → codex → aider → opencode → gemini
+ *
+ * The default is ordered by capability+reliability for general coding work
+ * as of May 2026:
+ *   - claude-code: strongest at multi-file reasoning + tool use
+ *   - codex: strongest at independent review + adversarial mode
+ *   - aider: most reliable for surgical single-file edits
+ *   - opencode: cross-vendor flexibility within itself
+ *   - gemini: longest context window, but free-tier rate limits hit fast
+ *
+ * Users can override via `~/.codehere/config.json` `failoverChain` array.
+ * Per-task override also supported via SpawnOptions.failoverChain (Slice D
+ * wires this).
+ *
+ * Slice B scope (this commit): pure resolver + config schema + tests.
+ * Slices C-F wire user consent, mid-task hand-off, UI surfacing, e2e.
+ */
+/** Adapter ids in the order codehere supports. Keep in sync with adapter
+ *  registry. Used as the strict ordering for chain validation. */
+export const KNOWN_AGENT_IDS = ['claude-code', 'codex', 'aider', 'opencode', 'gemini'];
+/** Default fail-over chain. See module docblock for ordering rationale.
+ *  Each entry is the agent codehere will TRY in order when the previous
+ *  one is unavailable or has already been tried this hand-off. */
+export const DEFAULT_FAILOVER_CHAIN = ['claude-code', 'codex', 'aider', 'opencode', 'gemini'];
+/**
+ * Resolve the next fail-over target. Returns the adapter id to try, or
+ * null if no eligible target exists.
+ *
+ * Selection rules (in order):
+ *   1. Use preferredChain if provided, else DEFAULT_FAILOVER_CHAIN
+ *   2. Skip the failed agent itself
+ *   3. Skip any adapter in alreadyTried
+ *   4. Skip adapters not present in available[] OR with ready=false
+ *   5. Return the FIRST remaining adapter in chain order
+ *   6. If nothing remains, return null
+ *
+ * Pure — no spawn, no config read. Caller assembles the inputs.
+ */
+export function resolveFailoverTarget(opts) {
+    const chain = opts.preferredChain && opts.preferredChain.length > 0 ? opts.preferredChain : DEFAULT_FAILOVER_CHAIN;
+    const tried = new Set([opts.failedAgent, ...(opts.alreadyTried ?? [])]);
+    const readyById = new Map();
+    for (const a of opts.available)
+        readyById.set(a.id, a.ready);
+    for (const candidate of chain) {
+        if (tried.has(candidate))
+            continue;
+        if (readyById.get(candidate) !== true)
+            continue;
+        return candidate;
+    }
+    return null;
+}
+/**
+ * Validate a user-supplied chain (e.g. read from config.json). Returns the
+ * chain if every entry is a known agent id; throws otherwise. Caller
+ * (config-loader, Slice C) uses this to give a helpful error if the user
+ * mistypes an adapter name.
+ */
+export function validateFailoverChain(chain) {
+    if (!Array.isArray(chain)) {
+        throw new Error('failoverChain must be an array of agent ids');
+    }
+    const validated = [];
+    for (const item of chain) {
+        if (typeof item !== 'string') {
+            throw new Error(`failoverChain entries must be strings, got ${typeof item}`);
+        }
+        if (!isKnownAgentId(item)) {
+            throw new Error(`Unknown agent id in failoverChain: "${item}". Valid ids: ${KNOWN_AGENT_IDS.join(', ')}`);
+        }
+        if (validated.includes(item)) {
+            throw new Error(`Duplicate agent id in failoverChain: "${item}"`);
+        }
+        validated.push(item);
+    }
+    return validated;
+}
+function isKnownAgentId(id) {
+    return KNOWN_AGENT_IDS.includes(id);
+}
+/**
+ * Helper: convert an array of AgentAdapter (typically from an adapter
+ * registry) to the AdapterAvailability shape this module expects, given
+ * a readiness probe function. Used by callers who already have the
+ * adapter instances handy. Caller passes a probe like
+ * `adapter.checkReadiness().state === 'ready'`.
+ */
+export function toAvailability(adapters, isReady) {
+    return adapters.map((a) => ({ id: a.id, ready: isReady(a) }));
+}
+//# sourceMappingURL=failover-policy.js.map