mixdog 1.2.2 → 1.2.4

package/src/runtime/agent/orchestrator/session/manager/runtime-liveness.mjs

@@ -1,7 +1,10 @@
 // ── Runtime liveness map ──────────────────────────────────────────────
-// In-memory only. Tracks per-session stage + stream heartbeat so agent type=list
+// In-memory only. Tracks per-session stage + stream progress so agent type=list
 // can surface whether a session is actually alive vs stuck. Never persisted —
-// heartbeats would otherwise churn the session JSON on every SSE delta.
+// progress would otherwise churn the session JSON on every SSE delta. The Map
+// itself lives in the import-free leaf runtime-state.mjs so cold readers can
+// ask which turns are in flight (isSessionTurnInFlight /
+// inFlightSessionActivity); every mutation stays here.
 //
 // The Map and its timer companion are
 // module-level singletons — preserving the baseline's single-process shape.
@@ -20,14 +23,16 @@
 // }
 import { createAbortController } from '../../../../shared/abort-controller.mjs';
 import { emitSessionApprovalWaitChange } from '../../../../shared/session-approval-wait.mjs';
-import { publishHeartbeat, deleteHeartbeat } from '../store.mjs';
 import { DEFAULT_ACTIVITY_HEARTBEAT_MS } from '../../stall-policy.mjs';
+import { MODEL_THINKING_STAGE, awaitingModelResponse, lastProgressAt } from '../../../../shared/quiet-progress.mjs';
 import { finishBrowserTurn } from '../../../../browser-bridge/client.mjs';
 import { configureUsageMetricsRuntime, dropMetricSeenState, bumpUsageMetricsTurnId } from './usage-metrics.mjs';
+import { runtimeState as _runtimeState, isTurnInFlight } from './runtime-state.mjs';
+
+export { IN_FLIGHT_STAGES, inFlightSessionActivity } from './runtime-state.mjs';
 
 const HEARTBEAT_THROTTLE_MS = 60_000; // 60s
 
-const _runtimeState = new Map();
 const _toolActivityHeartbeats = new Map();
 const VALID_STAGES = new Set([
   'connecting',
@@ -99,7 +104,6 @@ function _touchSessionActivityProgress(id) {
   const now = Date.now();
   entry.lastProgressAt = now;
   entry.updatedAt = now;
-  publishHeartbeat(id, now);
 }
 
 function _startToolActivityHeartbeat(id) {
@@ -111,11 +115,17 @@ function _startToolActivityHeartbeat(id) {
 }
 
 export function updateSessionStage(id, stage) {
+  if (stage === MODEL_THINKING_STAGE) {
+    markSessionRequestSent(id);
+    return;
+  }
   if (!id || !VALID_STAGES.has(stage)) return;
   const entry = _touchRuntime(id);
   const now = Date.now();
   const priorStage = entry.stage;
   entry.stage = stage;
+  // A new stage (a retried attempt included) has not sent its request yet.
+  entry.requestSentAt = null;
   if (stage === 'requesting' && priorStage !== 'requesting') {
     entry.modelRequestStartedAt = now;
   }
@@ -148,6 +158,7 @@ export function markSessionAskStart(id) {
   entry.lastToolProtocolAt = null;
   entry.lastSemanticKind = null;
   entry.transportTrackingEnabled = false;
+  entry.requestSentAt = null;
   entry.lastToolCall = null;
   entry.toolStartedAt = null;
   entry.toolOutputTail = null;
@@ -166,14 +177,18 @@ export function markSessionAskStart(id) {
   entry.modelRequestStartedAt = null;
   entry.lastProgressAt = now;
   entry.updatedAt = now;
-  // Publish heartbeat immediately so the status aggregator picks the
-  // session up in the connecting / requesting window. Without this the
-  // .hb file only landed on the first stream chunk — producing a 3–10s
-  // (xhigh: 30s+) invisible gap where agent sessions ran but the
-  // statusline showed no maintenance/agent badge. STREAM_FRESH_MS (5 min)
-  // still drops a session whose provider truly never returns a chunk;
-  // markSessionStreamDelta keeps refreshing once chunks arrive.
-  return publishHeartbeat(id, now);
+}
+/** The provider put the request on the wire; its response headers are
+ *  pending. The turn stays `requesting` (every stage set and the watchdog
+ *  clock are unchanged); the send time lets surfaces show "model thinking"
+ *  until transport arrives. Not progress: lastProgressAt is untouched. */
+export function markSessionRequestSent(id) {
+  if (!id) return;
+  const entry = _runtimeState.get(id);
+  if (!entry || entry.closed || entry.controller?.signal?.aborted || entry.stage !== 'requesting') return;
+  const now = Date.now();
+  entry.requestSentAt = now;
+  entry.updatedAt = now;
 }
 export function enableSessionTransportTracking(id) {
   if (!id) return;
@@ -194,7 +209,6 @@ export function markSessionTransportActivity(id) {
   const now = Date.now();
   entry.lastTransportAt = now;
   entry.updatedAt = now;
-  publishHeartbeat(id, now);
 }
 function _normalizeModelProgressKind(kind) {
   let value = 'semantic';
@@ -211,10 +225,10 @@ export async function markSessionStreamDelta(id, kind = 'semantic') {
   // creates it before streaming begins). _touchRuntime would instead resurrect a
   // blank entry — and closeSession()/idle-sweep clear _runtimeState on a deferred
   // tick while a detached provider stream may still be trickling deltas. A delta
-  // arriving after that clear must NOT re-create an entry or it would republish the
-  // .hb heartbeat that markSessionClosed deleted, orphaning a dead session's
-  // heartbeat indefinitely (the disk tombstone blocks ask resumption but not this
-  // path). Skip a missing, tombstoned, or aborted entry — never refresh liveness.
+  // arriving after that clear must NOT re-create an entry or it would revive a
+  // dead session's runtime state (the disk tombstone blocks ask resumption but
+  // not this path). Skip a missing, tombstoned, or aborted entry — never refresh
+  // liveness.
   const entry = _runtimeState.get(id);
   if (!entry || entry.closed || entry.controller?.signal?.aborted || TERMINAL_STAGES.has(entry.stage)) return;
   const progressKind = _normalizeModelProgressKind(kind);
@@ -240,11 +254,7 @@ export async function markSessionStreamDelta(id, kind = 'semantic') {
   if (entry.stage === 'connecting' || entry.stage === 'requesting') {
     entry.stage = 'streaming';
   }
-  // Lightweight heartbeat (≤5s self-throttled) for the status aggregator.
-  // Disk-side session.lastHeartbeatAt below is the heavy 60s zombie-reaper
-  // signal; the .hb file is the fast fresh-session signal consumed by the
-  // status line.
-  publishHeartbeat(id, now);
+  // Disk-side session.lastHeartbeatAt is the 60s zombie-reaper signal.
   const session = entry.session;
   if (session && now - (session.lastHeartbeatAt || 0) > HEARTBEAT_THROTTLE_MS) {
     session.lastHeartbeatAt = now;
@@ -271,9 +281,7 @@ export function markSessionToolCall(id, toolName) {
   entry.lastToolProtocolAt = entry.toolStartedAt;
   entry.lastProgressAt = entry.toolStartedAt;
   entry.updatedAt = entry.toolStartedAt;
-  const heartbeat = publishHeartbeat(id, entry.toolStartedAt);
   _startToolActivityHeartbeat(id);
-  return heartbeat;
 }
 // Live shell-output tail for the CURRENT running tool. Written by the shell
 // tool's onOutputTail timer (~1 s cadence), read by engine transcript
@@ -341,10 +349,6 @@ export function markSessionDone(id, { empty = false } = {}) {
     entry.emptyFinal = false;
     entry.emptyFinalAt = null;
   }
-  // Terminal stage — drop the heartbeat so the status badge releases
-  // immediately. A subsequent ask on the same session re-publishes via
-  // markSessionStreamDelta on the first chunk.
-  return deleteHeartbeat(id);
 }
 // Tag a session as having completed with empty final synthesis (no
 // content/reasoning). Distinct from `markSessionDone`: still a success
@@ -368,9 +372,7 @@ export function markSessionError(id, msg) {
   // silent empty final). Clear the flag so the next ask starts clean.
   entry.emptyFinal = false;
   entry.emptyFinalAt = null;
-  const heartbeatDeleted = deleteHeartbeat(id);
   _unlinkParentAbortListener(entry);
-  return heartbeatDeleted;
 }
 export function markSessionCancelled(id) {
   if (!id) return;
@@ -380,24 +382,19 @@ export function markSessionCancelled(id) {
   _settleTerminalEntry(entry, 'done', null);
   entry.emptyFinal = false;
   entry.emptyFinalAt = null;
-  const heartbeatDeleted = deleteHeartbeat(id);
   _unlinkParentAbortListener(entry);
-  return heartbeatDeleted;
 }
 export function getSessionRuntime(id) {
   return id ? _runtimeState.get(id) || null : null;
 }
 
-// Stages that still own live provider/tool work: compaction, idle cleanup and
-// runtime unload all stay away from an entry in one of them.
-export const IN_FLIGHT_STAGES = new Set(['connecting', 'requesting', 'streaming', 'tool_running', 'cancelling']);
+/** Whether this session's turn (provider or tool work) is running now. */
+export function isSessionTurnInFlight(sessionId) {
+  return Boolean(sessionId) && isTurnInFlight(_runtimeState.get(sessionId));
+}
 
 export function isSessionCompactionBlocked(sessionId) {
-  if (!sessionId) return false;
-  const entry = _runtimeState.get(sessionId);
-  if (!entry || entry.closed === true) return false;
-  if (entry.controller && !entry.controller.signal?.aborted) return true;
-  return IN_FLIGHT_STAGES.has(entry.stage);
+  return isSessionTurnInFlight(sessionId);
 }
 
 export function getSessionProgressSnapshot(sessionId) {
@@ -418,6 +415,9 @@ export function getSessionProgressSnapshot(sessionId) {
     firstActivityAt,
     firstSemanticAt,
     lastTransportAt: entry.lastTransportAt || 0,
+    requestSentAt: entry.requestSentAt || 0,
+    // Request on the wire, headers pending: the model is queued or thinking.
+    awaitingModelResponse: awaitingModelResponse(entry),
     lastSemanticAt: entry.lastSemanticAt || 0,
     lastSemanticKind: entry.lastSemanticKind || null,
     lastReasoningAt: entry.lastReasoningAt || 0,
@@ -482,14 +482,7 @@ export function getSessionAbortSignal(sessionId) {
  * either skip the watchdog or treat 0 as "no progress yet".
  */
 export function getSessionLastProgressAt(sessionId) {
-  const entry = _runtimeState.get(sessionId);
-  if (!entry) return 0;
-  return Math.max(
-    entry.lastProgressAt || 0,
-    entry.lastStreamDeltaAt || 0,
-    entry.toolStartedAt || 0,
-    entry.askStartedAt || 0
-  );
+  return lastProgressAt(_runtimeState.get(sessionId));
 }
 
 /**

package/src/runtime/agent/orchestrator/session/manager/runtime-state.mjs

@@ -0,0 +1,50 @@
+// manager/runtime-state.mjs
+// The process-global runtime liveness map and its turn-activity reads.
+// runtime-liveness.mjs owns every entry and mutation; this leaf has no
+// imports, so a cold reader (the daemon's session catalog) can ask which turns
+// are in flight without loading the session manager graph. Every session runs
+// inline in the daemon, so this map is the whole answer to "is this session's
+// turn running".
+
+export const runtimeState = new Map();
+
+// Stages that still own live provider/tool work: compaction, idle cleanup and
+// runtime unload all stay away from an entry in one of them.
+export const IN_FLIGHT_STAGES = new Set(['connecting', 'requesting', 'streaming', 'tool_running', 'cancelling']);
+
+/** Whether a runtime entry's turn (provider or tool work) is running now. */
+export function isTurnInFlight(entry) {
+  if (!entry || entry.closed === true) return false;
+  if (entry.controller && !entry.controller.signal?.aborted) return true;
+  return IN_FLIGHT_STAGES.has(entry.stage);
+}
+
+const cleanLower = (value) =>
+  String(value || '')
+    .trim()
+    .toLowerCase();
+
+/**
+ * Turn activity of every session this process runs: `working` holds the ids
+ * whose turn is in flight, `agentWorking` the root owner (Lead) ids of every
+ * in-flight Agent session.
+ */
+export function inFlightSessionActivity() {
+  const working = new Set();
+  const agentWorking = new Set();
+  for (const [id, entry] of runtimeState) {
+    if (!isTurnInFlight(entry)) continue;
+    working.add(id);
+    const session = entry.session;
+    const ownerSessionId = String(session?.ownerSessionId || session?.parentSessionId || '').trim();
+    const agent = cleanLower(session?.agent);
+    if (
+      ownerSessionId &&
+      ownerSessionId !== id &&
+      (cleanLower(session?.owner) === 'agent' || (agent && agent !== 'lead'))
+    ) {
+      agentWorking.add(ownerSessionId);
+    }
+  }
+  return { working, agentWorking };
+}

package/src/runtime/agent/orchestrator/session/manager/session-close.mjs

@@ -17,7 +17,9 @@ import { clearTurnCheckpoint } from './turn-checkpoint.mjs';
 import { forgetSessionSaveBaseline } from '../store/save-worker.mjs';
 import { forgetSessionLoadCache } from '../store/load-cache.mjs';
 import { releaseReadSnapshotScope } from '../../tools/builtin/snapshot-store.mjs';
-import { cancelNativeTasks } from '../../tools/lib/native-spawn-client.mjs';
+import { cancelOwnedShellTrees } from '../../tools/lib/owned-shell-trees.mjs';
+import { noteShellOwnerSessionClosed } from '../../tools/builtin/lib/shell-job-records.mjs';
+import { forgetSideQuestion } from '../side-question-store.mjs';
 
 /**
  * Close a session. Plants a `closed=true` tombstone on disk with a bumped
@@ -46,15 +48,17 @@ export function closeSession(id, reason = 'manual', opts = {}) {
   const entry = _getRuntimeEntry(id);
   // askSession owns the interruption tracker that can merge committed
   // iterations, the current partial response, and observed tool results into
-  // one canonical transcript. Finalize that in-memory snapshot synchronously
+  // one canonical transcript. Stage that in-memory snapshot synchronously
   // BEFORE the lifecycle generation changes; once generation is bumped, the
-  // normal cancellation cleanup save is intentionally rejected as stale.
+  // normal cancellation cleanup save is intentionally rejected as stale. It
+  // is only staged: a refused barrier rolls it back so the turn keeps running
+  // and checkpointing as if no close had been attempted.
+  let closeSnapshot = null;
   try {
-    entry?.prepareCloseSnapshot?.(reason);
+    closeSnapshot = entry?.prepareCloseSnapshot?.tentative?.(reason) ?? null;
   } catch {
     /* best-effort */
   }
-  _stopToolActivityHeartbeat(id);
   // 1. Tombstone first — this wins the race against saveSession().
   //    Skipped when tombstone=false: no closed:true marker is planted, so
   //    the session file stays intact and resumeSession() will accept it.
@@ -66,7 +70,10 @@ export function closeSession(id, reason = 'manual', opts = {}) {
   //    it once disk generation moves past that. Without this bump the late
   //    write could silently overwrite the session after the user resumes
   //    it back (BL: burned-session late-save clobber).
-  const newGen = tombstone ? markSessionClosed(id, reason) : bumpSessionGeneration(id, reason);
+  const outcome = { absent: false };
+  const newGen = tombstone
+    ? markSessionClosed(id, reason, { outcome })
+    : bumpSessionGeneration(id, reason, { outcome });
   // Durable lifecycle barrier check. ANY nonnumeric result means the barrier
   // is not on disk — a write failure, a liveness/ownership veto, a contended
   // commit lock, or a missing record. Only a failed write publishes a
@@ -76,13 +83,23 @@ export function closeSession(id, reason = 'manual', opts = {}) {
   // crash checkpoint while the session stays open and resumable on disk — the
   // way a failed close silently destroys a turn. Leave every runtime
   // structure intact, surface the cause, and report failure to the caller.
-  if (typeof newGen !== 'number') {
+  //
+  // The one exception is a record that was legitimately already gone (never
+  // saved, or deleted): the barrier cancelled its pending writes under the
+  // commit lock and found no copy on disk or in memory, so there is nothing
+  // a late save could clobber and nothing left open to resume. That close
+  // succeeds and tears the runtime down normally.
+  if (typeof newGen !== 'number' && outcome.absent !== true) {
+    closeSnapshot?.rollback();
     reportCloseBarrierFailure({ id, reason, tombstone, entry });
     return false;
   }
+  // The staged snapshot was folded into the synchronous generation write
+  // above; committing it stops the turn's checkpoint writer. Only now is it
+  // safe to remove the crash fallback.
+  closeSnapshot?.commit();
+  _stopToolActivityHeartbeat(id);
   cancelOwnedShellProcesses({ id, reason, tombstone });
-  // prepareCloseSnapshot was folded into the synchronous generation write
-  // above. Only now is it safe to remove the crash fallback.
   clearTurnCheckpoint(id);
   teardownSessionRuntime({ id, entry, reason, tombstone, newGen });
   return true;
@@ -95,7 +112,7 @@ export function closeSession(id, reason = 'manual', opts = {}) {
  */
 function reportCloseBarrierFailure({ id, reason, tombstone, entry }) {
   const commitError = getSessionLifecycleCommitError(id);
-  let detail = 'no durable barrier written (veto, contended commit, or missing record)';
+  let detail = 'no durable barrier written (veto or contended commit)';
   if (commitError) {
     const code = commitError.code ? ` (${commitError.code})` : '';
     detail = `${commitError.message}${code}`;
@@ -128,16 +145,27 @@ function reportCloseBarrierFailure({ id, reason, tombstone, entry }) {
  * with the unconfirmed outcome. The re-stamp is idempotent: markSessionClosed
  * keeps the original close time and generation and only upgrades the cancel
  * scalars (unconfirmed never downgrades back to cancelled).
+ *
+ * Every tree records its process identities before the kill (the kill may
+ * break the parent chain). When a snapshot is still pending the cancel is
+ * sent once it lands or after PROCESS_TABLE_READ_BOUND_MS, whichever first;
+ * the close itself does not wait. Holds this session leaves behind become
+ * releasable from any session that sees their workspace.
  */
 function cancelOwnedShellProcesses({ id, reason, tombstone }) {
-  let cancelConfirmed = true;
+  const record = (result) => {
+    if (tombstone && result?.confirmed === false) markSessionClosed(id, reason, { cancelStatus: 'cancel-unconfirmed' });
+  };
+  // A cancel that threw proved nothing either.
+  const unconfirmed = () => record({ confirmed: false });
   try {
-    cancelConfirmed = cancelNativeTasks({ ownerSessionId: id })?.confirmed !== false;
+    const result = cancelOwnedShellTrees(id);
+    if (typeof result?.then === 'function') result.then(record, unconfirmed);
+    else record(result);
   } catch {
-    // A cancel that threw proved nothing either.
-    cancelConfirmed = false;
+    unconfirmed();
   }
-  if (tombstone && !cancelConfirmed) markSessionClosed(id, reason, { cancelStatus: 'cancel-unconfirmed' });
+  noteShellOwnerSessionClosed(id);
 }
 
 /**
@@ -163,6 +191,7 @@ function teardownSessionRuntime({ id, entry, reason, tombstone, newGen }) {
       /* ignore */
     }
   }
+  forgetSideQuestion(id, { cancel: true });
   closeProviderConnections(id, `session-close:${reason}`);
   // Diagnostic: one-line stderr so operators can distinguish the four close
   // pathways (request-abort / manual / idle-sweep / runner-crash). iterCount
@@ -264,8 +293,8 @@ export function abortSessionTurn(id, reason = 'turn-abort') {
  *     what a settled turn left behind;
  *   - offload sidecars, the turn checkpoint and persisted pending messages
  *     are left intact — they are the follow-up turn's context, not runtime.
- * Terminal ownership stays with the caller's own reap path (agent-tool
- * scheduleReap → closeSession('terminal-reap')).
+ * A terminal session is never closed here; it stays open until it is
+ * explicitly cancelled or deleted.
  *
  * Returns false (changing nothing) when the session is still in flight.
  */
@@ -288,6 +317,7 @@ export function unloadSessionRuntime(id, reason = 'runtime-unload') {
     if (IN_FLIGHT_STAGES.has(entry.stage)) return false;
   }
   _stopToolActivityHeartbeat(id);
+  forgetSideQuestion(id, { cancel: true });
   closeProviderConnections(id, `runtime-unload:${reason}`);
   releaseSessionReadCaches(id);
   _clearSessionRuntime(id);

package/src/runtime/agent/orchestrator/session/manager/session-crud.mjs

@@ -27,8 +27,9 @@ import { isSessionCompactionBlocked, getSessionAbortSignal, _runtimeEntries } fr
 import { mintSessionId } from './session-id.mjs';
 import { hideCompactionArchive } from '../compaction-archive-capture.mjs';
 import { writeStderrBestEffort } from '../../../../shared/best-effort-stderr.mjs';
+import { forgetSideQuestion } from '../side-question-store.mjs';
 
-/** Force-flush session metrics to disk. Used by watchdog terminal-reap (fix B). */
+/** Force-flush session metrics to disk. */
 export async function flushSessionMetrics(sessionId) {
   if (!sessionId) return;
   const session = loadSession(sessionId);
@@ -91,13 +92,30 @@ export async function updateSessionManualTitle(id, title) {
   if (!session || session.closed === true) return false;
   const normalized = normalizeSessionTitle(title);
   if (!normalized) return false;
-  if (session.title === normalized && session.titleLocked === true) return false;
+  if (session.title === normalized && session.titleLocked === true && session.titleSource === 'user') return false;
   session.title = normalized;
   session.titleLocked = true;
+  session.titleSource = 'user';
   session.titleUpdatedAt = Date.now();
   await saveSessionAsync(session, { expectedGeneration: session.generation });
   return true;
 }
+// A title the model chose (session tool). Never overwrites a user title; a
+// legacy locked session without titleSource counts as user-titled. It locks
+// the title against auto-generated ones but stays replaceable by the model.
+export async function updateSessionAiTitle(id, title) {
+  const session = loadSession(id);
+  if (!session || session.closed === true) return { ok: false, reason: 'not-found' };
+  const normalized = normalizeSessionTitle(title);
+  if (!normalized) return { ok: false, reason: 'empty-title' };
+  if (session.titleLocked === true && session.titleSource !== 'ai') return { ok: false, reason: 'user-title' };
+  session.title = normalized;
+  session.titleLocked = true;
+  session.titleSource = 'ai';
+  session.titleUpdatedAt = Date.now();
+  await saveSessionAsync(session, { expectedGeneration: session.generation });
+  return { ok: true, title: normalized };
+}
 // --- Clear messages (keep system prompt + provider/model/cwd) ---
 // Token/provider accounting a cleared transcript starts from; shared by the
 // live session and the cold fork of its outgoing transcript.
@@ -262,8 +280,10 @@ export async function clearSessionMessages(sessionId, options = {}) {
 
   session.messages = keep;
   // Clear truncates the transcript wholesale; drop the provider prefix
-  // snapshot so the next send re-baselines instead of history_shrink.
+  // snapshot so the next send re-baselines instead of history_shrink, and
+  // the request a /btw side question would fork.
   delete session._providerPrefixGuardState;
+  forgetSideQuestion(sessionId);
   resetSessionBp3Environment(session);
   Object.assign(session, clearedTokenAccounting(now));
   session.compaction = {
@@ -372,9 +392,11 @@ export async function rewindSessionMessagesTo(sessionId, options = {}) {
   const removed = messages.length - start;
   session.messages = messages.slice(0, start);
   // The provider cache is keyed on the exact prefix we just truncated;
-  // the prefix-guard snapshot describes it too and must go with it.
+  // the prefix-guard snapshot and the /btw fork request describe it too and
+  // must go with it.
   session.providerState = undefined;
   delete session._providerPrefixGuardState;
+  forgetSideQuestion(sessionId);
   session.updatedAt = Date.now();
   session.lastUsedAt = Date.now();
   await saveSessionAsync(session, { expectedGeneration: session.generation });

package/src/runtime/agent/orchestrator/session/manager/session-fallback-title.mjs

@@ -0,0 +1,82 @@
+// manager/session-fallback-title.mjs
+// Durable, transcript-independent fallback title: the first usable
+// user-authored prompt, stored on `session.title` so the conversation keeps a
+// name after compaction replaces the transcript. Leaf module (no session-crud
+// import) so ask-turn-execute, compaction-runner and pre-send-compact can share it.
+import { compactSessionTitle } from '../../runtime-core/session-title.mjs';
+import { cleanSessionPreview, isSessionPreviewNoise, sessionMessageText } from '../../runtime-core/session-text.mjs';
+import { IMPORTED_MESSAGE_SOURCE } from '../imported-message.mjs';
+import { isActualUserInstructionMessage } from '../compact/messages.mjs';
+
+const UNTITLED_PLACEHOLDER = /^untitled(?:\s+session)?$/i;
+const MEDIA_PLACEHOLDER = /^\[(?:image|video|file)\]$/i;
+// Attachment envelopes carry payloads, not prose: closed blocks, then a block
+// that lost its closing tag (the rest of the text is payload), then bare
+// self-closing tags. Stripped before truncation so a large payload cannot
+// crowd the prompt out of the bounded source.
+const ATTACHMENT_TAGS = 'file|attachment|document|image|video|pdf';
+const ATTACHMENT_BLOCK = new RegExp(`<(${ATTACHMENT_TAGS})\\b[^>]*>[\\s\\S]*?<\\/\\1\\s*>`, 'gi');
+const ATTACHMENT_UNTERMINATED = new RegExp(`<(?:${ATTACHMENT_TAGS})\\b[^>]*>[\\s\\S]*$`, 'i');
+const ATTACHMENT_SELF_CLOSING = new RegExp(`<(?:${ATTACHMENT_TAGS})\\b[^>]*\\/>`, 'gi');
+const MEDIA_MARKER = /\[(?:Image|Video|File)(?:\s*#?\d+)?(?::[^\]\r\n]*)?\]/gi;
+
+function stripAttachmentEnvelopes(text) {
+  return text
+    .replace(ATTACHMENT_BLOCK, ' ')
+    .replace(ATTACHMENT_SELF_CLOSING, ' ')
+    .replace(ATTACHMENT_UNTERMINATED, ' ')
+    .replace(MEDIA_MARKER, ' ');
+}
+
+function isUsableTitle(title) {
+  const text = String(title || '').trim();
+  return !!text && !UNTITLED_PLACEHOLDER.test(text);
+}
+
+/** Bounded single-line title from user-authored text; '' when nothing usable. */
+export function fallbackTitleFromText(content) {
+  const raw = sessionMessageText(content);
+  if (!raw || /^\s*reference files:/i.test(raw)) return '';
+  const prose = stripAttachmentEnvelopes(raw);
+  if (isSessionPreviewNoise(prose)) return '';
+  const title = compactSessionTitle(cleanSessionPreview(prose, 4_000));
+  return isUsableTitle(title) && !MEDIA_PLACEHOLDER.test(title) ? title : '';
+}
+
+/** A turn the human typed: provenance lives in `meta` (`source` of an injected
+ *  goal/notification/compaction turn, `synthetic`), never on the message root. */
+function isHumanAuthoredTurn(message) {
+  if (message?.role !== 'user' || message.internal === true || message.synthetic === true) return false;
+  const meta = message.meta;
+  if (meta && typeof meta === 'object') {
+    if (meta.synthetic === true) return false;
+    if (meta.source && meta.source !== IMPORTED_MESSAGE_SOURCE) return false;
+  }
+  return isActualUserInstructionMessage(message);
+}
+
+/** Title from the first usable human user message of a transcript. */
+export function fallbackTitleFromMessages(messages) {
+  for (const message of Array.isArray(messages) ? messages : []) {
+    if (!isHumanAuthoredTurn(message)) continue;
+    const title = fallbackTitleFromText(message.content);
+    if (title) return title;
+  }
+  return '';
+}
+
+/** Fills `session.title` only when missing. Never touches a locked (manual/AI)
+ *  or generated title, and leaves generatedTitleStage unset so
+ *  updateSessionGeneratedTitle can still upgrade it. The caller persists. */
+export function applyFallbackSessionTitle(session, title) {
+  if (!session || !isUsableTitle(title) || isUsableTitle(session.title)) return false;
+  if (session.titleLocked === true || session.generatedTitleStage) return false;
+  session.title = title;
+  session.titleUpdatedAt = Date.now();
+  return true;
+}
+
+export function backfillFallbackSessionTitle(session, messages) {
+  if (!session || isUsableTitle(session.title)) return false;
+  return applyFallbackSessionTitle(session, fallbackTitleFromMessages(messages));
+}