@nklisch/pi-enhanced 0.4.1 → 0.4.2

package/node_modules/@nklisch/pi-astral-pocket/src/store.ts

@@ -1,23 +1,19 @@
-import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from "node:fs";
+import { createHash } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, readdirSync, renameSync, rmSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { join } from "node:path";
 
-/** Store layout under the pocket root:
- *   config.json          — toggles + distiller settings (config.ts)
- *   SUMMARY.md           — injected into astra's system prompt; mechanical render
- *   POCKET.md            — searchable registry, one line per note
- *   notes/<ts>-<slug>.md — append-only note files
- *   distilled.json       — distiller bookkeeping (which sessions are processed)
- */
+import { resolveProjectIdentity } from "./scope.js";
 
 const PINNED_START = "<!-- pocket:pinned:start -->";
 const PINNED_END = "<!-- pocket:pinned:end -->";
 const DIGEST_START = "<!-- pocket:digest:start -->";
 const DIGEST_END = "<!-- pocket:digest:end -->";
-
 const RECENT_NOTES_CAP = 20;
-const REGISTRY_LINE_CAP = 500;
-const BODY_SCAN_CAP = 200;
+const NOTE_EXCERPT = 320;
+const FULL_NOTE_EXCERPT = 4_000;
+const DIGEST_NOTE_CAP = 200;
+const DIGEST_NOTE_BYTES = 2_000;
 
 export function defaultAgentDir(): string {
   return process.env.PI_CODING_AGENT_DIR ?? join(homedir(), ".pi", "agent");
@@ -31,37 +27,59 @@ export function notesDir(root: string): string {
   return join(root, "notes");
 }
 
+function atomicWrite(path: string, contents: string): void {
+  const temporary = `${path}.${process.pid}.${Date.now()}.${Math.random().toString(16).slice(2)}.tmp`;
+  writeFileSync(temporary, contents, "utf8");
+  renameSync(temporary, path);
+}
+
 export function ensureLayout(root: string): void {
   mkdirSync(notesDir(root), { recursive: true });
   const registry = join(root, "POCKET.md");
-  if (!existsSync(registry)) {
-    writeFileSync(registry, "# Astral Pocket Registry\n\nOne line per note. Search this first.\n\n", "utf8");
-  }
-  if (!existsSync(join(root, "SUMMARY.md"))) {
-    writeFileSync(join(root, "SUMMARY.md"), renderSummary(root, []), "utf8");
-  }
+  if (!existsSync(registry)) atomicWrite(registry, renderRegistry([]));
+  if (!existsSync(join(root, "SUMMARY.md"))) atomicWrite(join(root, "SUMMARY.md"), renderSummary(root, []));
 }
 
+export type NoteScope = "project" | "global";
+
 export interface NoteInput {
   title: string;
   body: string;
   keywords?: string[];
-  /** cwd of the session taking the note; recorded for project-aware ranking. */
   project?: string;
+  projectId?: string;
+  scope?: NoteScope;
   source?: "agent" | "distilled";
 }
 
+export interface GeneratedNoteInput extends NoteInput {
+  sessionId: string;
+  sourcePath: string;
+  sourceUpdatedAt: string;
+  sourceSize: number;
+  sourceRevision: string;
+}
+
+interface StoredNote {
+  fileName: string;
+  title: string;
+  text: string;
+  body: string;
+  project: string;
+  projectId: string;
+  scope: NoteScope | "unknown";
+  source: string;
+  created: string;
+  updated: string;
+}
+
 function slugify(text: string): string {
-  const slug = text
-    .toLowerCase()
-    .replace(/[^a-z0-9]+/g, "-")
-    .replace(/^-+|-+$/g, "")
-    .slice(0, 48);
+  const slug = text.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 48);
   return slug || "note";
 }
 
 function stamp(date: Date): string {
-  return date.toISOString().replace(/[:.]/g, "-").replace("Z", "Z");
+  return date.toISOString().replace(/[:.]/g, "-");
 }
 
 function extractSection(markdown: string, start: string, end: string): string | null {
@@ -71,82 +89,183 @@ function extractSection(markdown: string, start: string, end: string): string |
   return markdown.slice(i + start.length, j).trim();
 }
 
-/** Write one note file and update the registry + summary. Returns the note's
- * file name. Callers that need cross-file mutation safety should wrap this in
- * `withFileMutationQueue(join(root, "POCKET.md"), ...)`. */
-export function writeNote(root: string, input: NoteInput, now: Date = new Date()): string {
-  ensureLayout(root);
-  const fileName = `${stamp(now)}-${slugify(input.title)}.md`;
-  const frontmatter = [
+function field(text: string, name: string): string {
+  const frontmatter = text.match(/^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/)?.[1] ?? "";
+  return frontmatter.match(new RegExp(`^${name}: (.*)$`, "m"))?.[1]?.trim() ?? "";
+}
+
+function noteTimestamp(note: StoredNote): number {
+  const parsed = Date.parse(note.updated || note.created);
+  return Number.isNaN(parsed) ? Number.NEGATIVE_INFINITY : parsed;
+}
+
+function compareNotesByTime(a: StoredNote, b: StoredNote): number {
+  const aTime = noteTimestamp(a);
+  const bTime = noteTimestamp(b);
+  if (aTime !== bTime) return aTime < bTime ? -1 : 1;
+  // Prefer deliberate and legacy notes at a time tie so a batch of generated
+  // notes cannot crowd them out solely because session hashes sort later.
+  const manualRank = Number(a.source !== "distilled") - Number(b.source !== "distilled");
+  return manualRank || a.fileName.localeCompare(b.fileName);
+}
+
+function readStoredNotes(root: string): StoredNote[] {
+  if (!existsSync(notesDir(root))) return [];
+  const notes: StoredNote[] = [];
+  for (const fileName of readdirSync(notesDir(root)).filter((name) => name.endsWith(".md"))) {
+    try {
+      const text = readFileSync(join(notesDir(root), fileName), "utf8");
+      const heading = text.match(/^# (.+)$/m)?.[1] ?? fileName;
+      const headingAt = text.search(/^# .+$/m);
+      const project = field(text, "project");
+      const declaredScope = field(text, "scope");
+      const scope: NoteScope | "unknown" = declaredScope === "global"
+        ? "global"
+        : declaredScope === "project" || (declaredScope === "" && project !== "" && project !== "unknown")
+          ? "project"
+          : "unknown";
+      notes.push({
+        fileName,
+        title: heading,
+        text,
+        body: headingAt >= 0 ? text.slice(headingAt).replace(/^# .+\n+/, "").trim() : text.trim(),
+        project,
+        projectId: field(text, "project_id") || (scope === "project" && project !== "" && project !== "unknown" ? resolveProjectIdentity(project) : ""),
+        scope,
+        source: field(text, "source") || "legacy",
+        created: field(text, "created"),
+        updated: field(text, "updated") || field(text, "source_updated_at") || field(text, "created"),
+      });
+    } catch {
+      // One unreadable note must not hide the remaining canonical note files.
+    }
+  }
+  return notes.sort(compareNotesByTime);
+}
+
+function noteMarkdown(input: NoteInput, metadata: string[], created: Date, updated: Date = created): string {
+  return [
     "---",
-    `created: ${now.toISOString()}`,
+    `created: ${created.toISOString()}`,
+    `updated: ${updated.toISOString()}`,
     `project: ${input.project ?? "unknown"}`,
+    `project_id: ${input.projectId ?? ""}`,
+    `scope: ${input.scope ?? "project"}`,
     `keywords: [${(input.keywords ?? []).join(", ")}]`,
     `source: ${input.source ?? "agent"}`,
+    ...metadata,
     "---",
+    "",
+    `# ${input.title}`,
+    "",
+    input.body.trim(),
+    "",
   ].join("\n");
-  writeFileSync(join(notesDir(root), fileName), `${frontmatter}\n\n# ${input.title}\n\n${input.body.trim()}\n`, "utf8");
+}
 
-  const projectTag = input.project ? (input.project.split("/").filter(Boolean).pop() ?? input.project) : "unknown";
-  const keywordTag = (input.keywords ?? []).join(", ");
-  const line = `- [${input.title}](notes/${fileName})${keywordTag ? ` — ${keywordTag}` : ""} — ${projectTag} — ${now.toISOString().slice(0, 10)}`;
-  appendRegistryLine(root, line);
-  rerenderSummary(root);
+function uniqueManualFile(root: string, input: NoteInput, now: Date): string {
+  const base = `${stamp(now)}-${slugify(input.title)}`;
+  let fileName = `${base}.md`;
+  let suffix = 2;
+  while (existsSync(join(notesDir(root), fileName))) fileName = `${base}-${suffix++}.md`;
   return fileName;
 }
 
-function appendRegistryLine(root: string, line: string): void {
-  const registry = join(root, "POCKET.md");
-  const existing = existsSync(registry) ? readFileSync(registry, "utf8") : "";
-  writeFileSync(registry, `${existing.trimEnd()}\n${line}\n`, "utf8");
+/** Write one deliberate note. Call inside the POCKET.md mutation queue. */
+export function writeNote(root: string, input: NoteInput, now: Date = new Date()): string {
+  ensureLayout(root);
+  const fileName = uniqueManualFile(root, input, now);
+  atomicWrite(join(notesDir(root), fileName), noteMarkdown(input, [], now));
+  rebuildDerivedStore(root);
+  return fileName;
+}
+
+export function generatedNoteFile(sessionId: string): string {
+  const identity = createHash("sha256").update(sessionId).digest("hex").slice(0, 24);
+  return `session-${identity}.md`;
+}
+
+/** Replace the one generated note owned by a session revision. */
+export function writeGeneratedNote(root: string, input: GeneratedNoteInput, now: Date = new Date()): string {
+  ensureLayout(root);
+  const fileName = generatedNoteFile(input.sessionId);
+  const existingPath = join(notesDir(root), fileName);
+  let created = now;
+  if (existsSync(existingPath)) {
+    const previousCreated = field(readFileSync(existingPath, "utf8"), "created");
+    if (previousCreated && !Number.isNaN(Date.parse(previousCreated))) created = new Date(previousCreated);
+  }
+  atomicWrite(existingPath, noteMarkdown(input, [
+    `session_id: ${input.sessionId}`,
+    `source_path: ${input.sourcePath}`,
+    `source_updated_at: ${input.sourceUpdatedAt}`,
+    `source_size: ${input.sourceSize}`,
+    `source_revision: ${input.sourceRevision}`,
+  ], created, now));
+  rebuildDerivedStore(root);
+  return fileName;
+}
+
+export function removeGeneratedNote(root: string, sessionId: string): boolean {
+  const path = join(notesDir(root), generatedNoteFile(sessionId));
+  if (!existsSync(path)) return false;
+  rmSync(path);
+  rebuildDerivedStore(root);
+  return true;
+}
+
+function registryLine(note: StoredNote): string {
+  const project = note.scope === "global"
+    ? "global"
+    : (note.project.split("/").filter(Boolean).pop() ?? note.project) || "unknown";
+  const date = (note.updated || note.created).slice(0, 10) || "unknown-date";
+  return `- [${note.title}](notes/${note.fileName}) — ${note.scope} — ${project} — ${date}`;
+}
+
+function renderRegistry(notes: StoredNote[]): string {
+  return [
+    "# Astral Pocket Registry",
+    "",
+    "Derived from the canonical Markdown files in `notes/`. Search this first.",
+    "",
+    ...notes.map(registryLine),
+    "",
+  ].join("\n");
+}
+
+export function countNotes(root: string): number {
+  return readStoredNotes(root).length;
 }
 
 export function readRegistryLines(root: string): string[] {
   const registry = join(root, "POCKET.md");
   if (!existsSync(registry)) return [];
-  return readFileSync(registry, "utf8")
-    .split("\n")
-    .filter((l) => l.startsWith("- ["));
+  return readFileSync(registry, "utf8").split("\n").filter((line) => line.startsWith("- ["));
 }
 
-/** Re-render SUMMARY.md mechanically: the pinned block and the
- * distiller-maintained digest block carry over verbatim from the existing
- * file; only the recent-notes index is regenerated. This is the mechanical
- * floor — it runs on every note write with zero LLM involvement. */
-export function rerenderSummary(root: string): void {
-  writeFileSync(join(root, "SUMMARY.md"), renderSummary(root, readRegistryLines(root)), "utf8");
+/** Rebuildable indexes are rendered from note files, never treated as note authority. */
+export function rebuildDerivedStore(root: string): void {
+  const notes = readStoredNotes(root);
+  atomicWrite(join(root, "POCKET.md"), renderRegistry(notes));
+  atomicWrite(join(root, "SUMMARY.md"), renderSummary(root, notes.map(registryLine)));
 }
 
+export const rerenderSummary = rebuildDerivedStore;
+
 function renderSummary(root: string, registryLines: string[]): string {
   const summaryPath = join(root, "SUMMARY.md");
   const existing = existsSync(summaryPath) ? readFileSync(summaryPath, "utf8") : "";
   const pinned = extractSection(existing, PINNED_START, PINNED_END) ?? "";
-  const digest =
-    extractSection(existing, DIGEST_START, DIGEST_END) ??
+  const digest = extractSection(existing, DIGEST_START, DIGEST_END) ??
     "_No digest yet. It is filled in by the distiller pass; until then, rely on Recent notes and search POCKET.md._";
   const recent = registryLines.slice(-RECENT_NOTES_CAP);
   return [
-    "# Astral Pocket Summary",
-    "",
-    PINNED_START,
-    pinned,
-    PINNED_END,
-    "",
-    "## Durable digest",
-    "",
-    DIGEST_START,
-    digest,
-    DIGEST_END,
-    "",
-    "## Recent notes",
-    "",
-    ...(recent.length > 0 ? recent : ["_No notes yet._"]),
-    "",
+    "# Astral Pocket Summary", "", PINNED_START, pinned, PINNED_END, "",
+    "## Durable digest", "", DIGEST_START, digest, DIGEST_END, "",
+    "## Recent notes", "", ...(recent.length > 0 ? recent : ["_No notes yet._"]), "",
   ].join("\n");
 }
 
-/** Replace the distiller-maintained digest block, preserving everything else.
- * Returns false when SUMMARY.md is missing the markers (never rendered). */
 export function updateDigest(root: string, digest: string): boolean {
   const summaryPath = join(root, "SUMMARY.md");
   if (!existsSync(summaryPath)) return false;
@@ -154,12 +273,10 @@ export function updateDigest(root: string, digest: string): boolean {
   const i = existing.indexOf(DIGEST_START);
   const j = existing.indexOf(DIGEST_END);
   if (i === -1 || j === -1 || j < i) return false;
-  writeFileSync(summaryPath, `${existing.slice(0, i + DIGEST_START.length)}\n${digest.trim()}\n${existing.slice(j)}`, "utf8");
+  atomicWrite(summaryPath, `${existing.slice(0, i + DIGEST_START.length)}\n${digest.trim()}\n${existing.slice(j)}`);
   return true;
 }
 
-/** The text injected into astra's system prompt, capped to keep the per-turn
- * cost bounded regardless of how large the summary grows. */
 export function readSummaryCapped(root: string, capBytes = 12_000): string {
   const summaryPath = join(root, "SUMMARY.md");
   if (!existsSync(summaryPath)) return "";
@@ -172,56 +289,139 @@ export interface PocketSearchHit {
   title: string;
   excerpt: string;
   project: string;
+  projectId: string;
+  source: string;
+  scope: NoteScope | "unknown";
+  date: string;
 }
 
-/** Case-insensitive keyword search over the registry, then the note bodies.
- * Registry hits rank first; current-project notes rank above others. */
-export function searchPocket(root: string, query: string, currentProject: string | undefined, limit: number): PocketSearchHit[] {
+/** Search complete canonical note content, then truncate only the returned excerpt. */
+export function searchPocket(
+  root: string,
+  query: string,
+  currentProject: string | undefined,
+  limit: number,
+  full = false,
+  recallScope: "current" | "all" = "current",
+): PocketSearchHit[] {
   const terms = query.toLowerCase().split(/\s+/).filter(Boolean);
   if (terms.length === 0) return [];
-  const matches = (haystack: string) => terms.every((t) => haystack.toLowerCase().includes(t));
-
-  const hits: PocketSearchHit[] = [];
-  for (const line of readRegistryLines(root).slice(-REGISTRY_LINE_CAP)) {
-    if (!matches(line)) continue;
-    const fileMatch = line.match(/\]\((notes\/[^)]+)\)/);
-    const titleMatch = line.match(/- \[([^\]]+)\]/);
-    if (!fileMatch) continue;
-    hits.push({
-      noteFile: fileMatch[1].replace(/^notes\//, ""),
-      title: titleMatch?.[1] ?? fileMatch[1],
-      excerpt: line,
-      project: "",
-    });
-  }
+  const cap = full ? FULL_NOTE_EXCERPT : NOTE_EXCERPT;
+  const hits = readStoredNotes(root)
+    .filter((note) => recallScope === "all" || note.scope === "global" || (note.scope === "project" && note.projectId === currentProject))
+    .filter((note) => terms.every((term) => note.text.toLowerCase().includes(term))).map((note) => {
+    const lowerBody = note.body.toLowerCase();
+    const bodyMatches = terms.map((term) => lowerBody.indexOf(term)).filter((at) => at >= 0);
+    const at = bodyMatches.length > 0 ? Math.min(...bodyMatches) : 0;
+    const start = Math.max(0, at - Math.floor(cap / 4));
+    const excerpt = note.body.slice(start, start + cap).trim();
+    return {
+      noteFile: note.fileName,
+      title: note.title,
+      excerpt: excerpt.length < note.body.slice(start).trim().length ? `${excerpt}…` : excerpt,
+      project: note.project,
+      projectId: note.projectId,
+      source: note.source,
+      scope: note.scope,
+      date: note.updated || note.created,
+    };
+  });
+  hits.sort((a, b) => {
+    const projectRank = Number(b.projectId === currentProject) - Number(a.projectId === currentProject);
+    const globalRank = Number(b.scope === "global") - Number(a.scope === "global");
+    return projectRank || globalRank || b.date.localeCompare(a.date) || b.noteFile.localeCompare(a.noteFile);
+  });
+  return hits.slice(0, Math.max(1, limit));
+}
+
+export interface DigestSnapshot {
+  fingerprint: string;
+  promptSource: string;
+  noteCount: number;
+}
+
+export type DigestScope = { kind: "project"; projectId: string } | { kind: "global" };
+
+export function digestScopeKey(scope: DigestScope): string {
+  return scope.kind === "global"
+    ? "global"
+    : `project:${createHash("sha256").update(scope.projectId).digest("hex").slice(0, 24)}`;
+}
 
-  const bodyHits: PocketSearchHit[] = [];
-  // Timestamp-prefixed names sort chronologically; cap the body scan at the
-  // newest files so recall stays fast as the store grows.
-  const files = readdirSync(notesDir(root))
-    .filter((f) => f.endsWith(".md"))
-    .sort()
-    .slice(-BODY_SCAN_CAP);
-  for (const file of files) {
-    if (hits.some((h) => h.noteFile === file)) continue;
-    const text = readFileSync(join(notesDir(root), file), "utf8");
-    if (!matches(text)) continue;
-    const project = text.match(/^project: (.+)$/m)?.[1] ?? "";
-    const title = text.match(/^# (.+)$/m)?.[1] ?? file;
-    const idx = text.toLowerCase().indexOf(terms[0]);
-    bodyHits.push({
-      noteFile: file,
-      title,
-      excerpt: text.slice(Math.max(0, idx - 120), idx + 280).trim(),
-      project,
-    });
+function digestPath(root: string, scope: DigestScope): string {
+  return join(root, "digests", `${digestScopeKey(scope).replace(":", "-")}.md`);
+}
+
+export function scopedDigestExists(root: string, scope: DigestScope): boolean {
+  return existsSync(digestPath(root, scope));
+}
+
+function successfulDigestFingerprint(root: string, scope: DigestScope): string | undefined {
+  try {
+    const state = JSON.parse(readFileSync(join(root, "distilled.json"), "utf8")) as { digestFingerprints?: Record<string, unknown> };
+    const value = state.digestFingerprints?.[digestScopeKey(scope)];
+    return typeof value === "string" ? value : undefined;
+  } catch {
+    return undefined;
   }
+}
 
-  const currentTag = currentProject?.split("/").filter(Boolean).pop();
-  const ranked = [...hits, ...bodyHits].sort((a, b) => {
-    const aCur = currentTag && a.project.endsWith(currentTag) ? 1 : 0;
-    const bCur = currentTag && b.project.endsWith(currentTag) ? 1 : 0;
-    return bCur - aCur;
-  });
-  return ranked.slice(0, limit);
+export function updateScopedDigest(root: string, scope: DigestScope, digest: string): void {
+  mkdirSync(join(root, "digests"), { recursive: true });
+  atomicWrite(digestPath(root, scope), `${digest.trim()}\n`);
+}
+
+/** Build injected context only from the current project and explicit global notes. */
+export function readScopedSummary(root: string, projectId: string, capBytes = 12_000): string {
+  const renderLayer = (scope: DigestScope, heading: string, layerCap: number): string => {
+    const notes = readStoredNotes(root).filter((note) =>
+      scope.kind === "global" ? note.scope === "global" : note.scope === "project" && note.projectId === scope.projectId,
+    );
+    let digest = "";
+    const currentFingerprint = createDigestSnapshot(root, scope).fingerprint;
+    if (successfulDigestFingerprint(root, scope) === currentFingerprint) {
+      try { digest = readFileSync(digestPath(root, scope), "utf8").trim(); } catch { /* derived cache may lag */ }
+    }
+    const recent = notes.slice(-RECENT_NOTES_CAP).map(registryLine);
+    const layer = [
+      `## ${heading}`,
+      "",
+      digest || "_No digest is available; use the source-linked recent notes below._",
+      "",
+      "### Recent source notes",
+      ...(recent.length > 0 ? recent : ["_None._"]),
+    ].join("\n");
+    return layer.length <= layerCap
+      ? layer
+      : `${layer.slice(0, layerCap)}\n_(layer truncated; use pocket_recall for source notes)_`;
+  };
+  const globalCap = Math.max(1_500, Math.floor(capBytes / 4));
+  const projectCap = Math.max(1_500, capBytes - globalCap - 40);
+  return [
+    "# Astral Pocket Summary",
+    "",
+    renderLayer({ kind: "project", projectId }, "Current repository memory", projectCap),
+    "",
+    renderLayer({ kind: "global" }, "Explicit global memory", globalCap),
+  ].join("\n");
+}
+
+/** Bounded, source-linked digest input built from notes rather than SUMMARY.md. */
+export function createDigestSnapshot(root: string, scope: DigestScope): DigestSnapshot {
+  const notes = readStoredNotes(root)
+    .filter((note) => scope.kind === "global" ? note.scope === "global" : note.scope === "project" && note.projectId === scope.projectId)
+    .slice(-DIGEST_NOTE_CAP);
+  const promptSource = notes.map((note) => [
+    `NOTE: notes/${note.fileName}`,
+    `TITLE: ${note.title}`,
+    `PROJECT: ${note.project || "unknown"}`,
+    `SOURCE: ${note.source || "legacy"}`,
+    `DATE: ${note.updated || note.created || "unknown"}`,
+    note.body.slice(0, DIGEST_NOTE_BYTES),
+  ].join("\n")).join("\n\n");
+  return {
+    fingerprint: createHash("sha256").update(promptSource).digest("hex"),
+    promptSource,
+    noteCount: notes.length,
+  };
 }

package/node_modules/@nklisch/pi-astral-pocket/src/tools.ts

@@ -4,11 +4,19 @@ import { withFileMutationQueue } from "@earendil-works/pi-coding-agent";
 import { join } from "node:path";
 
 import type { ActivationState } from "./activation.js";
+import { resolveProjectIdentity } from "./scope.js";
 import { searchAstraSessions } from "./sessions.js";
 import { readSummaryCapped, searchPocket, writeNote } from "./store.js";
 
 const INACTIVE_MESSAGE =
   "Pocket tools are only active in gpt-6-astra sessions with the pocket enabled (/pocket on).";
+const DEFAULT_RECALL_LIMIT = 10;
+export const MAX_RECALL_LIMIT_PER_SOURCE = 20;
+
+function normalizeRecallLimit(value: unknown): number {
+  if (typeof value !== "number" || !Number.isFinite(value)) return DEFAULT_RECALL_LIMIT;
+  return Math.min(MAX_RECALL_LIMIT_PER_SOURCE, Math.max(1, Math.trunc(value)));
+}
 
 export interface ToolDeps {
   state: ActivationState;
@@ -28,28 +36,39 @@ export function registerPocketTools(pi: ExtensionAPI, deps: ToolDeps): void {
     name: "pocket_note",
     label: "Pocket Note",
     description:
-      "Write a durable note to your persistent pocket. Notes survive across sessions. Use for decisions, conventions, pitfalls, and preferences worth remembering — never for secrets or ephemeral task state.",
+      "Write a durable note to your persistent pocket. Notes default to the current repository. Use global scope only for explicitly portable preferences or observations — never for secrets or ephemeral task state.",
     promptSnippet: "Save a durable cross-session note to the astral pocket",
     promptGuidelines: [
       "Use pocket_note when you learn something durable (a decision and why, a project convention, a pitfall, a user preference) — not for ephemeral task state.",
       "Never put secrets, credentials, tokens, or personal data in pocket notes.",
+      "Keep pocket_note project-scoped by default; use global scope only for a clearly general preference or conditional portable observation.",
     ],
     parameters: Type.Object({
       title: Type.String({ description: "Short note title" }),
       body: Type.String({ description: "Note content — a few sentences is enough" }),
       keywords: Type.Optional(Type.Array(Type.String(), { description: "2-5 recall keywords" })),
+      scope: Type.Optional(Type.Union([Type.Literal("project"), Type.Literal("global")], {
+        description: "Project by default. Use global only for explicitly portable preferences or observations.",
+      })),
     }),
-    async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+    async execute(_toolCallId, params, signal, _onUpdate, ctx) {
       if (!deps.state.active) throw new Error(INACTIVE_MESSAGE);
-      const fileName = await withFileMutationQueue(join(deps.root, "POCKET.md"), async () =>
-        writeNote(deps.root, {
+      if (signal?.aborted) throw new Error("Pocket note cancelled");
+      const project = ctx.cwd;
+      const scope = params.scope ?? "project";
+      const projectId = resolveProjectIdentity(project);
+      const fileName = await withFileMutationQueue(join(deps.root, "POCKET.md"), async () => {
+        if (signal?.aborted || !deps.state.active) throw new Error("Pocket note cancelled");
+        return writeNote(deps.root, {
           title: params.title,
           body: params.body,
           keywords: params.keywords,
-          project: ctx.cwd,
+          project,
+          projectId: scope === "project" ? projectId : undefined,
+          scope,
           source: "agent",
-        }),
-      );
+        });
+      });
       return textResult(`Note saved to the pocket: notes/${fileName}`);
     },
   });
@@ -58,7 +77,7 @@ export function registerPocketTools(pi: ExtensionAPI, deps: ToolDeps): void {
     name: "pocket_recall",
     label: "Pocket Recall",
     description:
-      "Search your persistent pocket notes and your past gpt-6-astra sessions. Summarized by default (tool names + truncated args/results); pass full: true for larger excerpts. Past-session output can contain sensitive data from earlier work — prefer summarized results.",
+      "Search current-repository and explicit global pocket notes plus current-repository Astra sessions. Summarized by default; pass full: true for larger excerpts or scope: all for intentional cross-repository precedent.",
     promptSnippet: "Search pocket notes and past astra sessions",
     promptGuidelines: [
       "Use pocket_recall for the quick pocket pass: search with keywords from the pocket summary before deep repo exploration.",
@@ -72,21 +91,30 @@ export function registerPocketTools(pi: ExtensionAPI, deps: ToolDeps): void {
         }),
       ),
       full: Type.Optional(Type.Boolean({ description: "Return larger excerpts (default: false)" })),
-      limit: Type.Optional(Type.Number({ description: "Max hits (default: 10)" })),
+      limit: Type.Optional(Type.Integer({
+        minimum: 1,
+        maximum: MAX_RECALL_LIMIT_PER_SOURCE,
+        description: "Max hits from each source (default: 10, maximum: 20)",
+      })),
+      scope: Type.Optional(Type.Union([Type.Literal("current"), Type.Literal("all")], {
+        description: "Current repository plus global notes by default; all includes foreign repositories as precedent.",
+      })),
     }),
     async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
       if (!deps.state.active) throw new Error(INACTIVE_MESSAGE);
       const source = params.source ?? "both";
-      const limit = params.limit ?? 10;
+      const limit = normalizeRecallLimit(params.limit);
+      const recallScope = params.scope ?? "current";
+      const projectId = resolveProjectIdentity(ctx.cwd);
       const sections: string[] = [];
 
       if (source === "pocket" || source === "both") {
-        const hits = searchPocket(deps.root, params.query, ctx.cwd, limit);
+        const hits = searchPocket(deps.root, params.query, projectId, limit, params.full, recallScope);
         sections.push(
           hits.length === 0
             ? "Pocket notes: no matches."
             : `Pocket notes (${hits.length}):\n${hits
-                .map((h) => `- ${h.title} [notes/${h.noteFile}]${h.project ? ` (${h.project})` : ""}\n  ${h.excerpt}`)
+                .map((h) => `- ${h.title} [notes/${h.noteFile}]${h.project ? ` (${h.project})` : ""} · scope: ${h.scope}${recallScope === "all" && h.scope === "project" && resolveProjectIdentity(h.project) !== projectId ? " · cross-repository precedent" : ""}${h.source ? ` · ${h.source}` : ""}${h.date ? ` · ${h.date}` : ""}\n  ${h.excerpt}`)
                 .join("\n")}`,
         );
       }
@@ -96,12 +124,14 @@ export function registerPocketTools(pi: ExtensionAPI, deps: ToolDeps): void {
           full: params.full,
           limit,
           maxAgeDays: deps.maxSessionAgeDays(),
+          projectId,
+          recallScope,
         });
         sections.push(
           hits.length === 0
             ? "Past astra sessions: no matches."
             : `Past astra sessions (${hits.length}):\n${hits
-                .map((h) => `- [${h.kind}] ${h.timestamp} (${h.project})\n  ${h.excerpt}`)
+                .map((h) => `- [${h.kind}] ${h.timestamp} (${h.project})${recallScope === "all" && resolveProjectIdentity(h.project) !== projectId ? " · cross-repository precedent" : ""}\n  ${h.excerpt}`)
                 .join("\n")}`,
         );
       }