@shardworks/claude-code-apparatus 0.1.274 → 0.1.275

package/README.md

@@ -55,18 +55,27 @@ import {
 
 ### Rate-Limit Detection
 
-The provider runs a **two-branch NDJSON detector** to identify rate-limited terminations and attach a structured `terminationTag` to the session result. The Animator's back-off state machine consumes the tag and transitions its pause-state doc accordingly.
+The provider runs a **single-branch, evidence-driven NDJSON detector** to identify rate-limited terminations and attach a structured `terminationTag` to the session result. The Animator's back-off state machine consumes the tag and transitions its pause-state doc accordingly.
 
 ```typescript
 import { detectRateLimitFromNdjson } from '@shardworks/claude-code-apparatus';
 ```
 
-Active detector branches (first-wins):
+The active branch matches the rate-limit pattern against the **top-level `error` field** (peer of `message`) on every NDJSON message — the shape claude actually emits on rate-limited assistant termination:
 
-1. **Structural `subtype`** — `parseStreamJsonMessage` inspects every NDJSON message whose `subtype` contains `rate_limit` / `rate-limit` and emits a tag with `source: 'ndjson-result'`.
-2. **Structural `is_error`** — if `msg.is_error === true` and the carried error text matches the rate-limit phrasing regex, the same tag is produced.
+```json
+{ "type": "assistant", "message": { "...": "..." }, "error": "rate_limit" }
+```
+
+When the regex matches, a tag with `source: 'ndjson-result'` is emitted. The detector is intentionally narrow: branches are added only when a real provider emission is observed, not pre-emptively.
+
+**Retired branches** (do not re-introduce without a live observation):
+
+- `subtype` — earlier speculative branch that emitted a tag when `msg.subtype` contained `rate_limit` / `rate-limit`. Retired because no live provider emission ever fired it.
+- `is_error` — earlier speculative branch that emitted a tag when `msg.is_error === true` and the carried error text matched the rate-limit pattern. Retired for the same reason.
+- `result`-text and stderr/exit-code cascades — retired earlier for false-positive pauses (an assistant's prose summary of a prior rate-limit / a generic non-zero exit code each tripped a false-positive pause once in production).
 
-Everything else surfaces as plain `failed`. The previous stderr-pattern and exit-code branches were retired after two production incidents where an assistant's prose summary / a generic non-zero exit code tripped a false-positive pause. Generic non-zero exit codes surface as `'failed'`; the babysitter no longer samples claude's stderr for pattern matches, only forwards it to the per-session log file.
+Everything else surfaces as plain `failed`. Generic non-zero exit codes do not produce a rate-limit tag; the babysitter no longer samples claude's stderr for pattern matches, only forwards it to the per-session log file.
 
 When a non-zero exit arrives without an NDJSON termination tag, the babysitter captures a `terminationDiagnostic: { exitCode, stderrExcerpt? }` on the session-record payload so operators can review the signal that fell through — without the Animator widening its pause gate on it.
 

package/dist/babysitter.d.ts

@@ -15,45 +15,31 @@
  *
  * The single-purpose primitives (stdin parsing, retrying HTTP, DLQ writes,
  * the SQLite trio, lifecycle reporters, stderr redirect) live in
- * `runtime.ts`. This file owns the orchestrator (`runBabysitter`), the
- * MCP/SSE proxy, and the script entry point. The previously-exported
- * primitives are re-exported below to preserve the package's public
- * surface.
+ * `runtime.ts`. The MCP/SSE proxy lives in `mcp-proxy.ts`. This file owns
+ * the orchestrator (`runBabysitter`) and the script entry point. The
+ * previously-exported primitives are re-exported below to preserve the
+ * package's public surface.
  *
  * See: docs/architecture/detached-sessions.md
  */
 import { spawn } from 'node:child_process';
-import { type BabysitterConfig, type SerializedTool, type TranscriptDb } from './runtime.ts';
+import { type BabysitterConfig, type TranscriptDb } from './runtime.ts';
 export { callGuildHttpApi, findRetryableCode, initTranscriptDb, openTranscriptDb, readConfigFromStdin, redirectStderrToFile, reportResult, reportRunning, resolveTerminalStatus, STDERR_DIAGNOSTIC_TAIL_LIMIT, writeToDlq, writeTranscript, } from './runtime.ts';
 export type { BabysitterConfig, SerializedTool, TranscriptDb, } from './runtime.ts';
-export interface McpProxyHandle {
-    /** URL for --mcp-config (e.g. "http://127.0.0.1:PORT/sse"). */
-    url: string;
-    /** Shut down the HTTP server and MCP transport. */
-    close(): Promise<void>;
-}
-/**
- * Create an MCP/SSE HTTP server that proxies tool calls to the guild.
- *
- * For each tool in the config, registers an MCP tool whose handler
- * forwards the call to the guild's Tool HTTP API via HTTP POST.
- *
- * Uses the low-level MCP Server class to register tools with raw
- * JSON Schema (the serialized params from the config).
- */
-export declare function createProxyMcpHttpServer(tools: SerializedTool[], guildToolUrl: string, sessionId: string): Promise<McpProxyHandle>;
+export { createProxyMcpHttpServer, type McpProxyHandle } from './mcp-proxy.ts';
 /**
  * Run the session babysitter.
  *
- * This is the main orchestration function. It:
- * 1. Opens SQLite for transcript streaming
- * 2. Starts the MCP proxy server
- * 3. Prepares session files (tmpDir, system prompt, mcp-config)
- * 4. Spawns claude
- * 5. Reports "running" status
- * 6. Streams transcript to SQLite
- * 7. Reports result on exit
- * 8. Cleans up
+ * Three-phase orchestrator threading a {@link BabysitterRuntimeContext}:
+ * `runInitPhase` allocates resources, `runSteadyStatePhase` reports
+ * lifecycle events and consumes claude's NDJSON stream, `runTerminalPhase`
+ * builds and submits the final result. The shared try/catch/finally
+ * funnels all error and cleanup handling.
+ *
+ * The orchestrator-error path goes through `reportResult` via the
+ * `StatusOverride` contract (no hand-rolled session-record + DLQ
+ * cascade) — `reportResult` is the single sink for both the normal
+ * `'failed'` path and the orchestrator-caught error path.
  */
 export declare function runBabysitter(config: BabysitterConfig, deps?: {
     /** Injected TranscriptDb for testing (avoids loading better-sqlite3). */

package/dist/babysitter.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"babysitter.d.ts","sourceRoot":"","sources":["../src/babysitter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,OAAO,EAAE,KAAK,EAAqB,MAAM,oBAAoB,CAAC;AAwB9D,OAAO,EAUL,KAAK,gBAAgB,EACrB,KAAK,cAAc,EACnB,KAAK,YAAY,EAClB,MAAM,cAAc,CAAC;AAItB,OAAO,EACL,gBAAgB,EAChB,iBAAiB,EACjB,gBAAgB,EAChB,gBAAgB,EAChB,mBAAmB,EACnB,oBAAoB,EACpB,YAAY,EACZ,aAAa,EACb,qBAAqB,EACrB,4BAA4B,EAC5B,UAAU,EACV,eAAe,GAChB,MAAM,cAAc,CAAC;AACtB,YAAY,EACV,gBAAgB,EAChB,cAAc,EACd,YAAY,GACb,MAAM,cAAc,CAAC;AAItB,MAAM,WAAW,cAAc;IAC7B,+DAA+D;IAC/D,GAAG,EAAE,MAAM,CAAC;IACZ,mDAAmD;IACnD,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB;AAID;;;;;;;;GAQG;AACH,wBAAsB,wBAAwB,CAC5C,KAAK,EAAE,cAAc,EAAE,EACvB,YAAY,EAAE,MAAM,EACpB,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC,cAAc,CAAC,CAmLzB;AAID;;;;;;;;;;;;GAYG;AACH,wBAAsB,aAAa,CACjC,MAAM,EAAE,gBAAgB,EACxB,IAAI,CAAC,EAAE;IACL,yEAAyE;IACzE,EAAE,CAAC,EAAE,YAAY,CAAC;IAClB,kCAAkC;IAClC,OAAO,CAAC,EAAE,OAAO,KAAK,CAAC;IACvB,8DAA8D;IAC9D,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB,GACA,OAAO,CAAC,IAAI,CAAC,CAqOf"}
+{"version":3,"file":"babysitter.d.ts","sourceRoot":"","sources":["../src/babysitter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,OAAO,EAAE,KAAK,EAAqB,MAAM,oBAAoB,CAAC;AAgB9D,OAAO,EAUL,KAAK,gBAAgB,EACrB,KAAK,YAAY,EAClB,MAAM,cAAc,CAAC;AAStB,OAAO,EACL,gBAAgB,EAChB,iBAAiB,EACjB,gBAAgB,EAChB,gBAAgB,EAChB,mBAAmB,EACnB,oBAAoB,EACpB,YAAY,EACZ,aAAa,EACb,qBAAqB,EACrB,4BAA4B,EAC5B,UAAU,EACV,eAAe,GAChB,MAAM,cAAc,CAAC;AACtB,YAAY,EACV,gBAAgB,EAChB,cAAc,EACd,YAAY,GACb,MAAM,cAAc,CAAC;AAEtB,OAAO,EAAE,wBAAwB,EAAE,KAAK,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAgR/E;;;;;;;;;;;;;GAaG;AACH,wBAAsB,aAAa,CACjC,MAAM,EAAE,gBAAgB,EACxB,IAAI,CAAC,EAAE;IACL,yEAAyE;IACzE,EAAE,CAAC,EAAE,YAAY,CAAC;IAClB,kCAAkC;IAClC,OAAO,CAAC,EAAE,OAAO,KAAK,CAAC;IACvB,8DAA8D;IAC9D,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB,GACA,OAAO,CAAC,IAAI,CAAC,CA2Ef"}