hammoc 1.8.4 → 1.9.0

package/packages/server/dist/utils/residencyActivation.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Story 38.7 — pure decision helpers for turn-flow residency ACTIVATION.
+ *
+ * Story 38.5 delivered the resident-engine registry + resource policy as a "ready
+ * seam" but never wired it into the turn flow (`chat:send` still re-spawned an
+ * engine every turn). This story turns it on. The two branch decisions that gate
+ * activation — "reuse the live resident engine vs create a fresh one" and "register
+ * a freshly-created engine as resident now vs at re-key" — are kept PURE here so
+ * they can be unit-tested WITHOUT the (pre-red) websocket socket harness, exactly
+ * as Story 38.3 (stopStrategy.ts) and 38.4 (runtimeParamStrategy.ts) did for their
+ * own branch logic. The stateful wiring that consumes these verdicts lives in
+ * handlers/websocket.ts; the engine lifecycle lives in
+ * services/engineResidencyRegistry.ts.
+ */
+/**
+ * Whether `handleChatSend` should REUSE the live resident engine for this session
+ * instead of creating (and ~3s re-spawning) a fresh one.
+ *
+ * Reuse only when ALL hold:
+ *  - `hasLiveResident` — the registry returned a live engine for this session
+ *    (a crashed/dead one was already dropped by `registry.get`, so a hit means live).
+ *  - not CLI — residency is SDK-engine-only (the CLI PTY lifecycle is untouched;
+ *    a CLI engine never registers, so this is a belt-and-suspenders guard).
+ *  - not a fork — `forkSession` is a query() CREATION option (no live-query setter,
+ *    38.5 probe), so a fork is inherently a NEW query for a NEW session; it must not
+ *    ride the original session's resident engine.
+ *  - not a branch/rewind — `resumeSessionAt` (conversation branching) and
+ *    `rewindToMessageUuid` (inline rewind-before-send) are likewise query() CREATION
+ *    options applied only when the persistent query is first built. Reusing a live
+ *    query would silently ignore them, so force a fresh (registry-replacing) query.
+ *
+ * Note there is no separate `isResuming` input: a resume whose target is already
+ * resident simply continues on that live engine (the `resume` option is only needed
+ * to rebuild a NON-resident session from JSONL), so `hasLiveResident` already
+ * captures it. A resume that also branches/rewinds is caught by `isBranchOrRewind`.
+ */
+export declare function shouldReuseResidentEngine(params: {
+    hasLiveResident: boolean;
+    engineMode: string | undefined;
+    isFork: boolean;
+    isBranchOrRewind: boolean;
+}): boolean;
+/**
+ * Whether a FRESHLY-CREATED engine should be registered as resident immediately at
+ * creation (before the send) rather than deferred.
+ *
+ * Registering before the send is what makes the engine `resident` so its callback
+ * path SKIPS the turn-end `close()` and the process survives into the next turn.
+ *
+ *  - SDK only — the CLI engine has no residency hooks (`register` is a feature-detect
+ *    no-op anyway; this keeps the caller from even trying).
+ *  - not a fork — a fork's final sessionId is unknown until the SDK assigns it, and
+ *    registering under the ORIGINAL session key at creation would clobber the
+ *    original's resident entry. A fork is therefore registered under its assigned id
+ *    at re-key time instead (see the websocket re-key mirror), not here.
+ */
+export declare function shouldRegisterOnCreate(params: {
+    engineMode: string | undefined;
+    isFork: boolean;
+}): boolean;
+//# sourceMappingURL=residencyActivation.d.ts.map

package/packages/server/dist/utils/residencyActivation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"residencyActivation.d.ts","sourceRoot":"","sources":["../../src/utils/residencyActivation.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,yBAAyB,CAAC,MAAM,EAAE;IAChD,eAAe,EAAE,OAAO,CAAC;IACzB,UAAU,EAAE,MAAM,GAAG,SAAS,CAAC;IAC/B,MAAM,EAAE,OAAO,CAAC;IAChB,gBAAgB,EAAE,OAAO,CAAC;CAC3B,GAAG,OAAO,CAOV;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,sBAAsB,CAAC,MAAM,EAAE;IAC7C,UAAU,EAAE,MAAM,GAAG,SAAS,CAAC;IAC/B,MAAM,EAAE,OAAO,CAAC;CACjB,GAAG,OAAO,CAEV"}

package/packages/server/dist/utils/residencyActivation.js

@@ -0,0 +1,60 @@
+/**
+ * Story 38.7 — pure decision helpers for turn-flow residency ACTIVATION.
+ *
+ * Story 38.5 delivered the resident-engine registry + resource policy as a "ready
+ * seam" but never wired it into the turn flow (`chat:send` still re-spawned an
+ * engine every turn). This story turns it on. The two branch decisions that gate
+ * activation — "reuse the live resident engine vs create a fresh one" and "register
+ * a freshly-created engine as resident now vs at re-key" — are kept PURE here so
+ * they can be unit-tested WITHOUT the (pre-red) websocket socket harness, exactly
+ * as Story 38.3 (stopStrategy.ts) and 38.4 (runtimeParamStrategy.ts) did for their
+ * own branch logic. The stateful wiring that consumes these verdicts lives in
+ * handlers/websocket.ts; the engine lifecycle lives in
+ * services/engineResidencyRegistry.ts.
+ */
+/**
+ * Whether `handleChatSend` should REUSE the live resident engine for this session
+ * instead of creating (and ~3s re-spawning) a fresh one.
+ *
+ * Reuse only when ALL hold:
+ *  - `hasLiveResident` — the registry returned a live engine for this session
+ *    (a crashed/dead one was already dropped by `registry.get`, so a hit means live).
+ *  - not CLI — residency is SDK-engine-only (the CLI PTY lifecycle is untouched;
+ *    a CLI engine never registers, so this is a belt-and-suspenders guard).
+ *  - not a fork — `forkSession` is a query() CREATION option (no live-query setter,
+ *    38.5 probe), so a fork is inherently a NEW query for a NEW session; it must not
+ *    ride the original session's resident engine.
+ *  - not a branch/rewind — `resumeSessionAt` (conversation branching) and
+ *    `rewindToMessageUuid` (inline rewind-before-send) are likewise query() CREATION
+ *    options applied only when the persistent query is first built. Reusing a live
+ *    query would silently ignore them, so force a fresh (registry-replacing) query.
+ *
+ * Note there is no separate `isResuming` input: a resume whose target is already
+ * resident simply continues on that live engine (the `resume` option is only needed
+ * to rebuild a NON-resident session from JSONL), so `hasLiveResident` already
+ * captures it. A resume that also branches/rewinds is caught by `isBranchOrRewind`.
+ */
+export function shouldReuseResidentEngine(params) {
+    return (params.hasLiveResident &&
+        params.engineMode !== 'cli' &&
+        !params.isFork &&
+        !params.isBranchOrRewind);
+}
+/**
+ * Whether a FRESHLY-CREATED engine should be registered as resident immediately at
+ * creation (before the send) rather than deferred.
+ *
+ * Registering before the send is what makes the engine `resident` so its callback
+ * path SKIPS the turn-end `close()` and the process survives into the next turn.
+ *
+ *  - SDK only — the CLI engine has no residency hooks (`register` is a feature-detect
+ *    no-op anyway; this keeps the caller from even trying).
+ *  - not a fork — a fork's final sessionId is unknown until the SDK assigns it, and
+ *    registering under the ORIGINAL session key at creation would clobber the
+ *    original's resident entry. A fork is therefore registered under its assigned id
+ *    at re-key time instead (see the websocket re-key mirror), not here.
+ */
+export function shouldRegisterOnCreate(params) {
+    return params.engineMode === 'sdk' && !params.isFork;
+}
+//# sourceMappingURL=residencyActivation.js.map

package/packages/server/dist/utils/residencyActivation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"residencyActivation.js","sourceRoot":"","sources":["../../src/utils/residencyActivation.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,UAAU,yBAAyB,CAAC,MAKzC;IACC,OAAO,CACL,MAAM,CAAC,eAAe;QACtB,MAAM,CAAC,UAAU,KAAK,KAAK;QAC3B,CAAC,MAAM,CAAC,MAAM;QACd,CAAC,MAAM,CAAC,gBAAgB,CACzB,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,sBAAsB,CAAC,MAGtC;IACC,OAAO,MAAM,CAAC,UAAU,KAAK,KAAK,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC;AACvD,CAAC"}

package/packages/server/dist/utils/residencyPolicy.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Story 38.5 (Task 6a/6b) — resident-engine resource policy, as a PURE classifier.
+ *
+ * Under turn-boundary process residency the server keeps one SDK engine process
+ * alive per active session (no ~3s re-spawn between turns — probe-confirmed GO).
+ * That residency MUST be bounded, or idle sessions accumulate engine processes
+ * without limit ("무정책 상주 금지"). Two independent bounds:
+ *
+ *   (a) idle timeout — a session with no turn activity for `idleTimeoutMs` is
+ *       closed and dropped; the next send naturally resumes it from JSONL.
+ *   (b) count cap    — at most `maxEngines` resident engines; when a new one would
+ *       exceed the cap, evict the LEAST-recently-active (LRU) sessions first.
+ *
+ * This is server-side *process lifecycle* management (how long a spawned engine
+ * lives), NOT traffic shaping (rate-limiting inbound requests) — the latter is
+ * infra/reverse-proxy territory. Kept pure (no timers, no engine handles, no
+ * socket deps) so the eviction/idle decisions are unit-testable without the
+ * (pre-red) websocket harness — same discipline as stopStrategy.ts /
+ * runtimeParamStrategy.ts. The stateful registry that HOLDS the engines and acts
+ * on these verdicts lives in services/engineResidencyRegistry.ts.
+ */
+/** Minimal shape the policy needs about a resident engine — just its liveness clock. */
+export interface ResidencyEntryInfo {
+    sessionId: string;
+    /** Wall-clock ms of the last turn activity on this session (Date.now() at touch). */
+    lastActivityAt: number;
+}
+/** Tunable bounds. `idleTimeoutMs <= 0` disables the idle sweep; `maxEngines <= 0` disables the cap. */
+export interface ResidencyPolicyConfig {
+    idleTimeoutMs: number;
+    maxEngines: number;
+}
+/** Hard floor/ceiling so a misconfigured preference can't disable bounding in a dangerous way. */
+export declare const RESIDENCY_LIMITS: {
+    /** Below this an idle timeout is treated as "disabled" (0) rather than an absurd churn. */
+    readonly MIN_IDLE_TIMEOUT_MS: 10000;
+    /** Absolute ceiling on resident engines regardless of preference (memory guard). */
+    readonly MAX_ENGINES_CEILING: 64;
+};
+/**
+ * Normalize a raw config (e.g. from preferences) into a safe effective policy:
+ * an idle timeout under the floor (but > 0) is lifted to the floor; the count cap
+ * is clamped to the ceiling. 0/negative means "disabled" for that bound and is
+ * preserved as-is.
+ */
+export declare function normalizeResidencyConfig(raw: Partial<ResidencyPolicyConfig>): ResidencyPolicyConfig;
+/**
+ * Session ids whose last activity is older than the idle timeout at `now`.
+ * Returns [] when the idle sweep is disabled (`idleTimeoutMs <= 0`). Order is
+ * oldest-first so callers can log/act deterministically.
+ */
+export declare function selectIdleExpired(entries: readonly ResidencyEntryInfo[], idleTimeoutMs: number, now: number): string[];
+/**
+ * LRU sessions to evict so that, after ADDING `incoming` new engines, the resident
+ * count does not exceed `maxEngines`. `incoming` defaults to 0 (pure over-cap
+ * trim of the current set). Sessions in `protectedIds` are never selected (e.g.
+ * the session whose turn is starting right now) — they still COUNT toward the cap,
+ * so more of the remaining LRU entries are evicted to make room. Returns
+ * oldest-first (the eviction order); [] when the cap is disabled or not exceeded.
+ */
+export declare function selectLruEvictions(entries: readonly ResidencyEntryInfo[], maxEngines: number, incoming?: number, protectedIds?: readonly string[]): string[];
+//# sourceMappingURL=residencyPolicy.d.ts.map

package/packages/server/dist/utils/residencyPolicy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"residencyPolicy.d.ts","sourceRoot":"","sources":["../../src/utils/residencyPolicy.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,wFAAwF;AACxF,MAAM,WAAW,kBAAkB;IACjC,SAAS,EAAE,MAAM,CAAC;IAClB,qFAAqF;IACrF,cAAc,EAAE,MAAM,CAAC;CACxB;AAED,wGAAwG;AACxG,MAAM,WAAW,qBAAqB;IACpC,aAAa,EAAE,MAAM,CAAC;IACtB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,kGAAkG;AAClG,eAAO,MAAM,gBAAgB;IAC3B,2FAA2F;;IAE3F,oFAAoF;;CAE5E,CAAC;AAEX;;;;;GAKG;AACH,wBAAgB,wBAAwB,CAAC,GAAG,EAAE,OAAO,CAAC,qBAAqB,CAAC,GAAG,qBAAqB,CAUnG;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAC/B,OAAO,EAAE,SAAS,kBAAkB,EAAE,EACtC,aAAa,EAAE,MAAM,EACrB,GAAG,EAAE,MAAM,GACV,MAAM,EAAE,CAMV;AAED;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAChC,OAAO,EAAE,SAAS,kBAAkB,EAAE,EACtC,UAAU,EAAE,MAAM,EAClB,QAAQ,SAAI,EACZ,YAAY,GAAE,SAAS,MAAM,EAAO,GACnC,MAAM,EAAE,CAcV"}

package/packages/server/dist/utils/residencyPolicy.js

@@ -0,0 +1,82 @@
+/**
+ * Story 38.5 (Task 6a/6b) — resident-engine resource policy, as a PURE classifier.
+ *
+ * Under turn-boundary process residency the server keeps one SDK engine process
+ * alive per active session (no ~3s re-spawn between turns — probe-confirmed GO).
+ * That residency MUST be bounded, or idle sessions accumulate engine processes
+ * without limit ("무정책 상주 금지"). Two independent bounds:
+ *
+ *   (a) idle timeout — a session with no turn activity for `idleTimeoutMs` is
+ *       closed and dropped; the next send naturally resumes it from JSONL.
+ *   (b) count cap    — at most `maxEngines` resident engines; when a new one would
+ *       exceed the cap, evict the LEAST-recently-active (LRU) sessions first.
+ *
+ * This is server-side *process lifecycle* management (how long a spawned engine
+ * lives), NOT traffic shaping (rate-limiting inbound requests) — the latter is
+ * infra/reverse-proxy territory. Kept pure (no timers, no engine handles, no
+ * socket deps) so the eviction/idle decisions are unit-testable without the
+ * (pre-red) websocket harness — same discipline as stopStrategy.ts /
+ * runtimeParamStrategy.ts. The stateful registry that HOLDS the engines and acts
+ * on these verdicts lives in services/engineResidencyRegistry.ts.
+ */
+/** Hard floor/ceiling so a misconfigured preference can't disable bounding in a dangerous way. */
+export const RESIDENCY_LIMITS = {
+    /** Below this an idle timeout is treated as "disabled" (0) rather than an absurd churn. */
+    MIN_IDLE_TIMEOUT_MS: 10_000,
+    /** Absolute ceiling on resident engines regardless of preference (memory guard). */
+    MAX_ENGINES_CEILING: 64,
+};
+/**
+ * Normalize a raw config (e.g. from preferences) into a safe effective policy:
+ * an idle timeout under the floor (but > 0) is lifted to the floor; the count cap
+ * is clamped to the ceiling. 0/negative means "disabled" for that bound and is
+ * preserved as-is.
+ */
+export function normalizeResidencyConfig(raw) {
+    const rawIdle = raw.idleTimeoutMs ?? 0;
+    const idleTimeoutMs = rawIdle <= 0
+        ? 0
+        : Math.max(rawIdle, RESIDENCY_LIMITS.MIN_IDLE_TIMEOUT_MS);
+    const rawMax = raw.maxEngines ?? 0;
+    const maxEngines = rawMax <= 0
+        ? 0
+        : Math.min(rawMax, RESIDENCY_LIMITS.MAX_ENGINES_CEILING);
+    return { idleTimeoutMs, maxEngines };
+}
+/**
+ * Session ids whose last activity is older than the idle timeout at `now`.
+ * Returns [] when the idle sweep is disabled (`idleTimeoutMs <= 0`). Order is
+ * oldest-first so callers can log/act deterministically.
+ */
+export function selectIdleExpired(entries, idleTimeoutMs, now) {
+    if (idleTimeoutMs <= 0)
+        return [];
+    return [...entries]
+        .filter((e) => now - e.lastActivityAt >= idleTimeoutMs)
+        .sort((a, b) => a.lastActivityAt - b.lastActivityAt)
+        .map((e) => e.sessionId);
+}
+/**
+ * LRU sessions to evict so that, after ADDING `incoming` new engines, the resident
+ * count does not exceed `maxEngines`. `incoming` defaults to 0 (pure over-cap
+ * trim of the current set). Sessions in `protectedIds` are never selected (e.g.
+ * the session whose turn is starting right now) — they still COUNT toward the cap,
+ * so more of the remaining LRU entries are evicted to make room. Returns
+ * oldest-first (the eviction order); [] when the cap is disabled or not exceeded.
+ */
+export function selectLruEvictions(entries, maxEngines, incoming = 0, protectedIds = []) {
+    if (maxEngines <= 0)
+        return [];
+    const total = entries.length + incoming;
+    const overflow = total - maxEngines;
+    if (overflow <= 0)
+        return [];
+    const protectedSet = new Set(protectedIds);
+    const evictable = [...entries]
+        .filter((e) => !protectedSet.has(e.sessionId))
+        .sort((a, b) => a.lastActivityAt - b.lastActivityAt);
+    // Cannot evict more than the evictable pool (protected entries stay even if that
+    // means briefly exceeding the cap — the alternative would kill a live turn).
+    return evictable.slice(0, Math.min(overflow, evictable.length)).map((e) => e.sessionId);
+}
+//# sourceMappingURL=residencyPolicy.js.map

package/packages/server/dist/utils/residencyPolicy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"residencyPolicy.js","sourceRoot":"","sources":["../../src/utils/residencyPolicy.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAeH,kGAAkG;AAClG,MAAM,CAAC,MAAM,gBAAgB,GAAG;IAC9B,2FAA2F;IAC3F,mBAAmB,EAAE,MAAM;IAC3B,oFAAoF;IACpF,mBAAmB,EAAE,EAAE;CACf,CAAC;AAEX;;;;;GAKG;AACH,MAAM,UAAU,wBAAwB,CAAC,GAAmC;IAC1E,MAAM,OAAO,GAAG,GAAG,CAAC,aAAa,IAAI,CAAC,CAAC;IACvC,MAAM,aAAa,GAAG,OAAO,IAAI,CAAC;QAChC,CAAC,CAAC,CAAC;QACH,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,OAAO,EAAE,gBAAgB,CAAC,mBAAmB,CAAC,CAAC;IAC5D,MAAM,MAAM,GAAG,GAAG,CAAC,UAAU,IAAI,CAAC,CAAC;IACnC,MAAM,UAAU,GAAG,MAAM,IAAI,CAAC;QAC5B,CAAC,CAAC,CAAC;QACH,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,MAAM,EAAE,gBAAgB,CAAC,mBAAmB,CAAC,CAAC;IAC3D,OAAO,EAAE,aAAa,EAAE,UAAU,EAAE,CAAC;AACvC,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,iBAAiB,CAC/B,OAAsC,EACtC,aAAqB,EACrB,GAAW;IAEX,IAAI,aAAa,IAAI,CAAC;QAAE,OAAO,EAAE,CAAC;IAClC,OAAO,CAAC,GAAG,OAAO,CAAC;SAChB,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,GAAG,CAAC,CAAC,cAAc,IAAI,aAAa,CAAC;SACtD,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,cAAc,GAAG,CAAC,CAAC,cAAc,CAAC;SACnD,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC;AAC7B,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,kBAAkB,CAChC,OAAsC,EACtC,UAAkB,EAClB,QAAQ,GAAG,CAAC,EACZ,eAAkC,EAAE;IAEpC,IAAI,UAAU,IAAI,CAAC;QAAE,OAAO,EAAE,CAAC;IAC/B,MAAM,KAAK,GAAG,OAAO,CAAC,MAAM,GAAG,QAAQ,CAAC;IACxC,MAAM,QAAQ,GAAG,KAAK,GAAG,UAAU,CAAC;IACpC,IAAI,QAAQ,IAAI,CAAC;QAAE,OAAO,EAAE,CAAC;IAE7B,MAAM,YAAY,GAAG,IAAI,GAAG,CAAC,YAAY,CAAC,CAAC;IAC3C,MAAM,SAAS,GAAG,CAAC,GAAG,OAAO,CAAC;SAC3B,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,YAAY,CAAC,GAAG,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC;SAC7C,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,cAAc,GAAG,CAAC,CAAC,cAAc,CAAC,CAAC;IAEvD,iFAAiF;IACjF,6EAA6E;IAC7E,OAAO,SAAS,CAAC,KAAK,CAAC,CAAC,EAAE,IAAI,CAAC,GAAG,CAAC,QAAQ,EAAE,SAAS,CAAC,MAAM,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC;AAC1F,CAAC"}

package/packages/server/dist/utils/runtimeParamStrategy.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Story 38.4 — runtime parameter transition strategy.
+ *
+ * Classifies each mid-session parameter change as either injectable into the
+ * LIVE persistent query via a runtime setter (no process restart, no ~3s
+ * relaunch) or requiring a generator restart (a fresh query — the session /
+ * conversation is preserved, only the underlying generation process restarts).
+ *
+ * The classification is the probe-confirmed GO/NO-GO verdict from
+ * `scripts/probe-persistent-hooks.mjs runtime` (feedback_sdk_verify — measured,
+ * not assumed):
+ *
+ *   · model          → runtime-inject  (Query.setModel — GO: the next turn's
+ *                                        response reports the new model id)
+ *   · permissionMode  → runtime-inject  (Query.setPermissionMode — GO, in place
+ *                                        since Story 37.5; survives the
+ *                                        persistent stream)
+ *   · thinking        → runtime-inject  (Query.setMaxThinkingTokens — GO, but no
+ *                                        caller changes it mid-turn today; the
+ *                                        budget is derived at query creation from
+ *                                        the model + showThinkingBlocks pref, so
+ *                                        it stays a creation option — capability
+ *                                        confirmed, wiring deferred)
+ *   · effort          → restart         (the Query interface has NO setEffort —
+ *                                        effort is a query() creation option only,
+ *                                        so a change is inherently NO-GO for
+ *                                        runtime injection and falls back to a
+ *                                        generator restart)
+ *
+ * This is a PURE classifier (no SDK / socket dependency) so the "runtime inject
+ * vs fallback" branch (AC3) is unit-testable without the pre-red websocket
+ * harness. It is the SEAM the Story 38.5 residency path consumes: when a
+ * retained live query exists across turns, a 'runtime-inject' param is applied
+ * via its setter while a 'restart' param forces `createPersistentQuery`. Under
+ * the current instance-per-turn production (Story 38.1), every send already
+ * recreates the query, so 'restart' is the status quo and the turn-between
+ * benefit of 'runtime-inject' only becomes observable once 38.5 keeps the
+ * process resident — 38.4 leaves the seam, it does not implement residency.
+ */
+export type RuntimeParam = 'model' | 'permissionMode' | 'thinking' | 'effort';
+export type RuntimeTransition = 'runtime-inject' | 'restart';
+/**
+ * How a mid-session change to `param` reaches the engine: injected into the live
+ * query via its runtime setter, or applied by restarting the generator (new
+ * query, session preserved). See the module doc for the probe verdict backing
+ * each mapping.
+ */
+export declare function runtimeTransitionFor(param: RuntimeParam): RuntimeTransition;
+/** True when `param` can be applied to a live query without a generator restart. */
+export declare function canRuntimeInject(param: RuntimeParam): boolean;
+//# sourceMappingURL=runtimeParamStrategy.d.ts.map

package/packages/server/dist/utils/runtimeParamStrategy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtimeParamStrategy.d.ts","sourceRoot":"","sources":["../../src/utils/runtimeParamStrategy.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AAEH,MAAM,MAAM,YAAY,GAAG,OAAO,GAAG,gBAAgB,GAAG,UAAU,GAAG,QAAQ,CAAC;AAE9E,MAAM,MAAM,iBAAiB,GAAG,gBAAgB,GAAG,SAAS,CAAC;AAE7D;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,YAAY,GAAG,iBAAiB,CAS3E;AAED,oFAAoF;AACpF,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,YAAY,GAAG,OAAO,CAE7D"}

package/packages/server/dist/utils/runtimeParamStrategy.js

@@ -0,0 +1,60 @@
+/**
+ * Story 38.4 — runtime parameter transition strategy.
+ *
+ * Classifies each mid-session parameter change as either injectable into the
+ * LIVE persistent query via a runtime setter (no process restart, no ~3s
+ * relaunch) or requiring a generator restart (a fresh query — the session /
+ * conversation is preserved, only the underlying generation process restarts).
+ *
+ * The classification is the probe-confirmed GO/NO-GO verdict from
+ * `scripts/probe-persistent-hooks.mjs runtime` (feedback_sdk_verify — measured,
+ * not assumed):
+ *
+ *   · model          → runtime-inject  (Query.setModel — GO: the next turn's
+ *                                        response reports the new model id)
+ *   · permissionMode  → runtime-inject  (Query.setPermissionMode — GO, in place
+ *                                        since Story 37.5; survives the
+ *                                        persistent stream)
+ *   · thinking        → runtime-inject  (Query.setMaxThinkingTokens — GO, but no
+ *                                        caller changes it mid-turn today; the
+ *                                        budget is derived at query creation from
+ *                                        the model + showThinkingBlocks pref, so
+ *                                        it stays a creation option — capability
+ *                                        confirmed, wiring deferred)
+ *   · effort          → restart         (the Query interface has NO setEffort —
+ *                                        effort is a query() creation option only,
+ *                                        so a change is inherently NO-GO for
+ *                                        runtime injection and falls back to a
+ *                                        generator restart)
+ *
+ * This is a PURE classifier (no SDK / socket dependency) so the "runtime inject
+ * vs fallback" branch (AC3) is unit-testable without the pre-red websocket
+ * harness. It is the SEAM the Story 38.5 residency path consumes: when a
+ * retained live query exists across turns, a 'runtime-inject' param is applied
+ * via its setter while a 'restart' param forces `createPersistentQuery`. Under
+ * the current instance-per-turn production (Story 38.1), every send already
+ * recreates the query, so 'restart' is the status quo and the turn-between
+ * benefit of 'runtime-inject' only becomes observable once 38.5 keeps the
+ * process resident — 38.4 leaves the seam, it does not implement residency.
+ */
+/**
+ * How a mid-session change to `param` reaches the engine: injected into the live
+ * query via its runtime setter, or applied by restarting the generator (new
+ * query, session preserved). See the module doc for the probe verdict backing
+ * each mapping.
+ */
+export function runtimeTransitionFor(param) {
+    switch (param) {
+        case 'model':
+        case 'permissionMode':
+        case 'thinking':
+            return 'runtime-inject';
+        case 'effort':
+            return 'restart';
+    }
+}
+/** True when `param` can be applied to a live query without a generator restart. */
+export function canRuntimeInject(param) {
+    return runtimeTransitionFor(param) === 'runtime-inject';
+}
+//# sourceMappingURL=runtimeParamStrategy.js.map

package/packages/server/dist/utils/runtimeParamStrategy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtimeParamStrategy.js","sourceRoot":"","sources":["../../src/utils/runtimeParamStrategy.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AAMH;;;;;GAKG;AACH,MAAM,UAAU,oBAAoB,CAAC,KAAmB;IACtD,QAAQ,KAAK,EAAE,CAAC;QACd,KAAK,OAAO,CAAC;QACb,KAAK,gBAAgB,CAAC;QACtB,KAAK,UAAU;YACb,OAAO,gBAAgB,CAAC;QAC1B,KAAK,QAAQ;YACX,OAAO,SAAS,CAAC;IACrB,CAAC;AACH,CAAC;AAED,oFAAoF;AACpF,MAAM,UAAU,gBAAgB,CAAC,KAAmB;IAClD,OAAO,oBAAoB,CAAC,KAAK,CAAC,KAAK,gBAAgB,CAAC;AAC1D,CAAC"}

package/packages/server/dist/utils/stopStrategy.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Story 38.3: pure decision helpers for the Stop button (`chat:abort`) split and
+ * the user-interrupt suppression predicates.
+ *
+ * These were extracted from the websocket handler so the orchestration decisions
+ * — how a running stream is stopped, and how a turn-only interrupt's error result
+ * is treated — can be unit-tested WITHOUT a live socket harness. The socket-level
+ * suite (websocket.test.ts chat:send path) is blocked by a pre-existing environmental
+ * red (QA gate 38.3 TEST-COV-1), so adding socket tests would introduce new red.
+ * Keeping the branch logic pure gives AC1 (abort/interrupt split) and the interrupt
+ * suppression branches a deterministic regression guard that does not touch sockets.
+ */
+/** How the Stop button stops a running stream. */
+export type StopStrategy = 'interrupt' | 'abort';
+/**
+ * Decide how the Stop button stops a running stream (Story 38.3 AC1).
+ *
+ *  - SDK engine that exposes `interrupt()` → `'interrupt'`: turn-only, the persistent
+ *    query's generator/session stays alive so the conversation can continue.
+ *  - CLI engine (PTY Ctrl+C runs off the abortController), OR an SDK engine not yet
+ *    created (boot window, no interrupt capability) → `'abort'`: hard abort.
+ *
+ * Faithful to the inline guard `engineMode !== 'cli' && svc?.interrupt`.
+ */
+export declare function resolveStopStrategy(params: {
+    engineMode: string | undefined;
+    canInterrupt: boolean;
+}): StopStrategy;
+/**
+ * A turn-only interrupt ends the turn with an `error_during_execution` result. That
+ * is the intended Stop, not a failure — its error emission is suppressed (viewers
+ * already received `stream:detached`), so no spurious error card appears.
+ */
+export declare function shouldSuppressResultError(userInterrupted: boolean): boolean;
+/**
+ * An interrupted turn still fires `onComplete` to finalize partial output, but it is
+ * a Stop rather than a natural finish — skip the "완료" completion notification.
+ * `hasNotifiableViewers` folds in `notificationService.shouldNotify(sockets.size)`.
+ */
+export declare function shouldNotifyComplete(userInterrupted: boolean, hasNotifiableViewers: boolean): boolean;
+/**
+ * Whether an error result while resuming should be converted to a thrown error and
+ * retried. A user interrupt ALSO ends the turn with an error result, so it must not
+ * be mistaken for a resume failure and retried — the user asked to stop.
+ *
+ * Faithful to `isError && isResumeAttempt && !aborted && !userInterrupted && !hasEmittedOutput`.
+ */
+export declare function shouldRetryResumeAfterError(params: {
+    isError: boolean;
+    isResumeAttempt: boolean;
+    aborted: boolean;
+    userInterrupted: boolean;
+    hasEmittedOutput: boolean;
+}): boolean;
+/**
+ * Whether the turn should hold, waiting on in-flight background tasks, at the end of
+ * the main generation. A user interrupt means "stop now" — do NOT hold. (The hard-abort
+ * path short-circuits via its aborted signal; the interrupt path leaves the signal unset,
+ * so this gates on the flag explicitly.)
+ */
+export declare function shouldWaitForBackgroundTasks(userInterrupted: boolean, backgroundIsWaiting: boolean): boolean;
+//# sourceMappingURL=stopStrategy.d.ts.map

package/packages/server/dist/utils/stopStrategy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stopStrategy.d.ts","sourceRoot":"","sources":["../../src/utils/stopStrategy.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,kDAAkD;AAClD,MAAM,MAAM,YAAY,GAAG,WAAW,GAAG,OAAO,CAAC;AAEjD;;;;;;;;;GASG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE;IAC1C,UAAU,EAAE,MAAM,GAAG,SAAS,CAAC;IAC/B,YAAY,EAAE,OAAO,CAAC;CACvB,GAAG,YAAY,CAEf;AAED;;;;GAIG;AACH,wBAAgB,yBAAyB,CAAC,eAAe,EAAE,OAAO,GAAG,OAAO,CAE3E;AAED;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,eAAe,EAAE,OAAO,EAAE,oBAAoB,EAAE,OAAO,GAAG,OAAO,CAErG;AAED;;;;;;GAMG;AACH,wBAAgB,2BAA2B,CAAC,MAAM,EAAE;IAClD,OAAO,EAAE,OAAO,CAAC;IACjB,eAAe,EAAE,OAAO,CAAC;IACzB,OAAO,EAAE,OAAO,CAAC;IACjB,eAAe,EAAE,OAAO,CAAC;IACzB,gBAAgB,EAAE,OAAO,CAAC;CAC3B,GAAG,OAAO,CAQV;AAED;;;;;GAKG;AACH,wBAAgB,4BAA4B,CAAC,eAAe,EAAE,OAAO,EAAE,mBAAmB,EAAE,OAAO,GAAG,OAAO,CAE5G"}

package/packages/server/dist/utils/stopStrategy.js

@@ -0,0 +1,65 @@
+/**
+ * Story 38.3: pure decision helpers for the Stop button (`chat:abort`) split and
+ * the user-interrupt suppression predicates.
+ *
+ * These were extracted from the websocket handler so the orchestration decisions
+ * — how a running stream is stopped, and how a turn-only interrupt's error result
+ * is treated — can be unit-tested WITHOUT a live socket harness. The socket-level
+ * suite (websocket.test.ts chat:send path) is blocked by a pre-existing environmental
+ * red (QA gate 38.3 TEST-COV-1), so adding socket tests would introduce new red.
+ * Keeping the branch logic pure gives AC1 (abort/interrupt split) and the interrupt
+ * suppression branches a deterministic regression guard that does not touch sockets.
+ */
+/**
+ * Decide how the Stop button stops a running stream (Story 38.3 AC1).
+ *
+ *  - SDK engine that exposes `interrupt()` → `'interrupt'`: turn-only, the persistent
+ *    query's generator/session stays alive so the conversation can continue.
+ *  - CLI engine (PTY Ctrl+C runs off the abortController), OR an SDK engine not yet
+ *    created (boot window, no interrupt capability) → `'abort'`: hard abort.
+ *
+ * Faithful to the inline guard `engineMode !== 'cli' && svc?.interrupt`.
+ */
+export function resolveStopStrategy(params) {
+    return params.engineMode !== 'cli' && params.canInterrupt ? 'interrupt' : 'abort';
+}
+/**
+ * A turn-only interrupt ends the turn with an `error_during_execution` result. That
+ * is the intended Stop, not a failure — its error emission is suppressed (viewers
+ * already received `stream:detached`), so no spurious error card appears.
+ */
+export function shouldSuppressResultError(userInterrupted) {
+    return userInterrupted;
+}
+/**
+ * An interrupted turn still fires `onComplete` to finalize partial output, but it is
+ * a Stop rather than a natural finish — skip the "완료" completion notification.
+ * `hasNotifiableViewers` folds in `notificationService.shouldNotify(sockets.size)`.
+ */
+export function shouldNotifyComplete(userInterrupted, hasNotifiableViewers) {
+    return !userInterrupted && hasNotifiableViewers;
+}
+/**
+ * Whether an error result while resuming should be converted to a thrown error and
+ * retried. A user interrupt ALSO ends the turn with an error result, so it must not
+ * be mistaken for a resume failure and retried — the user asked to stop.
+ *
+ * Faithful to `isError && isResumeAttempt && !aborted && !userInterrupted && !hasEmittedOutput`.
+ */
+export function shouldRetryResumeAfterError(params) {
+    return (params.isError &&
+        params.isResumeAttempt &&
+        !params.aborted &&
+        !params.userInterrupted &&
+        !params.hasEmittedOutput);
+}
+/**
+ * Whether the turn should hold, waiting on in-flight background tasks, at the end of
+ * the main generation. A user interrupt means "stop now" — do NOT hold. (The hard-abort
+ * path short-circuits via its aborted signal; the interrupt path leaves the signal unset,
+ * so this gates on the flag explicitly.)
+ */
+export function shouldWaitForBackgroundTasks(userInterrupted, backgroundIsWaiting) {
+    return !userInterrupted && backgroundIsWaiting;
+}
+//# sourceMappingURL=stopStrategy.js.map

package/packages/server/dist/utils/stopStrategy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"stopStrategy.js","sourceRoot":"","sources":["../../src/utils/stopStrategy.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAKH;;;;;;;;;GASG;AACH,MAAM,UAAU,mBAAmB,CAAC,MAGnC;IACC,OAAO,MAAM,CAAC,UAAU,KAAK,KAAK,IAAI,MAAM,CAAC,YAAY,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,OAAO,CAAC;AACpF,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,yBAAyB,CAAC,eAAwB;IAChE,OAAO,eAAe,CAAC;AACzB,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,oBAAoB,CAAC,eAAwB,EAAE,oBAA6B;IAC1F,OAAO,CAAC,eAAe,IAAI,oBAAoB,CAAC;AAClD,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,2BAA2B,CAAC,MAM3C;IACC,OAAO,CACL,MAAM,CAAC,OAAO;QACd,MAAM,CAAC,eAAe;QACtB,CAAC,MAAM,CAAC,OAAO;QACf,CAAC,MAAM,CAAC,eAAe;QACvB,CAAC,MAAM,CAAC,gBAAgB,CACzB,CAAC;AACJ,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,4BAA4B,CAAC,eAAwB,EAAE,mBAA4B;IACjG,OAAO,CAAC,eAAe,IAAI,mBAAmB,CAAC;AACjD,CAAC"}

package/packages/server/resources/internals/INDEX.md

@@ -8,7 +8,7 @@ Read individual entries **on demand** when the user's request involves the under
 
 ## Entries
 
-- [Image Storage](./image-storage.md) — On-disk path and filename scheme for chat-attached images
+- [Image Storage](./image-storage.md) — On-disk path and filename scheme for chat-attached images, and why chat-attached PDFs have no on-disk copy at all
 - [Harness File Layout](./harness-files.md) — Where `.claude/` items (skills, commands, agents, hooks, MCP servers, `CLAUDE.md`) live on disk, when changes take effect, the Context Builder's Hammoc-managed SessionStart files, plugin install-state paths, and how the Secret-on-Shared guard relates to direct file writes
 - [Observability Storage](./observability-storage.md) — Where the MCP call log and exact-token-count cache live, their JSONL/JSON format, body-stripping, and 30-day retention
 - [BMad QA-Fix Marker](./bmad-qa-fix-marker.md) — The `<!-- hammoc:qa-fix -->` story-file convention that drives QA re-review recommendations and the board's "QA Fixed" badge

package/packages/server/resources/internals/image-storage.md

@@ -2,6 +2,8 @@
 
 When the user attaches an image to a chat message, Hammoc saves it under **Claude Code's per-project session data**, not inside the project being worked on. The user does not see this — they just attach and send. This document is for an agent that needs to read or correlate the file directly.
 
+> **PDF attachments do not use this mechanism** — chat-attached PDFs are never written to disk. See the "PDF attachments" section at the bottom.
+
 ## On-disk location
 
 ```
@@ -47,6 +49,16 @@ For an agent: in CLI mode an attached image arrives as a literal "use your Read
 
 ## Limits
 
-- 5 images per message
-- 10 MB per image
+- 5 attachments per message — a **shared cap across images and PDFs combined**
+- 10 MB per image; 20 MB combined raw size per message (all attachments together)
 - Total per-session storage is bounded only by disk; there is no automatic eviction other than session deletion.
+
+## PDF attachments (not stored on disk)
+
+Chat-attached PDFs bypass this storage entirely:
+
+- **No file is written** under `images/<sessionId>/` or anywhere else. The PDF travels to the model as an inline base64 `document` content block, and the stored chat message keeps only the original filename with an empty URL — there is no on-disk path an agent can Read.
+- **SDK engine only.** The CLI engine rejects any message carrying a PDF before it is sent (server-side validation error), so no CLI `--add-dir` path-reference variant exists for PDFs.
+- Per-PDF size cap is 20 MB, inside the shared 5-attachment / 20 MB-combined message limits above.
+
+If a task needs the PDF bytes themselves, the agent cannot recover them from session storage — ask the user to place the file into the project tree instead.