pi-midcompact 0.4.0 → 0.5.0

package/src/inventory.ts

@@ -0,0 +1,295 @@
+// Read-only inspection over the frozen visible atom snapshot. Owns the
+// user-led inventory and factual measurement of explicit candidate spans.
+// Output is bounded and never returns full message or tool bodies.
+
+import { isProtectedAtom } from "./atoms.js";
+import { aggregateMetrics } from "./content-metrics.js";
+import { toolCalls, truncateMiddle } from "./messages.js";
+import type {
+  Atom,
+  InventoryGroup,
+  InventoryPage,
+  InventoryPiUsage,
+  InventoryQuery,
+  InventoryTotals,
+  TransactionState,
+} from "./types.js";
+
+export const DEFAULT_PAGE_SIZE = 20;
+export const MAX_PAGE_SIZE = 50;
+export const SPAN_INSPECTION_OUTPUT_LIMIT = 12_000;
+
+const USER_GROUP_LABEL_LIMIT = 80;
+const SPAN_LANDMARK_LIMIT = 180;
+
+export interface InspectSpan {
+  start: string;
+  end: string;
+}
+
+/** Opaque cursor encoding the next group index to start from. */
+export function encodeCursor(nextGroupIndex: number): string {
+  return btoa(JSON.stringify({ g: nextGroupIndex }));
+}
+
+export function decodeCursor(cursor: string): number | undefined {
+  try {
+    const decoded = JSON.parse(atob(cursor));
+    if (decoded && typeof decoded.g === "number") return decoded.g;
+    return undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+function piUsageFromAnchor(transaction: TransactionState): InventoryPiUsage {
+  const usage = transaction.anchorUsage;
+  if (!usage) {
+    return { available: false, contextWindow: null, tokens: null, percent: null, provenance: "Pi reported at anchor start" };
+  }
+  return {
+    available: true,
+    contextWindow: usage.contextWindow,
+    tokens: usage.tokens,
+    percent: usage.percent,
+    provenance: "Pi reported at anchor start",
+  };
+}
+
+function buildGroups(atoms: readonly Atom[]): InventoryGroup[] {
+  if (atoms.length === 0) return [];
+
+  // Group boundaries: a new user-led group begins at each "user" atom. Atoms
+  // before the first user atom form a single prefix group.
+  const groups: InventoryGroup[] = [];
+  let current: Atom[] | null = null;
+  let groupIndex = 0;
+
+  const flush = () => {
+    if (!current) return;
+    groups.push(buildGroup(groupIndex, current, /* isPrefix */ false));
+    groupIndex += 1;
+    current = null;
+  };
+
+  for (const atom of atoms) {
+    if (atom.kind === "user") {
+      flush();
+      current = [atom];
+    } else if (current) {
+      current.push(atom);
+    } else {
+      // Before the first user message: seed a prefix group.
+      current = [atom];
+    }
+  }
+  flush();
+
+  // Mark the prefix group: it is the first group whose first atom is not a user atom.
+  if (groups.length > 0 && groups[0]!.startAtomRef === atoms[0]!.ref && atoms[0]!.kind !== "user") {
+    groups[0] = { ...groups[0]!, isPrefix: true };
+  }
+  return groups;
+}
+
+function buildGroup(groupIndex: number, groupAtoms: readonly Atom[], isPrefix: boolean): InventoryGroup {
+  const first = groupAtoms[0]!;
+  const last = groupAtoms[groupAtoms.length - 1]!;
+  const metrics = aggregateMetrics(groupAtoms.map((atom) => atom.metrics));
+  let protectedCount = 0;
+  let compressibleCount = 0;
+  let messageCount = 0;
+  for (const atom of groupAtoms) {
+    if (isProtectedAtom(atom)) protectedCount += 1;
+    else compressibleCount += 1;
+    messageCount += atom.messages.length;
+  }
+  const mimeTypes = [...new Set(metrics.images.map((image) => image.mimeType))].sort();
+  const label = groupLabel(first, isPrefix);
+  return {
+    ref: `g${String(groupIndex + 1).padStart(4, "0")}`,
+    label,
+    isPrefix,
+    startAtomRef: first.ref,
+    endAtomRef: last.ref,
+    atomCount: groupAtoms.length,
+    messageCount,
+    contentChars: metrics.contentChars,
+    imageCount: metrics.imageCount,
+    imagePayloadBytes: metrics.images.reduce((sum, image) => sum + image.payloadBytes, 0),
+    imageMimeTypes: mimeTypes,
+    protectedAtomCount: protectedCount,
+    compressibleAtomCount: compressibleCount,
+  };
+}
+
+function groupLabel(firstAtom: Atom, isPrefix: boolean): string {
+  if (isPrefix) return "context before first user message";
+  const userMessage = firstAtom.messages.find((ref) => ref.message.role === "user");
+  if (!userMessage) return firstAtom.ref;
+  return truncateMiddle(renderUserLabel(userMessage.message), USER_GROUP_LABEL_LIMIT);
+}
+
+function renderUserLabel(message: import("./types.js").MessageLike): string {
+  const text = typeof message.content === "string"
+    ? message.content
+    : Array.isArray(message.content)
+      ? (message.content as Array<{ type?: string; text?: string }>).find((p) => p?.type === "text")?.text ?? ""
+      : "";
+  return text || `[${message.role}]`;
+}
+
+function buildTotals(atoms: readonly Atom[], groups: readonly InventoryGroup[]): InventoryTotals {
+  const metrics = aggregateMetrics(atoms.map((atom) => atom.metrics));
+  let protectedCount = 0;
+  let compressibleCount = 0;
+  for (const atom of atoms) {
+    if (isProtectedAtom(atom)) protectedCount += 1;
+    else compressibleCount += 1;
+  }
+  return {
+    atomCount: atoms.length,
+    messageCount: atoms.reduce((sum, atom) => sum + atom.messages.length, 0),
+    contentChars: metrics.contentChars,
+    imageCount: metrics.imageCount,
+    imagePayloadBytes: metrics.images.reduce((sum, image) => sum + image.payloadBytes, 0),
+    groupCount: groups.length,
+    protectedAtomCount: protectedCount,
+    compressibleAtomCount: compressibleCount,
+  };
+}
+
+export interface InventoryContext {
+  transaction: TransactionState;
+}
+
+export function buildInventory(atoms: readonly Atom[], query: InventoryQuery, context: InventoryContext): InventoryPage {
+  const pageSize = clampPageSize(query.pageSize);
+  const allGroups = buildGroups(atoms);
+  const startGroup = query.cursor ? (decodeCursor(query.cursor) ?? 0) : 0;
+  const safeStart = Math.max(0, Math.min(startGroup, allGroups.length));
+  const slice = allGroups.slice(safeStart, safeStart + pageSize);
+  const nextIndex = safeStart + slice.length;
+  const nextCursor = nextIndex < allGroups.length ? encodeCursor(nextIndex) : null;
+
+  return {
+    anchor: { transactionId: context.transaction.id, anchorEntryId: context.transaction.anchorEntryId },
+    piUsage: piUsageFromAnchor(context.transaction),
+    totals: buildTotals(atoms, allGroups),
+    groups: slice,
+    nextCursor,
+    pageSize,
+  };
+}
+
+function clampPageSize(requested: number | undefined): number {
+  if (typeof requested !== "number" || !Number.isFinite(requested)) return DEFAULT_PAGE_SIZE;
+  const rounded = Math.round(requested);
+  if (rounded < 1) return 1;
+  return Math.min(rounded, MAX_PAGE_SIZE);
+}
+
+/** Format an inventory page with bounded user landmarks and no full bodies. */
+export function formatInventory(page: InventoryPage): string {
+  const lines: string[] = [];
+  const usage = page.piUsage;
+  if (usage.available) {
+    const pct = usage.percent === null || !Number.isFinite(usage.percent) ? "unavailable" : `${round1(usage.percent)}%`;
+    lines.push(`Anchor Pi usage (${usage.provenance}): ${usage.tokens === null ? "unavailable" : usage.tokens} / ${usage.contextWindow ?? "?"} tokens (${pct}).`);
+  } else {
+    lines.push(`Anchor Pi usage (${usage.provenance}): unavailable; not derived from local char counts.`);
+  }
+  lines.push(
+    `Totals: ${page.totals.atomCount} atoms, ${page.totals.messageCount} messages, ${page.totals.contentChars} content chars, ${page.totals.imageCount} images (${page.totals.imagePayloadBytes} payload bytes), ${page.totals.groupCount} groups (${page.totals.protectedAtomCount} protected, ${page.totals.compressibleAtomCount} compressible).`,
+  );
+  lines.push(`Page ${page.groups.length === 0 ? "(empty)" : `${page.groups.length} group(s)`}:`);
+  for (const group of page.groups) {
+    const mimes = group.imageMimeTypes.length ? ` images: ${group.imageCount} (${group.imageMimeTypes.join("/")}, ${group.imagePayloadBytes} bytes)` : " images: 0";
+    const prefix = group.isPrefix ? " [prefix]" : "";
+    lines.push(
+      `${group.ref}${prefix} ${group.startAtomRef}→${group.endAtomRef} | ${group.atomCount} atoms, ${group.messageCount} msgs, ${group.contentChars} chars,${mimes} | ${group.protectedAtomCount} protected / ${group.compressibleAtomCount} compressible | ${group.label}`,
+    );
+  }
+  if (page.nextCursor) lines.push(`next cursor: ${page.nextCursor}`);
+  lines.push("Note: inventory shows factual structure and bounded user landmarks only; no full message body, assistant/tool preview, summary, or image base64. Use locate for specific content.");
+  return lines.join("\n");
+}
+
+/** Measure explicit, possibly overlapping candidate spans without mutating the DraftPlan. */
+export function formatSpanInspection(atoms: readonly Atom[], spans: readonly InspectSpan[]): string {
+  if (spans.length === 0) throw new Error("inspect spans requires at least one start/end span.");
+  const byRef = new Map(atoms.map((atom) => [atom.ref, atom]));
+  const anchorChars = aggregateMetrics(atoms.map((atom) => atom.metrics)).contentChars;
+  const lines = [
+    `Candidate span inspection: ${spans.length} requested · factual content measurements only; no per-span token estimate.`,
+  ];
+  let shown = 0;
+
+  for (const span of spans) {
+    const start = byRef.get(span.start);
+    const end = byRef.get(span.end);
+    if (!start || !end) throw new Error(`Unknown span ref ${!start ? span.start : span.end}; re-run inspect against the current snapshot.`);
+    if (start.index > end.index) throw new Error(`Span ${span.start} → ${span.end} is reversed.`);
+
+    const selected = atoms.slice(start.index, end.index + 1);
+    const block = formatSpanBlock(selected, start, end, anchorChars);
+    const currentLength = lines.join("\n\n").length;
+    if (currentLength + 2 + block.length > SPAN_INSPECTION_OUTPUT_LIMIT) {
+      const notice = `Output budget reached: showed ${shown} of ${spans.length} requested spans. Inspect the remainder in another call.`;
+      if (currentLength + 2 + notice.length <= SPAN_INSPECTION_OUTPUT_LIMIT) lines.push(notice);
+      break;
+    }
+    lines.push(block);
+    shown += 1;
+  }
+  return lines.join("\n\n");
+}
+
+function formatSpanBlock(selected: readonly Atom[], start: Atom, end: Atom, anchorChars: number): string {
+  const metrics = aggregateMetrics(selected.map((atom) => atom.metrics));
+  const roleCounts = new Map<string, number>();
+  const toolCounts = new Map<string, number>();
+  let messageCount = 0;
+  let toolCallCount = 0;
+  let toolExchangeCount = 0;
+  let protectedCount = 0;
+
+  for (const atom of selected) {
+    if (atom.kind === "tool_exchange") toolExchangeCount += 1;
+    if (isProtectedAtom(atom)) protectedCount += 1;
+    for (const ref of atom.messages) {
+      messageCount += 1;
+      roleCounts.set(ref.message.role, (roleCounts.get(ref.message.role) ?? 0) + 1);
+      for (const call of toolCalls(ref.message)) {
+        toolCallCount += 1;
+        toolCounts.set(call.name, (toolCounts.get(call.name) ?? 0) + 1);
+      }
+    }
+  }
+
+  const roleSummary = [...roleCounts.entries()].map(([role, count]) => `${role} ${count}`).join(" · ") || "none";
+  const toolSummary = [...toolCounts.entries()]
+    .sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0]))
+    .map(([name, count]) => `${name} ${count}`)
+    .join(" · ");
+  const imageMimes = [...new Set(metrics.images.map((image) => image.mimeType))].sort();
+  const imageBytes = metrics.images.reduce((sum, image) => sum + image.payloadBytes, 0);
+  const charShare = anchorChars > 0 ? round1((metrics.contentChars / anchorChars) * 100) : "0";
+  const protectedRefs = selected.filter(isProtectedAtom).map((atom) => atom.ref).join(", ");
+
+  return [
+    `${start.ref} → ${end.ref}`,
+    `from: ${truncateMiddle(start.fullText, SPAN_LANDMARK_LIMIT)}`,
+    `to: ${truncateMiddle(end.fullText, SPAN_LANDMARK_LIMIT)}`,
+    `scope: ${selected.length} atoms · ${messageCount} messages (${roleSummary})`,
+    `work: ${toolExchangeCount} tool exchanges · ${toolCallCount} tool calls${toolSummary ? ` (${truncateMiddle(toolSummary, SPAN_LANDMARK_LIMIT)})` : ""}`,
+    `content: ${metrics.contentChars} chars · ${charShare}% of anchor factual content`,
+    `images: ${metrics.imageCount}${imageMimes.length ? ` (${truncateMiddle(imageMimes.join("/"), SPAN_LANDMARK_LIMIT)}, ${imageBytes} payload bytes)` : ""}`,
+    `selection: ${selected.length - protectedCount} compressible · ${protectedCount} protected${protectedRefs ? ` (${truncateMiddle(protectedRefs, SPAN_LANDMARK_LIMIT)})` : ""}`,
+  ].join("\n");
+}
+
+function round1(value: number): string {
+  const rounded = Math.round(value * 10) / 10;
+  return Number.isInteger(rounded) ? String(rounded) : rounded.toFixed(1);
+}

package/src/messages.ts

@@ -43,6 +43,12 @@ export function contentText(content: unknown): string {
       const name = typeof part.name === "string" ? part.name : "tool";
       const args = "arguments" in part ? part.arguments : {};
       out.push(`${name}(${safeJson(args)})`);
+    } else if (part.type === "image") {
+      // Image parts must not be silently dropped from rendered text; surface a
+      // placeholder so locate, preview and recall visibly account for them.
+      // Full image facts (payload bytes, dimensions) come from content-metrics.
+      const mime = typeof part.mimeType === "string" ? part.mimeType : "unknown";
+      out.push(`[image: ${mime}]`);
     }
   }
   return out.join("\n");
@@ -86,11 +92,60 @@ export function approxTokens(text: string): number {
 }
 
 export function truncate(text: string, limit: number): string {
-  const normalized = text.replace(/\s+/g, " ").trim();
+  const normalized = normalizePreviewText(text);
   if (normalized.length <= limit) return normalized;
   return `${normalized.slice(0, Math.max(0, limit - 1))}…`;
 }
 
+/** Preserve both identifying ends of a bounded landmark or oversized body. */
+export function truncateMiddle(text: string, limit: number): string {
+  const normalized = normalizePreviewText(text);
+  if (normalized.length <= limit) return normalized;
+  if (limit < 32) return truncate(normalized, limit);
+
+  let marker = " … [middle omitted] … ";
+  for (let attempt = 0; attempt < 3; attempt += 1) {
+    const kept = Math.max(2, limit - marker.length);
+    const omitted = Math.max(0, normalized.length - kept);
+    marker = ` … [${omitted} chars omitted] … `;
+  }
+  const kept = Math.max(2, limit - marker.length);
+  const headLength = Math.ceil(kept / 2);
+  const tailLength = Math.floor(kept / 2);
+  return `${normalized.slice(0, headLength)}${marker}${normalized.slice(-tailLength)}`;
+}
+
+/** Return a bounded excerpt centered on a case-insensitive text match. */
+export function excerptAround(text: string, pattern: string, limit: number): string {
+  const normalized = normalizePreviewText(text);
+  const needle = normalizePreviewText(pattern);
+  if (!needle || normalized.length <= limit) return truncateMiddle(normalized, limit);
+  const matchIndex = normalized.toLocaleLowerCase().indexOf(needle.toLocaleLowerCase());
+  if (matchIndex < 0) return truncateMiddle(normalized, limit);
+
+  const hasPrefix = matchIndex > 0;
+  const matchEnd = matchIndex + needle.length;
+  const hasSuffix = matchEnd < normalized.length;
+  const prefixMarker = hasPrefix ? "… " : "";
+  const suffixMarker = hasSuffix ? " …" : "";
+  const available = Math.max(1, limit - prefixMarker.length - suffixMarker.length);
+  if (needle.length >= available) {
+    return `${prefixMarker}${truncateMiddle(normalized.slice(matchIndex, matchEnd), available)}${suffixMarker}`;
+  }
+  const context = available - needle.length;
+  const before = Math.min(matchIndex, Math.floor(context / 2));
+  const after = Math.min(normalized.length - matchEnd, context - before);
+  const unused = context - before - after;
+  const extraBefore = Math.min(matchIndex - before, unused);
+  const start = matchIndex - before - extraBefore;
+  const end = Math.min(normalized.length, matchEnd + after + (unused - extraBefore));
+  return `${start > 0 ? "… " : ""}${normalized.slice(start, end)}${end < normalized.length ? " …" : ""}`;
+}
+
+function normalizePreviewText(text: string): string {
+  return text.replace(/\s+/g, " ").trim();
+}
+
 export function mapEntryIds(messages: MessageLike[], branch: readonly SessionEntryLike[]): Array<string | undefined> {
   const queues = new Map<string, string[]>();
   for (const entry of branch) {

package/src/plan.ts

@@ -1,26 +1,39 @@
+// Draft plan ownership. Owns pending-to-summarized draft transitions and the
+// bounded Agent-facing plan output. A DraftRange boundary can be fixed while
+// its summary is still empty ("pending"); only ranges with non-empty summaries
+// form a review draft and can commit. Show and mutation formatters expose
+// bounded semantic landmarks without dumping the full shared plan repeatedly.
+
 import type { Atom, DraftPlan, DraftRange, DraftTelemetry } from "./types.js";
-import { estimateCompressedTokens } from "./projection.js";
+import { isProtectedAtom } from "./atoms.js";
+import { estimateCompressedTokens, rangeMetricsForAtoms, replacementContentChars } from "./projection.js";
 import { formatTelemetry } from "./telemetry.js";
+import { truncateMiddle } from "./messages.js";
 
 export function emptyDraft(transactionId: string): DraftPlan {
   return { version: 1, transactionId, revision: 0, ranges: [] };
 }
 
+/** Add an ordinary draft range from start/end atom refs. Summary may be empty (pending). */
 export function addDraftRange(
   draft: DraftPlan,
   atoms: Atom[],
-  input: { start: string; end: string; summary: string; topic?: string },
+  input: { start: string; end: string; summary?: string; topic?: string },
 ): DraftPlan {
   const start = atoms.find((atom) => atom.ref === input.start);
   const end = atoms.find((atom) => atom.ref === input.end);
-  if (!start || !end) throw new Error("Unknown atom ref; run locate again against the current anchor snapshot.");
+  if (!start || !end) throw new Error("Unknown atom ref; run locate/inspect again against the current anchor snapshot.");
   if (start.index > end.index) throw new Error("start must not occur after end.");
   const selected = atoms.slice(start.index, end.index + 1);
   if (selected.length === 0) throw new Error("Empty range.");
-  const unsafe = selected.find((atom) => !atom.compressible || !atom.protocolClosed || atom.kind === "compressed");
+  const unsafe = selected.find((atom) => isProtectedAtom(atom));
   if (unsafe) throw new Error(`Range crosses protected atom ${unsafe.ref} (${unsafe.kind}). Split the plan around it.`);
   const overlaps = draft.ranges.some((range) => !(end.index < range.startIndex || start.index > range.endIndex));
   if (overlaps) throw new Error("Range overlaps an existing draft range.");
+
+  const metrics = rangeMetricsForAtoms(selected);
+  const summary = input.summary ?? "";
+  const replacement = replacementContentChars(summary, input.topic);
   const id = nextDraftId(draft);
   const range: DraftRange = {
     id,
@@ -29,17 +42,34 @@ export function addDraftRange(
     startIndex: start.index,
     endIndex: end.index,
     topic: input.topic,
-    summary: input.summary,
+    summary,
     entryIds: selected.flatMap((atom) => atom.entryIds),
     messageKeys: selected.flatMap((atom) => atom.messageKeys),
+    originalContentChars: metrics.contentChars,
+    originalImageCount: metrics.imageCount,
+    originalImagePayloadBytes: metrics.images.reduce((sum, image) => sum + image.payloadBytes, 0),
+    replacementContentChars: replacement,
     originalApproxTokens: selected.reduce((sum, atom) => sum + atom.approxTokens, 0),
-    compressedApproxTokens: estimateCompressedTokens(input.summary, input.topic),
+    compressedApproxTokens: estimateCompressedTokens(summary, input.topic),
     startPreview: start.preview,
     endPreview: end.preview,
   };
   return { ...draft, revision: draft.revision + 1, ranges: [...draft.ranges, range].sort((a, b) => a.startIndex - b.startIndex) };
 }
 
+/** Create ranges from finalized ordinary spans (post selection subtraction). Summaries are pending (empty). */
+export function addPendingRanges(
+  draft: DraftPlan,
+  atoms: Atom[],
+  spans: readonly { startRef: string; endRef: string }[],
+): DraftPlan {
+  let next = draft;
+  for (const span of spans) {
+    next = addDraftRange(next, atoms, { start: span.startRef, end: span.endRef, summary: "" });
+  }
+  return next;
+}
+
 export function updateDraftRange(
   draft: DraftPlan,
   draftId: string,
@@ -49,11 +79,12 @@ export function updateDraftRange(
   if (!target) throw new Error(`Unknown draft range ${draftId}.`);
   const summary = patch.summary ?? target.summary;
   const topic = patch.topic ?? target.topic;
+  const replacement = replacementContentChars(summary, topic);
   return {
     ...draft,
     revision: draft.revision + 1,
     ranges: draft.ranges.map((range) => range.id === draftId
-      ? { ...range, summary, topic, compressedApproxTokens: estimateCompressedTokens(summary, topic) }
+      ? { ...range, summary, topic, replacementContentChars: replacement, compressedApproxTokens: estimateCompressedTokens(summary, topic) }
       : range),
   };
 }
@@ -72,22 +103,147 @@ function nextDraftId(draft: DraftPlan): string {
   return `d${max + 1}`;
 }
 
-export function formatDraft(draft: DraftPlan, telemetry?: DraftTelemetry): string {
+/** Replace the current range set with normalized ordinary spans, preserving exact prior ranges. */
+export function replaceDraftRanges(
+  draft: DraftPlan,
+  atoms: Atom[],
+  spans: readonly { startRef: string; endRef: string }[],
+): DraftPlan {
+  const existing = new Map(draft.ranges.map((range) => [`${range.startRef}:${range.endRef}`, range]));
+  let nextId = draft.ranges.reduce((max, range) => {
+    const match = /^d(\d+)$/.exec(range.id);
+    return match ? Math.max(max, Number(match[1])) : max;
+  }, 0);
+  const ranges: DraftRange[] = [];
+
+  for (const span of spans) {
+    const previous = existing.get(`${span.startRef}:${span.endRef}`);
+    if (previous) {
+      ranges.push(previous);
+      continue;
+    }
+    const created = addDraftRange(emptyDraft(draft.transactionId), atoms, {
+      start: span.startRef,
+      end: span.endRef,
+      summary: "",
+    }).ranges[0]!;
+    nextId += 1;
+    ranges.push({ ...created, id: `d${nextId}` });
+  }
+
+  return { ...draft, revision: draft.revision + 1, ranges };
+}
+
+/** True when every range has a non-empty summary (i.e. the draft is review-ready). */
+export function isReviewReady(draft: DraftPlan): boolean {
+  return draft.ranges.length > 0 && draft.ranges.every((range) => range.summary.trim().length > 0);
+}
+
+const BRIEF_LANDMARK_LIMIT = 180;
+const BRIEF_SUMMARY_LIMIT = 500;
+const DRAFT_OUTPUT_LIMIT = 12_000;
+const FULL_DRAFT_OUTPUT_LIMIT = 40_000;
+
+export interface DraftFormatOptions {
+  detail?: "brief" | "full";
+  draftId?: string;
+  atoms?: readonly Atom[];
+}
+
+/** Agent-facing plan output with bounded semantic landmarks and summaries. */
+export function formatDraft(draft: DraftPlan, telemetry?: DraftTelemetry, options: DraftFormatOptions = {}): string {
+  if (options.detail === "full" && !options.draftId) {
+    throw new Error("plan show detail=full requires draft_id.");
+  }
+  const selected = options.draftId
+    ? draft.ranges.filter((range) => range.id === options.draftId)
+    : draft.ranges;
+  const atomsByRef = options.atoms ? new Map(options.atoms.map((atom) => [atom.ref, atom])) : undefined;
+  if (options.draftId && selected.length === 0) throw new Error(`Unknown draft range ${options.draftId}.`);
+
   const lines: string[] = [];
-  if (telemetry) lines.push(formatTelemetry(telemetry), "");
+  if (telemetry) lines.push(formatTelemetry(telemetry));
   if (draft.ranges.length === 0) {
     lines.push(`Draft v${draft.revision}: no compression ranges.`);
-    return lines.join("\n");
+    return lines.join("\n\n");
   }
-  const before = draft.ranges.reduce((sum, range) => sum + range.originalApproxTokens, 0);
-  const after = draft.ranges.reduce((sum, range) => sum + range.compressedApproxTokens, 0);
-  lines.push(`Draft v${draft.revision}: ${draft.ranges.length} range(s), ~${before} → ~${after} tokens`);
-  for (const range of draft.ranges) {
-    lines.push(`\n${range.id}: ${range.startRef} → ${range.endRef}${range.topic ? ` | ${range.topic}` : ""}`);
-    lines.push(`~${range.originalApproxTokens} → ~${range.compressedApproxTokens} tokens`);
-    lines.push(`summary: ${range.summary}`);
-    lines.push(`start: ${range.startPreview}`);
-    if (range.endRef !== range.startRef) lines.push(`end: ${range.endPreview}`);
+  lines.push(draftHeader(draft));
+
+  if (options.detail === "full") {
+    const remainingBudget = Math.max(1, FULL_DRAFT_OUTPUT_LIMIT - lines.join("\n\n").length - 2);
+    lines.push(formatRangeFull(selected[0]!, remainingBudget, atomsByRef));
+    return lines.join("\n\n");
+  }
+
+  let shown = 0;
+  for (const range of selected) {
+    const block = formatRangeBrief(range, atomsByRef);
+    const currentLength = lines.join("\n\n").length;
+    if (currentLength + 2 + block.length > DRAFT_OUTPUT_LIMIT) {
+      const notice = `Output budget reached: showed ${shown} of ${selected.length} range(s). Use draft_id to inspect one range.`;
+      if (currentLength + 2 + notice.length <= DRAFT_OUTPUT_LIMIT) lines.push(notice);
+      break;
+    }
+    lines.push(block);
+    shown += 1;
+  }
+  return lines.join("\n\n");
+}
+
+/** Concise confirmation for one DraftPlan mutation; explicit show owns full awareness. */
+export function formatPlanMutation(
+  draft: DraftPlan,
+  op: "add" | "update" | "remove",
+  changedId: string,
+  atoms?: readonly Atom[],
+): string {
+  const pendingCount = draft.ranges.filter((range) => range.summary.trim().length === 0).length;
+  const verb = op === "add" ? "added" : op === "update" ? "updated" : "removed";
+  const lines = [`Draft v${draft.revision}: ${verb} ${changedId} · ${draft.ranges.length} range(s) · ${pendingCount} pending summary.`];
+  if (op !== "remove") {
+    const changed = draft.ranges.find((range) => range.id === changedId);
+    const atomsByRef = atoms ? new Map(atoms.map((atom) => [atom.ref, atom])) : undefined;
+    if (changed) lines.push(formatRangeBrief(changed, atomsByRef));
   }
-  return lines.join("\n");
+  return lines.join("\n\n");
+}
+
+function draftHeader(draft: DraftPlan): string {
+  const pendingCount = draft.ranges.filter((range) => range.summary.trim().length === 0).length;
+  const reviewState = pendingCount === 0 ? "ready for review" : `${pendingCount} pending summary`;
+  return `Draft v${draft.revision}: ${draft.ranges.length} range(s) (${reviewState}).`;
+}
+
+function formatRangeBrief(range: DraftRange, atomsByRef?: ReadonlyMap<string, Atom>): string {
+  const pending = range.summary.trim().length === 0;
+  return [
+    `${range.id}: ${range.startRef} → ${range.endRef}${range.topic ? ` | ${truncateMiddle(range.topic, BRIEF_LANDMARK_LIMIT)}` : ""} [${pending ? "pending summary" : "summarized"}]`,
+    `from: ${truncateMiddle(rangeEndpoint(range, "start", atomsByRef), BRIEF_LANDMARK_LIMIT)}`,
+    `to: ${truncateMiddle(rangeEndpoint(range, "end", atomsByRef), BRIEF_LANDMARK_LIMIT)}`,
+    `summary: ${pending ? "<pending>" : truncateMiddle(range.summary, BRIEF_SUMMARY_LIMIT)}`,
+    `metrics: ${range.originalContentChars} → ${range.replacementContentChars} content chars · ${range.originalImageCount} images (${range.originalImagePayloadBytes} payload bytes)`,
+  ].join("\n");
+}
+
+function formatRangeFull(range: DraftRange, outputLimit: number, atomsByRef?: ReadonlyMap<string, Atom>): string {
+  const prefix = [
+    `${range.id}: ${range.startRef} → ${range.endRef}${range.topic ? ` | ${truncateMiddle(range.topic, BRIEF_LANDMARK_LIMIT)}` : ""} [${range.summary.trim() ? "summarized" : "pending summary"}]`,
+    `from: ${truncateMiddle(rangeEndpoint(range, "start", atomsByRef), 700)}`,
+    `to: ${truncateMiddle(rangeEndpoint(range, "end", atomsByRef), 700)}`,
+    "summary: ",
+    `metrics: ${range.originalContentChars} → ${range.replacementContentChars} content chars · ${range.originalImageCount} images (${range.originalImagePayloadBytes} payload bytes)`,
+  ];
+  const fixedLength = prefix.join("\n").length;
+  const summaryBudget = Math.max(1, outputLimit - fixedLength);
+  const summary = range.summary.trim()
+    ? range.summary.length <= summaryBudget ? range.summary : truncateMiddle(range.summary, summaryBudget)
+    : "<pending>";
+  prefix[3] = `summary: ${summary}`;
+  return prefix.join("\n");
+}
+
+function rangeEndpoint(range: DraftRange, side: "start" | "end", atomsByRef?: ReadonlyMap<string, Atom>): string {
+  const ref = side === "start" ? range.startRef : range.endRef;
+  const stored = side === "start" ? range.startPreview : range.endPreview;
+  return atomsByRef?.get(ref)?.fullText || stored || ref;
 }

package/src/planning-lock.ts

@@ -0,0 +1,42 @@
+// Runtime mutex over DraftPlan edits. Pure state machine, not persisted: the
+// owner is held in memory by index.ts and lost on reload by design. Agent turns
+// and user edit UIs cannot mutate the DraftPlan concurrently.
+
+export type PlanningLockOwner = "agent" | "ui";
+
+export interface PlanningLockState {
+  owner: PlanningLockOwner | undefined;
+}
+
+export function emptyPlanningLock(): PlanningLockState {
+  return { owner: undefined };
+}
+
+/** Agent path: returns false when a UI holds the lock. */
+export function agentCanMutate(state: PlanningLockState): boolean {
+  return state.owner !== "ui";
+}
+
+/** UI path: returns false when an Agent turn holds the lock. */
+export function tryAcquireUi(state: PlanningLockState): boolean {
+  if (state.owner === "agent") return false;
+  state.owner = "ui";
+  return true;
+}
+
+/** Acquire the Agent turn lock. Returns false when the UI holds it. */
+export function acquireAgent(state: PlanningLockState): boolean {
+  if (state.owner === "ui") return false;
+  state.owner = "agent";
+  return true;
+}
+
+/** Release the Agent lock on turn end. No-op if the UI holds it. */
+export function releaseAgent(state: PlanningLockState): void {
+  if (state.owner === "agent") state.owner = undefined;
+}
+
+/** Release the UI lock on close or abnormal disconnect. No-op if the Agent holds it. */
+export function releaseUi(state: PlanningLockState): void {
+  if (state.owner === "ui") state.owner = undefined;
+}