@oh-my-pi/pi-coding-agent 16.0.10 → 16.0.11

package/dist/types/advisor/index.d.ts

@@ -1,3 +1,4 @@
 export * from "./advise-tool";
 export * from "./runtime";
+export * from "./transcript-recorder";
 export * from "./watchdog";

package/dist/types/advisor/transcript-recorder.d.ts

@@ -0,0 +1,52 @@
+import type { AgentMessage } from "@oh-my-pi/pi-agent-core";
+/**
+ * Reserved transcript stem for advisor session files. Chosen so it cannot
+ * collide with a task subagent's `<id>.jsonl` (task ids are reserved against
+ * this exact stem in {@link AgentOutputManager}).
+ */
+export declare const ADVISOR_TRANSCRIPT_STEM = "__advisor";
+export declare const ADVISOR_TRANSCRIPT_FILENAME = "__advisor.jsonl";
+/**
+ * Append-only persister for an advisor agent's transcript.
+ *
+ * The advisor is a passive reviewer with its own model usage, so — like a task
+ * subagent — its turns are written to a JSONL inside the owning session's
+ * artifacts dir (`<session>/__advisor.jsonl`, `<session>/<SubId>/__advisor.jsonl`
+ * for subagent advisors). That single file gives the advisor model proper usage
+ * attribution in `omp stats` (the stats parser scans the session dir
+ * recursively) and a read-only transcript in the Agent Hub, without making the
+ * advisor a registered, messageable peer.
+ *
+ * The target is derived from the *session file* (`getSessionFile()`), never
+ * `getArtifactsDir()` — subagents adopt the parent's artifact manager, so the
+ * artifacts dir points at the parent root and every subagent advisor would
+ * collide. The file path is resolved synchronously when a message finalizes and
+ * captured for the queued write, so a `/new`, resume, or session switch in
+ * flight can never misattribute an old advisor turn into the new session's file.
+ * On such a switch the previous writer is closed and the new file opened on the
+ * next recorded turn. The recorder never truncates: the advisor's in-memory
+ * context resets/compacts independently, but every billed turn is appended here.
+ */
+export declare class AdvisorTranscriptRecorder {
+    #private;
+    private readonly resolveSessionFile;
+    private readonly resolveCwd;
+    /**
+     * @param after Optional barrier the queue starts behind — used on the advisor
+     *   on→off→on toggle so a fresh recorder's first `open` waits for the prior
+     *   recorder's `close` and the two never hold the same `__advisor.jsonl` at once.
+     */
+    constructor(resolveSessionFile: () => string | undefined, resolveCwd: () => string, after?: Promise<unknown>);
+    /**
+     * Persist one finalized advisor message. Assistant turns carry the usage the
+     * stats parser reads; tool results round out the Hub transcript; user deltas
+     * (the advisor's "session update" prompts) are persisted but flagged
+     * `synthetic`/agent-attributed so they never inflate user-message metrics.
+     * Non-conversational message kinds are skipped.
+     */
+    record(message: AgentMessage): void;
+    /** Flush pending writes (best-effort). */
+    flush(): Promise<void>;
+    /** Flush and close the writer, releasing the session file. */
+    close(): Promise<void>;
+}

package/dist/types/commit/agentic/agent.d.ts

@@ -1,4 +1,4 @@
-import { type ThinkingLevel } from "@oh-my-pi/pi-agent-core";
+import type { ThinkingLevel } from "@oh-my-pi/pi-agent-core";
 import type { Api, Model } from "@oh-my-pi/pi-ai";
 import type { ModelRegistry } from "../../config/model-registry";
 import type { Settings } from "../../config/settings";

package/dist/types/config/settings-schema.d.ts

@@ -775,10 +775,6 @@ export declare const SETTINGS_SCHEMA: {
             readonly description: "Remove the 1-character horizontal padding from the left and right of the terminal output";
         };
     };
-    readonly "display.tabWidth": {
-        readonly type: "number";
-        readonly default: 3;
-    };
     readonly "display.shimmer": {
         readonly type: "enum";
         readonly values: readonly ["classic", "kitt", "disabled"];

package/dist/types/edit/file-snapshot-store.d.ts

@@ -48,7 +48,7 @@ export declare function recordFileSnapshot(session: FileSnapshotStoreOwner, abso
 /**
  * The 1-indexed file lines a hashline-formatted body actually displayed.
  * Single `NN:` rows contribute that line; a collapsed summary `NN-MM:` row
- * (a `{ .. }` brace pair) contributes only its boundary lines `NN` and `MM` —
+ * (a `{ … }` brace pair) contributes only its boundary lines `NN` and `MM` —
  * the elided interior was never shown, so editing inside it must be rejected.
  */
 export declare function parseSeenLinesFromHashlineBody(body: string): number[];

package/dist/types/extensibility/extensions/types.d.ts

@@ -25,6 +25,7 @@ import type * as PiCodingAgent from "../../index";
 import type { MemoryRuntimeContext } from "../../memory-backend";
 import type { CustomEditor } from "../../modes/components/custom-editor";
 import type { Theme } from "../../modes/theme/theme";
+import type { CompactMode } from "../../session/compact-modes";
 import type { CustomMessage } from "../../session/messages";
 import type { ReadonlySessionManager, SessionManager } from "../../session/session-manager";
 import type { BashToolDetails, BashToolInput, FindToolDetails, FindToolInput, ReadToolDetails, ReadToolInput, SearchToolDetails, SearchToolInput, WriteToolInput } from "../../tools";
@@ -171,6 +172,12 @@ export interface ContextUsage {
 export interface CompactOptions {
     onComplete?: (result: CompactionResult) => void;
     onError?: (error: Error) => void;
+    /**
+     * Force a one-off compaction mode for this invocation, overriding the
+     * configured `compaction.strategy` / `remoteEnabled` (the `/compact`
+     * subcommands: `soft` | `remote` | `snapcompact`). Omitted = configured behavior.
+     */
+    mode?: CompactMode;
 }
 /**
  * Context passed to extension event handlers.

package/dist/types/modes/components/agent-hub.d.ts

@@ -62,6 +62,11 @@ export declare class AgentHubOverlayComponent extends Container {
     dispose(): void;
     render(width: number): readonly string[];
     handleInput(keyData: string): void;
-    /** Open the chat view for an agent id (public for table Enter and tests). */
+    /**
+     * Open the fullscreen transcript viewer for an agent id (public for table Enter
+     * and tests). Mounts {@link AgentTranscriptViewer} as a `fullscreen` overlay so it
+     * owns the alternate screen; the hub table stays mounted underneath and is
+     * restored when the viewer closes. No-op without a real TUI (render-only test stub).
+     */
     openChat(id: string): void;
 }

package/dist/types/modes/components/agent-transcript-viewer.d.ts

@@ -0,0 +1,39 @@
+import type { AgentTool } from "@oh-my-pi/pi-agent-core";
+import { type Component, type TUI } from "@oh-my-pi/pi-tui";
+import type { KeyId } from "../../config/keybindings";
+import type { MessageRenderer } from "../../extensibility/extensions/types";
+import type { AgentLifecycleManager } from "../../registry/agent-lifecycle";
+import type { AgentRegistry } from "../../registry/agent-registry";
+import type { SessionObserverRegistry } from "../session-observer-registry";
+import type { AgentHubRemote } from "./agent-hub";
+export interface AgentTranscriptViewerDeps {
+    agentId: string;
+    registry: AgentRegistry;
+    /** Collab guest: read transcript from the host instead of a local file. */
+    remote?: AgentHubRemote;
+    /** Progress/cost snapshot source for the stats line. */
+    observers?: SessionObserverRegistry;
+    /** Revive+prompt path for messageable local agents. Lazy to avoid touching the global. */
+    lifecycle?: () => AgentLifecycleManager;
+    ui: TUI;
+    getTool?: (name: string) => AgentTool | undefined;
+    getMessageRenderer?: (customType: string) => MessageRenderer | undefined;
+    cwd: string;
+    hideThinkingBlock?: () => boolean;
+    expandKeys: KeyId[];
+    /** Keys that toggle the whole hub closed (app.agents.hub + app.session.observe). */
+    hubKeys: KeyId[];
+    requestRender: () => void;
+    /** Close just this viewer (Esc), returning to the hub table. */
+    onClose: () => void;
+    /** Close this viewer AND the hub (hub-toggle keys). */
+    onHubClose: () => void;
+}
+export declare class AgentTranscriptViewer implements Component {
+    #private;
+    private readonly deps;
+    constructor(deps: AgentTranscriptViewerDeps);
+    dispose(): void;
+    handleInput(data: string): void;
+    render(width: number): readonly string[];
+}

package/dist/types/modes/components/chat-transcript-builder.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Builds transcript components from persisted session message entries — the
+ * file/remote-backed counterpart to {@link UiHelpers.addMessageToChat} (which is
+ * bound to the live InteractiveModeContext). Used by the fullscreen transcript
+ * viewer ({@link AgentTranscriptViewer}) to render a parked subagent / advisor /
+ * collab-guest transcript that has no live session.
+ *
+ * Unlike the old incremental hub sync, {@link ChatTranscriptBuilder.rebuild}
+ * always discards prior components and rebuilds the whole transcript from the
+ * supplied entries. Re-rendering a growing transcript is therefore O(n) in the
+ * entry count, but it cannot duplicate or misorder rows the way incremental
+ * component reuse could.
+ */
+import type { AgentTool } from "@oh-my-pi/pi-agent-core";
+import { type TUI } from "@oh-my-pi/pi-tui";
+import type { MessageRenderer } from "../../extensibility/extensions/types";
+import type { SessionMessageEntry } from "../../session/session-entries";
+import { TranscriptContainer } from "./transcript-container";
+export interface ChatTranscriptBuilderDeps {
+    ui: TUI;
+    getTool?: (name: string) => AgentTool | undefined;
+    getMessageRenderer?: (customType: string) => MessageRenderer | undefined;
+    cwd: string;
+    hideThinkingBlock?: () => boolean;
+    requestRender: () => void;
+}
+export declare class ChatTranscriptBuilder {
+    #private;
+    private readonly deps;
+    readonly container: TranscriptContainer;
+    constructor(deps: ChatTranscriptBuilderDeps);
+    /** Whether the transcript currently holds any rendered rows. */
+    get isEmpty(): boolean;
+    /** Discard all components and rebuild the whole transcript from `entries`. */
+    rebuild(entries: SessionMessageEntry[]): void;
+    /** Toggle tool-output expansion across every expandable component. */
+    setExpanded(expanded: boolean): void;
+    get expanded(): boolean;
+    /** Tear down components (sealing pending spinners) and clear build state. */
+    reset(): void;
+    dispose(): void;
+}

package/dist/types/modes/controllers/command-controller.d.ts

@@ -3,6 +3,7 @@ import { type ProviderDetails, type UsageReport } from "@oh-my-pi/pi-ai";
 import type { CompactOptions } from "../../extensibility/extensions/types";
 import { theme } from "../../modes/theme/theme";
 import type { InteractiveModeContext } from "../../modes/types";
+import type { CompactMode } from "../../session/compact-modes";
 import { type ShakeMode } from "../../session/shake-types";
 export declare class CommandController {
     #private;
@@ -31,14 +32,14 @@ export declare class CommandController {
     handleRenameCommand(title: string): Promise<void>;
     handleBashCommand(command: string, excludeFromContext?: boolean): Promise<void>;
     handlePythonCommand(code: string, excludeFromContext?: boolean): Promise<void>;
-    handleCompactCommand(customInstructions?: string, beforeFlush?: (outcome: CompactionOutcome) => void | Promise<void>): Promise<CompactionOutcome>;
+    handleCompactCommand(customInstructions?: string, mode?: CompactMode, beforeFlush?: (outcome: CompactionOutcome) => void | Promise<void>): Promise<CompactionOutcome>;
     /**
      * TUI handler for `/shake`. `elide` drops heavy structural content and
      * `images` strips image blocks. Rebuilds the chat and reports counts.
      */
     handleShakeCommand(mode: ShakeMode): Promise<void>;
     handleSkillCommand(skillPath: string, args: string): Promise<void>;
-    executeCompaction(customInstructionsOrOptions?: string | CompactOptions, isAuto?: boolean, beforeFlush?: (outcome: CompactionOutcome) => void | Promise<void>): Promise<CompactionOutcome>;
+    executeCompaction(customInstructionsOrOptions?: string | CompactOptions, isAuto?: boolean, beforeFlush?: (outcome: CompactionOutcome) => void | Promise<void>, mode?: CompactMode): Promise<CompactionOutcome>;
     handleHandoffCommand(customInstructions?: string): Promise<void>;
 }
 export declare function renderProviderSection(details: ProviderDetails, uiTheme: Pick<typeof theme, "fg">): string;

package/dist/types/modes/interactive-mode.d.ts

@@ -12,6 +12,7 @@ import type { CompactOptions } from "../extensibility/extensions/types";
 import type { MCPManager } from "../mcp";
 import { type PlanApprovalDetails } from "../plan-mode/approved-plan";
 import type { AgentSession } from "../session/agent-session";
+import type { CompactMode } from "../session/compact-modes";
 import { HistoryStorage } from "../session/history-storage";
 import type { SessionContext } from "../session/session-context";
 import type { SessionManager } from "../session/session-manager";
@@ -298,7 +299,7 @@ export declare class InteractiveMode implements InteractiveModeContext {
     handlePythonCommand(code: string, excludeFromContext?: boolean): Promise<void>;
     handleMCPCommand(text: string): Promise<void>;
     handleSSHCommand(text: string): Promise<void>;
-    handleCompactCommand(customInstructions?: string, beforeFlush?: (outcome: CompactionOutcome) => void | Promise<void>): Promise<CompactionOutcome>;
+    handleCompactCommand(customInstructions?: string, mode?: CompactMode, beforeFlush?: (outcome: CompactionOutcome) => void | Promise<void>): Promise<CompactionOutcome>;
     handleHandoffCommand(customInstructions?: string): Promise<void>;
     handleShakeCommand(mode: ShakeMode): Promise<void>;
     executeCompaction(customInstructionsOrOptions?: string | CompactOptions, isAuto?: boolean): Promise<CompactionOutcome>;

package/dist/types/modes/types.d.ts

@@ -11,6 +11,7 @@ import type { CompactOptions } from "../extensibility/extensions/types";
 import type { MCPManager } from "../mcp";
 import type { PlanApprovalDetails } from "../plan-mode/approved-plan";
 import type { AgentSession } from "../session/agent-session";
+import type { CompactMode } from "../session/compact-modes";
 import type { HistoryStorage } from "../session/history-storage";
 import type { SessionContext } from "../session/session-context";
 import type { SessionManager } from "../session/session-manager";
@@ -273,7 +274,7 @@ export interface InteractiveModeContext {
     handlePythonCommand(code: string, excludeFromContext?: boolean): Promise<void>;
     handleMCPCommand(text: string): Promise<void>;
     handleSSHCommand(text: string): Promise<void>;
-    handleCompactCommand(customInstructions?: string): Promise<CompactionOutcome>;
+    handleCompactCommand(customInstructions?: string, mode?: CompactMode): Promise<CompactionOutcome>;
     handleHandoffCommand(customInstructions?: string): Promise<void>;
     handleShakeCommand(mode: ShakeMode): Promise<void>;
     handleMoveCommand(targetPath: string): Promise<void>;

package/dist/types/registry/agent-registry.d.ts

@@ -18,7 +18,13 @@ export declare const MAIN_AGENT_ID = "Main";
  * - `aborted`: hard-killed, terminal.
  */
 export type AgentStatus = "running" | "idle" | "parked" | "aborted";
-export type AgentKind = "main" | "sub";
+/**
+ * - `main`/`sub`: the user-facing agent tree (driving agent + task subagents).
+ * - `advisor`: a passive review transcript persisted like a subagent for usage
+ *   attribution and Agent Hub observability, but never a peer — hidden from
+ *   agent-facing rosters (`irc`, `history://`) and not messageable/revivable.
+ */
+export type AgentKind = "main" | "sub" | "advisor";
 export interface AgentRef {
     id: string;
     displayName: string;
@@ -81,8 +87,9 @@ export declare class AgentRegistry {
     get(id: string): AgentRef | undefined;
     list(): AgentRef[];
     /**
-     * Returns every alive agent (running | idle) except the caller.
-     * Flat namespace: every agent can see every other agent.
+     * Returns every alive agent (running | idle) except the caller. Advisor refs
+     * are observability-only transcripts, never peers, so they are excluded.
+     * Flat namespace: every other agent is visible.
      */
     listVisibleTo(id: string): AgentRef[];
     onChange(listener: RegistryListener): () => void;

package/dist/types/session/compact-modes.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Manual `/compact` subcommands. Kept in a dependency-free leaf module so the
+ * slash-command registry, the interactive controllers, and `AgentSession`
+ * can all import the mode metadata + parser without pulling in the heavy
+ * `agent-session` module graph (which would form an import cycle through the
+ * slash-command registry) — same rationale as `shake-types.ts`.
+ *
+ * Each mode is a one-off override layered on top of the configured
+ * `compaction.*` settings for a single invocation; it never mutates settings.
+ * Adding a mode is a single entry here: the command surface (autocomplete +
+ * ACP hint), the parser, and the engine override all read this table.
+ */
+/** Subcommand selecting a one-off compaction mode for manual `/compact`. */
+export type CompactMode = "soft" | "remote" | "snapcompact";
+/**
+ * Per-invocation overrides merged over the configured `compaction.*` settings.
+ * Narrowed to the two knobs the modes actually flip; the result stays
+ * assignable to the full `CompactionSettings`.
+ */
+export interface CompactionOverride {
+    strategy?: "context-full" | "snapcompact";
+    remoteEnabled?: boolean;
+}
+export interface CompactModeDef {
+    readonly name: CompactMode;
+    /** One-line description surfaced in autocomplete + help. */
+    readonly description: string;
+    /** Settings overrides applied on top of `compaction.*` for this run. */
+    readonly overrides: CompactionOverride;
+    /**
+     * When true, the mode produces no LLM summary, so trailing focus text is
+     * meaningless and rejected by the parser (snapcompact archives history into
+     * images without a directed summary).
+     */
+    readonly rejectsFocus?: boolean;
+    /**
+     * When true, the mode explicitly demands a remote path; the engine warns and
+     * falls back to a local summary if neither a remote endpoint nor a
+     * provider-native compaction path is available.
+     */
+    readonly requiresRemote?: boolean;
+}
+export declare const COMPACT_MODES: readonly CompactModeDef[];
+/** Resolve a subcommand token (case-insensitive) to its mode definition. */
+export declare function findCompactMode(name: string): CompactModeDef | undefined;
+/** Parsed `/compact` arguments: an optional mode plus optional focus text. */
+export interface ParsedCompactArgs {
+    mode?: CompactMode;
+    instructions?: string;
+}
+/**
+ * Split `/compact` args into a leading mode subcommand + focus instructions.
+ *
+ * Backward compatible: when the first token is not a known mode, the entire
+ * argument string is treated as focus instructions (the historical behavior).
+ * A recognized mode with `rejectsFocus` and trailing text is an error.
+ */
+export declare function parseCompactArgs(args: string): ParsedCompactArgs | {
+    error: string;
+};

package/dist/types/session/streaming-output.d.ts

@@ -163,8 +163,6 @@ export declare function truncateMiddle(content: string, options?: TruncationOpti
 export interface InlineByteCapOptions {
     /** Inline byte budget. Defaults to {@link DEFAULT_MAX_BYTES}. */
     maxBytes?: number;
-    /** What the text is, for the elision marker (e.g. "bash output"). */
-    label: string;
     /**
      * Persist the full text as a session artifact. When an artifact id is
      * returned, a `[raw output: artifact://<id>]` footer is appended so the

package/dist/types/tools/__tests__/json-tree.test.d.ts

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@oh-my-pi/pi-coding-agent",
-	"version": "16.0.10",
+	"version": "16.0.11",
 	"description": "Coding agent CLI with read, bash, edit, write tools and session management",
 	"homepage": "https://omp.sh",
 	"author": "Can Boluk",
@@ -48,17 +48,17 @@
 		"@agentclientprotocol/sdk": "0.25.0",
 		"@babel/parser": "^7.29.7",
 		"@mozilla/readability": "^0.6.0",
-		"@oh-my-pi/hashline": "16.0.10",
-		"@oh-my-pi/omp-stats": "16.0.10",
-		"@oh-my-pi/pi-agent-core": "16.0.10",
-		"@oh-my-pi/pi-ai": "16.0.10",
-		"@oh-my-pi/pi-catalog": "16.0.10",
-		"@oh-my-pi/pi-mnemopi": "16.0.10",
-		"@oh-my-pi/pi-natives": "16.0.10",
-		"@oh-my-pi/pi-tui": "16.0.10",
-		"@oh-my-pi/pi-utils": "16.0.10",
-		"@oh-my-pi/pi-wire": "16.0.10",
-		"@oh-my-pi/snapcompact": "16.0.10",
+		"@oh-my-pi/hashline": "16.0.11",
+		"@oh-my-pi/omp-stats": "16.0.11",
+		"@oh-my-pi/pi-agent-core": "16.0.11",
+		"@oh-my-pi/pi-ai": "16.0.11",
+		"@oh-my-pi/pi-catalog": "16.0.11",
+		"@oh-my-pi/pi-mnemopi": "16.0.11",
+		"@oh-my-pi/pi-natives": "16.0.11",
+		"@oh-my-pi/pi-tui": "16.0.11",
+		"@oh-my-pi/pi-utils": "16.0.11",
+		"@oh-my-pi/pi-wire": "16.0.11",
+		"@oh-my-pi/snapcompact": "16.0.11",
 		"@opentelemetry/api": "^1.9.1",
 		"@opentelemetry/context-async-hooks": "^2.7.1",
 		"@opentelemetry/exporter-trace-otlp-proto": "^0.218.0",

package/src/advisor/index.ts

@@ -1,3 +1,4 @@
 export * from "./advise-tool";
 export * from "./runtime";
+export * from "./transcript-recorder";
 export * from "./watchdog";

package/src/advisor/transcript-recorder.ts

@@ -0,0 +1,136 @@
+import * as path from "node:path";
+import type { AgentMessage } from "@oh-my-pi/pi-agent-core";
+import type { Message, UserMessage } from "@oh-my-pi/pi-ai";
+import { logger } from "@oh-my-pi/pi-utils";
+import { SessionManager } from "../session/session-manager";
+
+/**
+ * Reserved transcript stem for advisor session files. Chosen so it cannot
+ * collide with a task subagent's `<id>.jsonl` (task ids are reserved against
+ * this exact stem in {@link AgentOutputManager}).
+ */
+export const ADVISOR_TRANSCRIPT_STEM = "__advisor";
+export const ADVISOR_TRANSCRIPT_FILENAME = `${ADVISOR_TRANSCRIPT_STEM}.jsonl`;
+
+const JSONL_SUFFIX = ".jsonl";
+
+/**
+ * Append-only persister for an advisor agent's transcript.
+ *
+ * The advisor is a passive reviewer with its own model usage, so — like a task
+ * subagent — its turns are written to a JSONL inside the owning session's
+ * artifacts dir (`<session>/__advisor.jsonl`, `<session>/<SubId>/__advisor.jsonl`
+ * for subagent advisors). That single file gives the advisor model proper usage
+ * attribution in `omp stats` (the stats parser scans the session dir
+ * recursively) and a read-only transcript in the Agent Hub, without making the
+ * advisor a registered, messageable peer.
+ *
+ * The target is derived from the *session file* (`getSessionFile()`), never
+ * `getArtifactsDir()` — subagents adopt the parent's artifact manager, so the
+ * artifacts dir points at the parent root and every subagent advisor would
+ * collide. The file path is resolved synchronously when a message finalizes and
+ * captured for the queued write, so a `/new`, resume, or session switch in
+ * flight can never misattribute an old advisor turn into the new session's file.
+ * On such a switch the previous writer is closed and the new file opened on the
+ * next recorded turn. The recorder never truncates: the advisor's in-memory
+ * context resets/compacts independently, but every billed turn is appended here.
+ */
+export class AdvisorTranscriptRecorder {
+	#manager: SessionManager | undefined;
+	#file: string | undefined;
+	/** Serializes the async open/close against synchronous appends so records land in order. */
+	#queue: Promise<void>;
+
+	/**
+	 * @param after Optional barrier the queue starts behind — used on the advisor
+	 *   on→off→on toggle so a fresh recorder's first `open` waits for the prior
+	 *   recorder's `close` and the two never hold the same `__advisor.jsonl` at once.
+	 */
+	constructor(
+		private readonly resolveSessionFile: () => string | undefined,
+		private readonly resolveCwd: () => string,
+		after?: Promise<unknown>,
+	) {
+		this.#queue = after
+			? after.then(
+					() => {},
+					() => {},
+				)
+			: Promise.resolve();
+	}
+
+	/**
+	 * Persist one finalized advisor message. Assistant turns carry the usage the
+	 * stats parser reads; tool results round out the Hub transcript; user deltas
+	 * (the advisor's "session update" prompts) are persisted but flagged
+	 * `synthetic`/agent-attributed so they never inflate user-message metrics.
+	 * Non-conversational message kinds are skipped.
+	 */
+	record(message: AgentMessage): void {
+		let persisted: Message;
+		switch (message.role) {
+			case "assistant":
+			case "toolResult":
+				persisted = message;
+				break;
+			case "user":
+				// Clone so the live advisor message stays untouched; mark synthetic so
+				// stats' user-message metrics skip these agent-internal review prompts.
+				persisted = { ...(message as UserMessage), synthetic: true, attribution: "agent" };
+				break;
+			default:
+				return;
+		}
+		const sessionFile = this.resolveSessionFile();
+		if (!sessionFile?.endsWith(JSONL_SUFFIX)) return;
+		const file = path.join(sessionFile.slice(0, -JSONL_SUFFIX.length), ADVISOR_TRANSCRIPT_FILENAME);
+		const cwd = this.resolveCwd();
+		this.#enqueue(async () => {
+			if (file !== this.#file) {
+				await this.#closeManager();
+				this.#manager = await SessionManager.open(file, undefined, undefined, {
+					initialCwd: cwd,
+					suppressBreadcrumb: true,
+				});
+				this.#file = file;
+			}
+			this.#manager?.appendMessage(persisted);
+		});
+	}
+
+	/** Flush pending writes (best-effort). */
+	flush(): Promise<void> {
+		return this.#enqueueResult(async () => {
+			if (this.#manager) await this.#manager.flush();
+		});
+	}
+
+	/** Flush and close the writer, releasing the session file. */
+	close(): Promise<void> {
+		return this.#enqueueResult(() => this.#closeManager());
+	}
+
+	async #closeManager(): Promise<void> {
+		const manager = this.#manager;
+		this.#manager = undefined;
+		this.#file = undefined;
+		if (!manager) return;
+		try {
+			await manager.close();
+		} catch (err) {
+			logger.debug("advisor transcript close failed", { err: String(err) });
+		}
+	}
+
+	#enqueue(work: () => Promise<void>): void {
+		this.#queue = this.#queue.then(work, work).catch(err => {
+			logger.debug("advisor transcript record failed", { err: String(err) });
+		});
+	}
+
+	#enqueueResult(work: () => Promise<void>): Promise<void> {
+		const next = this.#queue.then(work, work);
+		this.#queue = next.catch(() => {});
+		return next;
+	}
+}

package/src/cli/stats-cli.ts

@@ -4,6 +4,7 @@
  * Handles `omp stats` subcommand for viewing AI usage statistics.
  */
 
+import { truncateToWidth } from "@oh-my-pi/pi-tui/utils";
 import { APP_NAME, formatDuration, formatNumber, formatPercent } from "@oh-my-pi/pi-utils";
 import chalk from "chalk";
 import { openPath } from "../utils/open";
@@ -32,7 +33,7 @@ function createSyncProgressReporter(): {
 			const counter = chalk.cyan(`[${event.current}/${event.total}]`);
 			const line = `${counter} ${pct}%  ${label}`;
 			const columns = stream.columns ?? 120;
-			const trimmed = truncateToColumns(line, columns - 1);
+			const trimmed = truncateToWidth(line, columns - 1);
 			stream.write(`\r${trimmed.padEnd(lastWidth)}`);
 			lastWidth = trimmed.length;
 		},
@@ -50,16 +51,6 @@ function shortenSessionFile(p: string): string {
 	return idx >= 0 ? p.slice(idx + marker.length) : p;
 }
 
-function truncateToColumns(s: string, max: number): string {
-	if (max <= 0) return "";
-	const width = Bun.stringWidth(s, { countAnsiEscapeCodes: false });
-	if (width <= max) return s;
-	// Cheap right-trim with an ellipsis - we don't need ANSI-aware slicing
-	// because the colored prefix is short and the truncated tail is the
-	// dim filename, where dropping bytes is fine.
-	return `${s.slice(0, Math.max(0, max - 1))}\u2026`;
-}
-
 // =============================================================================
 // Types
 // =============================================================================

package/src/collab/host.ts

@@ -17,7 +17,7 @@ import { logger } from "@oh-my-pi/pi-utils";
 import type { BusChannel, AgentEvent as WireAgentEvent, SessionEntry as WireSessionEntry } from "@oh-my-pi/pi-wire";
 import type { InteractiveModeContext } from "../modes/types";
 import { AgentLifecycleManager } from "../registry/agent-lifecycle";
-import { AgentRegistry } from "../registry/agent-registry";
+import { type AgentRef, AgentRegistry } from "../registry/agent-registry";
 import type { AgentSessionEvent } from "../session/agent-session";
 import { stripImagesFromMessage, USER_INTERRUPT_LABEL } from "../session/messages";
 import type { SessionEntry as StoredSessionEntry } from "../session/session-entries";
@@ -445,18 +445,24 @@ export class CollabHost {
 	}
 
 	#snapshotAgents(): AgentSnapshot[] {
-		return AgentRegistry.global()
-			.list()
-			.map(ref => ({
-				id: ref.id,
-				displayName: ref.displayName,
-				kind: ref.kind,
-				parentId: ref.parentId,
-				status: ref.status,
-				hasSessionFile: !!ref.sessionFile,
-				createdAt: ref.createdAt,
-				lastActivity: ref.lastActivity,
-			}));
+		return (
+			AgentRegistry.global()
+				.list()
+				// Advisor transcripts are local observability only; never mirror them to
+				// guests (the wire AgentSnapshot kind has no `advisor`, and guests must not
+				// be able to chat/kill/revive them).
+				.filter((ref): ref is AgentRef & { kind: "main" | "sub" } => ref.kind !== "advisor")
+				.map(ref => ({
+					id: ref.id,
+					displayName: ref.displayName,
+					kind: ref.kind,
+					parentId: ref.parentId,
+					status: ref.status,
+					hasSessionFile: !!ref.sessionFile,
+					createdAt: ref.createdAt,
+					lastActivity: ref.lastActivity,
+				}))
+		);
 	}
 
 	#scheduleAgentsBroadcast(): void {
@@ -472,6 +478,12 @@ export class CollabHost {
 			this.#rejectReadOnly("agent control", fromPeer);
 			return;
 		}
+		// Advisor refs are excluded from snapshots, but reject control by id defensively:
+		// a stale/malicious client must never chat/kill/revive a read-only advisor transcript.
+		if (AgentRegistry.global().get(agentId)?.kind === "advisor") {
+			this.#socket?.send({ t: "error", message: `agent ${agentId}: advisor transcripts are read-only` }, fromPeer);
+			return;
+		}
 		const fail = (err: unknown) => {
 			logger.warn("collab agent-cmd failed", { cmd, agentId, error: String(err) });
 			this.#socket?.send({ t: "error", message: `agent ${agentId}: ${String(err)}` }, fromPeer);