@threadbase-sh/streamer 1.61.1 → 1.61.2

package/dist/index.d.cts

@@ -105,15 +105,19 @@ interface FlagDefinition {
 type ClaudeFlagValue = string | string[] | boolean;
 type ClaudeFlagValues = Record<string, ClaudeFlagValue>;
 
-interface FeatureFlagDefinition {
-    /** Stable config/wire key. Used in server.yaml, on the CLI, and over HTTP. */
-    id: string;
+/** Spec for one flag in the keyed registry. The id is the object key, not a field. */
+interface FeatureFlagSpec {
     /** Shipped to clients alongside the values so a UI can render it. */
     description: string;
     default: boolean;
     /** Full env var name. */
     env: string;
 }
+/** Wire shape: the keyed spec plus its id, for GET /api/config/feature-flags. */
+interface FeatureFlagDefinition extends FeatureFlagSpec {
+    /** Stable config/wire key. Used in server.yaml, on the CLI, and over HTTP. */
+    id: FeatureFlagId;
+}
 /**
  * Values arriving from a config source. PARTIAL on purpose: server.yaml, the
  * CLI and ServerConfig each speak about the flags they mention and stay silent
@@ -130,32 +134,42 @@ type ResolvedFeatureFlags = Record<FeatureFlagId, boolean>;
  * `override` is the legacy ServerConfig field (see resolveFeatureFlags).
  */
 type FeatureFlagSource = "override" | "env" | "cli" | "yaml" | "default";
-declare const FEATURE_FLAGS: readonly [{
-    readonly id: "codexSystemPrompt";
-    readonly description: string;
-    readonly default: false;
-    readonly env: "THREADBASE_FEATURE_CODEX_SYSTEM_PROMPT";
-}, {
-    readonly id: "sessionRehydration";
-    readonly description: string;
-    readonly default: true;
-    readonly env: "THREADBASE_FEATURE_SESSION_REHYDRATION";
-}, {
-    readonly id: "liveActivityPush";
-    readonly description: string;
-    readonly default: false;
-    readonly env: "THREADBASE_FEATURE_LIVE_ACTIVITY_PUSH";
-}, {
-    readonly id: "e2ee";
-    readonly description: string;
-    readonly default: false;
-    readonly env: "THREADBASE_FEATURE_E2EE";
-}, {
-    readonly id: "ptyHost";
-    readonly description: string;
-    readonly default: false;
-    readonly env: "THREADBASE_FEATURE_PTY_HOST";
-}];
+/**
+ * The registry, keyed by flag name.
+ *
+ * Prefer `FEATURE_FLAGS.ptyHost` over a string lookup. A typo is a compile
+ * error; `findFeatureFlag("…")` is only for untrusted yaml/CLI tokens.
+ *
+ * `as const` + `keyof` is what makes `flags.ptyHsot` a compile error instead of
+ * `undefined`. A TS enum would add a runtime object without a stronger type.
+ */
+declare const FEATURE_FLAGS: {
+    readonly codexSystemPrompt: {
+        readonly description: string;
+        readonly default: false;
+        readonly env: "THREADBASE_FEATURE_CODEX_SYSTEM_PROMPT";
+    };
+    readonly sessionRehydration: {
+        readonly description: string;
+        readonly default: true;
+        readonly env: "THREADBASE_FEATURE_SESSION_REHYDRATION";
+    };
+    readonly liveActivityPush: {
+        readonly description: string;
+        readonly default: false;
+        readonly env: "THREADBASE_FEATURE_LIVE_ACTIVITY_PUSH";
+    };
+    readonly e2ee: {
+        readonly description: string;
+        readonly default: false;
+        readonly env: "THREADBASE_FEATURE_E2EE";
+    };
+    readonly ptyHost: {
+        readonly description: string;
+        readonly default: false;
+        readonly env: "THREADBASE_FEATURE_PTY_HOST";
+    };
+};
 /**
  * The registry's ids as a union, derived rather than declared.
  *
@@ -165,7 +179,7 @@ declare const FEATURE_FLAGS: readonly [{
  * was meant to gate — the exact failure the "total map" contract exists to
  * prevent, reachable through the one door that contract left open.
  */
-type FeatureFlagId = (typeof FEATURE_FLAGS)[number]["id"];
+type FeatureFlagId = keyof typeof FEATURE_FLAGS;
 
 declare const CLAUDE_CODE_PROVIDER: "claude-code";
 declare const CODEX_CLI_PROVIDER: "codex-cli";
@@ -2509,8 +2523,21 @@ declare class StreamerServer {
      */
     private waitForStartupOutcome;
     /**
-     * Drop every trace of a session that never became usable, and hand back what
-     * it failed with.
+     * Drop every trace of a managed session: in-memory store, durable registry
+     * row, and the collision-probe markers that would otherwise outlive it.
+     *
+     * Used when a start never became usable (`abandonFailedStart`) and when stop
+     * is asked to discard an empty session that has no cached conversation. The
+     * registry delete is load-bearing — `rehydrateSessions` will bring the row
+     * back on the next boot if it remains.
+     *
+     * Callers that kill the PTY (`putOnHold`) must do that *first*: onStatusChange
+     * on idle writes `selfPtyEndedAt` and a registry status, and those have to
+     * be cleared here afterwards.
+     */
+    private forgetSession;
+    /**
+     * Drop every trace of a session that never became usable.
      *
      * The runner has already torn itself down (failStartup / handleExit); what
      * remains is server-side bookkeeping that would otherwise leave a dead

package/dist/index.d.ts

@@ -105,15 +105,19 @@ interface FlagDefinition {
 type ClaudeFlagValue = string | string[] | boolean;
 type ClaudeFlagValues = Record<string, ClaudeFlagValue>;
 
-interface FeatureFlagDefinition {
-    /** Stable config/wire key. Used in server.yaml, on the CLI, and over HTTP. */
-    id: string;
+/** Spec for one flag in the keyed registry. The id is the object key, not a field. */
+interface FeatureFlagSpec {
     /** Shipped to clients alongside the values so a UI can render it. */
     description: string;
     default: boolean;
     /** Full env var name. */
     env: string;
 }
+/** Wire shape: the keyed spec plus its id, for GET /api/config/feature-flags. */
+interface FeatureFlagDefinition extends FeatureFlagSpec {
+    /** Stable config/wire key. Used in server.yaml, on the CLI, and over HTTP. */
+    id: FeatureFlagId;
+}
 /**
  * Values arriving from a config source. PARTIAL on purpose: server.yaml, the
  * CLI and ServerConfig each speak about the flags they mention and stay silent
@@ -130,32 +134,42 @@ type ResolvedFeatureFlags = Record<FeatureFlagId, boolean>;
  * `override` is the legacy ServerConfig field (see resolveFeatureFlags).
  */
 type FeatureFlagSource = "override" | "env" | "cli" | "yaml" | "default";
-declare const FEATURE_FLAGS: readonly [{
-    readonly id: "codexSystemPrompt";
-    readonly description: string;
-    readonly default: false;
-    readonly env: "THREADBASE_FEATURE_CODEX_SYSTEM_PROMPT";
-}, {
-    readonly id: "sessionRehydration";
-    readonly description: string;
-    readonly default: true;
-    readonly env: "THREADBASE_FEATURE_SESSION_REHYDRATION";
-}, {
-    readonly id: "liveActivityPush";
-    readonly description: string;
-    readonly default: false;
-    readonly env: "THREADBASE_FEATURE_LIVE_ACTIVITY_PUSH";
-}, {
-    readonly id: "e2ee";
-    readonly description: string;
-    readonly default: false;
-    readonly env: "THREADBASE_FEATURE_E2EE";
-}, {
-    readonly id: "ptyHost";
-    readonly description: string;
-    readonly default: false;
-    readonly env: "THREADBASE_FEATURE_PTY_HOST";
-}];
+/**
+ * The registry, keyed by flag name.
+ *
+ * Prefer `FEATURE_FLAGS.ptyHost` over a string lookup. A typo is a compile
+ * error; `findFeatureFlag("…")` is only for untrusted yaml/CLI tokens.
+ *
+ * `as const` + `keyof` is what makes `flags.ptyHsot` a compile error instead of
+ * `undefined`. A TS enum would add a runtime object without a stronger type.
+ */
+declare const FEATURE_FLAGS: {
+    readonly codexSystemPrompt: {
+        readonly description: string;
+        readonly default: false;
+        readonly env: "THREADBASE_FEATURE_CODEX_SYSTEM_PROMPT";
+    };
+    readonly sessionRehydration: {
+        readonly description: string;
+        readonly default: true;
+        readonly env: "THREADBASE_FEATURE_SESSION_REHYDRATION";
+    };
+    readonly liveActivityPush: {
+        readonly description: string;
+        readonly default: false;
+        readonly env: "THREADBASE_FEATURE_LIVE_ACTIVITY_PUSH";
+    };
+    readonly e2ee: {
+        readonly description: string;
+        readonly default: false;
+        readonly env: "THREADBASE_FEATURE_E2EE";
+    };
+    readonly ptyHost: {
+        readonly description: string;
+        readonly default: false;
+        readonly env: "THREADBASE_FEATURE_PTY_HOST";
+    };
+};
 /**
  * The registry's ids as a union, derived rather than declared.
  *
@@ -165,7 +179,7 @@ declare const FEATURE_FLAGS: readonly [{
  * was meant to gate — the exact failure the "total map" contract exists to
  * prevent, reachable through the one door that contract left open.
  */
-type FeatureFlagId = (typeof FEATURE_FLAGS)[number]["id"];
+type FeatureFlagId = keyof typeof FEATURE_FLAGS;
 
 declare const CLAUDE_CODE_PROVIDER: "claude-code";
 declare const CODEX_CLI_PROVIDER: "codex-cli";
@@ -2509,8 +2523,21 @@ declare class StreamerServer {
      */
     private waitForStartupOutcome;
     /**
-     * Drop every trace of a session that never became usable, and hand back what
-     * it failed with.
+     * Drop every trace of a managed session: in-memory store, durable registry
+     * row, and the collision-probe markers that would otherwise outlive it.
+     *
+     * Used when a start never became usable (`abandonFailedStart`) and when stop
+     * is asked to discard an empty session that has no cached conversation. The
+     * registry delete is load-bearing — `rehydrateSessions` will bring the row
+     * back on the next boot if it remains.
+     *
+     * Callers that kill the PTY (`putOnHold`) must do that *first*: onStatusChange
+     * on idle writes `selfPtyEndedAt` and a registry status, and those have to
+     * be cleared here afterwards.
+     */
+    private forgetSession;
+    /**
+     * Drop every trace of a session that never became usable.
      *
      * The runner has already torn itself down (failStartup / handleExit); what
      * remains is server-side bookkeeping that would otherwise leave a dead

package/dist/index.js

@@ -445,40 +445,47 @@ function getLogger(component) {
 var logger = build(baseLogger);
 
 // src/feature-flags.ts
-var FEATURE_FLAGS = [
-  {
-    id: "codexSystemPrompt",
+var FEATURE_FLAGS = {
+  codexSystemPrompt: {
     description: "Send the built system prompt to fresh Codex sessions. Off by default: Codex has no --system-prompt flag, so the prompt goes in the positional [PROMPT] argument, which Codex treats as the user's opening turn rather than a system-level instruction.",
     default: false,
     env: "THREADBASE_FEATURE_CODEX_SYSTEM_PROMPT"
   },
-  {
-    id: "sessionRehydration",
+  sessionRehydration: {
     description: "Seed the session list at boot with sessions a previous streamer run left behind, so a restart leaves them one tap from resuming instead of silently gone. On by default, with a kill switch: it changes what GET /api/sessions contains.",
     default: true,
     env: "THREADBASE_FEATURE_SESSION_REHYDRATION"
   },
-  {
-    id: "liveActivityPush",
+  liveActivityPush: {
     description: "Drive iOS Live Activity surfaces for running sessions. Off by default: the streamer half needs an APNs p8 and a registered push-to-start token, and without both, mobile falls back to starting the activity locally \u2014 which freezes the moment the app backgrounds and expires silently after ~8h. Mobile reads this flag and skips its local path too, so one switch turns the whole surface off.",
     default: false,
     env: "THREADBASE_FEATURE_LIVE_ACTIVITY_PUSH"
   },
-  {
-    id: "e2ee",
+  e2ee: {
     description: "Application-layer encryption between a paired device and this server, independent of TLS, so a tunnel or a LAN observer on the path carries ciphertext. Off by default: it is negotiated per device, never forced, because released mobile builds cannot be force-updated and a server that demanded it would break every one of them.",
     default: false,
     env: "THREADBASE_FEATURE_E2EE"
   },
-  {
-    id: "ptyHost",
+  ptyHost: {
     description: "Keep live PTYs in a separate host process so a streamer restart can reconnect without restarting the agents. Off by default until cross-platform behavior is qualified.",
     default: false,
     env: "THREADBASE_FEATURE_PTY_HOST"
   }
-];
+};
+var FEATURE_FLAG_IDS = Object.keys(FEATURE_FLAGS);
+var FEATURE_FLAG_LIST = FEATURE_FLAG_IDS.map((id) => ({
+  id,
+  ...FEATURE_FLAGS[id]
+}));
+function isFeatureFlagId(id) {
+  return Object.hasOwn(FEATURE_FLAGS, id);
+}
+function getFeatureFlag(id) {
+  return { id, ...FEATURE_FLAGS[id] };
+}
 function findFeatureFlag(id) {
-  return FEATURE_FLAGS.find((f) => f.id === id);
+  if (!isFeatureFlagId(id)) return void 0;
+  return getFeatureFlag(id);
 }
 function parseBooleanEnv(raw) {
   if (raw === void 0) return void 0;
@@ -500,10 +507,11 @@ function validateFeatureFlagValues(raw) {
   }
   if (dropped.length > 0) {
     getLogger("feature-flags").warn(
-      `Ignoring unknown or non-boolean feature flags: ${dropped.join(", ")}`,
+      `Ignoring unknown or non-boolean feature flags: ${dropped.join(", ")}. Known ids (FEATURE_FLAGS keys, not env names): ${FEATURE_FLAG_IDS.join(", ")}`,
       {
         event: "config.feature_flags_dropped",
-        dropped
+        dropped,
+        known: FEATURE_FLAG_IDS
       }
     );
   }
@@ -513,7 +521,7 @@ function resolveFeatureFlags(opts) {
   const env = opts?.env ?? process.env;
   const values = {};
   const sources = {};
-  for (const def of FEATURE_FLAGS) {
+  for (const def of FEATURE_FLAG_LIST) {
     const rungs = [
       ["override", opts?.override?.[def.id]],
       ["env", parseBooleanEnv(env[def.env])],
@@ -527,10 +535,10 @@ function resolveFeatureFlags(opts) {
   return { values, sources };
 }
 function nonDefaultFeatureFlags(values) {
-  return FEATURE_FLAGS.filter((f) => values[f.id] !== f.default).map((f) => f.id);
+  return FEATURE_FLAG_LIST.filter((f) => values[f.id] !== f.default).map((f) => f.id);
 }
 function describeFeatureFlags(resolution) {
-  return FEATURE_FLAGS.map(
+  return FEATURE_FLAG_LIST.map(
     (f) => `${f.id}=${resolution.values[f.id]}(${resolution.sources[f.id]})`
   ).join(" ");
 }
@@ -10530,7 +10538,9 @@ var SessionHandlers = class {
       res.end(JSON.stringify({ error: "Session not found" }));
       return;
     }
+    const shouldForget = this.shouldForgetEmptySession(session);
     if (session.status === "idle") {
+      if (shouldForget) this.forgetEmptyStoppedSession(sessionId);
       res.writeHead(200, { "Content-Type": "application/json" });
       res.end(JSON.stringify({ status: "already_idle", sessionId }));
       return;
@@ -10558,6 +10568,7 @@ var SessionHandlers = class {
     this.ptyManager.putOnHold(sessionId);
     this.discoveryCache = null;
     const outcome = await Promise.race([idlePromise, timeoutPromise]);
+    if (shouldForget) this.forgetEmptyStoppedSession(sessionId);
     if (outcome === "idle") {
       res.write(`${JSON.stringify({ event: "stopped", sessionId })}
 `);
@@ -10570,6 +10581,42 @@ var SessionHandlers = class {
     }
     res.end();
   }
+  /**
+   * An unused start: the user never submitted a prompt, and the conversation
+   * cache has no row for this id (empty Codex/Claude often never write a JSONL).
+   * `conversationId === sessionId` is not evidence of history — only the cache
+   * is. promptCount > 0 or a cache hit keeps today's hold path.
+   */
+  shouldForgetEmptySession(session) {
+    const stored = this.sessionStore.getManaged(session.id);
+    const promptCount = Math.max(session.promptCount, stored?.promptCount ?? 0);
+    if (promptCount > 0) return false;
+    return !this.hasCachedConversationFor(session, stored);
+  }
+  hasCachedConversationFor(session, stored) {
+    const cache = this.cache;
+    if (!cache) return false;
+    const ids = /* @__PURE__ */ new Set([session.id]);
+    if (session.boundConversationId) ids.add(session.boundConversationId);
+    if (session.resumedFromConversationId) ids.add(session.resumedFromConversationId);
+    if (stored?.boundConversationId) ids.add(stored.boundConversationId);
+    if (stored?.resumedFromConversationId) ids.add(stored.resumedFromConversationId);
+    for (const id of ids) {
+      if (cache.hasConversation(id)) return true;
+    }
+    return false;
+  }
+  forgetEmptyStoppedSession(sessionId) {
+    this.log.info(`[stop] forgetting empty session ${sessionId.slice(0, 8)}`, {
+      event: "session.forget_empty",
+      sessionId
+    });
+    this.deps.forgetSession(sessionId);
+    this.wsHub.broadcast({
+      type: "session_list",
+      sessions: this.sessionStore.list(this.deps.ptyAttachedIds())
+    });
+  }
   async handleAdopt(sessionId, res) {
     const discovered = await discoverClaudeProcesses();
     this.sessionStore.setDiscovered(discovered);
@@ -15762,6 +15809,7 @@ var StreamerServer = class {
       spawnFlagOverrides: () => this.spawnFlagOverrides(),
       resolveConversationTarget: (sessionId) => this.resolveConversationTarget(sessionId),
       waitForStartupOutcome: (sessionId, timeoutMs) => this.waitForStartupOutcome(sessionId, timeoutMs),
+      forgetSession: (sessionId) => this.forgetSession(sessionId),
       abandonFailedStart: (sessionId) => this.abandonFailedStart(sessionId),
       enrichResumedSessionAsync: (sessionId, projectPath, conv) => this.enrichResumedSessionAsync(sessionId, projectPath, conv),
       findJsonlPath: (uuid) => this.conversationHandlers.findJsonlPath(uuid),
@@ -16753,7 +16801,7 @@ var StreamerServer = class {
    */
   getFeatureFlagsConfig() {
     return {
-      registry: FEATURE_FLAGS,
+      registry: FEATURE_FLAG_LIST,
       values: this.featureFlags,
       sources: this.featureFlagSources
     };
@@ -16987,29 +17035,44 @@ var StreamerServer = class {
     });
   }
   /**
-   * Drop every trace of a session that never became usable, and hand back what
-   * it failed with.
+   * Drop every trace of a managed session: in-memory store, durable registry
+   * row, and the collision-probe markers that would otherwise outlive it.
    *
-   * The runner has already torn itself down (failStartup / handleExit); what
-   * remains is server-side bookkeeping that would otherwise leave a dead
-   * session in the list, a registry row claiming a spawn, and a `selfPtyEndedAt`
-   * marker that would suppress the mtime collision signal on the NEXT resume —
-   * i.e. it would help hide the very owner we just collided with.
+   * Used when a start never became usable (`abandonFailedStart`) and when stop
+   * is asked to discard an empty session that has no cached conversation. The
+   * registry delete is load-bearing — `rehydrateSessions` will bring the row
+   * back on the next boot if it remains.
+   *
+   * Callers that kill the PTY (`putOnHold`) must do that *first*: onStatusChange
+   * on idle writes `selfPtyEndedAt` and a registry status, and those have to
+   * be cleared here afterwards.
    */
-  abandonFailedStart(sessionId) {
+  forgetSession(sessionId) {
     this.sessionStore.removeManaged(sessionId);
     this.selfPtyEndedAt.delete(sessionId);
     this.contendedSessions.delete(sessionId);
     try {
       this.managedSessionsRepo?.delete(sessionId);
     } catch (err) {
-      this.log.warn("[registry] failed to drop a failed start", {
+      this.log.warn("[registry] failed to drop a session", {
         event: "registry.forget_failed",
         sessionId,
         err
       });
     }
   }
+  /**
+   * Drop every trace of a session that never became usable.
+   *
+   * The runner has already torn itself down (failStartup / handleExit); what
+   * remains is server-side bookkeeping that would otherwise leave a dead
+   * session in the list, a registry row claiming a spawn, and a `selfPtyEndedAt`
+   * marker that would suppress the mtime collision signal on the NEXT resume —
+   * i.e. it would help hide the very owner we just collided with.
+   */
+  abandonFailedStart(sessionId) {
+    this.forgetSession(sessionId);
+  }
   enrichResumedSessionAsync(sessionId, projectPath, conv) {
     try {
       if (!this.sessionStore.getManaged(sessionId)) return;