brl-subagent 2.3.9 → 2.5.0

package/src/session-manager.ts

@@ -1,8 +1,9 @@
+// Purpose: Background execution: SDK sessions (`createAgentSession`), agent records, timeouts, steering, and settle paths.
 import { randomUUID } from 'crypto';
 import { join } from 'path';
-import { mkdirSync, writeFileSync, readFileSync, existsSync, readdirSync } from 'fs';
+import { mkdirSync, writeFileSync, readFileSync, readdirSync, existsSync } from 'fs';
 import type { BackgroundAgent, AgentStatus, GitMode, SubagentResult, SubagentRun, ThinkingLevel, SubagentToolOptions, UsageStats, ErrorCategory } from './types';
-import { EMPTY_USAGE, CUSTOM_ENTRY_TYPES, classifyError, classifyTerminalOutcome, isSubagentError, isProviderError, coherentFailureReason, SUBAGENT_ABORTED_MESSAGE } from './types';
+import { EMPTY_USAGE, classifyError, classifyTerminalOutcome, isProviderError, coherentFailureReason, SUBAGENT_ABORTED_MESSAGE } from './types';
 import { accumulateUsage } from './runner';
 import * as eventBus from './event-bus';
 import * as transcript from './transcript';
@@ -10,7 +11,11 @@ import { createEvent } from './event-bus';
 import { assertSafeAgentId, sanitizeErrorMessage } from './sanitize';
 import { wrapTask } from './prompt';
 import { createLogger } from './logging';
-import { getCurrentBranch, createWorkBranch, captureDiff, switchToBranch, deleteBranch, hasUncommittedChanges, getRepoRoot, commitAll, captureWorkingDiff } from './git';
+import { getCurrentBranch, getHeadState, restoreHead, createWorkBranch, captureDiff, deleteBranch, hasUncommittedChanges, getRepoRoot, commitAll, captureWorkingDiff } from './git';
+import type { HeadState } from './git';
+import { normalizeTimeout, DEFAULT_BACKGROUND_DEADLINE_MS } from './validate';
+import { currentProcessOwner } from './recovery';
+import { persistRunRecord } from './run-registry';
 
 const log = createLogger('brl-subagent');
 import type { ExtensionAPI, ExtensionContext } from '@earendil-works/pi-coding-agent';
@@ -83,7 +88,7 @@ function persistAgent(agent: BackgroundAgent): void {
   try {
     assertSafeAgentId(agent.id);
   } catch {
-    console.error(`[brl-subagent] Refusing to persist agent with invalid id: ${agent.id}`);
+    log.error(`Refusing to persist agent with invalid id: ${agent.id}`);
     return;
   }
   ensureStorageDir();
@@ -100,7 +105,7 @@ function persistAgent(agent: BackgroundAgent): void {
     writeFileSync(filePath, JSON.stringify(persistable, null, 2), { encoding: 'utf-8', mode: 0o600 });
   } catch (err) {
     // Log but never throw — persistence must not break execution
-    console.error(`[brl-subagent] Failed to persist agent ${agent.id}:`, err);
+    log.error(`Failed to persist agent ${agent.id}`, { error: err instanceof Error ? err.message : String(err) });
   }
 }
 
@@ -117,49 +122,6 @@ function loadAgent(id: string): BackgroundAgent | null {
   }
 }
 
-/**
- * Create a new background agent session
- * 
- * NOTE: In v2.0.3, this creates a record but does NOT actually spawn a pi session.
- * The actual session spawning will be implemented when pi's ExtensionAPI supports it.
- * For now, this is a placeholder that creates the agent record.
- */
-export function createSession(params: {
-  task: string;
-  type?: string;
-  description?: string;
-  model?: string;
-  thinkingLevel?: ThinkingLevel;
-  systemPrompt?: string;
-}): BackgroundAgent {
-  const id = generateUUID();
-  const agent: BackgroundAgent = {
-    id,
-    sessionId: `session-${id}`,
-    type: params.type || 'general-purpose',
-    description: params.description || params.task.slice(0, 50),
-    status: 'pending',
-    startedAt: Date.now(),
-    task: params.task,
-    model: params.model || 'unknown',
-    thinkingLevel: params.thinkingLevel || 'medium',
-  };
-  
-  agents.set(id, agent);
-  persistAgent(agent);
-
-  // Start transcript for this agent
-  transcript.startTranscript(agent.id, params.task);
-
-  eventBus.emit(eventBus.createEvent('subagent:created', agent.id, {
-    type: agent.type,
-    description: agent.description,
-    task: agent.task,
-  }));
-
-  return agent;
-}
-
 /**
  * Get agent record by ID
  */
@@ -178,20 +140,51 @@ export function getAgent(id: string): BackgroundAgent | null {
 }
 
 /**
- * List all background agents
+ * Option B U1: every agent record persisted on disk (cross-session — the
+ * `.pi/subagents/` store survives a process death; the conductor's session run
+ * entries do not). Boot recovery does NOT use this: it sources candidates from
+ * the durable run registry and reads background records ONE at a time by id
+ * (`recoverInflightRuns`'s `readAgentRecord`), precisely to avoid parsing the
+ * whole store; production has no caller for this sweep. Unreadable/corrupt
+ * files and unsafe ids are skipped, never thrown.
  */
-export function listAgents(): BackgroundAgent[] {
-  ensureStorageDir();
-  const files = readdirSync(STORAGE_DIR).filter(f => f.endsWith('.json'));
-  const result: BackgroundAgent[] = [];
-  
+export function listPersistedAgents(): BackgroundAgent[] {
+  let files: string[];
+  try {
+    if (!existsSync(STORAGE_DIR)) return [];
+    files = readdirSync(STORAGE_DIR);
+  } catch {
+    return [];
+  }
+  const records: BackgroundAgent[] = [];
   for (const file of files) {
-    const id = file.replace('.json', '');
-    const agent = agents.get(id) || loadAgent(id);
-    if (agent) result.push(agent);
+    if (!file.endsWith('.json')) continue;
+    const id = file.slice(0, -'.json'.length);
+    try {
+      assertSafeAgentId(id);
+    } catch {
+      continue;
+    }
+    const record = loadAgent(id);
+    if (record) records.push(record);
   }
-  
-  return result.sort((a, b) => b.startedAt - a.startedAt);
+  return records;
+}
+
+/**
+ * Option B U1 (D3): read-modify-write the interrupted mark onto a persisted
+ * agent record. Idempotent: an already-marked record is returned unchanged.
+ * Returns null when the record does not exist.
+ */
+export function markAgentInterrupted(id: string, interruptedAt: string): BackgroundAgent | null {
+  const agent = getAgent(id);
+  if (!agent) return null;
+  if (!agent.interruptedAt) {
+    agent.interruptedAt = interruptedAt;
+    agents.set(id, agent);
+    persistAgent(agent);
+  }
+  return agent;
 }
 
 /**
@@ -225,25 +218,6 @@ export function updateAgentStatus(id: string, status: AgentStatus, error?: strin
   return agent;
 }
 
-/**
- * Set agent result
- */
-export function setAgentResult(id: string, result: SubagentResult): BackgroundAgent | null {
-  const agent = getAgent(id);
-  if (!agent) return null;
-  
-  agent.result = result;
-  // Issue #179 (D1): honor the full terminal reason (stopReason error/aborted/
-  // length/incomplete), not exitCode alone — a mid-run provider death resolves
-  // with exitCode 0 and was previously recorded as 'completed'.
-  agent.status = isSubagentError(result) ? 'failed' : 'completed';
-  agent.completedAt = Date.now();
-  
-  agents.set(id, agent);
-  persistAgent(agent);
-  return agent;
-}
-
 /**
  * Issue #179 (D4): when a run ends in a failure, the prose extracted by
  * extractFinalOutput may come from an EARLIER turn — the failing turn carries
@@ -281,7 +255,7 @@ function defaultTerminalMessage(stopReason: string | undefined): string {
  * Extract the final assistant text from a session's messages.
  * Falls back to the LAST assistant message with non-empty text content — the
  * final message is often a tool-call-only turn (agent stopped mid-turn, failed,
- * or hit the hard cap), and that turn carries no text of its own.
+ * or hit the deadline), and that turn carries no text of its own.
  */
 export function extractFinalOutput(session: { messages: Array<{ role: string; content?: Array<{ type: string; text?: string }> | string | null }> }): string {
   const assistants = [...session.messages].reverse().filter(m => m.role === 'assistant');
@@ -351,24 +325,45 @@ export async function stopAgent(id: string): Promise<BackgroundAgent | null> {
 }
 
 /**
- * Steer a running agent by injecting a message
- * 
- * NOTE: In v2.0.3, this is a placeholder.
- * Actual message injection will be implemented when pi's ExtensionAPI supports it.
+ * Steer a running agent by injecting a message into its live session.
+ *
+ * Issue #241: steering DELIVERS via the SDK's `AgentSession.steer()` — the
+ * message is queued while the agent is running and delivered after the current
+ * assistant turn finishes its tool calls, before the next model call.
+ *
+ * Steering is NOT a state transition: the agent stays 'running' (no status
+ * flip, no persistAgent) so REPEAT steers keep working. Delivery failures
+ * propagate to the caller — a false success would tell the conductor a steer
+ * landed when the agent never saw it. The transcript line is an audit record
+ * written AFTER successful delivery, best-effort: a landed steer must never be
+ * reported as failed because the audit write failed.
  */
-export function steerAgent(id: string, message: string): BackgroundAgent | null {
+export async function steerAgent(id: string, message: string): Promise<BackgroundAgent | null> {
   const agent = getAgent(id);
   if (!agent) return null;
   if (agent.status !== 'running') {
     throw new Error(`Cannot steer agent ${id}: status is ${agent.status}, not running`);
   }
 
-  // Record steering in transcript
-  transcript.appendEntry(id, 'user', `Steering: ${message}`);
+  const session = agent._sessionRef;
+  if (!session) {
+    throw new Error(`Cannot steer agent ${id}: no live session (the run may be settling)`);
+  }
+  if (typeof session.steer !== 'function') {
+    throw new Error('installed pi SDK has no AgentSession.steer — steering unsupported');
+  }
 
-  agent.status = 'steered';
-  agents.set(id, agent);
-  persistAgent(agent);
+  // Deliver FIRST — a rejection here must surface as a real tool error, never
+  // a recorded-but-undelivered steer.
+  await session.steer(message);
+
+  // Audit line — best-effort. The steer already landed; an append failure is
+  // logged, not propagated.
+  try {
+    transcript.appendEntry(id, 'user', `Steering: ${message}`);
+  } catch (err) {
+    log.warn(`steerAgent: transcript append failed for ${id}`, { error: (err as Error).message });
+  }
 
   eventBus.emit(eventBus.createEvent('subagent:steered', agent.id, { message }));
 
@@ -376,15 +371,13 @@ export function steerAgent(id: string, message: string): BackgroundAgent | null
 }
 
 /**
- * Get transcript path for an agent
+ * Get transcript path for an agent.
+ *
+ * Issue #276: the format lives in `transcript-path.ts` (the single source).
+ * This re-export preserves the historical `session-manager.getTranscriptPath`
+ * surface for `index.ts`'s dynamic import and the existing tests.
  */
-export function getTranscriptPath(id: string): string {
-  // F24: reachable with LLM-controlled ids (get_agent_result). Throw on invalid
-  // ids — the tool caller surfaces it as an error. (Defense in depth: getAgent
-  // already validated before this is reached with a live agent.)
-  assertSafeAgentId(id);
-  return join('.pi', 'output', `agent-${id}.jsonl`);
-}
+export { transcriptPath as getTranscriptPath } from './transcript-path';
 
 /**
  * Spawn a background session using pi's session API
@@ -415,6 +408,11 @@ export async function spawnBackgroundSession(
     /** Issue #114: per-unit priority — recorded on the run entry + agent record
      *  so the drill-in header and history carry it (absent → no segment). */
     priority?: string;
+    /** Option B U1: durability identity. A retry inherits the original's
+     *  dispatchId and records resumeOf/attempt; a fresh dispatch omits them. */
+    dispatchId?: string;
+    resumeOf?: string;
+    attempt?: number;
   }
 ): Promise<BackgroundAgent> {
   // Serialize access to pi API to prevent concurrent import races
@@ -525,6 +523,13 @@ export async function spawnBackgroundSession(
   // Set session name
   session.setSessionName(`background-${id.slice(0, 8)}`);
   
+  // Option B U1: durability identity. Background runs have no child process
+  // (the session is in-process), so there is no childMarker — only the owner
+  // identity that a boot scan uses to tell a live conductor from a dead one.
+  const dispatchId = params.dispatchId ?? generateUUID();
+  const attempt = params.attempt ?? 1;
+  const owner = currentProcessOwner();
+
   // Create agent record
   const agent: BackgroundAgent = {
     id,
@@ -537,6 +542,10 @@ export async function spawnBackgroundSession(
     model: params.model || 'unknown',
     thinkingLevel: params.thinkingLevel || 'medium',
     priority: params.priority,
+    dispatchId,
+    resumeOf: params.resumeOf,
+    attempt,
+    owner,
   };
   
   agents.set(id, agent);
@@ -562,8 +571,12 @@ export async function spawnBackgroundSession(
     priority: params.priority,
     startedAt: new Date().toISOString(),
     originalParams: params.originalParams,
+    dispatchId,
+    resumeOf: params.resumeOf,
+    attempt,
+    owner,
   };
-  pi.appendEntry(CUSTOM_ENTRY_TYPES.run, run);
+  persistRunRecord(pi, run, "background");
 
   // Issue #98: keep the session run entry in lockstep with the agent record —
   // every terminal branch that flips agent.status also finalizes the run entry
@@ -632,7 +645,7 @@ export async function spawnBackgroundSession(
           ? { ...(run.originalParams ?? {}), errorCategory }
           : run.originalParams,
     };
-    pi.appendEntry(CUSTOM_ENTRY_TYPES.run, entry);
+    persistRunRecord(pi, entry);
     // Issue #179 (D6): the explicit settle line — the log's job is to record the
     // CLASSIFIED OUTCOME, which cwd alone can never convey.
     log.info("Background run settled", {
@@ -717,9 +730,14 @@ export async function spawnBackgroundSession(
   // hard failure — never spawn an unisolated background agent that was asked
   // for isolation (fail-loud, same principle as foreground's fallback but
   // background cannot warn-and-continue safely).
-  let originalBranch: string | undefined;
+  let headState: HeadState | undefined;
   let workBranchName: string | undefined;
   let releaseGitLock: (() => void) | undefined;
+  // Idempotency guard for cleanupWorkBranch: it must be safe to call from both
+  // the normal settle path and the catch-all that runs when a settle step
+  // throws FIRST (before its own cleanup call). Without this the second call
+  // would re-restore/re-delete and log spurious warnings.
+  let gitCleanupDone = false;
   const gitCwd = params.cwd ?? ctx.cwd;
   if (params.gitMode === 'branch') {
     // C2: serialize the FULL branch lifecycle per repo. The spawnQueue only
@@ -752,13 +770,13 @@ export async function spawnBackgroundSession(
           'requesting background gitMode=branch isolation'
         );
       }
-      originalBranch = getCurrentBranch(gitCwd);
-      const branchResult = createWorkBranch(gitCwd, originalBranch);
+      headState = getHeadState(gitCwd);
+      const branchResult = createWorkBranch(gitCwd, headState.sha);
       if (branchResult.ok) {
         workBranchName = branchResult.branch;
         log.info('Created work branch for background agent', {
           branch: workBranchName,
-          base: originalBranch,
+          base: headState.branch,
           agentId: id,
         });
       } else {
@@ -796,7 +814,8 @@ export async function spawnBackgroundSession(
   // uncommitted edits would leak into the base working tree on switch —
   // commitAll first makes the diff real and the switch clean.
   const cleanupWorkBranch = (): { gitBranch?: string; gitDiff?: string } => {
-    if (!workBranchName || !originalBranch) return {};
+    if (gitCleanupDone || !workBranchName || !headState) return {};
+    gitCleanupDone = true;
     const info: { gitBranch?: string; gitDiff?: string } = { gitBranch: workBranchName };
     // The lock MUST be released on every exit path — early returns included.
     try {
@@ -834,7 +853,7 @@ export async function spawnBackgroundSession(
             if (workingDiff) info.gitDiff = workingDiff;
           }
         }
-        const diffResult = captureDiff(gitCwd, originalBranch);
+        const diffResult = captureDiff(gitCwd, headState.sha);
         if (diffResult.ok && diffResult.diff.trim()) {
           // Merge committed + working diffs — either can exist alone.
           info.gitDiff = info.gitDiff
@@ -845,9 +864,12 @@ export async function spawnBackgroundSession(
         log.warn(`captureDiff failed for background agent ${id}`, { error: (err as Error).message });
       }
       try {
-        switchToBranch(gitCwd, originalBranch);
+        const restoreResult = restoreHead(gitCwd, headState);
+        if (!restoreResult.ok) {
+          log.warn(`restoreHead failed for background agent ${id}`, { error: restoreResult.error });
+        }
       } catch (err) {
-        log.warn(`switchToBranch failed for background agent ${id}`, { error: (err as Error).message });
+        log.warn(`restoreHead failed for background agent ${id}`, { error: (err as Error).message });
       }
       try {
         deleteBranch(gitCwd, workBranchName);
@@ -868,6 +890,11 @@ export async function spawnBackgroundSession(
   // terminal so no zombie 'running' record survives; never rethrow.
   const markTerminalBestEffort = (fallback: AgentStatus): void => {
     try {
+      // Issue #53 / review C: this catch-all fires when a settle handler step
+      // threw — possibly BEFORE the branch's own cleanupWorkBranch() call. Run
+      // it here too (idempotent) so a throw can never bypass branch teardown
+      // and strand the work branch in the repo working tree.
+      cleanupWorkBranch();
       // Issue #31 (PR #76 review): this catch-all fires when a settle handler
       // threw — either BEFORE the branch's own capture (ref still live: capture
       // now, it is the last chance to record the session's output) or AFTER it
@@ -944,9 +971,13 @@ export async function spawnBackgroundSession(
   // Armed immediately after the prompt call so in-prompt preflight (auth
   // check, model resolution) counts toward the deadline; the abort lands in
   // the .then below as an aborted run (probe contract). We pre-set the status
-  // so the .then keeps 'stopped' with the timeout reason recorded. The value
-  // is normalized upstream (normalizeTimeout) but clamp again here — a raw
-  // >=2^31 or Infinity would make Node fire the timer at ~1ms (instant kill).
+  // so the .then keeps 'stopped' with the timeout reason recorded. The raw
+  // value is normalized here (issue #240): a raw >=2^31 or Infinity would make
+  // Node fire the timer at ~1ms (instant kill), so normalizeTimeout maps it to
+  // undefined. An explicit timeout is HONORED verbatim (no ceiling); only the
+  // no-timeout fallback uses the 30m background default. The `params.timeout`
+  // guard below keeps this timer unarmed on the no-timeout path, where the
+  // index.ts deadline timer owns the no-timeout default (no redundant timer).
   let timeoutHandle: ReturnType<typeof setTimeout> | undefined;
   if (params.timeout && params.timeout > 0) {
     timeoutHandle = setTimeout(() => {
@@ -966,7 +997,7 @@ export async function spawnBackgroundSession(
           error: (err as Error).message,
         });
       }
-    }, Math.min(params.timeout, 30 * 60 * 1000));
+    }, normalizeTimeout(params.timeout) ?? DEFAULT_BACKGROUND_DEADLINE_MS);
   }
 
   runPromise.then(() => {

package/src/state.ts

@@ -1,3 +1,4 @@
+// Purpose: Session-bound state container with versioned validation and migration for persisted settings.
 /**
  * brl-subagent — State Management (F5, F7, F9)
  *
@@ -34,6 +35,7 @@ import {
 	CIRCUIT_DEGRADED_THINKING,
 } from "./types";
 import { cleanupRuns } from "./history";
+import { persistRunRecord, type InflightRunKind } from "./run-registry";
 import type { Logger } from "./logging";
 
 // ---------------------------------------------------------------------------
@@ -68,14 +70,21 @@ export const STALE_FINALIZE_GRACE_MS = POLLER_TICK_MS + 1000;
 
 /**
  * Terminal-preferring run-entry lookup — the ONE implementation of the
- * preference rule.
+ * preference rule. Recovery's `dedupeRunEntriesById` delegates here, so the
+ * boot scan and every display/retry lookup agree by construction.
  *
  * Each run writes TWO custom entries sharing its id, in append order: a spawn
  * entry (status "running", carrying `originalParams`) FIRST, then the final
  * entry (status "done"/"failed", stamped with fullOutput/cost/duration) at
- * settle. Prefer the terminal entry; when none is terminal yet, fall back to
- * the first match (the pre-finalize spawn shape). Returns undefined when no
- * entry matches.
+ * settle. Preference, in order:
+ *
+ *   1. a TERMINAL entry (status !== "running") — the run is resolved;
+ *   2. among non-terminal entries, one carrying the D3 `interruptedAt` mark —
+ *      append-only stores keep the original spawn entry forever, so the marked
+ *      clone is the authoritative RECOVERED state U3's shared lookup reads;
+ *   3. otherwise the first match (the pre-finalize spawn shape).
+ *
+ * Returns undefined when no entry matches.
  */
 export function resolveTerminalRunEntry(
 	entries: SubagentRun[],
@@ -83,7 +92,37 @@ export function resolveTerminalRunEntry(
 ): SubagentRun | undefined {
 	const matching = entries.filter((r) => r.id === id);
 	if (matching.length === 0) return undefined;
-	return matching.find((r) => r.status !== "running") ?? matching[0];
+	return (
+		matching.find((r) => r.status !== "running") ??
+		matching.find((r) => r.interruptedAt) ??
+		matching[0]
+	);
+}
+
+/**
+ * Run-history display projection (issue #259): ONE record per SETTLED run.
+ *
+ * Each run appends two entries sharing its id — a spawn entry (status
+ * "running") first, then the terminal entry at settle — so a raw entry list
+ * renders every run twice and the spawn row shows a stale "running" forever.
+ * This collapses each id to its terminal-preferred entry via the ONE shared
+ * rule (`resolveTerminalRunEntry`). Runs still in flight (spawn entry, no
+ * terminal entry yet) are omitted: live state belongs to the monitor.
+ *
+ * Ordering is preserved from `entries`; callers pass `getRunEntries` output
+ * (newest-first via `cleanupRuns`), which stays the single ordering authority —
+ * no re-sort is performed here.
+ */
+export function collapseRunsForHistory(entries: SubagentRun[]): SubagentRun[] {
+	const display: SubagentRun[] = [];
+	const seen = new Set<string>();
+	for (const entry of entries) {
+		if (seen.has(entry.id)) continue;
+		seen.add(entry.id);
+		const resolved = resolveTerminalRunEntry(entries, entry.id);
+		if (resolved && resolved.status !== "running") display.push(resolved);
+	}
+	return display;
 }
 
 // ---------------------------------------------------------------------------
@@ -193,8 +232,14 @@ export class SessionState {
 		});
 	}
 
-	persistRun(pi: ExtensionAPI, run: SubagentRun): void {
-		pi.appendEntry(CUSTOM_ENTRY_TYPES.run, run);
+	/**
+	 * Persist a run record through the ONE choke point (`persistRunRecord`),
+	 * which appends the session entry AND mirrors the record into the durable
+	 * in-flight registry. `kind` is supplied at dispatch; terminal writes clear
+	 * the registry entry.
+	 */
+	persistRun(pi: ExtensionAPI, run: SubagentRun, kind?: InflightRunKind): void {
+		persistRunRecord(pi, run, kind);
 	}
 
 	// -------------------------------------------------------------------

package/src/templates.ts

@@ -1,3 +1,4 @@
+// Purpose: Task-template resolution: `${param}` substitution over the file-backed template tiers.
 /**
  * brl-subagent — Task Templates
  *

package/src/transcript-path.ts

@@ -0,0 +1,41 @@
+// Purpose: The single declaration of the transcript path format — filesystem (`join`) and display (POSIX) forms.
+import { join } from "node:path";
+import { assertSafeAgentId } from "./sanitize";
+
+/**
+ * The transcript directory, relative to the project root. This is the ONE
+ * declaration of the format; every other module derives its path from here
+ * rather than re-inlining `.pi/output` in a template string (issue #276).
+ */
+export const TRANSCRIPT_DIR = ".pi/output";
+
+/**
+ * Filesystem path to an agent's transcript: `<dir>/agent-<id>.jsonl`.
+ *
+ * SECURITY (F24): the id is validated through `assertSafeAgentId` BEFORE it
+ * reaches `path.join` — join does NOT sanitize `../` or absolute segments, so
+ * a traversal id would otherwise escape `dir`. Keep this chokepoint for every
+ * filesystem caller (`transcript.ts`, the `get_agent_result` re-export).
+ *
+ * `dir` is a parameter so `transcript.ts` can forward its mutable test-only
+ * `OUTPUT_DIR`; production callers take the `TRANSCRIPT_DIR` default.
+ */
+export function transcriptPath(agentId: string, dir: string = TRANSCRIPT_DIR): string {
+  assertSafeAgentId(agentId);
+  return join(dir, `agent-${agentId}.jsonl`);
+}
+
+/**
+ * Display form of the transcript path: `<TRANSCRIPT_DIR>/agent-<id>.jsonl`,
+ * always with forward slashes so the rendered panel is identical on every
+ * platform.
+ *
+ * This is deliberately format-only: it does NOT call `assertSafeAgentId` and
+ * must never throw. It is called during TUI rendering (`tui.ts` →
+ * `buildOutputHonestyLines`) from a stored run record, where a throw would
+ * break the panel. Display text is POSIX while filesystem access uses `join` —
+ * the two forms intentionally differ (settled in issue #276).
+ */
+export function transcriptDisplayPath(agentId: string): string {
+  return `${TRANSCRIPT_DIR}/agent-${agentId}.jsonl`;
+}

package/src/transcript-tail.ts

@@ -1,3 +1,4 @@
+// Purpose: Pure line-planning for the drill-in transcript overlay (no TUI imports).
 /**
  * brl-subagent — Pure transcript-tail rendering for the drill-in overlay
  *

package/src/transcript.ts

@@ -1,11 +1,17 @@
-import { join } from 'path';
+// Purpose: JSONL transcript recording for every agent run (`.pi/output/agent-<id>.jsonl`).
 import { mkdirSync, appendFileSync, readFileSync, existsSync } from 'fs';
 import type { TranscriptEntry, TranscriptEntryType } from './types';
-import { assertSafeAgentId } from './sanitize';
+import { transcriptPath, TRANSCRIPT_DIR } from './transcript-path';
+import { createLogger } from './logging';
+
+// Issue #265: route the settle-path warning through the logger (file-only by
+// default) instead of a raw console.warn that corrupts the pi TUI.
+const log = createLogger('brl-subagent');
 
 // Output directory — overridable for tests (issue #52): unit tests must NOT
-// write into the real repo .pi/ dir; the setter is test-only.
-let OUTPUT_DIR = '.pi/output';
+// write into the real repo .pi/ dir; the setter is test-only. Defaults to the
+// single-sourced TRANSCRIPT_DIR (issue #276).
+let OUTPUT_DIR = TRANSCRIPT_DIR;
 
 /**
  * TEST-ONLY: point the transcript output at an alternate directory.
@@ -29,13 +35,9 @@ function ensureOutputDir(): void {
  * Get transcript file path for an agent
  */
 export function getTranscriptPath(agentId: string): string {
-  // F24: single chokepoint for every transcript file path. All internal callers
-  // (startTranscript/appendEntry/getTranscript/completeTranscript) pass
-  // generateUUID() ids, but get_agent_result feeds LLM-controlled ids in via
-  // getTranscript. path.join does not sanitize "../" or absolute segments, so
-  // throw on anything that is not a UUID before it reaches the filesystem.
-  assertSafeAgentId(agentId);
-  return join(OUTPUT_DIR, `agent-${agentId}.jsonl`);
+  // Issue #276: the format and the F24 `assertSafeAgentId` chokepoint live in
+  // transcript-path.ts; here we only forward the mutable test-only OUTPUT_DIR.
+  return transcriptPath(agentId, OUTPUT_DIR);
 }
 
 /**
@@ -117,7 +119,7 @@ export function completeTranscript(agentId: string, status: string): void {
   // appending — that invariant is load-bearing for caller validation).
   const path = getTranscriptPath(agentId);
   if (!existsSync(path)) {
-    console.warn(`[brl-subagent] completeTranscript: transcript missing for agent ${agentId} — skipping completion entry`);
+    log.warn(`completeTranscript: transcript missing for agent ${agentId} — skipping completion entry`);
     return;
   }
   appendEntry(agentId, 'system', `Transcript completed: ${status}`);

package/src/tui-format.ts

@@ -1,3 +1,4 @@
+// Purpose: Pure TUI row formatting shared by the monitor and dashboard (no TUI imports).
 /**
  * brl-subagent — Pure TUI formatting helpers
  *