@kelceyp/caw-server 1.0.289 → 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-wrapper.mjs

@@ -219,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';