@kelceyp/caw-server 1.0.278 → 1.0.280

package/dist/pty-emit-result.mjs

@@ -41,6 +41,7 @@ export function emitResult({
     effectiveSessionId = null,
     startedAt = null,
     endedAt = null,
+    teardownReason = null,
     alreadyEmitted = false,
     suppressFallback = false,
     write = defaultWrite,
@@ -67,6 +68,14 @@ export function emitResult({
         if (startedAt !== null && endedAt !== null) {
             metadata.durationMs = endedAt - startedAt;
         }
+        // As1033 Task 6: append teardownReason ('stop' | 'watchdog') so the
+        // downstream stream handler (Task 5 landed the capture) and the
+        // JobRunner classifier gate (Task 7) can distinguish a clean Stop
+        // finish from a watchdog force-kill. Field order of the four
+        // pre-existing fields is preserved byte-for-byte.
+        if (teardownReason !== null) {
+            metadata.teardownReason = teardownReason;
+        }
         // D11 test-only override: when the wrapper's CAW_PTY_SUPPRESS_STOP_FALLBACK
         // gate is set, blank the `result` field on the success branch only. The
         // wire is deliberately identical to a real empty-message turn — that IS

package/dist/pty-wrapper.mjs

@@ -25,6 +25,7 @@ import { tmpdir, homedir } from 'os';
 import { execSync } from 'child_process';
 import { readSentinelPayload, hasPendingWork } from './pty-deferred-teardown.mjs';
 import { emitResult as emitResultLine } from './pty-emit-result.mjs';
+import { TEARDOWN_REASONS } from './teardownReasons.mjs';
 
 // --- Arg parsing ---
 
@@ -370,6 +371,11 @@ const SUPPRESS_STOP_FALLBACK = process.env.CAW_PTY_SUPPRESS_STOP_FALLBACK === '1
 
 let watchdogTimer = null;
 let teardownInitiated = false;
+// Captured at the top of teardown() on both paths (clean-Stop passes 'stop',
+// watchdog callback passes 'watchdog'). Read by emitResult() on the success
+// branch and written to metadata.teardownReason so the downstream
+// stream-handler and classifier (Task 7) can distinguish the two paths.
+let teardownReason = null;
 
 // Duration capture: wall clock from `pty.spawn` to top of `teardown()`.
 // `endedAt` is set by whichever teardown path fires first (normal SIGUSR1
@@ -381,24 +387,95 @@ let teardownInitiated = false;
 let startedAt = null;
 let endedAt = null;
 
+// Module-scope armed timestamp for the watchdog observability channel (As1012
+// Task 7). Written by `startOrResetWatchdog` on every call (initial arm and
+// each subsequent reset) and read by both `teardown()` and the setTimeout
+// expiry closure so `elapsedSinceArmMs` can be computed after the timer has
+// released. On a `reset` call the elapsed value is captured BEFORE `armedAt`
+// is overwritten so the emitted event carries the duration of the *previous*
+// armed interval (see item 4's ordering invariant).
+let armedAt = null;
+
+// Module-scope snapshot of the sentinel counts observed at the most recent
+// deferral, for the `WATCHDOG` observability channel (As1012 Task 13). Written
+// in the SIGUSR1 handler's defer branch BEFORE `startOrResetWatchdog()` so the
+// counts are in place if the watchdog subsequently fires; read from
+// `teardown()` when `reason === TEARDOWN_REASONS.WATCHDOG`. Lifted for the
+// same reason as `armedAt`: the SIGUSR1 handler's `bgCount` / `cronCount`
+// locals are block-scoped and out of scope inside the `setTimeout` closure
+// that eventually calls `teardown(TEARDOWN_REASONS.WATCHDOG)`. Overwritten on
+// every deferral, so it always holds the LAST deferral's counts — that is the
+// documented last-seen-snapshot semantic (design.md §Data on the wire).
+let lastDeferredCounts = null;
+
 // Forward declarations (assigned after ptyProcess is created)
 let ptyProcess = null;
 
+// --- Tagged event channel (As1012 Task 7) ---
+// Structured lifecycle events on stderr: `[caw:pty:event] <json>\n`. Consumed
+// downstream by JobRunner's `createStderrSplitter` (Task 6), which routes
+// matching lines through the operational tier (`caw:ops:pty:info`). Prose
+// stderr (every `log()` line above) is untouched — the splitter forwards
+// non-tagged bytes byte-identically to today's `stderrChunks` collector.
+// EPIPE is swallowed so a closed downstream pipe cannot crash the wrapper
+// (stderr is diagnostic; the tagged channel is best-effort).
+const EVENT_TAG = '[caw:pty:event] ';
+const emitEvent = (type, fields = {}) => {
+    const payload = {
+        type,
+        wrapperPid: process.pid,
+        claudePid: ptyProcess?.pid,
+        agentSessionId: effectiveSessionId,
+        ...fields
+    };
+    try {
+        process.stderr.write(`${EVENT_TAG}${JSON.stringify(payload)}\n`);
+    } catch (err) {
+        if (err && err.code !== 'EPIPE') throw err;
+    }
+};
+
 const startOrResetWatchdog = () => {
-    if (watchdogTimer) clearTimeout(watchdogTimer);
-    log(`Watchdog ${watchdogTimer ? 'reset' : 'armed'}: ${WATCHDOG_TIMEOUT_MS / 60000}m timeout`);
+    const wasArmed = watchdogTimer !== null;
+    if (wasArmed) clearTimeout(watchdogTimer);
+    log(`Watchdog ${wasArmed ? 'reset' : 'armed'}: ${WATCHDOG_TIMEOUT_MS / 60000}m timeout`);
+    // Ordering invariant (item 4): capture elapsedSinceArmMs BEFORE `armedAt`
+    // is overwritten so the `reset` event carries the duration of the previous
+    // armed interval. `armed` (first call) carries no elapsed value.
+    if (wasArmed) {
+        emitEvent('reset', { elapsedSinceArmMs: Date.now() - armedAt });
+    } else {
+        emitEvent('armed');
+    }
+    armedAt = Date.now();
     watchdogTimer = setTimeout(() => {
-        log(`Watchdog expired after ${WATCHDOG_TIMEOUT_MS / 60000}m with no progress, force-killing claude`);
-        teardown();
+        log(`Watchdog expired: ${WATCHDOG_TIMEOUT_MS / 60000}m elapsed since last deferred Stop, force-killing claude`);
+        emitEvent('expired', { elapsedSinceArmMs: Date.now() - armedAt });
+        teardown(TEARDOWN_REASONS.WATCHDOG);
     }, WATCHDOG_TIMEOUT_MS);
 };
 
-const teardown = () => {
+const teardown = (reason = TEARDOWN_REASONS.STOP) => {
     if (teardownInitiated) return;
     teardownInitiated = true;
     endedAt = Date.now();
-    log('Teardown: stop received, no pending work, killing claude');
+    teardownReason = reason;
+    log(`Teardown (reason=${reason}): killing claude`);
     log(`Duration: ${startedAt !== null ? (endedAt - startedAt) : 'unknown'} ms (startedAt=${startedAt}, endedAt=${endedAt})`);
+    // As1012 Task 13 — `pendingBgCount` / `pendingCronCount` ride only on the
+    // `reason=watchdog` teardown, using the same conditional-spread idiom as
+    // `elapsedSinceArmMs`. No null-guard is needed: `startOrResetWatchdog()`
+    // has exactly one call site (the defer branch below), and that branch
+    // always writes `lastDeferredCounts` BEFORE arming the timer — so a
+    // `reason=watchdog` teardown is only reachable after at least one
+    // deferral, and at least one of the two counts is guaranteed ≥ 1.
+    emitEvent('teardown', {
+        reason,
+        ...(armedAt !== null ? { elapsedSinceArmMs: Date.now() - armedAt } : {}),
+        ...(reason === TEARDOWN_REASONS.WATCHDOG && lastDeferredCounts !== null
+            ? { pendingBgCount: lastDeferredCounts.bgCount, pendingCronCount: lastDeferredCounts.cronCount }
+            : {})
+    });
     if (watchdogTimer) { clearTimeout(watchdogTimer); watchdogTimer = null; }
     stopPolling();
     if (ptyProcess) ptyProcess.kill('SIGINT');
@@ -413,12 +490,12 @@ process.on('SIGUSR1', () => {
     const payload = readSentinelPayload(sentinelPath);
     if (!payload) {
         log(`Warning: failed to read sentinel, proceeding with teardown`);
-        teardown();
+        teardown(TEARDOWN_REASONS.SENTINEL_UNREADABLE);
         return;
     }
     if (payload.error) {
         log(`StopFailure received: error=${payload.error}`);
-        teardown();
+        teardown(TEARDOWN_REASONS.STOP_FAILURE);
         return;
     }
     const bgCount = Array.isArray(payload.background_tasks) ? payload.background_tasks.length : 0;
@@ -426,10 +503,14 @@ process.on('SIGUSR1', () => {
     log(`Sentinel: background_tasks=${bgCount}, session_crons=${cronCount}`);
     if (hasPendingWork(payload)) {
         log('Deferring teardown: pending background work');
+        // As1012 Task 13 — capture BEFORE arming so the counts are already in
+        // place if the timer subsequently fires. Members named to match the
+        // locals above; the lift is a zero-translation copy.
+        lastDeferredCounts = { bgCount, cronCount };
         startOrResetWatchdog();
         return;
     }
-    teardown();
+    teardown(TEARDOWN_REASONS.STOP);
 });
 
 writeFileSync(wrapperPidPath, String(process.pid));
@@ -654,6 +735,7 @@ const emitResult = (hookData) => {
         effectiveSessionId,
         startedAt,
         endedAt,
+        teardownReason,
         alreadyEmitted: resultEmitted || failureEmitted,
         suppressFallback: SUPPRESS_STOP_FALLBACK,
         log
@@ -733,6 +815,10 @@ ptyProcess.onExit(({ exitCode }) => {
     // teardown() never ran on this path (Stop hook did not fire), so `endedAt` is
     // unset and `durationMs` is deliberately omitted from the emission — the
     // service appends the pre-existing `'0'` duration sentinel (Decision D3).
+    // As1063 Task 1 item 9: track whether this branch was the one that set
+    // failureEmitted so the onExit-branch diagnostic below can distinguish
+    // `matched-prompt-too-long` from `emitted-failure` (both set the flag).
+    let matchedPromptTooLong = false;
     if (!resultEmitted && !failureEmitted && ttyBuffer.includes('Prompt is too long')) {
         log('Prompt-too-long: omitting durationMs (teardown() never ran, endedAt unset)');
         process.stdout.write(JSON.stringify({
@@ -741,11 +827,30 @@ ptyProcess.onExit(({ exitCode }) => {
             message: 'Prompt is too long'
         }) + '\n');
         failureEmitted = true;
+        matchedPromptTooLong = true;
     }
 
     // Clean up temp directory
     try { rmSync(tempDir, { recursive: true, force: true }); } catch {}
 
+    // As1063 Task 1 item 9: emit which onExit branch was taken along with
+    // the wrapper exit reason (teardownReason) and a bounded ttyBuffer tail.
+    // Bounded per lifecycle event by the `exited` guard at the top of onExit
+    // (no unbounded per-turn accumulation). Written to stderr via log() so
+    // JobRunner's stderr splitter captures it into the outputTail without
+    // affecting the wrapper's stdout emission contract.
+    const branchTaken = resultEmitted
+        ? 'emitted-result'
+        : matchedPromptTooLong
+            ? 'matched-prompt-too-long'
+            : failureEmitted
+                ? 'emitted-failure'
+                : 'no-emission';
+    // Cap the tty tail to 256 chars and escape newlines so the line stays on
+    // one log entry regardless of what claude last wrote.
+    const ttyTail = ttyBuffer.slice(-256).replace(/\n/g, '\\n').replace(/\r/g, '\\r');
+    log(`onExit-branch: ${branchTaken} exitCode=${exitCode} teardownReason=${teardownReason ?? 'unset'} ttyTail="${ttyTail}"`);
+
     log(`Claude exited (code: ${exitCode})`);
 
     if (failureEmitted) {