@kelceyp/caw-server 1.0.290 → 1.1.0

package/dist/teardownReasons.mjs

@@ -1,100 +0,0 @@
-/**
- * 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/dist/transcript-tailer.mjs

@@ -1,206 +0,0 @@
-// TranscriptTailer — polls a Claude Code session transcript JSONL file, forwards
-// post-baseline entries to a consumer, and recovers transparently when the file
-// shrinks, is replaced (dev/ino change), tears mid-write, or contains
-// non-final unparseable lines. Sibling of `pty-wrapper.mjs`; not imported by it
-// at this task's end-of-task (wired in at Task 6).
-//
-// Instance-owned mutable state — no module-level mutables. Two instances
-// constructed against the same fixture path do not share state.
-
-import * as fs from 'node:fs';
-
-const TORN_PREFIX = 'tailTranscript: torn trailing line at cursor=';
-const REOPENED_PREFIX = 'tailTranscript: reopened path=';
-const UNPARSEABLE_PREFIX = 'tailTranscript: non-final unparseable line at offset=';
-const UNUSABLE_PREFIX = 'tailTranscript: boundary unusable, cause=';
-const READ_ERROR_PREFIX = 'tailTranscript: read error:';
-
-// Regex UUID extraction — used by the pre-baseline walk and re-walks so a
-// single unparseable line cannot poison the baseline the way per-line
-// JSON.parse would.
-const UUID_REGEX = /"uuid"\s*:\s*"([0-9a-fA-F-]+)"/g;
-
-function extractUuidsInto(text, set) {
-    UUID_REGEX.lastIndex = 0;
-    let match;
-    while ((match = UUID_REGEX.exec(text)) !== null) {
-        set.add(match[1]);
-    }
-}
-
-export function createTranscriptTailer({ log } = {}) {
-    const emit = typeof log === 'function'
-        ? log
-        : (message) => { process.stderr.write(message + '\n'); };
-
-    const state = {
-        path: null,
-        dev: null,
-        ino: null,
-        cursor: 0,
-        preBaselineUUIDs: new Set(),
-        processedUUIDs: new Set(),
-        boundaryEstablished: false,
-        unusable: false,
-        closed: false,
-    };
-
-    function setUnusable(cause) {
-        if (state.unusable) return;
-        state.unusable = true;
-        emit(`${UNUSABLE_PREFIX}${cause} — subsequent ticks will return no entries`);
-    }
-
-    function initialiseBoundary(path, options = {}) {
-        if (state.boundaryEstablished) return;
-        state.boundaryEstablished = true;
-        state.path = path;
-        const { resume = false } = options;
-        if (!resume) {
-            state.cursor = 0;
-            state.preBaselineUUIDs = new Set();
-            return;
-        }
-        // Case B: --resume — synchronous pre-spawn baseline take.
-        try {
-            const stats = fs.statSync(path);
-            const content = fs.readFileSync(path, 'utf-8');
-            state.dev = stats.dev;
-            state.ino = stats.ino;
-            state.cursor = stats.size;
-            state.preBaselineUUIDs = new Set();
-            extractUuidsInto(content, state.preBaselineUUIDs);
-        } catch {
-            setUnusable('readError');
-        }
-    }
-
-    function reopenAndRewalkBoundary() {
-        if (!state.boundaryEstablished) return;
-        if (state.unusable) return;
-        try {
-            const prevDev = state.dev;
-            const prevIno = state.ino;
-            const stats = fs.statSync(state.path);
-            const content = fs.readFileSync(state.path, 'utf-8');
-            const rebuilt = new Set();
-            extractUuidsInto(content, rebuilt);
-            state.dev = stats.dev;
-            state.ino = stats.ino;
-            state.cursor = stats.size;
-            state.preBaselineUUIDs = rebuilt;
-            emit(
-                `${REOPENED_PREFIX}${state.path} dev=${state.dev} ino=${state.ino} `
-                + `(was dev=${prevDev} ino=${prevIno}), cursor=0, `
-                + `re-walking to rebuild preBaselineUUIDs (${rebuilt.size} entries suppressed from forwarding)`
-            );
-        } catch {
-            setUnusable('reopenFailed');
-        }
-    }
-
-    function tick() {
-        if (!state.boundaryEstablished) return [];
-        if (state.unusable) return [];
-        if (state.closed) return [];
-
-        let stats;
-        try {
-            stats = fs.statSync(state.path);
-        } catch (err) {
-            if (err && err.code === 'ENOENT') return [];
-            emit(`${READ_ERROR_PREFIX} ${err && err.message ? err.message : String(err)}`);
-            return [];
-        }
-
-        if (state.dev !== null && state.ino !== null) {
-            if (stats.dev !== state.dev || stats.ino !== state.ino || stats.size < state.cursor) {
-                reopenAndRewalkBoundary();
-                return [];
-            }
-        } else {
-            // First successful stat since boundary establishment (Case A): record
-            // (dev, ino) implicitly so subsequent ticks can detect replacement.
-            state.dev = stats.dev;
-            state.ino = stats.ino;
-        }
-
-        if (stats.size <= state.cursor) return [];
-
-        const toRead = stats.size - state.cursor;
-        let buf;
-        try {
-            const fd = fs.openSync(state.path, 'r');
-            try {
-                buf = Buffer.alloc(toRead);
-                let totalRead = 0;
-                while (totalRead < toRead) {
-                    const n = fs.readSync(fd, buf, totalRead, toRead - totalRead, state.cursor + totalRead);
-                    if (n === 0) break;
-                    totalRead += n;
-                }
-                if (totalRead < toRead) buf = buf.slice(0, totalRead);
-            } finally {
-                fs.closeSync(fd);
-            }
-        } catch (err) {
-            emit(`${READ_ERROR_PREFIX} ${err && err.message ? err.message : String(err)}`);
-            return [];
-        }
-
-        const entries = [];
-        const startCursor = state.cursor;
-        let localOffset = 0;
-
-        while (localOffset < buf.length) {
-            const nlIdx = buf.indexOf(0x0A, localOffset);
-            if (nlIdx === -1) {
-                // Incomplete trailing line — leave cursor at its start; re-read next poll.
-                const tornPos = startCursor + localOffset;
-                state.cursor = tornPos;
-                emit(`${TORN_PREFIX}${tornPos}, deferring; will re-read next poll`);
-                return entries;
-            }
-            const line = buf.slice(localOffset, nlIdx).toString('utf-8');
-            const lineByteOffset = startCursor + localOffset;
-
-            if (line.length > 0) {
-                let entry;
-                let parsed = false;
-                try {
-                    entry = JSON.parse(line);
-                    parsed = true;
-                } catch {
-                    emit(`${UNPARSEABLE_PREFIX}${lineByteOffset} — skipping (cursor still advances)`);
-                }
-                if (parsed) {
-                    const uuid = entry && typeof entry === 'object' ? entry.uuid : undefined;
-                    if (!uuid || (!state.preBaselineUUIDs.has(uuid) && !state.processedUUIDs.has(uuid))) {
-                        if (uuid) state.processedUUIDs.add(uuid);
-                        entries.push(entry);
-                    }
-                }
-            }
-
-            localOffset = nlIdx + 1;
-        }
-
-        state.cursor = startCursor + buf.length;
-        return entries;
-    }
-
-    function close() {
-        state.closed = true;
-    }
-
-    return {
-        initialiseBoundary,
-        tick,
-        close,
-        reopenAndRewalkBoundary,
-        get path() { return state.path; },
-        get unusable() { return state.unusable; },
-        get preBaselineUUIDs() { return state.preBaselineUUIDs; },
-        get boundaryEstablished() { return state.boundaryEstablished; },
-    };
-}