@astrosheep/pi-context 0.25.2 → 0.26.0

package/dist/src/dream/settings.d.ts

@@ -0,0 +1,16 @@
+import { type PiContextSettings } from "../settings.js";
+export type DreamerSetting = {
+    pattern?: string;
+    warnings: string[];
+};
+/**
+ * `pi-context.dreamer` is a non-empty model pattern. Anything else present is ignored
+ * with one warning; absent means no configured pattern, so the automatic model applies.
+ */
+export declare function deriveDreamer(settings: PiContextSettings): DreamerSetting;
+/**
+ * Resolve the configurable dreamer model from Pi settings for a CLI invocation: global
+ * `~/.pi/agent/settings.json` merged with the project's `.pi/settings.json`, project
+ * values winning per key. A settings read failure degrades to no pattern with one warning.
+ */
+export declare function readDreamerSettings(cwd?: string): DreamerSetting;

package/dist/src/history/history-tools.d.ts

@@ -0,0 +1,2 @@
+import { type ExtensionAPI } from "@earendil-works/pi-coding-agent";
+export declare function registerHistoryTools(pi: ExtensionAPI): void;

package/dist/src/history/history.d.ts

@@ -0,0 +1,57 @@
+import type { SessionReader } from "../session-reader.js";
+type HistoryItem = {
+    windowId: string;
+    itemId: string;
+    role: "user" | "assistant" | "tool_call" | "tool" | "system" | "developer";
+    content: string;
+    createdAt: string | undefined;
+    toolName?: string;
+    outputTruncated?: boolean;
+    fullOutputPath?: string;
+    toolError?: boolean;
+};
+type HistoryWindow = {
+    windowId: string;
+    createdAt?: string;
+    items: HistoryItem[];
+};
+type HistoryFilter = {
+    window_id?: string | null;
+    role?: HistoryItem["role"] | null;
+    tool_name?: string | null;
+    recent_first?: boolean;
+};
+export declare function contentText(content: unknown): string;
+/** Build durable, on-demand history directly from every entry on the current session branch. */
+export declare function historyFromSession(ctx: SessionReader): HistoryWindow[];
+export declare function visibleItem(item: HistoryItem, maxChars?: number): {
+    truncated: boolean;
+    total_chars: number;
+    truncated_content: string;
+    tool_error?: boolean | undefined;
+    output_truncated?: boolean | undefined;
+    full_output_path?: string | null | undefined;
+    window_id: string;
+    item_id: string;
+    role: "user" | "assistant" | "tool_call" | "tool" | "system" | "developer";
+    tool_name: string | null;
+};
+export declare function allItems(ctx: SessionReader): HistoryItem[];
+/**
+ * window_id must name a real window; anything else is a named error, not a silent empty page
+ * (a window that exists but has no matching items after the other filters stays a legal empty
+ * page). Returns the teaching message plus the known window ids so the error is self-healing.
+ */
+export declare function unknownWindowId(ctx: SessionReader, params: HistoryFilter): {
+    message: string;
+    known: string[];
+} | undefined;
+/**
+ * A role×tool_name combination is vacuous — provably empty from the taxonomy alone, before
+ * any data is read — when tool_name is given alongside a role that never carries one. Only
+ * "tool_call" and "tool" items have a tool name. Returns the teaching error message, or
+ * undefined when the combination can match.
+ */
+export declare function vacuousRoleToolCombo(params: HistoryFilter): string | undefined;
+export declare function filteredItems(ctx: SessionReader, params: HistoryFilter): HistoryItem[];
+export {};

package/dist/src/index.d.ts

@@ -0,0 +1,39 @@
+import { type ExtensionAPI, type ExtensionFactory, type SettingsManager } from "@earendil-works/pi-coding-agent";
+import { deriveThresholds } from "./context/thresholds.js";
+import { mergePiContextSettings } from "./settings.js";
+import { assertVirtualPath } from "./notes/address.js";
+export { historyFromSession } from "./history/history.js";
+export { notesFromSession } from "./pi/notes/session-replay.js";
+/**
+ * Create an extension factory bound to an SDK settings authority. The host must pass
+ * the same manager to createAgentSession and to this factory's resource loader.
+ */
+export declare function createPiContext(options?: {
+    settingsManager?: SettingsManager;
+}): ExtensionFactory;
+/** The Pi-discovered extension keeps the standard file-backed settings behavior. */
+export default function piContext(pi: ExtensionAPI): void;
+export declare const internal: {
+    MAX_NOTE_BYTES: number;
+    NOTE_TYPE: string;
+    BOOT_TYPE: string;
+    GUIDANCE_TYPE: string;
+    WARNING_TYPE: string;
+    CONTINUATION_TYPE: string;
+    WARNING_PROMPT: string;
+    WARNING_CONTENT: string;
+    WARNING_RUNWAY_TOKENS: number;
+    RESET_MARKER_TYPE: string;
+    CONTINUATION: string;
+    CONTEXT_WINDOW_OPEN_TAG: string;
+    CONTEXT_WINDOW_CLOSE_TAG: string;
+    CONTEXT_WINDOW_PROTOCOL_OPEN_TAG: string;
+    CONTEXT_WINDOW_PROTOCOL_CLOSE_TAG: string;
+    GUIDANCE_OPEN_TAG: string;
+    PI_CONTEXT_SETTINGS_KEY: string;
+    DEFAULT_RESERVE_TOKENS: number;
+    DEFAULT_REMINDER_MARGIN_TOKENS: number;
+    deriveThresholds: typeof deriveThresholds;
+    mergePiContextSettings: typeof mergePiContextSettings;
+    assertVirtualPath: typeof assertVirtualPath;
+};

package/dist/src/index.js

@@ -1,13 +1,13 @@
 import { VERSION } from "@earendil-works/pi-coding-agent";
 import { registerHistoryTools } from "./history/history-tools.js";
-import { registerNotesTools } from "./notes/tools.js";
+import { registerNotesTools } from "./pi/notes/tools.js";
 import { deriveThresholds } from "./context/thresholds.js";
 import { registerContext } from "./context/runtime.js";
 import { mergePiContextSettings } from "./settings.js";
-import { NOTE_TYPE, BOOT_TYPE, GUIDANCE_TYPE, WARNING_TYPE, RESET_MARKER_TYPE, CONTINUATION_TYPE, MAX_NOTE_BYTES, CONTEXT_WINDOW_OPEN_TAG, CONTEXT_WINDOW_CLOSE_TAG, CONTEXT_WINDOW_PROTOCOL_OPEN_TAG, CONTEXT_WINDOW_PROTOCOL_CLOSE_TAG, GUIDANCE_OPEN_TAG, PI_CONTEXT_SETTINGS_KEY, DEFAULT_RESERVE_TOKENS, DEFAULT_REMINDER_MARGIN_TOKENS, WARNING_RUNWAY_TOKENS, CONTINUATION, WARNING_PROMPT } from "./protocol.js";
+import { NOTE_TYPE, BOOT_TYPE, GUIDANCE_TYPE, WARNING_TYPE, RESET_MARKER_TYPE, CONTINUATION_TYPE, MAX_NOTE_BYTES, CONTEXT_WINDOW_OPEN_TAG, CONTEXT_WINDOW_CLOSE_TAG, CONTEXT_WINDOW_PROTOCOL_OPEN_TAG, CONTEXT_WINDOW_PROTOCOL_CLOSE_TAG, GUIDANCE_OPEN_TAG, PI_CONTEXT_SETTINGS_KEY, DEFAULT_RESERVE_TOKENS, DEFAULT_REMINDER_MARGIN_TOKENS, WARNING_RUNWAY_TOKENS, CONTINUATION, WARNING_PROMPT, WARNING_CONTENT } from "./protocol.js";
 import { assertVirtualPath } from "./notes/address.js";
 export { historyFromSession } from "./history/history.js";
-export { notesFromSession } from "./notes/session-replay.js";
+export { notesFromSession } from "./pi/notes/session-replay.js";
 function registerPiContext(pi, settingsManager) {
     const [major, minor] = VERSION.split(".").map(Number);
     if (!(major > 0 || (major === 0 && minor >= 87))) {
@@ -28,4 +28,4 @@ export function createPiContext(options = {}) {
 export default function piContext(pi) {
     registerPiContext(pi);
 }
-export const internal = { MAX_NOTE_BYTES, NOTE_TYPE, BOOT_TYPE, GUIDANCE_TYPE, WARNING_TYPE, CONTINUATION_TYPE, WARNING_PROMPT, WARNING_RUNWAY_TOKENS, RESET_MARKER_TYPE, CONTINUATION, CONTEXT_WINDOW_OPEN_TAG, CONTEXT_WINDOW_CLOSE_TAG, CONTEXT_WINDOW_PROTOCOL_OPEN_TAG, CONTEXT_WINDOW_PROTOCOL_CLOSE_TAG, GUIDANCE_OPEN_TAG, PI_CONTEXT_SETTINGS_KEY, DEFAULT_RESERVE_TOKENS, DEFAULT_REMINDER_MARGIN_TOKENS, deriveThresholds, mergePiContextSettings, assertVirtualPath };
+export const internal = { MAX_NOTE_BYTES, NOTE_TYPE, BOOT_TYPE, GUIDANCE_TYPE, WARNING_TYPE, CONTINUATION_TYPE, WARNING_PROMPT, WARNING_CONTENT, WARNING_RUNWAY_TOKENS, RESET_MARKER_TYPE, CONTINUATION, CONTEXT_WINDOW_OPEN_TAG, CONTEXT_WINDOW_CLOSE_TAG, CONTEXT_WINDOW_PROTOCOL_OPEN_TAG, CONTEXT_WINDOW_PROTOCOL_CLOSE_TAG, GUIDANCE_OPEN_TAG, PI_CONTEXT_SETTINGS_KEY, DEFAULT_RESERVE_TOKENS, DEFAULT_REMINDER_MARGIN_TOKENS, deriveThresholds, mergePiContextSettings, assertVirtualPath };

package/dist/src/notes/address.d.ts

@@ -0,0 +1,26 @@
+import type { NotesContext } from "./context.js";
+import { type Scope } from "./paths.js";
+export type NoteAddress = {
+    scope: Scope;
+    path: string;
+    who?: string;
+};
+export declare const ADDRESS_FORMS = "legal prefixes are @project/, @human/, @self/, and @model/; bare names are this session";
+export declare function assertVirtualPath(value: unknown): string;
+/**
+ * Minimal glob over virtual note paths: `*` matches any run within a segment (never
+ * `/`), `**` matches any run across segments (a leading double-star followed by a
+ * slash also matches zero segments, so it covers the root too), `?` matches exactly
+ * one non-`/` character. Everything else is literal and the match is anchored to the
+ * whole path.
+ */
+export declare function globToRegExp(pattern: string): RegExp;
+/** Glob patterns are not virtual paths (`*` is legal), so they get their own guard. */
+export declare function assertGlobPattern(value: unknown): string | undefined;
+/**
+ * Decode one public note address into its physical home and virtual path. @self and @model
+ * are relative; explicit agents/models addresses always name a canonical slug.
+ */
+export declare function assertAddress(value: unknown): NoteAddress;
+/** Render a virtual path in its one unambiguous public address form. */
+export declare function addressFor(context: NotesContext, scope: Scope, path: string, who?: string): string;

package/dist/src/notes/address.js

@@ -1,4 +1,4 @@
-import { agentSlug, modelSlug, SLUG_PATTERN } from "./paths.js";
+import { SLUG_PATTERN } from "./paths.js";
 export const ADDRESS_FORMS = "legal prefixes are @project/, @human/, @self/, and @model/; bare names are this session";
 export function assertVirtualPath(value) {
     if (typeof value !== "string" || value.length === 0)
@@ -37,7 +37,7 @@ export function globToRegExp(pattern) {
     }
     return new RegExp(`${source}$`);
 }
-/** Glob patterns are not virtual paths (`*` is legal), so they get their own guard: no NUL, no backslashes. */
+/** Glob patterns are not virtual paths (`*` is legal), so they get their own guard. */
 export function assertGlobPattern(value) {
     if (value === undefined || value === null || value === "")
         return undefined;
@@ -48,12 +48,8 @@ export function assertGlobPattern(value) {
     return value;
 }
 /**
- * Decode the one public note address into its physical home and virtual path. This is a
- * tool-boundary rule: replay paths keep using assertVirtualPath directly and are untouched.
- * The word after `@` is always a reserved home name; agent and model names live at the
- * second level (@agents/faye/, never @faye/), so user-chosen names can never collide with
- * the reserved set. `@self` and `@model` are relative — `who` stays undefined and the
- * store resolves the current agent/model at call time.
+ * Decode one public note address into its physical home and virtual path. @self and @model
+ * are relative; explicit agents/models addresses always name a canonical slug.
  */
 export function assertAddress(value) {
     if (typeof value !== "string")
@@ -96,10 +92,8 @@ export function assertAddress(value) {
     assertVirtualPath(path);
     return { scope, path, who };
 }
-/** Render a virtual path in its one unambiguous public address form. Relative forms
- * (@self/, @model/) never render: the canonical address always carries the resolved
- * name, so listings alone tell every home apart. */
-export function addressFor(ctx, scope, path, who) {
+/** Render a virtual path in its one unambiguous public address form. */
+export function addressFor(context, scope, path, who) {
     if (scope === "session")
         return path;
     if (scope === "project")
@@ -107,6 +101,6 @@ export function addressFor(ctx, scope, path, who) {
     if (scope === "human")
         return `@human/${path}`;
     if (scope === "agent")
-        return `@agents/${who ?? agentSlug(ctx)}/${path}`;
-    return `@models/${who ?? modelSlug(ctx)}/${path}`;
+        return `@agents/${who ?? context.agent}/${path}`;
+    return `@models/${who ?? context.model}/${path}`;
 }

package/dist/src/notes/constants.d.ts

@@ -0,0 +1,3 @@
+export declare const MAX_NOTE_BYTES = 1000000;
+/** Write-time cap on a virtual note path. Reads and legacy replay stay uncapped. */
+export declare const MAX_NOTE_PATH_BYTES = 512;

package/dist/src/notes/constants.js

@@ -0,0 +1,3 @@
+export const MAX_NOTE_BYTES = 1_000_000;
+/** Write-time cap on a virtual note path. Reads and legacy replay stay uncapped. */
+export const MAX_NOTE_PATH_BYTES = 512;

package/dist/src/notes/context.d.ts

@@ -0,0 +1,10 @@
+/** Explicit, host-neutral identity for one notes store. */
+export type NotesContext = Readonly<{
+    home: string;
+    sessionId: string;
+    projectKey: string;
+    agent: string;
+    model: string;
+}>;
+/** Validate and snapshot caller identity; no global or environment defaults are consulted. */
+export declare function snapshotNotesContext(value: NotesContext): NotesContext;

package/dist/src/notes/context.js

@@ -0,0 +1,33 @@
+import { resolve } from "node:path";
+import { SLUG_PATTERN } from "./paths.js";
+function requireString(field, value) {
+    if (typeof value !== "string" || value.length === 0)
+        throw new TypeError(`notes context ${field} must be a non-empty string`);
+    return value;
+}
+function assertDirectoryComponent(field, value) {
+    if (value === "." || value === ".." || /[\\/\0:]/.test(value)) {
+        throw new TypeError(`notes context ${field} must be a safe single directory component`);
+    }
+}
+/** Validate and snapshot caller identity; no global or environment defaults are consulted. */
+export function snapshotNotesContext(value) {
+    if (typeof value !== "object" || value === null || Array.isArray(value))
+        throw new TypeError("notes context must be a plain object");
+    const prototype = Object.getPrototypeOf(value);
+    if (prototype !== Object.prototype && prototype !== null)
+        throw new TypeError("notes context must be a plain object");
+    const homeValue = requireString("home", value.home);
+    const sessionId = requireString("sessionId", value.sessionId);
+    const projectKey = requireString("projectKey", value.projectKey);
+    const agent = requireString("agent", value.agent);
+    const model = requireString("model", value.model);
+    assertDirectoryComponent("sessionId", sessionId);
+    assertDirectoryComponent("projectKey", projectKey);
+    if (!SLUG_PATTERN.test(agent))
+        throw new TypeError("notes context agent must be a canonical lowercase slug");
+    if (!SLUG_PATTERN.test(model))
+        throw new TypeError("notes context model must be a canonical lowercase slug");
+    const home = resolve(homeValue);
+    return Object.freeze({ home, sessionId, projectKey, agent, model });
+}

package/dist/src/notes/frontmatter.d.ts

@@ -0,0 +1,46 @@
+import type { Scope } from "./paths.js";
+export type NoteStatus = "active" | "superseded" | "pending" | "archived";
+export type Origin = "user" | "self" | "external";
+/**
+ * Harness-owned note metadata. The eight required keys are always written; the four optional
+ * sleep-shift keys survive this layer untouched when present. `[key: string]: unknown` carries
+ * any frontmatter key this layer does not know, preserved verbatim across rewrites.
+ */
+export type NoteMeta = {
+    scope: Scope;
+    origin: Origin;
+    status: NoteStatus;
+    stale: boolean;
+    createdAt: number;
+    updatedAt: number;
+    lastAccessed: number;
+    accessCount: number;
+    sourceWindow?: string;
+    supersedes?: string;
+    recurrenceCount?: number;
+    recurrenceWindows?: string[];
+    /** Project ownership on newly-created session notes; legacy/invalid values are preserved as-is. */
+    project?: unknown;
+    [key: string]: unknown;
+};
+/**
+ * Format epoch milliseconds as an ISO 8601 string in the host's local time zone with an
+ * explicit numeric offset (e.g. 2026-09-15T17:31:45.392+08:00). A UTC host renders
+ * "+00:00"; the "Z" designator is never used, and Date.parse round-trips the value.
+ */
+export declare function localIso(epochMs: number): string;
+export declare function isScope(value: unknown): value is Scope;
+export declare function isOrigin(value: unknown): value is Origin;
+/**
+ * Parse a note file. Missing known keys take the Design defaults (status active, stale false,
+ * accessCount 0, timestamps now); unknown keys are carried through untouched. Known
+ * snake_case metadata is refused because it requires the explicit manual migration.
+ */
+export declare function parseNote(raw: string, now?: number): {
+    meta: NoteMeta;
+    body: string;
+};
+/** Serialize frontmatter + blank line + body. Known keys emit in Design order, extras after. */
+export declare function serializeNote(meta: NoteMeta, body: string): string;
+/** Strip a leading frontmatter block from user content, so a note body is pure content. */
+export declare function stripLeadingFrontmatter(content: string): string;

package/dist/src/notes/frontmatter.js

@@ -1,9 +1,10 @@
 const SCOPES = ["session", "project", "human", "agent", "model"];
 const ORIGINS = ["user", "self", "external"];
 const STATUSES = ["active", "superseded", "pending", "archived"];
-const TIMESTAMP_KEYS = ["created_at", "updated_at", "last_accessed"];
+const TIMESTAMP_KEYS = ["createdAt", "updatedAt", "lastAccessed"];
+const LEGACY_KNOWN_KEYS = ["created_at", "updated_at", "last_accessed", "access_count", "source_window", "recurrence_count", "recurrence_windows"];
 /** Emission order, exactly the Design's key list. */
-const KNOWN_KEYS = ["origin", "status", "stale", "created_at", "updated_at", "last_accessed", "access_count", "source_window", "supersedes", "recurrence_count", "recurrence_windows"];
+const KNOWN_KEYS = ["origin", "status", "stale", "createdAt", "updatedAt", "lastAccessed", "accessCount", "sourceWindow", "supersedes", "recurrenceCount", "recurrenceWindows"];
 const pad2 = (value) => String(value).padStart(2, "0");
 /**
  * Format epoch milliseconds as an ISO 8601 string in the host's local time zone with an
@@ -69,7 +70,7 @@ function parseFrontmatter(raw) {
     }
     if (close === -1)
         return { fields: {}, body: raw };
-    const fields = {};
+    const fields = Object.create(null);
     for (let index = 1; index < close; index++) {
         const line = lines[index];
         const match = /^([A-Za-z_][A-Za-z0-9_-]*):(.*)$/.exec(line);
@@ -97,10 +98,14 @@ function parseFrontmatter(raw) {
 }
 /**
  * Parse a note file. Missing known keys take the Design defaults (status active, stale false,
- * access_count 0, timestamps now); unknown keys are carried through untouched.
+ * accessCount 0, timestamps now); unknown keys are carried through untouched. Known
+ * snake_case metadata is refused because it requires the explicit manual migration.
  */
 export function parseNote(raw, now = Date.now()) {
     const { fields, body } = parseFrontmatter(raw);
+    const legacyKeys = LEGACY_KNOWN_KEYS.filter((key) => Object.hasOwn(fields, key));
+    if (legacyKeys.length > 0)
+        throw new Error(`legacy note metadata ${legacyKeys.join(", ")} requires manual migration to camelCase before this note can be used`);
     const meta = { ...fields };
     // scope is a legacy on-disk field: store callers derive it from the file's home and
     // overwrite it after parsing, so an absent or outdated value just falls back.
@@ -110,7 +115,7 @@ export function parseNote(raw, now = Date.now()) {
     meta.stale = meta.stale === true;
     for (const key of TIMESTAMP_KEYS)
         meta[key] = toEpoch(meta[key], now);
-    meta.access_count = typeof meta.access_count === "number" && Number.isFinite(meta.access_count) ? meta.access_count : 0;
+    meta.accessCount = typeof meta.accessCount === "number" && Number.isFinite(meta.accessCount) ? meta.accessCount : 0;
     return { meta: meta, body };
 }
 /** Emit a YAML scalar: bare for safe strings and JSON literals, JSON-quoted otherwise. */

package/dist/src/notes/index.d.ts

@@ -0,0 +1,4 @@
+export { createNotesStore, NoteError } from "./store.js";
+export { projectKey, slugify } from "./paths.js";
+export type { NotesContext } from "./context.js";
+export type { EditOperation, EditOptions, NoteChange, NoteEditResult, NoteErrorCode, NoteMatch, NoteMeta, NoteReadResult, NoteRow, NoteSearchRow, NoteStatus, NoteWriteResult, NotesQuery, NotesStore, Origin, Scope, WriteOptions, } from "./store.js";

package/dist/src/notes/index.js

@@ -0,0 +1,2 @@
+export { createNotesStore, NoteError } from "./store.js";
+export { projectKey, slugify } from "./paths.js";

package/dist/src/notes/paths.d.ts

@@ -0,0 +1,21 @@
+import type { NotesContext } from "./context.js";
+export type Scope = "session" | "project" | "human" | "agent" | "model";
+/** The one legal home-name shape: lowercase [a-z0-9-] runs separated by single dashes. */
+export declare const SLUG_PATTERN: RegExp;
+/** Slugify a caller-declared identity; identity is never inferred from note content. */
+export declare function slugify(value: string): string;
+/** `<basename(absGitRoot)-sha1(absGitRoot)[:8]>`, or the same formula over cwd with no git root. */
+export declare function projectKey(cwd: string): string;
+/** Absolute directory holding the per-session note homes. */
+export declare function sessionHomesRoot(home: string): string;
+/** Absolute directory holding one scope's notes. The context's home is already resolved. */
+export declare function scopeDir(scope: Scope, context: NotesContext, who?: string): string;
+/** Every existing home directory of the agents/ or models/ namespace, as names. */
+export declare function namespaceSlugs(namespace: "agents" | "models", home: string): Promise<string[]>;
+/**
+ * Notes are markdown files: a virtual path without an `.md` suffix gains one, an explicit
+ * `.md` is kept as-is, so `a/b` and `a/b.md` name the same physical file.
+ */
+export declare function noteFileName(vpath: string): string;
+/** Absolute file path for a virtual path in a scope. Callers validate the vpath first. */
+export declare function physicalPath(scope: Scope, vpath: string, context: NotesContext, who?: string): string;

package/dist/src/notes/paths.js

@@ -1,99 +1,91 @@
 import { createHash } from "node:crypto";
-import { existsSync, readdirSync, renameSync } from "node:fs";
-import { homedir } from "node:os";
-import { basename, dirname, join, resolve } from "node:path";
-/** Physical home of the on-disk note store: $PI_NOTES_HOME or ~/.agents/notes. */
-export function notesRoot() {
-    const override = process.env.PI_NOTES_HOME;
-    return override && override.length > 0 ? resolve(override) : join(homedir(), ".agents", "notes");
+import { existsSync, readFileSync, statSync } from "node:fs";
+import { readdir } from "node:fs/promises";
+import { basename, dirname, join, resolve, sep } from "node:path";
+/** The one legal home-name shape: lowercase [a-z0-9-] runs separated by single dashes. */
+export const SLUG_PATTERN = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+/** Slugify a caller-declared identity; identity is never inferred from note content. */
+export function slugify(value) {
+    const slug = value.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
+    return slug.length > 0 ? slug : "root";
 }
-/** Absolute directory holding the per-session note homes. */
-export function sessionHomesRoot(home = notesRoot()) {
-    return join(home, "pi", "session");
+/** `<basename(absGitRoot)-sha1(absGitRoot)[:8]>`, or the same formula over cwd with no git root. */
+export function projectKey(cwd) {
+    const absolute = resolve(cwd);
+    const root = gitRoot(absolute) ?? absolute;
+    const digest = createHash("sha1").update(root).digest("hex").slice(0, 8);
+    return `${basename(root)}-${digest}`;
 }
 /**
- * Absolute git root for `cwd`, walking upward until a directory holds a `.git` entry.
- * No git root yields undefined, which projectKey then replaces with the cwd itself.
+ * Repository root behind one `.git` entry. A `.git` directory is the main checkout
+ * itself. A `.git` file is a worktree or submodule pointer: a linked worktree names
+ * `<main>/.git/worktrees/<name>` and resolves to `<main>`, so every worktree of one
+ * repository shares one project identity. Submodules, bare repositories, and separate
+ * git dirs keep the current directory.
  */
+function repositoryRoot(dir) {
+    let stats;
+    try {
+        stats = statSync(join(dir, ".git"));
+    }
+    catch {
+        return dir;
+    }
+    if (stats.isDirectory())
+        return dir;
+    let pointer;
+    try {
+        pointer = readFileSync(join(dir, ".git"), "utf8");
+    }
+    catch {
+        return dir;
+    }
+    const match = /^gitdir:\s*(.+)$/m.exec(pointer);
+    if (!match)
+        return dir;
+    const parts = resolve(dir, match[1].trim()).split(sep);
+    const worktrees = parts.lastIndexOf("worktrees");
+    if (worktrees <= 0 || worktrees !== parts.length - 2)
+        return dir;
+    const common = parts.slice(0, worktrees).join(sep);
+    return basename(common) === ".git" ? dirname(common) : dir;
+}
+/** Absolute repository root for cwd, walking upward until a directory holds a `.git` entry. */
 function gitRoot(cwd) {
     let dir = resolve(cwd);
     for (;;) {
         if (existsSync(join(dir, ".git")))
-            return dir;
+            return repositoryRoot(dir);
         const parent = dirname(dir);
         if (parent === dir)
             return undefined;
         dir = parent;
     }
 }
-/** `<basename(absGitRoot)-sha1(absGitRoot)[:8]>`, or the same formula over cwd with no git root. */
-export function projectKey(cwd) {
-    const absolute = resolve(cwd);
-    const root = gitRoot(absolute) ?? absolute;
-    const digest = createHash("sha1").update(root).digest("hex").slice(0, 8);
-    return `${basename(root)}-${digest}`;
-}
-/** Session identity comes from the pi session manager; ids are filesystem-safe by construction. */
-function sessionId(ctx) {
-    return ctx.sessionManager.getSessionId();
-}
-/** The one legal home-name shape: lowercase [a-z0-9-] runs separated by single dashes. */
-export const SLUG_PATTERN = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
-/**
- * Identity slugs: one declared name per home, never detected from prompt content.
- * `PI_NOTES_AGENT` declares who is running (default "root"); the model slug derives
- * from the live model id, provider prefix stripped. Both slugified to [a-z0-9-].
- */
-export function slugify(value) {
-    const slug = value.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
-    return slug.length > 0 ? slug : "root";
-}
-/** The current agent's home name: the launch-declared identity, defaulting to "root". */
-export function agentSlug(_ctx) {
-    return slugify(process.env.PI_NOTES_AGENT ?? "root");
-}
-/** The current model's home name, live-resolved from ctx.model; "default" when unknown. */
-export function modelSlug(ctx) {
-    const id = ctx.model?.id;
-    if (!id)
-        return "default";
-    return slugify(id.split("/").pop() ?? id);
+/** Absolute directory holding the per-session note homes. */
+export function sessionHomesRoot(home) {
+    return join(home, "pi", "session");
 }
-/**
- * Absolute directory holding every note of one scope. `who` names an agent or model
- * home absolutely; omitted, the current one resolves (agent from PI_NOTES_AGENT,
- * model live from ctx.model).
- */
-export function scopeDir(scope, ctx, who) {
+/** Absolute directory holding one scope's notes. The context's home is already resolved. */
+export function scopeDir(scope, context, who) {
+    if (!["session", "project", "human", "agent", "model"].includes(scope))
+        throw new TypeError("invalid notes scope");
+    if (who !== undefined && (scope !== "agent" && scope !== "model" || !SLUG_PATTERN.test(who)))
+        throw new TypeError("who must be a canonical agent/model slug");
     if (scope === "human")
-        return join(notesRoot(), "human");
+        return join(context.home, "human");
     if (scope === "project")
-        return join(notesRoot(), "project", projectKey(ctx.cwd));
+        return join(context.home, "project", context.projectKey);
     if (scope === "agent")
-        return join(notesRoot(), "agents", who ?? agentSlug(ctx));
+        return join(context.home, "agents", who ?? context.agent);
     if (scope === "model")
-        return join(notesRoot(), "models", who ?? modelSlug(ctx));
-    return join(sessionHomesRoot(), sessionId(ctx));
-}
-/**
- * One-time migration of the pre-v0.25 `personal/` home to `human/`. Runs at extension
- * activation; returns a warning string when both directories exist (no auto-merge),
- * undefined otherwise. Old note bodies are history, not addresses, and stay untouched.
- */
-export function migrateLegacyHomes(home = notesRoot()) {
-    const legacy = join(home, "personal");
-    const modern = join(home, "human");
-    if (!existsSync(legacy))
-        return undefined;
-    if (existsSync(modern))
-        return "both personal/ and human/ exist under the notes home; migrate by hand, no automatic merge";
-    renameSync(legacy, modern);
-    return undefined;
+        return join(context.home, "models", who ?? context.model);
+    return join(sessionHomesRoot(context.home), context.sessionId);
 }
-/** Every existing home directory of the agents/ or models/ namespace, as slugs. */
-export function namespaceSlugs(namespace, home = notesRoot()) {
+/** Every existing home directory of the agents/ or models/ namespace, as names. */
+export async function namespaceSlugs(namespace, home) {
     try {
-        return readdirSync(join(home, namespace), { withFileTypes: true })
+        return (await readdir(join(home, namespace), { withFileTypes: true }))
             .filter((entry) => entry.isDirectory())
             .map((entry) => entry.name)
             .sort();
@@ -110,6 +102,10 @@ export function noteFileName(vpath) {
     return vpath.endsWith(".md") ? vpath : `${vpath}.md`;
 }
 /** Absolute file path for a virtual path in a scope. Callers validate the vpath first. */
-export function physicalPath(scope, vpath, ctx, who) {
-    return join(scopeDir(scope, ctx, who), ...noteFileName(vpath).split("/"));
+export function physicalPath(scope, vpath, context, who) {
+    if (typeof vpath !== "string" || vpath.length === 0 || vpath.includes("\0") || vpath.includes("\\") || vpath.startsWith("/"))
+        throw new TypeError("path must be a safe virtual relative path");
+    if (vpath.split("/").some((part) => part.length === 0 || part === "." || part === ".."))
+        throw new TypeError("path contains an unsupported component");
+    return join(scopeDir(scope, context, who), ...noteFileName(vpath).split("/"));
 }