jeo-code 0.7.30 → 0.7.32

package/src/agent/lsp-rename-tool.ts

@@ -0,0 +1,108 @@
+/**
+ * `lsp_rename` tool — cross-file TypeScript/JavaScript symbol rename (gjc `lsp`
+ * `action:"rename"` parity), using the same in-process `ts.LanguageService` as the
+ * read-only `lsp` tool. MUTATING: kept as its own tool (not an action on `lsp`) so
+ * the read-only-role toolset filter — which excludes tools by NAME — cannot be
+ * bypassed by an `apply:true` argument hidden inside a nominally "read-only" tool.
+ * Writes go through the existing `writeTool`, so the mutation lock and stale-read
+ * guard apply exactly as they do for `write`/`edit`/`ast_edit`.
+ */
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+import type * as ts from "typescript";
+import type { ToolHandler } from "./engine";
+import type { ToolResult } from "./tools";
+import { writeTool } from "./tools";
+import { languageServiceFor, parseSymbolSelector, resolvePosition, lineTextAt, lineOfPosition, formatLocation } from "./ts-language-service";
+
+/** One-line protocol description appended to the launch system prompt. */
+export const LSP_RENAME_TOOL_PROTOCOL_LINE =
+  `lsp_rename {file, line, symbol?, new_name, apply?} — rename a TypeScript/JavaScript symbol across every ` +
+  `file in the project via the same in-process language service as 'lsp' (same file/line/symbol addressing). ` +
+  `'apply' defaults to true (writes files — mutation lock/stale-read checks apply, same as write/edit); ` +
+  `apply:false previews every location that would change without writing anything.`;
+
+function err(message: string): ToolResult {
+  return { success: false, output: "", error: message };
+}
+
+const IDENTIFIER_RE = /^[A-Za-z_$][A-Za-z0-9_$]*$/;
+
+export function createLspRenameTool(): ToolHandler {
+  return async (args: Record<string, any>, cwd: string): Promise<ToolResult> => {
+    const fileArg = typeof args.file === "string" ? args.file.trim() : "";
+    if (!fileArg) return err(`lsp_rename requires a non-empty "file".`);
+
+    const newName = typeof args.new_name === "string" ? args.new_name.trim()
+      : typeof args.newName === "string" ? args.newName.trim() : "";
+    if (!newName) return err(`lsp_rename requires a non-empty "new_name".`);
+    if (!IDENTIFIER_RE.test(newName)) return err(`"new_name" must be a valid identifier, got '${newName}'.`);
+
+    const absPath = path.resolve(cwd, fileArg);
+    let text: string;
+    try {
+      text = await fs.readFile(absPath, "utf-8");
+    } catch {
+      return err(`Cannot read file '${fileArg}'.`);
+    }
+
+    const lineRaw = args.line;
+    const line = typeof lineRaw === "number" ? lineRaw : parseInt(String(lineRaw ?? ""), 10);
+    if (!Number.isFinite(line) || line < 1) return err(`lsp_rename requires a positive integer "line".`);
+
+    const symbol = parseSymbolSelector(typeof args.symbol === "string" ? args.symbol : undefined);
+    const pos = resolvePosition(text, line, symbol);
+    if ("error" in pos) return err(pos.error);
+
+    const service = await languageServiceFor(cwd, absPath);
+    const renameInfo = service.getRenameInfo(absPath, pos.position, {});
+    if (!renameInfo.canRename) {
+      const reason = "localizedErrorMessage" in renameInfo ? renameInfo.localizedErrorMessage : "not a renameable symbol here";
+      return err(`Cannot rename here: ${reason}.`);
+    }
+
+    const locations = service.findRenameLocations(absPath, pos.position, false, false, {}) ?? [];
+    if (locations.length === 0) return { success: true, output: "No rename locations found." };
+
+    const apply = args.apply !== false; // default true
+
+    const byFile = new Map<string, ts.TextSpan[]>();
+    for (const loc of locations) {
+      const spans = byFile.get(loc.fileName) ?? [];
+      spans.push(loc.textSpan);
+      byFile.set(loc.fileName, spans);
+    }
+
+    const preview: string[] = [];
+    let totalEdits = 0;
+    for (const [fName, spans] of byFile) {
+      const rel = path.relative(cwd, fName) || fName;
+      let content: string;
+      try {
+        content = await fs.readFile(fName, "utf-8");
+      } catch {
+        return err(`Cannot read file '${rel}' while applying rename.`);
+      }
+
+      for (const span of spans) {
+        totalEdits++;
+        const line1 = lineOfPosition(content, span.start);
+        preview.push(formatLocation(rel, line1, lineTextAt(content, line1)));
+      }
+
+      if (apply) {
+        let newText = content;
+        for (const span of [...spans].sort((a, b) => b.start - a.start)) {
+          newText = newText.slice(0, span.start) + newName + newText.slice(span.start + span.length);
+        }
+        const res = await writeTool(rel, newText, cwd);
+        if (!res.success) return err(`${rel}: ${res.error ?? "write failed"}`);
+      }
+    }
+
+    const header = apply
+      ? `Renamed ${totalEdits} occurrence(s) across ${byFile.size} file(s):`
+      : `Preview: ${totalEdits} occurrence(s) across ${byFile.size} file(s) would be renamed to '${newName}' (apply:false, nothing written):`;
+    return { success: true, output: `${header}\n${preview.join("\n")}` };
+  };
+}

package/src/agent/lsp-tool.ts

@@ -0,0 +1,177 @@
+/**
+ * `lsp` tool — read-only TypeScript/JavaScript language-service queries (gjc `lsp`
+ * parity, scoped to TS/JS/TSX/JSX via the in-process `ts.LanguageService` from
+ * `ts-language-service.ts` — NOT a real LSP client/server, NOT multi-language).
+ * Safe for every subagent role. Cross-file rename (mutating) is the separate
+ * `lsp_rename` tool so the read-only-role toolset filter (which gates by tool
+ * NAME, not by argument) cannot be bypassed by a `rename` action hidden in here.
+ */
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+import * as ts from "typescript";
+import type { ToolHandler } from "./engine";
+import type { ToolResult } from "./tools";
+import { languageServiceFor, parseSymbolSelector, resolvePosition, lineTextAt, lineOfPosition, formatLocation } from "./ts-language-service";
+import { resolveTargetFiles } from "./ast-file-scan";
+
+/** One-line protocol description appended to the launch system prompt. */
+export const LSP_TOOL_PROTOCOL_LINE =
+  `lsp {action:"definition"|"references"|"hover"|"symbols"|"diagnostics", file, line?, symbol?} — ` +
+  `TypeScript/JavaScript language-service queries (in-process ts.LanguageService, not a real LSP server). ` +
+  `'symbol' is a substring on 'line' used to resolve the column automatically (append "#N" to pick the Nth ` +
+  `occurrence). 'definition'/'references'/'hover' need file+line(+symbol); 'symbols' needs only file; ` +
+  `'diagnostics' takes file (a path, glob, or "*" for the whole project) and needs no line/symbol. Cross-file ` +
+  `rename is the separate 'lsp_rename' tool.`;
+
+async function readAbs(absPath: string): Promise<string | null> {
+  try {
+    return await fs.readFile(absPath, "utf-8");
+  } catch {
+    return null;
+  }
+}
+
+function err(message: string): ToolResult {
+  return { success: false, output: "", error: message };
+}
+
+interface ResolvedTarget {
+  absPath: string;
+  rel: string;
+  text: string;
+  position: number;
+}
+
+async function resolveTarget(args: Record<string, any>, cwd: string): Promise<ResolvedTarget | { error: string }> {
+  const fileArg = typeof args.file === "string" ? args.file.trim() : "";
+  if (!fileArg) return { error: `lsp requires a non-empty "file".` };
+  const absPath = path.resolve(cwd, fileArg);
+  const text = await readAbs(absPath);
+  if (text === null) return { error: `Cannot read file '${fileArg}'.` };
+
+  const lineRaw = args.line;
+  const line = typeof lineRaw === "number" ? lineRaw : parseInt(String(lineRaw ?? ""), 10);
+  if (!Number.isFinite(line) || line < 1) return { error: `lsp requires a positive integer "line".` };
+
+  const symbol = parseSymbolSelector(typeof args.symbol === "string" ? args.symbol : undefined);
+  const pos = resolvePosition(text, line, symbol);
+  if ("error" in pos) return { error: pos.error };
+
+  return { absPath, rel: path.relative(cwd, absPath) || absPath, text, position: pos.position };
+}
+
+const MAX_REFERENCES_FULL = 50;
+const MAX_DIAGNOSTIC_FILES = 50;
+
+export function createLspTool(): ToolHandler {
+  return async (args: Record<string, any>, cwd: string): Promise<ToolResult> => {
+    const action = String(args.action ?? "").trim().toLowerCase();
+
+    if (action === "definition") {
+      const t = await resolveTarget(args, cwd);
+      if ("error" in t) return err(t.error);
+      const service = await languageServiceFor(cwd, t.absPath);
+      const result = service.getDefinitionAndBoundSpan(t.absPath, t.position);
+      const defs = result?.definitions ?? [];
+      if (defs.length === 0) return { success: true, output: "No definition found." };
+      const lines: string[] = [];
+      for (const d of defs) {
+        const dText = (await readAbs(d.fileName)) ?? "";
+        const dLine = lineOfPosition(dText, d.textSpan.start);
+        const rel = path.relative(cwd, d.fileName) || d.fileName;
+        lines.push(formatLocation(rel, dLine, lineTextAt(dText, dLine)));
+      }
+      return { success: true, output: lines.join("\n") };
+    }
+
+    if (action === "references") {
+      const t = await resolveTarget(args, cwd);
+      if ("error" in t) return err(t.error);
+      const service = await languageServiceFor(cwd, t.absPath);
+      const refs = service.getReferencesAtPosition(t.absPath, t.position) ?? [];
+      if (refs.length === 0) return { success: true, output: "No references found." };
+      const lines: string[] = [];
+      for (let i = 0; i < refs.length; i++) {
+        const r = refs[i]!;
+        const rel = path.relative(cwd, r.fileName) || r.fileName;
+        const rText = (await readAbs(r.fileName)) ?? "";
+        const rLine = lineOfPosition(rText, r.textSpan.start);
+        lines.push(i < MAX_REFERENCES_FULL ? formatLocation(rel, rLine, lineTextAt(rText, rLine)) : `${rel}:${rLine}`);
+      }
+      return { success: true, output: `${refs.length} reference(s):\n${lines.join("\n")}` };
+    }
+
+    if (action === "hover") {
+      const t = await resolveTarget(args, cwd);
+      if ("error" in t) return err(t.error);
+      const service = await languageServiceFor(cwd, t.absPath);
+      const info = service.getQuickInfoAtPosition(t.absPath, t.position);
+      if (!info) return { success: true, output: "No hover info available at that position." };
+      const signature = (info.displayParts ?? []).map(p => p.text).join("");
+      const doc = (info.documentation ?? []).map(p => p.text).join("").trim();
+      return { success: true, output: doc ? `${signature}\n\n${doc}` : signature };
+    }
+
+    if (action === "symbols") {
+      const fileArg = typeof args.file === "string" ? args.file.trim() : "";
+      if (!fileArg) return err(`lsp {action:"symbols"} requires a non-empty "file".`);
+      const absPath = path.resolve(cwd, fileArg);
+      const text = await readAbs(absPath);
+      if (text === null) return err(`Cannot read file '${fileArg}'.`);
+      const service = await languageServiceFor(cwd, absPath);
+      const items = service.getNavigationBarItems(absPath);
+      const lines: string[] = [];
+      const walk = (nodes: readonly ts.NavigationBarItem[], depth: number) => {
+        for (const n of nodes) {
+          const span = n.spans[0];
+          const line1 = span ? lineOfPosition(text, span.start) : undefined;
+          lines.push(`${"  ".repeat(depth)}${n.text} (${n.kind})${line1 ? ` — line ${line1}` : ""}`);
+          if (n.childItems && n.childItems.length) walk(n.childItems, depth + 1);
+        }
+      };
+      walk(items, 0);
+      return { success: true, output: lines.length ? lines.join("\n") : "No symbols found." };
+    }
+
+    if (action === "diagnostics") {
+      const fileArg = args.file;
+      const rawPaths = fileArg === "*"
+        ? ["**/*"]
+        : Array.isArray(fileArg) ? fileArg.map((p: unknown) => String(p))
+        : typeof fileArg === "string" && fileArg.trim() ? [fileArg.trim()]
+        : [];
+      if (rawPaths.length === 0) {
+        return err(`lsp {action:"diagnostics"} requires a "file" (path, glob, or "*" for the whole project).`);
+      }
+      let files: string[];
+      try {
+        files = await resolveTargetFiles(rawPaths, cwd);
+      } catch (e: any) {
+        return err(e.message);
+      }
+      if (files.length === 0) return { success: true, output: "No matching TypeScript/JavaScript files." };
+
+      const scanned = files.slice(0, MAX_DIAGNOSTIC_FILES);
+      const lines: string[] = [];
+      let count = 0;
+      for (const absPath of scanned) {
+        const service = await languageServiceFor(cwd, absPath);
+        const text = (await readAbs(absPath)) ?? "";
+        const diags = [...service.getSyntacticDiagnostics(absPath), ...service.getSemanticDiagnostics(absPath)];
+        if (diags.length === 0) continue;
+        const rel = path.relative(cwd, absPath) || absPath;
+        for (const d of diags) {
+          count++;
+          const msg = ts.flattenDiagnosticMessageText(d.messageText, " ");
+          const line1 = d.start !== undefined ? lineOfPosition(text, d.start) : 0;
+          lines.push(`${rel}:${line1}: ${msg}`);
+        }
+      }
+      if (count === 0) return { success: true, output: `0 diagnostics across ${scanned.length} file(s).` };
+      const note = files.length > MAX_DIAGNOSTIC_FILES ? ` (scanned first ${MAX_DIAGNOSTIC_FILES} of ${files.length} files)` : "";
+      return { success: true, output: `${count} diagnostic(s)${note}:\n${lines.join("\n")}` };
+    }
+
+    return err(`Unknown lsp action '${action}'. Use definition | references | hover | symbols | diagnostics.`);
+  };
+}

package/src/agent/memory-graph.ts

@@ -39,6 +39,8 @@ export interface ConceptGraph {
   edges: Map<string, Set<string>>;
   /** from-ID → set of link targets that have NO node (tolerated broken links). */
   broken: Map<string, Set<string>>;
+  /** ponytail: cached undirected adjacency for O(1) retrieval during graph expansion */
+  adj?: Map<string, Set<string>>;
 }
 
 /** A markdown inline link `](target)` — captures the target, not the label. */
@@ -115,7 +117,10 @@ function undirectedAdjacency(graph: ConceptGraph): Map<string, Set<string>> {
  * nodes are dropped. With `hops` 0 this is just the valid seeds.
  */
 export function expandByGraph(seedIds: Iterable<string>, graph: ConceptGraph, hops = 1): Set<string> {
-  const adj = undirectedAdjacency(graph);
+  if (!graph.adj) {
+    graph.adj = undirectedAdjacency(graph);
+  }
+  const adj = graph.adj;
   const result = new Set<string>();
   for (const id of seedIds) if (graph.nodes.has(id)) result.add(id);
   let frontier = [...result];

package/src/agent/memory.ts

@@ -251,57 +251,58 @@ export async function lintMemoryBundle(cwd: string): Promise<GraphLintReport> {
   return lintConceptGraph(concepts, buildConceptGraph(concepts));
 }
 
+const CONCEPT_LOAD_BATCH = 16;
+
 async function loadConceptsFromBundle(bundleDir: string): Promise<Concept[]> {
   const files = await findMarkdownFiles(bundleDir);
-  const concepts: Concept[] = [];
-  for (const file of files) {
+  const loadOne = async (file: string): Promise<Concept | null> => {
     const relPath = path.relative(bundleDir, file).replace(/\\/g, "/");
-    if (isReservedFile(relPath)) continue;
+    if (isReservedFile(relPath)) return null;
 
-    // Skip the read+parse when the file is byte-for-byte unchanged since we last
-    // saw it (same mtime+size). A missing stat falls through to a fresh read.
     let sig: string | null = null;
     try {
       const st = await fs.stat(file);
       sig = `${st.mtimeMs}:${st.size}`;
     } catch {
-      continue;
+      return null;
     }
     const cached = parsedConceptCache.get(file);
     if (cached && cached.sig === sig) {
-      // LRU refresh so a hot file is evicted last.
       parsedConceptCache.delete(file);
       parsedConceptCache.set(file, cached);
-      if (cached.concept) concepts.push(cached.concept);
-      continue;
+      return cached.concept;
     }
 
-    let parsed;
     try {
-      parsed = parseConcept(await fs.readFile(file, "utf-8"));
+      const parsed = parseConcept(await fs.readFile(file, "utf-8"));
+      if (!parsed.hasFrontmatter) {
+        cacheParsedConcept(file, sig, null);
+        return null;
+      }
+      const fm = parsed.frontmatter;
+      const concept: Concept = {
+        type: (fm.type as string) || "RepoFact",
+        title: (fm.title as string) || path.basename(file, ".md"),
+        description: (fm.description as string) || "",
+        body: parsed.body.trim(),
+        tags: Array.isArray(fm.tags) ? fm.tags.filter((t): t is string => typeof t === "string") : [],
+        confidence: typeof fm.confidence === "string" ? fm.confidence : "high",
+        pinned: fm.pinned === true,
+        relPath,
+      };
+      cacheParsedConcept(file, sig, concept);
+      return concept;
     } catch {
       cacheParsedConcept(file, sig, null);
-      continue;
+      return null;
     }
-    if (!parsed.hasFrontmatter) {
-      cacheParsedConcept(file, sig, null);
-      continue;
-    }
-    const fm = parsed.frontmatter;
-    const concept: Concept = {
-      type: (fm.type as string) || "RepoFact",
-      title: (fm.title as string) || path.basename(file, ".md"),
-      description: (fm.description as string) || "",
-      body: parsed.body.trim(),
-      tags: Array.isArray(fm.tags) ? fm.tags.filter((t): t is string => typeof t === "string") : [],
-      confidence: typeof fm.confidence === "string" ? fm.confidence : "high",
-      pinned: fm.pinned === true,
-      relPath,
-    };
-    cacheParsedConcept(file, sig, concept);
-    concepts.push(concept);
+  };
+  const results: Concept[] = [];
+  for (let i = 0; i < files.length; i += CONCEPT_LOAD_BATCH) {
+    const batch = await Promise.all(files.slice(i, i + CONCEPT_LOAD_BATCH).map(loadOne));
+    for (const c of batch) if (c) results.push(c);
   }
-  return concepts;
+  return results;
 }
 
 /** Store a per-file parse result under its stat signature, evicting the oldest
@@ -329,12 +330,35 @@ export interface CorpusStats {
   df: Map<string, number>;
 }
 
+interface LowercasedConceptFields {
+  title: string;
+  description: string;
+  body: string;
+  type: string;
+  tagsText: string;
+  searchableText: string;
+}
+const lowercasedFieldsCache = new WeakMap<Concept, LowercasedConceptFields>();
+
+function getLowercasedFields(concept: Concept): LowercasedConceptFields {
+  let cached = lowercasedFieldsCache.get(concept);
+  if (!cached) {
+    const title = concept.title.toLowerCase();
+    const description = concept.description.toLowerCase();
+    const body = concept.body.toLowerCase();
+    const type = concept.type.toLowerCase();
+    const tagsText = concept.tags.map(t => t.toLowerCase()).join(" ");
+    const searchableText = [title, tagsText, type, description, body].join(" ");
+    cached = { title, description, body, type, tagsText, searchableText };
+    lowercasedFieldsCache.set(concept, cached);
+  }
+  return cached;
+}
+
 /** Lowercased searchable text of a concept (title + tags + type + description +
  *  body) — the field corpus over which document frequency is measured. */
 function searchableText(concept: Concept): string {
-  return [concept.title, concept.tags.join(" "), concept.type, concept.description, concept.body]
-    .join(" ")
-    .toLowerCase();
+  return getLowercasedFields(concept).searchableText;
 }
 
 /** Build IDF corpus stats from the concept set: per distinct token, how many
@@ -372,19 +396,15 @@ function tokenIdf(token: string, stats: CorpusStats): number {
  *  field-weighted presence count (IDF = 1). 0 = no hit. */
 export function scoreConcept(concept: Concept, tokens: string[], stats?: CorpusStats): number {
   if (tokens.length === 0) return 0;
-  const title = concept.title.toLowerCase();
-  const desc = concept.description.toLowerCase();
-  const body = concept.body.toLowerCase();
-  const type = concept.type.toLowerCase();
-  const tags = concept.tags.map(t => t.toLowerCase());
+  const fields = getLowercasedFields(concept);
   let score = 0;
   for (const t of tokens) {
     let weight = 0;
-    if (title.includes(t)) weight += 5;
-    if (tags.some(tag => tag.includes(t))) weight += 3;
-    if (type.includes(t)) weight += 2;
-    if (desc.includes(t)) weight += 2;
-    if (body.includes(t)) weight += 1;
+    if (fields.title.includes(t)) weight += 5;
+    if (fields.tagsText.includes(t)) weight += 3;
+    if (fields.type.includes(t)) weight += 2;
+    if (fields.description.includes(t)) weight += 2;
+    if (fields.body.includes(t)) weight += 1;
     score += stats ? weight * tokenIdf(t, stats) : weight;
   }
   return score;
@@ -462,10 +482,10 @@ function graphProximityOrder(concepts: Concept[], seedIds: string[], graph: Conc
  *  final tiebreak. The failure boost only fires when the query actually hits the
  *  concept (score > 0), so an unrelated FailedAttempt never crowds out relevant
  *  context. */
-function priorityOrder(concepts: Concept[], query?: string): Concept[] {
+function priorityOrder(concepts: Concept[], query?: string, stats?: CorpusStats, graph?: ConceptGraph): Concept[] {
   const tokens = tokenize(query);
-  const stats = buildCorpusStats(concepts);
-  const scored = concepts.map(c => ({ c, id: conceptId(c.relPath), score: scoreConcept(c, tokens, stats) }));
+  const localStats = stats ?? buildCorpusStats(concepts);
+  const scored = concepts.map(c => ({ c, id: conceptId(c.relPath), score: scoreConcept(c, tokens, localStats) }));
 
   // Channel 1 — lexical ("sparse"/BM25): query-hit concepts, IDF score descending.
   // Stable sort keeps input order on ties.
@@ -474,7 +494,8 @@ function priorityOrder(concepts: Concept[], query?: string): Concept[] {
   // Channel 2 — graph proximity ("dense"): neighbours of the query-hit seeds.
   let graphOrder: string[] = [];
   if (tokens.length > 0 && lexicalOrder.length > 0) {
-    graphOrder = graphProximityOrder(concepts, lexicalOrder, buildConceptGraph(concepts));
+    const localGraph = graph ?? buildConceptGraph(concepts);
+    graphOrder = graphProximityOrder(concepts, lexicalOrder, localGraph);
   }
 
   const fused = reciprocalRankFusion([lexicalOrder, graphOrder]);
@@ -483,9 +504,6 @@ function priorityOrder(concepts: Concept[], query?: string): Concept[] {
     .map(({ c, id, score }, i) => ({
       concept: c,
       i,
-      // Query-relevant past failure → resurface first so the loop is reminded of
-      // what NOT to repeat for the current task. Gated on score > 0: a stale,
-      // unrelated dead end stays out of the way.
       failure: c.type === "FailedAttempt" && score > 0,
       core: c.confidence === "high",
       rrf: fused.get(id) ?? 0,
@@ -554,8 +572,11 @@ function selectWithinBudget(concepts: Concept[], query: string | undefined, budg
   const sectionLenByType = new Map<string, number>(); // type -> rendered length of that type's section so far
   let total = 0; // rendered length of `selected` under renderConcepts
 
+  const stats = buildCorpusStats(concepts);
+  const graph = buildConceptGraph(concepts);
+
   const take = (pool: Concept[]) => {
-    for (const c of priorityOrder(pool, query)) {
+    for (const c of priorityOrder(pool, query, stats, graph)) {
       const itemLen = renderConceptItem(c).length;
       const priorSectionLen = sectionLenByType.get(c.type);
       let newSectionLen: number;
@@ -579,7 +600,7 @@ function selectWithinBudget(concepts: Concept[], query: string | undefined, budg
   };
   take(concepts.filter(c => c.pinned)); // reserved budget: invariants survive the cap
   take(concepts.filter(c => !c.pinned)); // recency/query fill in the remaining budget
-  if (selected.length === 0 && concepts.length > 0) selected.push(priorityOrder(concepts, query)[0]!);
+  if (selected.length === 0 && concepts.length > 0) selected.push(priorityOrder(concepts, query, stats, graph)[0]!);
   return selected;
 }
 

package/src/agent/session.ts

@@ -316,6 +316,33 @@ export async function latestSessionId(cwd = process.cwd()): Promise<string | und
   return list[0]?.id;
 }
 
+/** Result of resolving a full session id or a short id prefix. */
+export type SessionRefResolution =
+  | { kind: "ok"; id: string }
+  | { kind: "ambiguous"; matches: string[] }
+  | { kind: "not-found" };
+
+/** Resolve a full session id OR a short id PREFIX (gjc-parity: `--resume <prefix>`,
+ *  `/session resume <prefix>`) to exactly one session id. Exact match wins immediately
+ *  (fast path, no directory scan) before falling back to a prefix scan of listSessions(). */
+export async function resolveSessionRef(idOrPrefix: string, cwd = process.cwd()): Promise<SessionRefResolution> {
+  const trimmed = idOrPrefix.trim();
+  if (!trimmed) return { kind: "not-found" };
+  // Fast path: exact file exists.
+  try {
+    await fs.access(sessionPath(trimmed, cwd));
+    return { kind: "ok", id: trimmed };
+  } catch {
+    // fall through to prefix scan
+  }
+  const all = await listSessions(cwd);
+  const lower = trimmed.toLowerCase();
+  const matches = all.filter(s => s.id.toLowerCase().startsWith(lower)).map(s => s.id);
+  if (matches.length === 1) return { kind: "ok", id: matches[0]! };
+  if (matches.length > 1) return { kind: "ambiguous", matches };
+  return { kind: "not-found" };
+}
+
 /**
  * Locate the session's JSONL header, apply `mutate`, and rewrite the file in place.
  * `mutate` returns false to signal "no change needed" (skips the write). Shared by

package/src/agent/subagent-registry.ts

@@ -6,6 +6,11 @@
  * `subagent` control tool. Concurrency is real (JS event loop): a detached run's
  * awaits interleave with the parent's between steps.
  *
+ * Detached runs also support live steering (peer messaging) via `steer()` /
+ * `steerDrainFor()` — a running parent (or another subagent, via the `irc` tool)
+ * can push a message into a running detached subagent's inbox; the subagent's own
+ * agent loop drains it between steps, same mechanism as ordinary task steering.
+ *
  * Lifecycle is bounded to the turn that created the registry — `cancelAll()` on
  * turn teardown guarantees no background promise leaks into the next turn.
  */
@@ -34,13 +39,17 @@ interface Entry {
   abort: AbortController;
 }
 
-/** A detached run: receives its own AbortSignal and resolves to the subagent's
- *  final ToolResult. The runner is responsible for streaming live events itself. */
-export type DetachedRunner = (signal: AbortSignal) => Promise<ToolResult>;
+/** A detached run: receives its own AbortSignal and its own registry id, and
+ *  resolves to the subagent's final ToolResult. The `id` param lets a runner
+ *  wire up its own steer drain (e.g. `registry.steerDrainFor(id)`); runners that
+ *  don't need it can ignore the 2nd param. The runner is responsible for
+ *  streaming live events itself. */
+export type DetachedRunner = (signal: AbortSignal, id: string) => Promise<ToolResult>;
 
 export class SubagentRegistry {
   private readonly entries = new Map<string, Entry>();
   private readonly seq = new Map<string, number>();
+  private readonly steerInboxes = new Map<string, string[]>();
 
   /** Register and START a detached run; returns the (running) record immediately. */
   launch(role: string, task: string, runner: DetachedRunner): SubagentRecord {
@@ -55,9 +64,10 @@ export class SubagentRegistry {
       status: "running",
       startedAt: Date.now(),
     };
+    this.steerInboxes.set(id, []);
     const promise = (async () => {
       try {
-        const res = await runner(abort.signal);
+        const res = await runner(abort.signal, id);
         // A cancel that already fired wins — don't overwrite the terminal state.
         if (record.status === "cancelled") return;
         record.status = res.success ? "completed" : "failed";
@@ -69,6 +79,7 @@ export class SubagentRegistry {
         record.result = err instanceof Error ? err.message : String(err);
       } finally {
         if (record.finishedAt === undefined) record.finishedAt = Date.now();
+        this.steerInboxes.delete(id);
       }
     })();
     this.entries.set(id, { record, promise, abort });
@@ -107,6 +118,31 @@ export class SubagentRegistry {
     return targets.map(e => e.record);
   }
 
+  /** Push a live message into a running id's steer inbox (parent → detached subagent,
+   *  or subagent → subagent via the `irc` tool). Returns false if the id is unknown,
+   *  not running, or the (trimmed) message is empty — true once queued. */
+  steer(id: string, message: string): boolean {
+    const rec = this.get(id);
+    if (!rec || rec.status !== "running") return false;
+    const trimmed = message.trim();
+    if (!trimmed) return false;
+    const inbox = this.steerInboxes.get(id);
+    if (!inbox) return false;
+    inbox.push(trimmed);
+    return true;
+  }
+
+  /** A drain closure bound to one id — splices its inbox to empty on each call.
+   *  Wire this into a detached runner's own agent-loop `steer` option so pending
+   *  messages are picked up between the subagent's own steps. */
+  steerDrainFor(id: string): () => string[] {
+    return () => {
+      const inbox = this.steerInboxes.get(id);
+      if (!inbox || inbox.length === 0) return [];
+      return inbox.splice(0, inbox.length);
+    };
+  }
+
   /** Cancel the given ids (or all running, when empty): aborts the run and marks the
    *  record cancelled. Already-terminal records are returned unchanged. */
   cancel(ids: string[]): SubagentRecord[] {