@kelceyp/caw-server 1.0.288 → 1.0.290

package/dist/pty-emit-result.mjs

@@ -14,30 +14,136 @@
  * `hookData`; a null / falsy `hookData` is a no-op, mirroring the wrapper's
  * pre-extraction `if (!existsSync(sentinelPath)) return;` guard one level up.
  *
- * Wire is preserved byte-for-byte relative to the pre-extraction wrapper:
- *   - success line: `{ type: 'result', result, metadata }` with
- *     `metadata = { sessionId, transcriptPath, permissionMode[, durationMs] }`
- *     — same field set, same field order, same fallback chains
- *     (`hookData.transcript_path || transcriptPath || null`,
- *      `hookData.session_id || effectiveSessionId`, `hookData.permission_mode || null`).
- *   - error line: `{ type: 'error', error, message }` — same shape, no
- *     `metadata` field at all.
+ * Wire. This function writes at most one line, of one of two shapes:
+ *   - success line (Stop):
+ *     `{ type: 'result', result, metadata, stopFallback }`.
+ *   - error line (StopFailure, `hookData.error` truthy):
+ *     `{ type: 'error', error, message[, error_details], metadata, stopFallback }`
+ *     (As1071 design S4). `error_details` is the StopFailure payload's own
+ *     `error_details`, copied verbatim (any JSON type, `null` included) and
+ *     only when the payload has the key; it is diagnostic evidence, never a
+ *     reset-time source. The success line never carries it.
+ * Both lines get `metadata` from the one builder, `buildMetadata()`, so the two
+ * cannot drift: `{ sessionId, transcriptPath, permissionMode[, durationMs][, teardownReason] }`
+ * (`durationMs` when both timestamps are given, `teardownReason` when the
+ * wrapper passes one, omitted rather than `null` otherwise; fallback chains
+ * `hookData.session_id || effectiveSessionId`,
+ * `hookData.transcript_path || transcriptPath || null`,
+ * `hookData.permission_mode || null`). On a real StopFailure turn the wrapper
+ * passes `teardownReason: 'stop-failure'` and both timestamps, so the error
+ * line meets `teardownReasons.mjs` contract point 2 too.
+ * `stopFallback` (As1072) is appended as the LAST top-level key of both lines
+ * and is not a `metadata` key. The success line is the pre-As1072 line with
+ * that one key added before its closing brace. The no-op paths
+ * (`alreadyEmitted`, a falsy `hookData`, and the `catch` below) write no line
+ * at all.
  *
  * The double-emit guard (previously `if (resultEmitted || failureEmitted) return;`
  * at `pty-wrapper.mjs:401`) is preserved via the `alreadyEmitted` input: the
  * caller passes the current flag state, and the function no-ops when true.
  * The return value `{ emitted: 'result' | 'error' | null }` lets the caller
  * translate a successful call back into its module-level `resultEmitted` /
- * `failureEmitted` flags. After As1080 Increment A the wrapper no longer has
- * any text-based prompt-rejection branch, so this delegator is the sole
- * emitter of `{ type: 'error', ... }` lines on the wrapper's stdout — a
- * genuine API-level rejection reaches it only when the Stop-hook sentinel
+ * `failureEmitted` flags. This is not the wrapper's only writer of
+ * `{ type: 'error', ... }` lines: As1080's `prompt-rejection-detector.mjs`
+ * writes its own `prompt_too_long` line, which does not pass through here. A
+ * vendor StopFailure reaches this function only when the Stop-hook sentinel
  * carries a structured `error` field.
  */
 
+// --- stopFallback vocabulary (As1072) ---
+//
+// What happened to the Stop-hook `last_assistant_message` fallback on a turn.
+// The wrapper writes the value on its own terminal line, so the component that
+// holds `hookData` is the one that decides it:
+//   - `present` / `empty` / `absent` / `invalid` — written by `emitResult()` on
+//     both lines, from `deriveStopFallback()`;
+//   - `suppressed` — written by `emitResult()` on the success line only, when
+//     the CAW_PTY_SUPPRESS_STOP_FALLBACK test override is set;
+//   - `not-emitted` — NEVER written by the wrapper. No terminal line exists to
+//     carry it, so only `claude-session.js` derives it, from the absence of a
+//     `result` / `error` line.
+// `unknown` is deliberately in NEITHER export below. It is the record layer's
+// sentinel (`sentinels.js`) with one writer, `JobService.updateJobMetadata`,
+// which uses it when no value reached the record. Adding it here would create
+// a second writer.
+// The vocabulary lives in this module, the only wrapper-side writer, so the
+// wrapper's import closure (and with it `build:all` and `Dockerfile.session`)
+// does not grow.
+
+export const STOP_FALLBACK = Object.freeze({
+    PRESENT:     'present',
+    EMPTY:       'empty',
+    ABSENT:      'absent',
+    INVALID:     'invalid',
+    SUPPRESSED:  'suppressed',
+    NOT_EMITTED: 'not-emitted',   // derived by claude-session.js; never written by the wrapper
+});
+
+// Exactly the values a wrapper line may carry; claude-session.js accepts only these.
+// A frozen array, not a Set: Object.freeze does not stop Set.prototype.add/delete.
+export const STOP_FALLBACK_WIRE_VALUES = Object.freeze([
+    STOP_FALLBACK.PRESENT,
+    STOP_FALLBACK.EMPTY,
+    STOP_FALLBACK.ABSENT,
+    STOP_FALLBACK.INVALID,
+    STOP_FALLBACK.SUPPRESSED,
+]);
+
+export const isStopFallbackWireValue = (value) =>
+    typeof value === 'string' && STOP_FALLBACK_WIRE_VALUES.includes(value);
+
+/**
+ * Classify the Stop / StopFailure payload's `last_assistant_message` by own-key
+ * presence, not truthiness. First match wins:
+ *   1. `suppressFallback` set                            → `suppressed`
+ *   2. not an own key, or own with value `undefined`     → `absent`
+ *   3. not a string (`null` included)                    → `invalid`
+ *   4. `''`                                              → `empty`
+ *   5. any other string (whitespace-only included)       → `present`
+ *
+ * An own `undefined` is `absent` (As1072 KD3): `hookData` is parsed JSON, which
+ * cannot carry one, and the vendor serialises an `undefined` value as a missing
+ * key. Total: an omitted options argument means no override; a `hookData` that
+ * cannot hold the own key (`undefined`, `null`, a primitive, an array) is
+ * `absent`; it never throws and only returns wire values. `emitResult()` passes
+ * `suppressFallback` on the success branch only.
+ */
+export const deriveStopFallback = (hookData, options) => {
+    if (options?.suppressFallback) return STOP_FALLBACK.SUPPRESSED;
+    if (hookData === null || hookData === undefined) return STOP_FALLBACK.ABSENT;
+    if (!Object.hasOwn(hookData, 'last_assistant_message')) return STOP_FALLBACK.ABSENT;
+    const value = hookData.last_assistant_message;
+    if (value === undefined) return STOP_FALLBACK.ABSENT;
+    if (typeof value !== 'string') return STOP_FALLBACK.INVALID;
+    if (value === '') return STOP_FALLBACK.EMPTY;
+    return STOP_FALLBACK.PRESENT;
+};
+
 const defaultWrite = (line) => process.stdout.write(line);
 const defaultLog = () => {};
 
+// The one `metadata` builder both lines use (As1071 S4). Field order is part
+// of the success line's wire, which must stay byte-identical.
+const buildMetadata = ({ hookData, transcriptPath, effectiveSessionId, startedAt, endedAt, teardownReason }) => {
+    const metadata = {
+        sessionId: hookData.session_id || effectiveSessionId,
+        transcriptPath: hookData.transcript_path || transcriptPath || null,
+        permissionMode: hookData.permission_mode || null
+    };
+    if (startedAt !== null && endedAt !== null) {
+        metadata.durationMs = endedAt - startedAt;
+    }
+    // As1033 Task 6: append teardownReason ('stop' | 'watchdog' |
+    // 'stop-failure' | ...) so the downstream stream handler and the
+    // JobRunner classifier gate can distinguish a clean Stop finish from a
+    // watchdog force-kill. Omitted, never `null`, when the wrapper passes
+    // none (`teardownReasons.mjs` contract point 3).
+    if (teardownReason !== null) {
+        metadata.teardownReason = teardownReason;
+    }
+    return metadata;
+};
+
 export function emitResult({
     hookData,
     transcriptPath = null,
@@ -54,41 +160,41 @@ export function emitResult({
     if (!hookData) return { emitted: null };
 
     try {
+        const metadataInputs = { hookData, transcriptPath, effectiveSessionId, startedAt, endedAt, teardownReason };
+
         if (hookData.error) {
-            write(JSON.stringify({
+            const line = {
                 type: 'error',
                 error: hookData.error,
                 message: hookData.last_assistant_message || ''
-            }) + '\n');
+            };
+            // Present-only and verbatim (As1071 S4): own-key presence, not
+            // truthiness, so `null`, `false`, `0` and `''` are copied as-is.
+            if (Object.hasOwn(hookData, 'error_details')) {
+                line.error_details = hookData.error_details;
+            }
+            line.metadata = buildMetadata(metadataInputs);
+            // No override on this branch (KD7): the line records the payload's
+            // real state, never `suppressed`.
+            line.stopFallback = deriveStopFallback(hookData);
+            write(JSON.stringify(line) + '\n');
             return { emitted: 'error' };
         }
 
-        const metadata = {
-            sessionId: hookData.session_id || effectiveSessionId,
-            transcriptPath: hookData.transcript_path || transcriptPath || null,
-            permissionMode: hookData.permission_mode || null
-        };
-        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;
-        }
+        const metadata = buildMetadata(metadataInputs);
         // 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
-        // the point of the override. Metadata, field order, and everything else
-        // stay byte-for-byte identical (Task 3's guarantee).
+        // line still declares itself (As1072): `stopFallback: 'suppressed'`,
+        // whatever the payload held, so the record can tell the override from a
+        // real payload. `result` is still `''`, so the As1005 D11 transcript-tail
+        // + override combination still reaches the loud empty-turn failure
+        // downstream. `metadata` is untouched.
         const result = suppressFallback ? '' : (hookData.last_assistant_message || '');
         write(JSON.stringify({
             type: 'result',
             result,
-            metadata
+            metadata,
+            stopFallback: deriveStopFallback(hookData, { suppressFallback })
         }) + '\n');
         return { emitted: 'result' };
     } catch (err) {

package/dist/pty-non-interactive-setup.mjs

@@ -7,14 +7,22 @@
  * `--skip-non-interactive-setup`.
  *
  * Fail-fast / atomic / idempotent write contract (As1016):
+ *   - `CLAUDE_CONFIG_DIR` refused → before any filesystem access, throw the
+ *     As1065 guard's own error (`assertClaudeConfigDirForwardable` in
+ *     `claude-config-dir-guard.mjs`), whose message starts with
+ *     `CLAUDE_CONFIG_DIR_REFUSED (<RULE>): ...`. This module does not own
+ *     the config-dir check; it delegates to the guard, the same predicate
+ *     the claude strategies' direct-mode `validatePrerequisites` apply.
  *   - Absent  → seed with data = {} and mode 0o644, then atomic write.
  *   - Present but stat/read/parse fails (with one-shot SyntaxError retry) →
  *     throw a typed error whose message starts with
- *     `CLAUDE_JSON_UNREADABLE (<code>): <path>. ...`. No write. The wrapper's
- *     discriminating catch (pty-wrapper.mjs `:316`) re-emits `err.message + '\n'`
- *     to stderr and calls `process.exit(1)` — byte-for-byte identical to
- *     today's inline behaviour. Non-`CLAUDE_JSON_UNREADABLE` errors are
- *     rethrown by the wrapper.
+ *     `CLAUDE_JSON_UNREADABLE (<code>): <path>. ...`. No write.
+ *   - The wrapper's discriminating catch (the `ensureNonInteractiveSetup`
+ *     call site in `pty-wrapper.mjs`) classifies both prefixes,
+ *     `CLAUDE_JSON_UNREADABLE` and `CLAUDE_CONFIG_DIR_REFUSED`: it re-emits
+ *     `err.message + '\n'` to stderr and calls `process.exit(1)` —
+ *     byte-for-byte identical to today's inline behaviour. Every other
+ *     error is rethrown by the wrapper.
  *   - Present and read succeeded → apply the guarded mutations; short-circuit
  *     via the idempotent guard when both onboarding and every trust-set entry
  *     are already recorded.
@@ -36,7 +44,9 @@
  * from `server/dist/`, and the wrapper carries its own inline copy for the
  * same reason. Three co-located literals (`shared/jobErrorPrefixes.js`,
  * `pty-wrapper.mjs`, this module) must stay in sync per As1016 D8 (extended
- * from dual- to triple-literal by this commit).
+ * from dual- to triple-literal by this commit). The
+ * `CLAUDE_CONFIG_DIR_REFUSED` prefix is not carried here: it lives in the
+ * guard (literal copy 2 of 2; copy 1 is in `shared/jobErrorPrefixes.js`).
  */
 
 import {
@@ -53,6 +63,7 @@ import {
     readdirSync,
 } from 'fs';
 import { join, dirname, basename, resolve, isAbsolute } from 'path';
+import { assertClaudeConfigDirForwardable } from './claude-config-dir-guard.mjs';
 
 export const CLAUDE_JSON_UNREADABLE_PREFIX = 'CLAUDE_JSON_UNREADABLE';
 
@@ -83,18 +94,19 @@ export const ensureNonInteractiveSetup = (cwd, { home, configDir, log = noopLog
     // not consult, silently defeating both the setup and the mutex that
     // serialises writes to it. Route the seed through `$CLAUDE_CONFIG_DIR`
     // when it is present, else fall back to `$HOME` (Task 3 pre-AC-19
-    // behaviour). Absolute-path validation on `configDir` matches `home`'s
-    // fail-fast shape so the wrapper's discriminating catch classifies both
-    // identically.
-    let baseDir = home;
-    if (configDir !== undefined && configDir !== null) {
-        if (typeof configDir !== 'string' || configDir.length === 0 || !isAbsolute(configDir)) {
-            throw new Error(
-                `${CLAUDE_JSON_UNREADABLE_PREFIX} (CLAUDE_CONFIG_DIR_INVALID): CLAUDE_CONFIG_DIR is set but is not an absolute path (got ${JSON.stringify(configDir)}). Unset it or point it at an absolute path, then retry.`
-            );
-        }
-        baseDir = configDir;
-    }
+    // behaviour).
+    //
+    // The value check belongs to the As1065 guard
+    // (`assertClaudeConfigDirForwardable`), the same predicate the claude
+    // strategies' direct-mode `validatePrerequisites` apply. A refused value
+    // throws the guard's own `CLAUDE_CONFIG_DIR_REFUSED (<RULE>): ...` error,
+    // unwrapped, before anything below touches the filesystem; the wrapper's
+    // discriminating catch classifies that prefix alongside
+    // `CLAUDE_JSON_UNREADABLE`. `configDir` is `string | undefined`: a
+    // non-string, including `null`, throws the guard's `TypeError` (As1065
+    // KD5).
+    assertClaudeConfigDirForwardable(configDir);
+    const baseDir = configDir === undefined ? home : configDir;
 
     const nominal = join(baseDir, '.claude.json');
 

package/dist/pty-wrapper.mjs

@@ -27,6 +27,7 @@ import { readSentinelPayload, hasPendingWork } from './pty-deferred-teardown.mjs
 import { emitResult as emitResultLine } from './pty-emit-result.mjs';
 import { TEARDOWN_REASONS } from './teardownReasons.mjs';
 import { ensureNonInteractiveSetup } from './pty-non-interactive-setup.mjs';
+import { CLAUDE_CONFIG_DIR_REFUSED_PREFIX } from './claude-config-dir-guard.mjs';
 import { createTranscriptTailer } from './transcript-tailer.mjs';
 import { createPromptRejectionDetector } from './prompt-rejection-detector.mjs';
 
@@ -91,8 +92,10 @@ try {
 // (`claude-session.js#getDockerConfig`'s `commandParts` omits it by
 // design), so the in-container wrapper still runs the setup itself. This
 // wrapper's local call site preserves the same discriminating catch that
-// re-emits classified `CLAUDE_JSON_UNREADABLE` errors byte-for-byte with
-// today's stderr + exit contract and rethrows every other error. See As1016
+// re-emits classified errors byte-for-byte with today's stderr + exit
+// contract and rethrows every other error. Two prefixes are classified:
+// `CLAUDE_JSON_UNREADABLE` (As1016) and `CLAUDE_CONFIG_DIR_REFUSED` (As1065,
+// the guard's refusal of the container's own `CLAUDE_CONFIG_DIR`). See As1016
 // for the fail-fast / atomic / idempotent invariants that module preserves.
 //
 // The invocation stays here (post log()/stdin-drain/claude-binary,
@@ -117,6 +120,12 @@ try {
 // `server/dist/`, and the wrapper keeps this local const so the
 // discriminating catch below can classify without importing the sibling's
 // export. Keep all three literals in sync per As1016 D8.
+//
+// The second classified prefix, `CLAUDE_CONFIG_DIR_REFUSED_PREFIX`, is NOT
+// carried as a literal here: it is imported above from
+// `./claude-config-dir-guard.mjs`, which is already in this wrapper's
+// closure via `pty-non-interactive-setup.mjs`. It has exactly two literals
+// (`shared/jobErrorPrefixes.js` and the guard; As1065 KD4).
 const CLAUDE_JSON_UNREADABLE_PREFIX = 'CLAUDE_JSON_UNREADABLE';
 
 // As1050 Commit B (C3) — the `--skip-non-interactive-setup` CLI arg is
@@ -138,14 +147,20 @@ if (!hasFlag('--skip-non-interactive-setup')) {
             log
         });
     } catch (err) {
-        // Discriminating catch: only classified `CLAUDE_JSON_UNREADABLE`-prefixed
-        // throws are re-emitted to stderr as a fail-fast (matching today's
+        // Discriminating catch: only throws with one of the two classified
+        // prefixes are re-emitted to stderr as a fail-fast (matching today's
         // process.stderr.write + process.exit(1) contract byte-for-byte; the
         // extracted module's `.message` omits the trailing `\n` that the wrapper
-        // concatenates here). All other errors are RETHROWN — the wrapper does
-        // NOT swallow them, so today's uncaught-exception behaviour on
-        // non-`CLAUDE_JSON_UNREADABLE` failures is preserved.
-        if (err && typeof err.message === 'string' && err.message.startsWith(CLAUDE_JSON_UNREADABLE_PREFIX)) {
+        // concatenates here):
+        //   - `CLAUDE_JSON_UNREADABLE` — the As1016 file-level and `HOME_UNSET`
+        //     fail-fast branches;
+        //   - `CLAUDE_CONFIG_DIR_REFUSED` — the As1065 guard refusing the
+        //     container's own `CLAUDE_CONFIG_DIR` (`ensureNonInteractiveSetup`
+        //     delegates its config-dir check to `assertClaudeConfigDirForwardable`).
+        // All other errors are RETHROWN — the wrapper does NOT swallow them, so
+        // today's uncaught-exception behaviour on unclassified failures is
+        // preserved.
+        if (err && typeof err.message === 'string' && (err.message.startsWith(CLAUDE_JSON_UNREADABLE_PREFIX) || err.message.startsWith(CLAUDE_CONFIG_DIR_REFUSED_PREFIX))) {
             process.stderr.write(err.message + '\n');
             process.exit(1);
         }
@@ -204,7 +219,12 @@ const WATCHDOG_TIMEOUT_MS = Number.parseInt(process.env.CAW_PTY_WATCHDOG_TIMEOUT
 //   fallback consumes `result` instead of the missing transcript stream.
 // CAW_PTY_SUPPRESS_STOP_FALLBACK: blank the emitted `result` field on the
 //   success branch of pty-emit-result (only when hookData is non-null and
-//   the success branch runs). Used to prove the AC-5 gate downstream.
+//   the success branch runs). The line declares the override as
+//   `stopFallback: 'suppressed'` (As1072), so it is not mistaken for a real
+//   empty-message turn; the error branch is never affected. Used to prove the
+//   AC-5 gate downstream: `result` is still `''`, so with
+//   CAW_PTY_DISABLE_TRANSCRIPT_TAIL the turn still reaches the loud empty-turn
+//   failure.
 const DISABLE_TRANSCRIPT_TAIL = process.env.CAW_PTY_DISABLE_TRANSCRIPT_TAIL === '1';
 const SUPPRESS_STOP_FALLBACK = process.env.CAW_PTY_SUPPRESS_STOP_FALLBACK === '1';