@kelceyp/caw-server 1.0.278 → 1.0.280

package/dist/teardownReasons.mjs

@@ -0,0 +1,100 @@
+/**
+ * teardownReasons.mjs — closed enum for the pty-wrapper's `teardown()` reason,
+ * shared between the observability path (As1012) and the classification path
+ * (As1033).
+ *
+ * Authored under As1012 as part of the S2 workshop's Q4 outcome — imported by
+ * `pty-wrapper.mjs` (emit site) and by `JobRunner.js`'s watchdog gate + the
+ * stream-handler metadata plumbing on the As1033 side.
+ *
+ * Non-forced-path contract (joint As1012 × As1033)
+ * ------------------------------------------------
+ *
+ *   1. `teardown()` runs on every graceful exit path. Four call sites; four
+ *      enum values: `WATCHDOG` (expiry), `SENTINEL_UNREADABLE`, `STOP_FAILURE`,
+ *      `STOP` (normal completion via the Stop hook). Normal completion is NOT a
+ *      no-teardown case — it is `teardown('stop')`. **`STOP` is a real value.**
+ *
+ *   2. `emitResult` always writes `metadata.teardownReason` when it runs, with
+ *      a value from this enum. The field is NOT optional on the graceful path —
+ *      consumers read it directly without an `undefined` check.
+ *
+ *   3. **`metadata.teardownReason` is omitted (not `null`) whenever the pty
+ *      child exits without `teardown()` firing.** Absence is the signal — the
+ *      enum does not carry a *no-teardown* value. Four non-teardown exit
+ *      paths, listed exhaustively so a future debugger does not misread the
+ *      gap:
+ *
+ *        a. **Child self-exit** — `claude` returns of its own accord before
+ *           the Stop hook fires (rare; e.g. an unhandled internal error).
+ *           `onExit` runs with a non-zero code; `emitResult` runs; the field
+ *           is omitted because `teardown()` never called `emitResult` with a
+ *           reason. Classifier reads a distinct exit class from `exitCode`.
+ *        b. **External signal to the wrapper** (SIGTERM/SIGINT delivered
+ *           externally, not from the wrapper's own deadline path). Wrapper
+ *           may or may not manage to emit anything depending on the signal
+ *           and its handler set at the moment.
+ *        c. **Prompt-too-long emission** — the wrapper's stdout emits its
+ *           result branch directly without routing through `teardown()`
+ *           (`pty-wrapper.mjs:733` and its neighbours; see
+ *           Easy-to-Miss #5 in As1012's design). Field omitted.
+ *        d. **As1006's F2 SIGKILL** — the wrapper-self-terminate path with a
+ *           process-group SIGKILL of the PTY child under the wrapper's own
+ *           deadline. SIGKILL is unmaskable; the wrapper is dead before it
+ *           can emit; the entire `type:"result"` JSONL line is absent.
+ *
+ *      **`As1006's F2 SIGKILL path is an OUT-OF-ENUM EXIT PATH`, as are the
+ *      other three above.** Do not read this enum as enumerating every wrapper
+ *      exit. An F2-killed job leaves NO wrapper-side breadcrumb via this
+ *      enum — that gap is by design, not by omission. As1033's dissent from
+ *      workshop round 3 is honoured by this note.
+ *
+ *      The classifier's contract for any of the four non-teardown cases:
+ *      `turnSignals.teardownReason === undefined` is a **distinct exit
+ *      class** — spawn failure / SIGKILL / crash / prompt-too-long / external
+ *      signal — not a teardown. Classification gate ordering (As1033):
+ *      `WATCHDOG` gate first (positive match on `reason === WATCHDOG`); other
+ *      reasons fall through unchanged; missing reason routes to the
+ *      spawn-failure / no-result branch.
+ *
+ *   4. Lifecycle events (`armed`, `reset`, `expired`, `teardown`) share the
+ *      enum only via the `teardown` event's `reason` field. `armed` / `reset`
+ *      / `expired` observability events carry `type`, not `reason` — no enum
+ *      value on those.
+ *
+ *   5. **The enum is closed at story-close.** Adding a value requires a
+ *      coordinated change to both this module AND the classification gate in
+ *      `JobRunner.js`. This is a maintenance rule, not a note — treat the set
+ *      below as fixed.
+ *
+ * Consumers
+ * ---------
+ *
+ *   - `pty-wrapper.mjs` — emit sites: `teardown(reason)` calls at the watchdog
+ *     expiry closure (`WATCHDOG`), sentinel-read failure (`SENTINEL_UNREADABLE`),
+ *     StopFailure hook (`STOP_FAILURE`), clean no-pending-work path (`STOP`).
+ *   - `pty-emit-result.mjs` — writes `metadata.teardownReason` on the result
+ *     JSONL line (As1033).
+ *   - `claude-session.js` — `getMetadata()` propagates the value into
+ *     `turnSignals.teardownReason` (As1033).
+ *   - `JobRunner.js` — watchdog classification gate reads
+ *     `turnSignals.teardownReason` and compares against `TEARDOWN_REASONS.WATCHDOG`
+ *     (As1033).
+ *   - `Log.js` observability — the `WATCHDOG event=teardown reason=<value>`
+ *     line format (As1012) references the enum values verbatim.
+ *
+ * Packaging
+ * ---------
+ *
+ * Copied verbatim into `dist/` by `server/package.json`'s `build:all` script,
+ * alongside `pty-wrapper.mjs`, `pty-emit-result.mjs`, and
+ * `pty-deferred-teardown.mjs`. Not bundled — the wrapper is executed as a
+ * standalone node process and imports this module by relative path.
+ */
+
+export const TEARDOWN_REASONS = Object.freeze({
+    WATCHDOG:              'watchdog',
+    STOP:                  'stop',
+    SENTINEL_UNREADABLE:   'sentinel-unreadable',
+    STOP_FAILURE:          'stop-failure',
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kelceyp/caw-server",
-  "version": "1.0.278",
+  "version": "1.0.280",
   "description": "CAW server - REST API, MCP server and core features",
   "type": "module",
   "main": "dist/main.js",
@@ -19,7 +19,7 @@
     "build": "bash scripts/bun-build.sh",
     "build:client": "cd ../client && bun run build",
     "build:cli": "cd ../cli && bun run build && cp dist/cli.js ../server/dist/",
-    "build:all": "bun run clean && bun run generate:applyPojo && bun run build:client && bun run build && cp src/core/services/embedding-worker.js dist/embedding-worker.js && cp src/core/agents/pty-wrapper.mjs dist/pty-wrapper.mjs && cp src/core/agents/pty-deferred-teardown.mjs dist/pty-deferred-teardown.mjs && cp src/core/agents/pty-emit-result.mjs dist/pty-emit-result.mjs && bun run build:cli",
+    "build:all": "bun run clean && bun run generate:applyPojo && bun run build:client && bun run build && cp src/core/services/embedding-worker.js dist/embedding-worker.js && cp src/core/agents/pty-wrapper.mjs dist/pty-wrapper.mjs && cp src/core/agents/pty-deferred-teardown.mjs dist/pty-deferred-teardown.mjs && cp src/core/agents/pty-emit-result.mjs dist/pty-emit-result.mjs && cp src/core/agents/teardownReasons.mjs dist/teardownReasons.mjs && bun run build:cli",
     "dev": "STATIC_PATH=../client/src bun --define __BUILTIN_POSTHOG_KEY__=null run src/main.js",
     "start": "node dist/main.js",
     "test": "bun test --define __BUILTIN_POSTHOG_KEY__=null test/unit test/integration test/component test/cli test/investigation && (cd ../client && bun test)",