@caupulican/pi-adaptative 0.81.38 → 0.81.40

package/dist/core/worktree-sync/store.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Worktree-sync on-disk store: coordination state shared by EVERY process working on one repo.
+ *
+ * Lives under `<git-common-dir>/pi-worktree-sync/` -- all worktrees of a repository share the git
+ * common dir, so the store is repo-scoped and cross-process by construction, survives `/reload`
+ * and crashes, is invisible to `git status`, and needs no gitignore entry.
+ *
+ * The store is an INDEX, not the truth: freshness/dirtiness/progress are always re-derived from
+ * git by the engine (`git-engine.ts`). A deleted or corrupt store is rebuildable via reconcile --
+ * every reader here treats missing/corrupt files as "absent", never as an error.
+ *
+ * Writes are tmp+rename atomic (`util/atomic-file.ts`); the audit log uses the shared bounded JSONL
+ * sink, which serializes concurrent writers and atomically rotates to its newest low-water tail.
+ * The integration lock is a mkdir-atomic directory with an owner manifest: mkdir either succeeds
+ * (lock acquired) or fails EEXIST (held), with takeover ONLY for a provably-dead same-host owner.
+ */
+import type { IntegrationLockAcquisition, IntegrationLockOwner, LandingTransaction, LaneRegistration, WorktreeSyncEpoch } from "./codes.ts";
+export interface SyncStorePaths {
+    root: string;
+    epochFile: string;
+    landingTransactionFile: string;
+    lanesDir: string;
+    lockDir: string;
+    lockOwnerFile: string;
+    lockGuardFile: string;
+    lifecycleLockFile: string;
+    eventsFile: string;
+}
+/** Grace window after which an ownerless lock dir (crash between mkdir and owner write) counts as
+ * dead and may be taken over. Fresh ownerless dirs are conservatively treated as held. */
+export declare const OWNERLESS_LOCK_STALE_MS = 30000;
+export declare function syncStorePaths(gitCommonDir: string): SyncStorePaths;
+/**
+ * Stable per-repo slug for the lane-worktree checkout root: sanitized repo basename plus 8 hex of
+ * sha256 over the REALPATH of the git common dir -- same-named repos in different places cannot
+ * collide, and every worktree of one repo resolves the same slug.
+ */
+export declare function repoSlug(repoTopLevel: string, gitCommonDir: string): string;
+export declare function readEpoch(paths: SyncStorePaths): Promise<WorktreeSyncEpoch | undefined>;
+export declare function writeEpoch(paths: SyncStorePaths, epoch: WorktreeSyncEpoch): Promise<void>;
+export declare function readLandingTransaction(paths: SyncStorePaths): Promise<LandingTransaction | undefined>;
+export declare function writeLandingTransaction(paths: SyncStorePaths, transaction: LandingTransaction): Promise<void>;
+export declare function clearLandingTransaction(paths: SyncStorePaths): Promise<void>;
+export declare function readLane(paths: SyncStorePaths, laneKey: string): Promise<LaneRegistration | undefined>;
+export declare function writeLane(paths: SyncStorePaths, lane: LaneRegistration): Promise<void>;
+export declare function listLanes(paths: SyncStorePaths): Promise<LaneRegistration[]>;
+/** Append one audit event as a single JSON line. `at` is stamped here so every event carries it. */
+export declare function appendAuditEvent(paths: SyncStorePaths, event: {
+    event: string;
+} & Record<string, unknown>, at: string): Promise<void>;
+export interface IntegrationLockDeps {
+    /** Injectable liveness probe (deterministic tests). Default: same-host `process.kill(pid, 0)`. */
+    isPidAlive?: (owner: IntegrationLockOwner) => boolean;
+    now?: () => string;
+    nowMs?: () => number;
+}
+/** Same-host pid liveness. A foreign-host owner is ALWAYS treated as alive -- never taken over. */
+export declare function defaultIsPidAlive(owner: IntegrationLockOwner): boolean;
+/**
+ * Acquire the single integration lock (G1: landing is serialized). Non-blocking: a held lock
+ * returns `{acquired:false, holder, holderAlive}` immediately -- callers surface `lock_busy` and
+ * retry on their own cadence rather than spinning here. Takeover happens ONLY when the recorded
+ * owner is provably dead on this host (or the lock dir is ownerless and older than
+ * {@link OWNERLESS_LOCK_STALE_MS}); every takeover is audited.
+ */
+export declare function acquireIntegrationLock(paths: SyncStorePaths, owner: Omit<IntegrationLockOwner, "acquiredAt" | "token">, deps?: IntegrationLockDeps): Promise<IntegrationLockAcquisition>;
+export declare function releaseIntegrationLock(paths: SyncStorePaths, token: string, deps?: IntegrationLockDeps): Promise<boolean>;
+export declare function readLockHolder(paths: SyncStorePaths): Promise<IntegrationLockOwner | undefined>;
+//# sourceMappingURL=store.d.ts.map

package/dist/core/worktree-sync/store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"store.d.ts","sourceRoot":"","sources":["../../../src/core/worktree-sync/store.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Worktree-sync on-disk store: coordination state shared by EVERY process working on one repo.\n *\n * Lives under `<git-common-dir>/pi-worktree-sync/` -- all worktrees of a repository share the git\n * common dir, so the store is repo-scoped and cross-process by construction, survives `/reload`\n * and crashes, is invisible to `git status`, and needs no gitignore entry.\n *\n * The store is an INDEX, not the truth: freshness/dirtiness/progress are always re-derived from\n * git by the engine (`git-engine.ts`). A deleted or corrupt store is rebuildable via reconcile --\n * every reader here treats missing/corrupt files as \"absent\", never as an error.\n *\n * Writes are tmp+rename atomic (`util/atomic-file.ts`); the audit log uses the shared bounded JSONL\n * sink, which serializes concurrent writers and atomically rotates to its newest low-water tail.\n * The integration lock is a mkdir-atomic directory with an owner manifest: mkdir either succeeds\n * (lock acquired) or fails EEXIST (held), with takeover ONLY for a provably-dead same-host owner.\n */\n\nimport { createHash, randomUUID } from \"node:crypto\";\nimport { promises as fsPromises, realpathSync } from \"node:fs\";\nimport { hostname as osHostname } from \"node:os\";\nimport { basename, dirname, join } from \"node:path\";\nimport { withFileLock, writeFileAtomic } from \"../util/atomic-file.ts\";\nimport { appendBoundedJsonLine, type BoundedJsonlLimits } from \"../util/bounded-jsonl.ts\";\nimport type {\n\tIntegrationLockAcquisition,\n\tIntegrationLockOwner,\n\tLandingTransaction,\n\tLaneRegistration,\n\tWorktreeSyncEpoch,\n} from \"./codes.ts\";\n\nexport interface SyncStorePaths {\n\troot: string;\n\tepochFile: string;\n\tlandingTransactionFile: string;\n\tlanesDir: string;\n\tlockDir: string;\n\tlockOwnerFile: string;\n\tlockGuardFile: string;\n\tlifecycleLockFile: string;\n\teventsFile: string;\n}\n\n/** Grace window after which an ownerless lock dir (crash between mkdir and owner write) counts as\n * dead and may be taken over. Fresh ownerless dirs are conservatively treated as held. */\nexport const OWNERLESS_LOCK_STALE_MS = 30_000;\n\nconst STORE_DIR_NAME = \"pi-worktree-sync\";\nconst WORKTREE_AUDIT_EVENT_LIMITS: BoundedJsonlLimits = {\n\tmaxBytes: 4 * 1024 * 1024,\n\ttargetBytes: Math.floor(4 * 1024 * 1024 * 0.75),\n\tmaxRecords: 10_000,\n};\n\nexport function syncStorePaths(gitCommonDir: string): SyncStorePaths {\n\tconst root = join(gitCommonDir, STORE_DIR_NAME);\n\treturn {\n\t\troot,\n\t\tepochFile: join(root, \"epoch.json\"),\n\t\tlandingTransactionFile: join(root, \"landing-transaction.json\"),\n\t\tlanesDir: join(root, \"lanes\"),\n\t\tlockDir: join(root, \"locks\", \"integration\"),\n\t\tlockOwnerFile: join(root, \"locks\", \"integration\", \"owner.json\"),\n\t\tlockGuardFile: join(root, \"locks\", \"integration-metadata\"),\n\t\tlifecycleLockFile: join(root, \"locks\", \"lifecycle\"),\n\t\teventsFile: join(root, \"events.jsonl\"),\n\t};\n}\n\n/**\n * Stable per-repo slug for the lane-worktree checkout root: sanitized repo basename plus 8 hex of\n * sha256 over the REALPATH of the git common dir -- same-named repos in different places cannot\n * collide, and every worktree of one repo resolves the same slug.\n */\nexport function repoSlug(repoTopLevel: string, gitCommonDir: string): string {\n\tlet canonical = gitCommonDir;\n\ttry {\n\t\tcanonical = realpathSync(gitCommonDir);\n\t} catch {\n\t\t// Unresolvable (already-deleted repo during teardown): hash the raw path deterministically.\n\t}\n\tconst hash = createHash(\"sha256\").update(canonical).digest(\"hex\").slice(0, 8);\n\tconst base = basename(repoTopLevel)\n\t\t.toLowerCase()\n\t\t.replace(/[^a-z0-9-]+/g, \"-\")\n\t\t.replace(/^-+|-+$/g, \"\")\n\t\t.slice(0, 48);\n\treturn `${base || \"repo\"}-${hash}`;\n}\n\nasync function readJsonFile<T>(filePath: string): Promise<T | undefined> {\n\tlet raw: string;\n\ttry {\n\t\traw = await fsPromises.readFile(filePath, \"utf-8\");\n\t} catch {\n\t\treturn undefined;\n\t}\n\ttry {\n\t\treturn JSON.parse(raw) as T;\n\t} catch {\n\t\t// Corrupt store files are treated as absent -- git remains the truth and reconcile rebuilds.\n\t\treturn undefined;\n\t}\n}\n\nexport async function readEpoch(paths: SyncStorePaths): Promise<WorktreeSyncEpoch | undefined> {\n\treturn readJsonFile<WorktreeSyncEpoch>(paths.epochFile);\n}\n\nexport async function writeEpoch(paths: SyncStorePaths, epoch: WorktreeSyncEpoch): Promise<void> {\n\tawait writeFileAtomic(paths.epochFile, `${JSON.stringify(epoch, null, \"\\t\")}\\n`);\n}\n\nexport async function readLandingTransaction(paths: SyncStorePaths): Promise<LandingTransaction | undefined> {\n\tconst value = await readJsonFile<unknown>(paths.landingTransactionFile);\n\tif (typeof value !== \"object\" || value === null || Array.isArray(value)) return undefined;\n\tconst record = value as Record<string, unknown>;\n\tif (\n\t\ttypeof record.laneKey !== \"string\" ||\n\t\ttypeof record.priorMainSha !== \"string\" ||\n\t\ttypeof record.testedTipSha !== \"string\" ||\n\t\t!Array.isArray(record.changedPaths) ||\n\t\t!record.changedPaths.every((path) => typeof path === \"string\") ||\n\t\ttypeof record.changedPathsTruncated !== \"boolean\" ||\n\t\ttypeof record.lockToken !== \"string\" ||\n\t\t(record.gate !== \"passed\" && record.gate !== \"off\") ||\n\t\t(record.stage !== \"ready_to_merge\" &&\n\t\t\trecord.stage !== \"main_moved\" &&\n\t\t\trecord.stage !== \"epoch_written\" &&\n\t\t\trecord.stage !== \"audit_logged\")\n\t) {\n\t\treturn undefined;\n\t}\n\treturn record as unknown as LandingTransaction;\n}\n\nexport async function writeLandingTransaction(paths: SyncStorePaths, transaction: LandingTransaction): Promise<void> {\n\tawait writeFileAtomic(paths.landingTransactionFile, `${JSON.stringify(transaction, null, \"\\t\")}\\n`);\n}\n\nexport async function clearLandingTransaction(paths: SyncStorePaths): Promise<void> {\n\ttry {\n\t\tawait fsPromises.unlink(paths.landingTransactionFile);\n\t} catch (error) {\n\t\tif ((error as NodeJS.ErrnoException).code !== \"ENOENT\") throw error;\n\t}\n}\n\nfunction laneFile(paths: SyncStorePaths, laneKey: string): string {\n\treturn join(paths.lanesDir, `${laneKey}.json`);\n}\n\nexport async function readLane(paths: SyncStorePaths, laneKey: string): Promise<LaneRegistration | undefined> {\n\treturn readJsonFile<LaneRegistration>(laneFile(paths, laneKey));\n}\n\nexport async function writeLane(paths: SyncStorePaths, lane: LaneRegistration): Promise<void> {\n\tawait writeFileAtomic(laneFile(paths, lane.laneKey), `${JSON.stringify(lane, null, \"\\t\")}\\n`);\n}\n\nexport async function listLanes(paths: SyncStorePaths): Promise<LaneRegistration[]> {\n\tlet entries: string[];\n\ttry {\n\t\tentries = await fsPromises.readdir(paths.lanesDir);\n\t} catch {\n\t\treturn [];\n\t}\n\tconst lanes: LaneRegistration[] = [];\n\tfor (const entry of entries.sort()) {\n\t\tif (!entry.endsWith(\".json\")) continue;\n\t\tconst lane = await readJsonFile<LaneRegistration>(join(paths.lanesDir, entry));\n\t\tif (lane?.laneKey) lanes.push(lane);\n\t}\n\treturn lanes;\n}\n\n/** Append one audit event as a single JSON line. `at` is stamped here so every event carries it. */\nexport async function appendAuditEvent(\n\tpaths: SyncStorePaths,\n\tevent: { event: string } & Record<string, unknown>,\n\tat: string,\n): Promise<void> {\n\tawait appendBoundedJsonLine(paths.eventsFile, { at, ...event }, WORKTREE_AUDIT_EVENT_LIMITS);\n}\n\nexport interface IntegrationLockDeps {\n\t/** Injectable liveness probe (deterministic tests). Default: same-host `process.kill(pid, 0)`. */\n\tisPidAlive?: (owner: IntegrationLockOwner) => boolean;\n\tnow?: () => string;\n\tnowMs?: () => number;\n}\n\n/** Same-host pid liveness. A foreign-host owner is ALWAYS treated as alive -- never taken over. */\nexport function defaultIsPidAlive(owner: IntegrationLockOwner): boolean {\n\tif (owner.hostname !== osHostname()) return true;\n\ttry {\n\t\tprocess.kill(owner.pid, 0);\n\t\treturn true;\n\t} catch (err) {\n\t\t// EPERM means the pid exists but belongs to another user -- alive. Only ESRCH is dead.\n\t\treturn (err as NodeJS.ErrnoException).code === \"EPERM\";\n\t}\n}\n\nasync function readLockOwner(paths: SyncStorePaths): Promise<IntegrationLockOwner | undefined> {\n\treturn readJsonFile<IntegrationLockOwner>(paths.lockOwnerFile);\n}\n\nasync function tryMkdirLock(paths: SyncStorePaths): Promise<boolean> {\n\ttry {\n\t\tawait fsPromises.mkdir(paths.lockDir, { recursive: false });\n\t\treturn true;\n\t} catch (err) {\n\t\tif ((err as NodeJS.ErrnoException).code === \"ENOENT\") {\n\t\t\t// Parent `locks/` missing on first use: create it, then retry the ATOMIC non-recursive mkdir.\n\t\t\tawait fsPromises.mkdir(dirname(paths.lockDir), { recursive: true });\n\t\t\ttry {\n\t\t\t\tawait fsPromises.mkdir(paths.lockDir, { recursive: false });\n\t\t\t\treturn true;\n\t\t\t} catch {\n\t\t\t\treturn false;\n\t\t\t}\n\t\t}\n\t\treturn false;\n\t}\n}\n\n/**\n * Acquire the single integration lock (G1: landing is serialized). Non-blocking: a held lock\n * returns `{acquired:false, holder, holderAlive}` immediately -- callers surface `lock_busy` and\n * retry on their own cadence rather than spinning here. Takeover happens ONLY when the recorded\n * owner is provably dead on this host (or the lock dir is ownerless and older than\n * {@link OWNERLESS_LOCK_STALE_MS}); every takeover is audited.\n */\nexport async function acquireIntegrationLock(\n\tpaths: SyncStorePaths,\n\towner: Omit<IntegrationLockOwner, \"acquiredAt\" | \"token\">,\n\tdeps: IntegrationLockDeps = {},\n): Promise<IntegrationLockAcquisition> {\n\treturn withFileLock(paths.lockGuardFile, async () => {\n\t\tconst now = deps.now ?? (() => new Date().toISOString());\n\t\tconst nowMs = deps.nowMs ?? (() => Date.now());\n\t\tconst isPidAlive = deps.isPidAlive ?? defaultIsPidAlive;\n\t\tfor (let attempt = 0; attempt < 2; attempt++) {\n\t\t\tif (await tryMkdirLock(paths)) {\n\t\t\t\tconst token = randomUUID();\n\t\t\t\tconst manifest: IntegrationLockOwner = { ...owner, token, acquiredAt: now() };\n\t\t\t\tawait fsPromises.writeFile(paths.lockOwnerFile, `${JSON.stringify(manifest)}\\n`, \"utf-8\");\n\t\t\t\tawait appendAuditEvent(\n\t\t\t\t\tpaths,\n\t\t\t\t\t{ event: \"lock_acquired\", ...(attempt > 0 ? { takeover: true } : {}) },\n\t\t\t\t\tnow(),\n\t\t\t\t);\n\t\t\t\treturn { acquired: true, takeover: attempt > 0, token };\n\t\t\t}\n\n\t\t\tconst holder = await readLockOwner(paths);\n\t\t\tif (holder) {\n\t\t\t\tif (isPidAlive(holder)) return { acquired: false, holder, holderAlive: true };\n\t\t\t} else {\n\t\t\t\t// Ownerless dir: a crash between mkdir and the owner write. Only stale ones are dead.\n\t\t\t\tlet dirMtimeMs: number | undefined;\n\t\t\t\ttry {\n\t\t\t\t\tdirMtimeMs = (await fsPromises.stat(paths.lockDir)).mtimeMs;\n\t\t\t\t} catch {\n\t\t\t\t\tcontinue;\n\t\t\t\t}\n\t\t\t\tif (nowMs() - dirMtimeMs < OWNERLESS_LOCK_STALE_MS) return { acquired: false, holderAlive: true };\n\t\t\t}\n\n\t\t\t// Metadata serialization makes the stale observation and directory removal one guarded\n\t\t\t// operation; a successor cannot be removed by a stale observer.\n\t\t\tawait fsPromises.rm(paths.lockDir, { recursive: true, force: true });\n\t\t\tawait appendAuditEvent(\n\t\t\t\tpaths,\n\t\t\t\t{\n\t\t\t\t\tevent: \"lock_takeover\",\n\t\t\t\t\t...(holder ? { deadOwnerPid: holder.pid, deadOwnerLaneKey: holder.laneKey } : {}),\n\t\t\t\t},\n\t\t\t\tnow(),\n\t\t\t);\n\t\t}\n\t\tconst holder = await readLockOwner(paths);\n\t\treturn { acquired: false, holder, holderAlive: holder ? isPidAlive(holder) : true };\n\t});\n}\n\nexport async function releaseIntegrationLock(\n\tpaths: SyncStorePaths,\n\ttoken: string,\n\tdeps: IntegrationLockDeps = {},\n): Promise<boolean> {\n\treturn withFileLock(paths.lockGuardFile, async () => {\n\t\tconst now = deps.now ?? (() => new Date().toISOString());\n\t\tconst holder = await readLockOwner(paths);\n\t\tif (!holder || holder.token !== token) return false;\n\t\tawait fsPromises.rm(paths.lockDir, { recursive: true, force: true });\n\t\tawait appendAuditEvent(paths, { event: \"lock_released\" }, now());\n\t\treturn true;\n\t});\n}\n\nexport async function readLockHolder(paths: SyncStorePaths): Promise<IntegrationLockOwner | undefined> {\n\treturn readLockOwner(paths);\n}\n"]}

package/dist/core/worktree-sync/store.js

@@ -0,0 +1,252 @@
+/**
+ * Worktree-sync on-disk store: coordination state shared by EVERY process working on one repo.
+ *
+ * Lives under `<git-common-dir>/pi-worktree-sync/` -- all worktrees of a repository share the git
+ * common dir, so the store is repo-scoped and cross-process by construction, survives `/reload`
+ * and crashes, is invisible to `git status`, and needs no gitignore entry.
+ *
+ * The store is an INDEX, not the truth: freshness/dirtiness/progress are always re-derived from
+ * git by the engine (`git-engine.ts`). A deleted or corrupt store is rebuildable via reconcile --
+ * every reader here treats missing/corrupt files as "absent", never as an error.
+ *
+ * Writes are tmp+rename atomic (`util/atomic-file.ts`); the audit log uses the shared bounded JSONL
+ * sink, which serializes concurrent writers and atomically rotates to its newest low-water tail.
+ * The integration lock is a mkdir-atomic directory with an owner manifest: mkdir either succeeds
+ * (lock acquired) or fails EEXIST (held), with takeover ONLY for a provably-dead same-host owner.
+ */
+import { createHash, randomUUID } from "node:crypto";
+import { promises as fsPromises, realpathSync } from "node:fs";
+import { hostname as osHostname } from "node:os";
+import { basename, dirname, join } from "node:path";
+import { withFileLock, writeFileAtomic } from "../util/atomic-file.js";
+import { appendBoundedJsonLine } from "../util/bounded-jsonl.js";
+/** Grace window after which an ownerless lock dir (crash between mkdir and owner write) counts as
+ * dead and may be taken over. Fresh ownerless dirs are conservatively treated as held. */
+export const OWNERLESS_LOCK_STALE_MS = 30_000;
+const STORE_DIR_NAME = "pi-worktree-sync";
+const WORKTREE_AUDIT_EVENT_LIMITS = {
+    maxBytes: 4 * 1024 * 1024,
+    targetBytes: Math.floor(4 * 1024 * 1024 * 0.75),
+    maxRecords: 10_000,
+};
+export function syncStorePaths(gitCommonDir) {
+    const root = join(gitCommonDir, STORE_DIR_NAME);
+    return {
+        root,
+        epochFile: join(root, "epoch.json"),
+        landingTransactionFile: join(root, "landing-transaction.json"),
+        lanesDir: join(root, "lanes"),
+        lockDir: join(root, "locks", "integration"),
+        lockOwnerFile: join(root, "locks", "integration", "owner.json"),
+        lockGuardFile: join(root, "locks", "integration-metadata"),
+        lifecycleLockFile: join(root, "locks", "lifecycle"),
+        eventsFile: join(root, "events.jsonl"),
+    };
+}
+/**
+ * Stable per-repo slug for the lane-worktree checkout root: sanitized repo basename plus 8 hex of
+ * sha256 over the REALPATH of the git common dir -- same-named repos in different places cannot
+ * collide, and every worktree of one repo resolves the same slug.
+ */
+export function repoSlug(repoTopLevel, gitCommonDir) {
+    let canonical = gitCommonDir;
+    try {
+        canonical = realpathSync(gitCommonDir);
+    }
+    catch {
+        // Unresolvable (already-deleted repo during teardown): hash the raw path deterministically.
+    }
+    const hash = createHash("sha256").update(canonical).digest("hex").slice(0, 8);
+    const base = basename(repoTopLevel)
+        .toLowerCase()
+        .replace(/[^a-z0-9-]+/g, "-")
+        .replace(/^-+|-+$/g, "")
+        .slice(0, 48);
+    return `${base || "repo"}-${hash}`;
+}
+async function readJsonFile(filePath) {
+    let raw;
+    try {
+        raw = await fsPromises.readFile(filePath, "utf-8");
+    }
+    catch {
+        return undefined;
+    }
+    try {
+        return JSON.parse(raw);
+    }
+    catch {
+        // Corrupt store files are treated as absent -- git remains the truth and reconcile rebuilds.
+        return undefined;
+    }
+}
+export async function readEpoch(paths) {
+    return readJsonFile(paths.epochFile);
+}
+export async function writeEpoch(paths, epoch) {
+    await writeFileAtomic(paths.epochFile, `${JSON.stringify(epoch, null, "\t")}\n`);
+}
+export async function readLandingTransaction(paths) {
+    const value = await readJsonFile(paths.landingTransactionFile);
+    if (typeof value !== "object" || value === null || Array.isArray(value))
+        return undefined;
+    const record = value;
+    if (typeof record.laneKey !== "string" ||
+        typeof record.priorMainSha !== "string" ||
+        typeof record.testedTipSha !== "string" ||
+        !Array.isArray(record.changedPaths) ||
+        !record.changedPaths.every((path) => typeof path === "string") ||
+        typeof record.changedPathsTruncated !== "boolean" ||
+        typeof record.lockToken !== "string" ||
+        (record.gate !== "passed" && record.gate !== "off") ||
+        (record.stage !== "ready_to_merge" &&
+            record.stage !== "main_moved" &&
+            record.stage !== "epoch_written" &&
+            record.stage !== "audit_logged")) {
+        return undefined;
+    }
+    return record;
+}
+export async function writeLandingTransaction(paths, transaction) {
+    await writeFileAtomic(paths.landingTransactionFile, `${JSON.stringify(transaction, null, "\t")}\n`);
+}
+export async function clearLandingTransaction(paths) {
+    try {
+        await fsPromises.unlink(paths.landingTransactionFile);
+    }
+    catch (error) {
+        if (error.code !== "ENOENT")
+            throw error;
+    }
+}
+function laneFile(paths, laneKey) {
+    return join(paths.lanesDir, `${laneKey}.json`);
+}
+export async function readLane(paths, laneKey) {
+    return readJsonFile(laneFile(paths, laneKey));
+}
+export async function writeLane(paths, lane) {
+    await writeFileAtomic(laneFile(paths, lane.laneKey), `${JSON.stringify(lane, null, "\t")}\n`);
+}
+export async function listLanes(paths) {
+    let entries;
+    try {
+        entries = await fsPromises.readdir(paths.lanesDir);
+    }
+    catch {
+        return [];
+    }
+    const lanes = [];
+    for (const entry of entries.sort()) {
+        if (!entry.endsWith(".json"))
+            continue;
+        const lane = await readJsonFile(join(paths.lanesDir, entry));
+        if (lane?.laneKey)
+            lanes.push(lane);
+    }
+    return lanes;
+}
+/** Append one audit event as a single JSON line. `at` is stamped here so every event carries it. */
+export async function appendAuditEvent(paths, event, at) {
+    await appendBoundedJsonLine(paths.eventsFile, { at, ...event }, WORKTREE_AUDIT_EVENT_LIMITS);
+}
+/** Same-host pid liveness. A foreign-host owner is ALWAYS treated as alive -- never taken over. */
+export function defaultIsPidAlive(owner) {
+    if (owner.hostname !== osHostname())
+        return true;
+    try {
+        process.kill(owner.pid, 0);
+        return true;
+    }
+    catch (err) {
+        // EPERM means the pid exists but belongs to another user -- alive. Only ESRCH is dead.
+        return err.code === "EPERM";
+    }
+}
+async function readLockOwner(paths) {
+    return readJsonFile(paths.lockOwnerFile);
+}
+async function tryMkdirLock(paths) {
+    try {
+        await fsPromises.mkdir(paths.lockDir, { recursive: false });
+        return true;
+    }
+    catch (err) {
+        if (err.code === "ENOENT") {
+            // Parent `locks/` missing on first use: create it, then retry the ATOMIC non-recursive mkdir.
+            await fsPromises.mkdir(dirname(paths.lockDir), { recursive: true });
+            try {
+                await fsPromises.mkdir(paths.lockDir, { recursive: false });
+                return true;
+            }
+            catch {
+                return false;
+            }
+        }
+        return false;
+    }
+}
+/**
+ * Acquire the single integration lock (G1: landing is serialized). Non-blocking: a held lock
+ * returns `{acquired:false, holder, holderAlive}` immediately -- callers surface `lock_busy` and
+ * retry on their own cadence rather than spinning here. Takeover happens ONLY when the recorded
+ * owner is provably dead on this host (or the lock dir is ownerless and older than
+ * {@link OWNERLESS_LOCK_STALE_MS}); every takeover is audited.
+ */
+export async function acquireIntegrationLock(paths, owner, deps = {}) {
+    return withFileLock(paths.lockGuardFile, async () => {
+        const now = deps.now ?? (() => new Date().toISOString());
+        const nowMs = deps.nowMs ?? (() => Date.now());
+        const isPidAlive = deps.isPidAlive ?? defaultIsPidAlive;
+        for (let attempt = 0; attempt < 2; attempt++) {
+            if (await tryMkdirLock(paths)) {
+                const token = randomUUID();
+                const manifest = { ...owner, token, acquiredAt: now() };
+                await fsPromises.writeFile(paths.lockOwnerFile, `${JSON.stringify(manifest)}\n`, "utf-8");
+                await appendAuditEvent(paths, { event: "lock_acquired", ...(attempt > 0 ? { takeover: true } : {}) }, now());
+                return { acquired: true, takeover: attempt > 0, token };
+            }
+            const holder = await readLockOwner(paths);
+            if (holder) {
+                if (isPidAlive(holder))
+                    return { acquired: false, holder, holderAlive: true };
+            }
+            else {
+                // Ownerless dir: a crash between mkdir and the owner write. Only stale ones are dead.
+                let dirMtimeMs;
+                try {
+                    dirMtimeMs = (await fsPromises.stat(paths.lockDir)).mtimeMs;
+                }
+                catch {
+                    continue;
+                }
+                if (nowMs() - dirMtimeMs < OWNERLESS_LOCK_STALE_MS)
+                    return { acquired: false, holderAlive: true };
+            }
+            // Metadata serialization makes the stale observation and directory removal one guarded
+            // operation; a successor cannot be removed by a stale observer.
+            await fsPromises.rm(paths.lockDir, { recursive: true, force: true });
+            await appendAuditEvent(paths, {
+                event: "lock_takeover",
+                ...(holder ? { deadOwnerPid: holder.pid, deadOwnerLaneKey: holder.laneKey } : {}),
+            }, now());
+        }
+        const holder = await readLockOwner(paths);
+        return { acquired: false, holder, holderAlive: holder ? isPidAlive(holder) : true };
+    });
+}
+export async function releaseIntegrationLock(paths, token, deps = {}) {
+    return withFileLock(paths.lockGuardFile, async () => {
+        const now = deps.now ?? (() => new Date().toISOString());
+        const holder = await readLockOwner(paths);
+        if (!holder || holder.token !== token)
+            return false;
+        await fsPromises.rm(paths.lockDir, { recursive: true, force: true });
+        await appendAuditEvent(paths, { event: "lock_released" }, now());
+        return true;
+    });
+}
+export async function readLockHolder(paths) {
+    return readLockOwner(paths);
+}
+//# sourceMappingURL=store.js.map

package/dist/core/worktree-sync/store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"store.js","sourceRoot":"","sources":["../../../src/core/worktree-sync/store.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Worktree-sync on-disk store: coordination state shared by EVERY process working on one repo.\n *\n * Lives under `<git-common-dir>/pi-worktree-sync/` -- all worktrees of a repository share the git\n * common dir, so the store is repo-scoped and cross-process by construction, survives `/reload`\n * and crashes, is invisible to `git status`, and needs no gitignore entry.\n *\n * The store is an INDEX, not the truth: freshness/dirtiness/progress are always re-derived from\n * git by the engine (`git-engine.ts`). A deleted or corrupt store is rebuildable via reconcile --\n * every reader here treats missing/corrupt files as \"absent\", never as an error.\n *\n * Writes are tmp+rename atomic (`util/atomic-file.ts`); the audit log uses the shared bounded JSONL\n * sink, which serializes concurrent writers and atomically rotates to its newest low-water tail.\n * The integration lock is a mkdir-atomic directory with an owner manifest: mkdir either succeeds\n * (lock acquired) or fails EEXIST (held), with takeover ONLY for a provably-dead same-host owner.\n */\n\nimport { createHash, randomUUID } from \"node:crypto\";\nimport { promises as fsPromises, realpathSync } from \"node:fs\";\nimport { hostname as osHostname } from \"node:os\";\nimport { basename, dirname, join } from \"node:path\";\nimport { withFileLock, writeFileAtomic } from \"../util/atomic-file.ts\";\nimport { appendBoundedJsonLine, type BoundedJsonlLimits } from \"../util/bounded-jsonl.ts\";\nimport type {\n\tIntegrationLockAcquisition,\n\tIntegrationLockOwner,\n\tLandingTransaction,\n\tLaneRegistration,\n\tWorktreeSyncEpoch,\n} from \"./codes.ts\";\n\nexport interface SyncStorePaths {\n\troot: string;\n\tepochFile: string;\n\tlandingTransactionFile: string;\n\tlanesDir: string;\n\tlockDir: string;\n\tlockOwnerFile: string;\n\tlockGuardFile: string;\n\tlifecycleLockFile: string;\n\teventsFile: string;\n}\n\n/** Grace window after which an ownerless lock dir (crash between mkdir and owner write) counts as\n * dead and may be taken over. Fresh ownerless dirs are conservatively treated as held. */\nexport const OWNERLESS_LOCK_STALE_MS = 30_000;\n\nconst STORE_DIR_NAME = \"pi-worktree-sync\";\nconst WORKTREE_AUDIT_EVENT_LIMITS: BoundedJsonlLimits = {\n\tmaxBytes: 4 * 1024 * 1024,\n\ttargetBytes: Math.floor(4 * 1024 * 1024 * 0.75),\n\tmaxRecords: 10_000,\n};\n\nexport function syncStorePaths(gitCommonDir: string): SyncStorePaths {\n\tconst root = join(gitCommonDir, STORE_DIR_NAME);\n\treturn {\n\t\troot,\n\t\tepochFile: join(root, \"epoch.json\"),\n\t\tlandingTransactionFile: join(root, \"landing-transaction.json\"),\n\t\tlanesDir: join(root, \"lanes\"),\n\t\tlockDir: join(root, \"locks\", \"integration\"),\n\t\tlockOwnerFile: join(root, \"locks\", \"integration\", \"owner.json\"),\n\t\tlockGuardFile: join(root, \"locks\", \"integration-metadata\"),\n\t\tlifecycleLockFile: join(root, \"locks\", \"lifecycle\"),\n\t\teventsFile: join(root, \"events.jsonl\"),\n\t};\n}\n\n/**\n * Stable per-repo slug for the lane-worktree checkout root: sanitized repo basename plus 8 hex of\n * sha256 over the REALPATH of the git common dir -- same-named repos in different places cannot\n * collide, and every worktree of one repo resolves the same slug.\n */\nexport function repoSlug(repoTopLevel: string, gitCommonDir: string): string {\n\tlet canonical = gitCommonDir;\n\ttry {\n\t\tcanonical = realpathSync(gitCommonDir);\n\t} catch {\n\t\t// Unresolvable (already-deleted repo during teardown): hash the raw path deterministically.\n\t}\n\tconst hash = createHash(\"sha256\").update(canonical).digest(\"hex\").slice(0, 8);\n\tconst base = basename(repoTopLevel)\n\t\t.toLowerCase()\n\t\t.replace(/[^a-z0-9-]+/g, \"-\")\n\t\t.replace(/^-+|-+$/g, \"\")\n\t\t.slice(0, 48);\n\treturn `${base || \"repo\"}-${hash}`;\n}\n\nasync function readJsonFile<T>(filePath: string): Promise<T | undefined> {\n\tlet raw: string;\n\ttry {\n\t\traw = await fsPromises.readFile(filePath, \"utf-8\");\n\t} catch {\n\t\treturn undefined;\n\t}\n\ttry {\n\t\treturn JSON.parse(raw) as T;\n\t} catch {\n\t\t// Corrupt store files are treated as absent -- git remains the truth and reconcile rebuilds.\n\t\treturn undefined;\n\t}\n}\n\nexport async function readEpoch(paths: SyncStorePaths): Promise<WorktreeSyncEpoch | undefined> {\n\treturn readJsonFile<WorktreeSyncEpoch>(paths.epochFile);\n}\n\nexport async function writeEpoch(paths: SyncStorePaths, epoch: WorktreeSyncEpoch): Promise<void> {\n\tawait writeFileAtomic(paths.epochFile, `${JSON.stringify(epoch, null, \"\\t\")}\\n`);\n}\n\nexport async function readLandingTransaction(paths: SyncStorePaths): Promise<LandingTransaction | undefined> {\n\tconst value = await readJsonFile<unknown>(paths.landingTransactionFile);\n\tif (typeof value !== \"object\" || value === null || Array.isArray(value)) return undefined;\n\tconst record = value as Record<string, unknown>;\n\tif (\n\t\ttypeof record.laneKey !== \"string\" ||\n\t\ttypeof record.priorMainSha !== \"string\" ||\n\t\ttypeof record.testedTipSha !== \"string\" ||\n\t\t!Array.isArray(record.changedPaths) ||\n\t\t!record.changedPaths.every((path) => typeof path === \"string\") ||\n\t\ttypeof record.changedPathsTruncated !== \"boolean\" ||\n\t\ttypeof record.lockToken !== \"string\" ||\n\t\t(record.gate !== \"passed\" && record.gate !== \"off\") ||\n\t\t(record.stage !== \"ready_to_merge\" &&\n\t\t\trecord.stage !== \"main_moved\" &&\n\t\t\trecord.stage !== \"epoch_written\" &&\n\t\t\trecord.stage !== \"audit_logged\")\n\t) {\n\t\treturn undefined;\n\t}\n\treturn record as unknown as LandingTransaction;\n}\n\nexport async function writeLandingTransaction(paths: SyncStorePaths, transaction: LandingTransaction): Promise<void> {\n\tawait writeFileAtomic(paths.landingTransactionFile, `${JSON.stringify(transaction, null, \"\\t\")}\\n`);\n}\n\nexport async function clearLandingTransaction(paths: SyncStorePaths): Promise<void> {\n\ttry {\n\t\tawait fsPromises.unlink(paths.landingTransactionFile);\n\t} catch (error) {\n\t\tif ((error as NodeJS.ErrnoException).code !== \"ENOENT\") throw error;\n\t}\n}\n\nfunction laneFile(paths: SyncStorePaths, laneKey: string): string {\n\treturn join(paths.lanesDir, `${laneKey}.json`);\n}\n\nexport async function readLane(paths: SyncStorePaths, laneKey: string): Promise<LaneRegistration | undefined> {\n\treturn readJsonFile<LaneRegistration>(laneFile(paths, laneKey));\n}\n\nexport async function writeLane(paths: SyncStorePaths, lane: LaneRegistration): Promise<void> {\n\tawait writeFileAtomic(laneFile(paths, lane.laneKey), `${JSON.stringify(lane, null, \"\\t\")}\\n`);\n}\n\nexport async function listLanes(paths: SyncStorePaths): Promise<LaneRegistration[]> {\n\tlet entries: string[];\n\ttry {\n\t\tentries = await fsPromises.readdir(paths.lanesDir);\n\t} catch {\n\t\treturn [];\n\t}\n\tconst lanes: LaneRegistration[] = [];\n\tfor (const entry of entries.sort()) {\n\t\tif (!entry.endsWith(\".json\")) continue;\n\t\tconst lane = await readJsonFile<LaneRegistration>(join(paths.lanesDir, entry));\n\t\tif (lane?.laneKey) lanes.push(lane);\n\t}\n\treturn lanes;\n}\n\n/** Append one audit event as a single JSON line. `at` is stamped here so every event carries it. */\nexport async function appendAuditEvent(\n\tpaths: SyncStorePaths,\n\tevent: { event: string } & Record<string, unknown>,\n\tat: string,\n): Promise<void> {\n\tawait appendBoundedJsonLine(paths.eventsFile, { at, ...event }, WORKTREE_AUDIT_EVENT_LIMITS);\n}\n\nexport interface IntegrationLockDeps {\n\t/** Injectable liveness probe (deterministic tests). Default: same-host `process.kill(pid, 0)`. */\n\tisPidAlive?: (owner: IntegrationLockOwner) => boolean;\n\tnow?: () => string;\n\tnowMs?: () => number;\n}\n\n/** Same-host pid liveness. A foreign-host owner is ALWAYS treated as alive -- never taken over. */\nexport function defaultIsPidAlive(owner: IntegrationLockOwner): boolean {\n\tif (owner.hostname !== osHostname()) return true;\n\ttry {\n\t\tprocess.kill(owner.pid, 0);\n\t\treturn true;\n\t} catch (err) {\n\t\t// EPERM means the pid exists but belongs to another user -- alive. Only ESRCH is dead.\n\t\treturn (err as NodeJS.ErrnoException).code === \"EPERM\";\n\t}\n}\n\nasync function readLockOwner(paths: SyncStorePaths): Promise<IntegrationLockOwner | undefined> {\n\treturn readJsonFile<IntegrationLockOwner>(paths.lockOwnerFile);\n}\n\nasync function tryMkdirLock(paths: SyncStorePaths): Promise<boolean> {\n\ttry {\n\t\tawait fsPromises.mkdir(paths.lockDir, { recursive: false });\n\t\treturn true;\n\t} catch (err) {\n\t\tif ((err as NodeJS.ErrnoException).code === \"ENOENT\") {\n\t\t\t// Parent `locks/` missing on first use: create it, then retry the ATOMIC non-recursive mkdir.\n\t\t\tawait fsPromises.mkdir(dirname(paths.lockDir), { recursive: true });\n\t\t\ttry {\n\t\t\t\tawait fsPromises.mkdir(paths.lockDir, { recursive: false });\n\t\t\t\treturn true;\n\t\t\t} catch {\n\t\t\t\treturn false;\n\t\t\t}\n\t\t}\n\t\treturn false;\n\t}\n}\n\n/**\n * Acquire the single integration lock (G1: landing is serialized). Non-blocking: a held lock\n * returns `{acquired:false, holder, holderAlive}` immediately -- callers surface `lock_busy` and\n * retry on their own cadence rather than spinning here. Takeover happens ONLY when the recorded\n * owner is provably dead on this host (or the lock dir is ownerless and older than\n * {@link OWNERLESS_LOCK_STALE_MS}); every takeover is audited.\n */\nexport async function acquireIntegrationLock(\n\tpaths: SyncStorePaths,\n\towner: Omit<IntegrationLockOwner, \"acquiredAt\" | \"token\">,\n\tdeps: IntegrationLockDeps = {},\n): Promise<IntegrationLockAcquisition> {\n\treturn withFileLock(paths.lockGuardFile, async () => {\n\t\tconst now = deps.now ?? (() => new Date().toISOString());\n\t\tconst nowMs = deps.nowMs ?? (() => Date.now());\n\t\tconst isPidAlive = deps.isPidAlive ?? defaultIsPidAlive;\n\t\tfor (let attempt = 0; attempt < 2; attempt++) {\n\t\t\tif (await tryMkdirLock(paths)) {\n\t\t\t\tconst token = randomUUID();\n\t\t\t\tconst manifest: IntegrationLockOwner = { ...owner, token, acquiredAt: now() };\n\t\t\t\tawait fsPromises.writeFile(paths.lockOwnerFile, `${JSON.stringify(manifest)}\\n`, \"utf-8\");\n\t\t\t\tawait appendAuditEvent(\n\t\t\t\t\tpaths,\n\t\t\t\t\t{ event: \"lock_acquired\", ...(attempt > 0 ? { takeover: true } : {}) },\n\t\t\t\t\tnow(),\n\t\t\t\t);\n\t\t\t\treturn { acquired: true, takeover: attempt > 0, token };\n\t\t\t}\n\n\t\t\tconst holder = await readLockOwner(paths);\n\t\t\tif (holder) {\n\t\t\t\tif (isPidAlive(holder)) return { acquired: false, holder, holderAlive: true };\n\t\t\t} else {\n\t\t\t\t// Ownerless dir: a crash between mkdir and the owner write. Only stale ones are dead.\n\t\t\t\tlet dirMtimeMs: number | undefined;\n\t\t\t\ttry {\n\t\t\t\t\tdirMtimeMs = (await fsPromises.stat(paths.lockDir)).mtimeMs;\n\t\t\t\t} catch {\n\t\t\t\t\tcontinue;\n\t\t\t\t}\n\t\t\t\tif (nowMs() - dirMtimeMs < OWNERLESS_LOCK_STALE_MS) return { acquired: false, holderAlive: true };\n\t\t\t}\n\n\t\t\t// Metadata serialization makes the stale observation and directory removal one guarded\n\t\t\t// operation; a successor cannot be removed by a stale observer.\n\t\t\tawait fsPromises.rm(paths.lockDir, { recursive: true, force: true });\n\t\t\tawait appendAuditEvent(\n\t\t\t\tpaths,\n\t\t\t\t{\n\t\t\t\t\tevent: \"lock_takeover\",\n\t\t\t\t\t...(holder ? { deadOwnerPid: holder.pid, deadOwnerLaneKey: holder.laneKey } : {}),\n\t\t\t\t},\n\t\t\t\tnow(),\n\t\t\t);\n\t\t}\n\t\tconst holder = await readLockOwner(paths);\n\t\treturn { acquired: false, holder, holderAlive: holder ? isPidAlive(holder) : true };\n\t});\n}\n\nexport async function releaseIntegrationLock(\n\tpaths: SyncStorePaths,\n\ttoken: string,\n\tdeps: IntegrationLockDeps = {},\n): Promise<boolean> {\n\treturn withFileLock(paths.lockGuardFile, async () => {\n\t\tconst now = deps.now ?? (() => new Date().toISOString());\n\t\tconst holder = await readLockOwner(paths);\n\t\tif (!holder || holder.token !== token) return false;\n\t\tawait fsPromises.rm(paths.lockDir, { recursive: true, force: true });\n\t\tawait appendAuditEvent(paths, { event: \"lock_released\" }, now());\n\t\treturn true;\n\t});\n}\n\nexport async function readLockHolder(paths: SyncStorePaths): Promise<IntegrationLockOwner | undefined> {\n\treturn readLockOwner(paths);\n}\n"]}

package/dist/core/worktree-sync/watcher.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Epoch watcher for lane-bound sessions: the prompt-awareness half of "perfect sync". Watches
+ * the shared `epoch.json` (fs.watch on its directory -- the file is replaced by rename) and, on
+ * an epoch advance by ANOTHER lane, injects one deterministic staleness notice through the host's
+ * message seam. Enforcement never rides on this watcher -- the lane gate (G8) and the land CAS
+ * (G3) fail closed even if it dies; this only makes lanes learn promptly instead of at their
+ * next tool call.
+ */
+import type { WorktreeSyncEpoch } from "./codes.ts";
+export interface EpochWatcherConfig {
+    epochFile: string;
+    /** The lane this session is bound to: lands BY this lane never notify it. */
+    laneKey: string;
+    notify: (text: string) => void;
+    /** Debounce for rename/change event bursts. */
+    debounceMs?: number;
+}
+export interface EpochWatcherHandle {
+    stop(): void;
+}
+/** Deterministic notice text -- assembled from epoch facts, never model-generated. */
+export declare function formatEpochNotice(epoch: WorktreeSyncEpoch, laneKey: string): string;
+/**
+ * Start watching. The initial epoch is read once as the baseline; only ADVANCES past it notify
+ * (a fresh session never gets a notice for history). fs.watch is backed by a low-frequency
+ * poll re-read on each event burst only -- no timers run while the store is quiet.
+ */
+export declare function startEpochWatcher(config: EpochWatcherConfig): EpochWatcherHandle;
+//# sourceMappingURL=watcher.d.ts.map

package/dist/core/worktree-sync/watcher.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"watcher.d.ts","sourceRoot":"","sources":["../../../src/core/worktree-sync/watcher.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAKH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAEpD,MAAM,WAAW,kBAAkB;IAClC,SAAS,EAAE,MAAM,CAAC;IAClB,6EAA6E;IAC7E,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IAC/B,+CAA+C;IAC/C,UAAU,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,kBAAkB;IAClC,IAAI,IAAI,IAAI,CAAC;CACb;AAUD,sFAAsF;AACtF,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,iBAAiB,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAYnF;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,kBAAkB,GAAG,kBAAkB,CAsDhF","sourcesContent":["/**\n * Epoch watcher for lane-bound sessions: the prompt-awareness half of \"perfect sync\". Watches\n * the shared `epoch.json` (fs.watch on its directory -- the file is replaced by rename) and, on\n * an epoch advance by ANOTHER lane, injects one deterministic staleness notice through the host's\n * message seam. Enforcement never rides on this watcher -- the lane gate (G8) and the land CAS\n * (G3) fail closed even if it dies; this only makes lanes learn promptly instead of at their\n * next tool call.\n */\n\nimport { readFile } from \"node:fs/promises\";\nimport { basename, dirname } from \"node:path\";\nimport { watchWithErrorHandler } from \"../../utils/fs-watch.ts\";\nimport type { WorktreeSyncEpoch } from \"./codes.ts\";\n\nexport interface EpochWatcherConfig {\n\tepochFile: string;\n\t/** The lane this session is bound to: lands BY this lane never notify it. */\n\tlaneKey: string;\n\tnotify: (text: string) => void;\n\t/** Debounce for rename/change event bursts. */\n\tdebounceMs?: number;\n}\n\nexport interface EpochWatcherHandle {\n\tstop(): void;\n}\n\nasync function readEpochFile(epochFile: string): Promise<WorktreeSyncEpoch | undefined> {\n\ttry {\n\t\treturn JSON.parse(await readFile(epochFile, \"utf-8\")) as WorktreeSyncEpoch;\n\t} catch {\n\t\treturn undefined;\n\t}\n}\n\n/** Deterministic notice text -- assembled from epoch facts, never model-generated. */\nexport function formatEpochNotice(epoch: WorktreeSyncEpoch, laneKey: string): string {\n\tconst changed =\n\t\tepoch.changedPaths.length > 0\n\t\t\t? `${epoch.changedPaths.slice(0, 10).join(\", \")}${epoch.changedPaths.length > 10 || epoch.changedPathsTruncated ? \", ...\" : \"\"}`\n\t\t\t: \"(no files listed)\";\n\treturn [\n\t\t`worktree-sync: main advanced to epoch ${epoch.epoch}`,\n\t\t`${epoch.landedLaneKey ? ` (landed by lane '${epoch.landedLaneKey}')` : \"\"}.`,\n\t\t` Changed: ${changed}.`,\n\t\t` Your lane '${laneKey}' must rebase main before further mutations/landing:`,\n\t\t` call worktree_sync {\"action\":\"sync\"} now, resolve any conflicts locally, then continue working.`,\n\t].join(\"\");\n}\n\n/**\n * Start watching. The initial epoch is read once as the baseline; only ADVANCES past it notify\n * (a fresh session never gets a notice for history). fs.watch is backed by a low-frequency\n * poll re-read on each event burst only -- no timers run while the store is quiet.\n */\nexport function startEpochWatcher(config: EpochWatcherConfig): EpochWatcherHandle {\n\tconst debounceMs = config.debounceMs ?? 250;\n\tlet lastSeenEpoch: number | undefined;\n\tlet debounceTimer: NodeJS.Timeout | undefined;\n\tlet stopped = false;\n\n\tconst evaluate = async (): Promise<void> => {\n\t\tif (stopped) return;\n\t\tconst epoch = await readEpochFile(config.epochFile);\n\t\tif (!epoch) return;\n\t\tif (lastSeenEpoch === undefined) {\n\t\t\tlastSeenEpoch = epoch.epoch;\n\t\t\treturn;\n\t\t}\n\t\tif (epoch.epoch <= lastSeenEpoch) return;\n\t\tlastSeenEpoch = epoch.epoch;\n\t\tif (epoch.landedLaneKey === config.laneKey) return;\n\t\tconfig.notify(formatEpochNotice(epoch, config.laneKey));\n\t};\n\n\t// Baseline read; any event after this compares against it.\n\tvoid evaluate();\n\n\tconst fileName = basename(config.epochFile);\n\t// watchWithErrorHandler canonicalizes the watched dir (realpathSync.native) before calling\n\t// fs.watch -- on Windows, a non-canonical (e.g. 8.3 short-form) path here hard-aborts the\n\t// process via libuv's fs-event assertion. It also attaches an 'error' listener so an async\n\t// watcher failure (EMFILE, dir removed, etc.) can never surface as an unhandled exception.\n\tconst watcher = watchWithErrorHandler(\n\t\tdirname(config.epochFile),\n\t\t(_eventType, changedName) => {\n\t\t\tif (stopped) return;\n\t\t\tif (changedName !== null && changedName !== fileName && changedName !== `${fileName}.tmp`) return;\n\t\t\tif (debounceTimer) clearTimeout(debounceTimer);\n\t\t\tdebounceTimer = setTimeout(() => {\n\t\t\t\tvoid evaluate();\n\t\t\t}, debounceMs);\n\t\t\tdebounceTimer.unref?.();\n\t\t},\n\t\t() => {\n\t\t\t// The store dir may not exist yet, or the watcher died after creation (EMFILE, dir\n\t\t\t// removed, etc). The lane gate (G8) and land CAS (G3) still fail closed at the next\n\t\t\t// tool call regardless -- this watcher is a promptness optimization only, so on error\n\t\t\t// we simply stop watching rather than retry; correctness never depended on it.\n\t\t},\n\t);\n\n\treturn {\n\t\tstop() {\n\t\t\tstopped = true;\n\t\t\tif (debounceTimer) clearTimeout(debounceTimer);\n\t\t\twatcher?.close();\n\t\t},\n\t};\n}\n"]}

package/dist/core/worktree-sync/watcher.js

@@ -0,0 +1,93 @@
+/**
+ * Epoch watcher for lane-bound sessions: the prompt-awareness half of "perfect sync". Watches
+ * the shared `epoch.json` (fs.watch on its directory -- the file is replaced by rename) and, on
+ * an epoch advance by ANOTHER lane, injects one deterministic staleness notice through the host's
+ * message seam. Enforcement never rides on this watcher -- the lane gate (G8) and the land CAS
+ * (G3) fail closed even if it dies; this only makes lanes learn promptly instead of at their
+ * next tool call.
+ */
+import { readFile } from "node:fs/promises";
+import { basename, dirname } from "node:path";
+import { watchWithErrorHandler } from "../../utils/fs-watch.js";
+async function readEpochFile(epochFile) {
+    try {
+        return JSON.parse(await readFile(epochFile, "utf-8"));
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Deterministic notice text -- assembled from epoch facts, never model-generated. */
+export function formatEpochNotice(epoch, laneKey) {
+    const changed = epoch.changedPaths.length > 0
+        ? `${epoch.changedPaths.slice(0, 10).join(", ")}${epoch.changedPaths.length > 10 || epoch.changedPathsTruncated ? ", ..." : ""}`
+        : "(no files listed)";
+    return [
+        `worktree-sync: main advanced to epoch ${epoch.epoch}`,
+        `${epoch.landedLaneKey ? ` (landed by lane '${epoch.landedLaneKey}')` : ""}.`,
+        ` Changed: ${changed}.`,
+        ` Your lane '${laneKey}' must rebase main before further mutations/landing:`,
+        ` call worktree_sync {"action":"sync"} now, resolve any conflicts locally, then continue working.`,
+    ].join("");
+}
+/**
+ * Start watching. The initial epoch is read once as the baseline; only ADVANCES past it notify
+ * (a fresh session never gets a notice for history). fs.watch is backed by a low-frequency
+ * poll re-read on each event burst only -- no timers run while the store is quiet.
+ */
+export function startEpochWatcher(config) {
+    const debounceMs = config.debounceMs ?? 250;
+    let lastSeenEpoch;
+    let debounceTimer;
+    let stopped = false;
+    const evaluate = async () => {
+        if (stopped)
+            return;
+        const epoch = await readEpochFile(config.epochFile);
+        if (!epoch)
+            return;
+        if (lastSeenEpoch === undefined) {
+            lastSeenEpoch = epoch.epoch;
+            return;
+        }
+        if (epoch.epoch <= lastSeenEpoch)
+            return;
+        lastSeenEpoch = epoch.epoch;
+        if (epoch.landedLaneKey === config.laneKey)
+            return;
+        config.notify(formatEpochNotice(epoch, config.laneKey));
+    };
+    // Baseline read; any event after this compares against it.
+    void evaluate();
+    const fileName = basename(config.epochFile);
+    // watchWithErrorHandler canonicalizes the watched dir (realpathSync.native) before calling
+    // fs.watch -- on Windows, a non-canonical (e.g. 8.3 short-form) path here hard-aborts the
+    // process via libuv's fs-event assertion. It also attaches an 'error' listener so an async
+    // watcher failure (EMFILE, dir removed, etc.) can never surface as an unhandled exception.
+    const watcher = watchWithErrorHandler(dirname(config.epochFile), (_eventType, changedName) => {
+        if (stopped)
+            return;
+        if (changedName !== null && changedName !== fileName && changedName !== `${fileName}.tmp`)
+            return;
+        if (debounceTimer)
+            clearTimeout(debounceTimer);
+        debounceTimer = setTimeout(() => {
+            void evaluate();
+        }, debounceMs);
+        debounceTimer.unref?.();
+    }, () => {
+        // The store dir may not exist yet, or the watcher died after creation (EMFILE, dir
+        // removed, etc). The lane gate (G8) and land CAS (G3) still fail closed at the next
+        // tool call regardless -- this watcher is a promptness optimization only, so on error
+        // we simply stop watching rather than retry; correctness never depended on it.
+    });
+    return {
+        stop() {
+            stopped = true;
+            if (debounceTimer)
+                clearTimeout(debounceTimer);
+            watcher?.close();
+        },
+    };
+}
+//# sourceMappingURL=watcher.js.map

package/dist/core/worktree-sync/watcher.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"watcher.js","sourceRoot":"","sources":["../../../src/core/worktree-sync/watcher.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Epoch watcher for lane-bound sessions: the prompt-awareness half of \"perfect sync\". Watches\n * the shared `epoch.json` (fs.watch on its directory -- the file is replaced by rename) and, on\n * an epoch advance by ANOTHER lane, injects one deterministic staleness notice through the host's\n * message seam. Enforcement never rides on this watcher -- the lane gate (G8) and the land CAS\n * (G3) fail closed even if it dies; this only makes lanes learn promptly instead of at their\n * next tool call.\n */\n\nimport { readFile } from \"node:fs/promises\";\nimport { basename, dirname } from \"node:path\";\nimport { watchWithErrorHandler } from \"../../utils/fs-watch.ts\";\nimport type { WorktreeSyncEpoch } from \"./codes.ts\";\n\nexport interface EpochWatcherConfig {\n\tepochFile: string;\n\t/** The lane this session is bound to: lands BY this lane never notify it. */\n\tlaneKey: string;\n\tnotify: (text: string) => void;\n\t/** Debounce for rename/change event bursts. */\n\tdebounceMs?: number;\n}\n\nexport interface EpochWatcherHandle {\n\tstop(): void;\n}\n\nasync function readEpochFile(epochFile: string): Promise<WorktreeSyncEpoch | undefined> {\n\ttry {\n\t\treturn JSON.parse(await readFile(epochFile, \"utf-8\")) as WorktreeSyncEpoch;\n\t} catch {\n\t\treturn undefined;\n\t}\n}\n\n/** Deterministic notice text -- assembled from epoch facts, never model-generated. */\nexport function formatEpochNotice(epoch: WorktreeSyncEpoch, laneKey: string): string {\n\tconst changed =\n\t\tepoch.changedPaths.length > 0\n\t\t\t? `${epoch.changedPaths.slice(0, 10).join(\", \")}${epoch.changedPaths.length > 10 || epoch.changedPathsTruncated ? \", ...\" : \"\"}`\n\t\t\t: \"(no files listed)\";\n\treturn [\n\t\t`worktree-sync: main advanced to epoch ${epoch.epoch}`,\n\t\t`${epoch.landedLaneKey ? ` (landed by lane '${epoch.landedLaneKey}')` : \"\"}.`,\n\t\t` Changed: ${changed}.`,\n\t\t` Your lane '${laneKey}' must rebase main before further mutations/landing:`,\n\t\t` call worktree_sync {\"action\":\"sync\"} now, resolve any conflicts locally, then continue working.`,\n\t].join(\"\");\n}\n\n/**\n * Start watching. The initial epoch is read once as the baseline; only ADVANCES past it notify\n * (a fresh session never gets a notice for history). fs.watch is backed by a low-frequency\n * poll re-read on each event burst only -- no timers run while the store is quiet.\n */\nexport function startEpochWatcher(config: EpochWatcherConfig): EpochWatcherHandle {\n\tconst debounceMs = config.debounceMs ?? 250;\n\tlet lastSeenEpoch: number | undefined;\n\tlet debounceTimer: NodeJS.Timeout | undefined;\n\tlet stopped = false;\n\n\tconst evaluate = async (): Promise<void> => {\n\t\tif (stopped) return;\n\t\tconst epoch = await readEpochFile(config.epochFile);\n\t\tif (!epoch) return;\n\t\tif (lastSeenEpoch === undefined) {\n\t\t\tlastSeenEpoch = epoch.epoch;\n\t\t\treturn;\n\t\t}\n\t\tif (epoch.epoch <= lastSeenEpoch) return;\n\t\tlastSeenEpoch = epoch.epoch;\n\t\tif (epoch.landedLaneKey === config.laneKey) return;\n\t\tconfig.notify(formatEpochNotice(epoch, config.laneKey));\n\t};\n\n\t// Baseline read; any event after this compares against it.\n\tvoid evaluate();\n\n\tconst fileName = basename(config.epochFile);\n\t// watchWithErrorHandler canonicalizes the watched dir (realpathSync.native) before calling\n\t// fs.watch -- on Windows, a non-canonical (e.g. 8.3 short-form) path here hard-aborts the\n\t// process via libuv's fs-event assertion. It also attaches an 'error' listener so an async\n\t// watcher failure (EMFILE, dir removed, etc.) can never surface as an unhandled exception.\n\tconst watcher = watchWithErrorHandler(\n\t\tdirname(config.epochFile),\n\t\t(_eventType, changedName) => {\n\t\t\tif (stopped) return;\n\t\t\tif (changedName !== null && changedName !== fileName && changedName !== `${fileName}.tmp`) return;\n\t\t\tif (debounceTimer) clearTimeout(debounceTimer);\n\t\t\tdebounceTimer = setTimeout(() => {\n\t\t\t\tvoid evaluate();\n\t\t\t}, debounceMs);\n\t\t\tdebounceTimer.unref?.();\n\t\t},\n\t\t() => {\n\t\t\t// The store dir may not exist yet, or the watcher died after creation (EMFILE, dir\n\t\t\t// removed, etc). The lane gate (G8) and land CAS (G3) still fail closed at the next\n\t\t\t// tool call regardless -- this watcher is a promptness optimization only, so on error\n\t\t\t// we simply stop watching rather than retry; correctness never depended on it.\n\t\t},\n\t);\n\n\treturn {\n\t\tstop() {\n\t\t\tstopped = true;\n\t\t\tif (debounceTimer) clearTimeout(debounceTimer);\n\t\t\twatcher?.close();\n\t\t},\n\t};\n}\n"]}

package/dist/index.d.ts

@@ -5,21 +5,31 @@ export { getAgentDir, VERSION } from "./config.ts";
 export { AgentSession, type AgentSessionConfig, type AgentSessionEvent, type AgentSessionEventListener, type ModelCycleResult, type ParsedSkillBlock, type PromptOptions, parseSkillBlock, type SessionStats, } from "./core/agent-session.ts";
 export { type ApiKeyCredential, type AuthCredential, type AuthStatus, AuthStorage, type AuthStorageBackend, FileAuthStorageBackend, InMemoryAuthStorageBackend, type OAuthCredential, } from "./core/auth-storage.ts";
 export { createEventBus, type EventBus, type EventBusController } from "./core/event-bus.ts";
-export type { AgentEndEvent, AgentStartEvent, AgentToolResult, AgentToolUpdateCallback, AppKeybinding, AutocompleteProviderFactory, BashToolCallEvent, BeforeAgentStartEvent, BeforeAgentStartEventResult, BeforeProviderRequestEvent, BeforeProviderRequestEventResult, BuildSystemPromptOptions, CompactOptions, ContextEvent, ContextUsage, CustomToolCallEvent, EditToolCallEvent, ExecOptions, ExecResult, Extension, ExtensionActions, ExtensionAPI, ExtensionCommandContext, ExtensionCommandContextActions, ExtensionContext, ExtensionContextActions, ExtensionError, ExtensionEvent, ExtensionFactory, ExtensionFlag, ExtensionHandler, ExtensionRuntime, ExtensionShortcut, ExtensionUIContext, ExtensionUIDialogOptions, ExtensionWidgetOptions, FindToolCallEvent, GrepToolCallEvent, InputEvent, InputEventResult, InputSource, KeybindingsManager, LoadExtensionsResult, LsToolCallEvent, MessageRenderer, MessageRenderOptions, ProviderConfig, ProviderModelConfig, ReadToolCallEvent, RegisteredCommand, RegisteredTool, ResolvedCommand, SessionBeforeCompactEvent, SessionBeforeForkEvent, SessionBeforeSwitchEvent, SessionBeforeTreeEvent, SessionCompactEvent, SessionShutdownEvent, SessionStartEvent, SessionTreeEvent, SlashCommandInfo, SlashCommandSource, SourceInfo, TerminalInputHandler, ToolCallEvent, ToolCallEventResult, ToolDefinition, ToolExecutionMode, ToolInfo, ToolRenderResultOptions, ToolResultEvent, TurnEndEvent, TurnStartEvent, UserBashEvent, UserBashEventResult, WidgetPlacement, WorkingIndicatorOptions, WriteToolCallEvent, } from "./core/extensions/index.ts";
+export type { AgentEndEvent, AgentStartEvent, AgentToolResult, AgentToolUpdateCallback, AppKeybinding, AutocompleteProviderFactory, BashToolCallEvent, BeforeAgentStartEvent, BeforeAgentStartEventResult, BeforeProviderRequestEvent, BeforeProviderRequestEventResult, BuildSystemPromptOptions, CompactOptions, ContextEvent, ContextUsage, CustomToolCallEvent, EditToolCallEvent, ExecOptions, ExecResult, Extension, ExtensionActions, ExtensionAPI, ExtensionCommandContext, ExtensionCommandContextActions, ExtensionContext, ExtensionContextActions, ExtensionError, ExtensionEvent, ExtensionFactory, ExtensionFlag, ExtensionHandler, ExtensionRuntime, ExtensionShortcut, ExtensionStorage, ExtensionUIContext, ExtensionUIDialogOptions, ExtensionWidgetOptions, ExtensionWorkRunOptions, FindToolCallEvent, GrepToolCallEvent, InputEvent, InputEventResult, InputSource, KeybindingsManager, LoadExtensionsResult, LsToolCallEvent, MessageRenderer, MessageRenderOptions, ProviderConfig, ProviderModelConfig, ReadToolCallEvent, RegisteredCommand, RegisteredTool, ResolvedCommand, SessionBeforeCompactEvent, SessionBeforeForkEvent, SessionBeforeSwitchEvent, SessionBeforeTreeEvent, SessionCompactEvent, SessionShutdownEvent, SessionStartEvent, SessionTreeEvent, SlashCommandInfo, SlashCommandSource, SourceInfo, TerminalInputHandler, ToolCallEvent, ToolCallEventResult, ToolDefinition, ToolExecutionMode, ToolInfo, ToolRenderResultOptions, ToolResultEvent, TurnEndEvent, TurnStartEvent, UserBashEvent, UserBashEventResult, WidgetPlacement, WorkingIndicatorOptions, WriteToolCallEvent, } from "./core/extensions/index.ts";
 export { createExtensionRuntime, defineTool, discoverAndLoadExtensions, ExtensionRunner, isBashToolResult, isEditToolResult, isFindToolResult, isGrepToolResult, isLsToolResult, isReadToolResult, isToolCallEventType, isWriteToolResult, wrapRegisteredTool, wrapRegisteredTools, } from "./core/extensions/index.ts";
 export type { ReadonlyFooterDataProvider } from "./core/footer-data-provider.ts";
 export { appendRunRecord, type ConfidenceMode, type ConfidenceResult, cleanupImprovementSandbox, compareMetric, computeMadConfidence, createImprovementDecisionTool, createImprovementLoopTool, createImprovementSandbox, decideImprovement, exportImprovementSandboxPatch, type GitStatusEntry, type ImprovementDecision, type ImprovementDecisionInput, type ImprovementDecisionReason, type ImprovementDecisionResult, type ImprovementLoopConfig, type ImprovementLoopExec, type ImprovementLoopInitInput, type ImprovementLoopPaths, type ImprovementLoopRecordInput, type ImprovementLoopState, type ImprovementLoopStatusInput, type ImprovementLoopToolAction, type ImprovementLoopToolDetails, type ImprovementMeasurementCommandResult, type ImprovementMeasurementResult, type ImprovementRunRecord, type ImprovementSandboxCleanupInput, type ImprovementSandboxCreateInput, type ImprovementSandboxExportInput, type ImprovementSandboxRecord, improvementLoopPaths, initImprovementLoop, type LowConfidenceAction, type MetricComparison, type MetricDirection, median, medianAbsoluteDeviation, metricMapFromOutput, type OwnedDiscardPlan, type OwnedDiscardPlanInput, parseGitPorcelainStatus, parseMetricLines, planOwnedDiscard, readImprovementLoopState, readRunRecords, recordImprovementRun, runImprovementMeasurement, selectPrimaryMetric, serializeRunRecord, } from "./core/improvement-loop.ts";
 export { ModelRegistry } from "./core/model-registry.ts";
+export * from "./core/orchestration/capability-gateway.ts";
+export * from "./core/orchestration/contracts.ts";
+export * from "./core/orchestration/event-store.ts";
+export * from "./core/orchestration/model-binding.ts";
+export * from "./core/orchestration/policy-compiler.ts";
+export * from "./core/orchestration/profile-registry.ts";
+export * from "./core/orchestration/profile-store.ts";
+export * from "./core/orchestration/task-runtime.ts";
 export type { PackageManager, PathMetadata, ProgressCallback, ProgressEvent, ResolvedPaths, ResolvedResource, } from "./core/package-manager.ts";
 export { DefaultPackageManager } from "./core/package-manager.ts";
+export { PI_ORCHESTRATION_AGENT_ID_ENV } from "./core/process-identity.ts";
 export { ACTIVE_TURN_TTL_MS, AUTO_RELOAD_COORDINATOR_TTL_MS, describeReloadSession, getPendingReloadBlockers, getReloadCoordinationDir, isReloadSessionProcessAlive, type PendingReloadBlockers, type ReloadBlockerOptions, type ReloadSessionRecord, } from "./core/reload-blockers.ts";
 export type { ResourceCollision, ResourceDiagnostic, ResourceLoader } from "./core/resource-loader.ts";
 export { DefaultResourceLoader, loadProjectContextFiles } from "./core/resource-loader.ts";
 export { mergeResourceProfileMap, mergeResourceProfileSettings, parseResourceProfileBlocks, parseResourceProfileInput, parseResourceProfileJson, stripResourceProfileBlocks, } from "./core/resource-profile-blocks.ts";
-export { AgentSessionRuntime, type AgentSessionRuntimeDiagnostic, type AgentSessionServices, type CreateAgentSessionFromServicesOptions, type CreateAgentSessionOptions, type CreateAgentSessionResult, type CreateAgentSessionRuntimeFactory, type CreateAgentSessionRuntimeResult, type CreateAgentSessionServicesOptions, createAgentSession, createAgentSessionFromServices, createAgentSessionRuntime, createAgentSessionServices, createBashTool, createCodingTools, createEditTool, createFindTool, createGrepTool, createLsTool, createReadOnlyTools, createReadTool, createWriteTool, type PromptTemplate, } from "./core/sdk.ts";
+export { AgentSessionRuntime, type AgentSessionRuntimeDiagnostic, type AgentSessionRuntimeResource, type AgentSessionServices, type AgentSessionSwitchOptions, type CreateAgentSessionFromServicesOptions, type CreateAgentSessionOptions, type CreateAgentSessionResult, type CreateAgentSessionRuntimeFactory, type CreateAgentSessionRuntimeResult, type CreateAgentSessionServicesOptions, createAgentSession, createAgentSessionFromServices, createAgentSessionRuntime, createAgentSessionServices, createBashTool, createCodingTools, createEditTool, createFindTool, createGrepTool, createLsTool, createReadOnlyTools, createReadTool, createWriteTool, type PromptTemplate, SessionReplacementCallbackError, SessionReplacementRuntimeError, } from "./core/sdk.ts";
 export { type CompactionSettings, type DirectoryResourceProfileInfo, getDirectoryResourceProfileInfo, type ImageSettings, matchesResourceProfilePattern, type PackageSource, type ResourceProfileFilterSettings, type ResourceProfileKind, type ResourceProfileSettings, type RetrySettings, SettingsManager, type SettingsManagerCreateOptions, } from "./core/settings-manager.ts";
 export { formatSkillsForPrompt, type LoadSkillsFromDirOptions, type LoadSkillsResult, loadSkills, loadSkillsFromDir, type Skill, type SkillFrontmatter, } from "./core/skills.ts";
 export { createSyntheticSourceInfo } from "./core/source-info.ts";
+export { type AskQuestion, type AskQuestionAnswer, AskQuestionDialog, type AskQuestionStopReason, type AskQuestionToolDetails, type AskQuestionToolInput, type AskQuestionToolOptions, createAskQuestionToolDefinition, } from "./core/tools/ask-question.ts";
 export { type BashOperations, type BashSpawnContext, type BashSpawnHook, type BashToolDetails, type BashToolInput, type BashToolOptions, createBashToolDefinition, createEditToolDefinition, createFindToolDefinition, createGrepToolDefinition, createLocalBashOperations, createLsToolDefinition, createReadToolDefinition, createWriteToolDefinition, DEFAULT_MAX_BYTES, DEFAULT_MAX_LINES, type EditOperations, type EditToolDetails, type EditToolInput, type EditToolOptions, type FindOperations, type FindToolDetails, type FindToolInput, type FindToolOptions, formatSize, type GrepOperations, type GrepToolDetails, type GrepToolInput, type GrepToolOptions, type LsOperations, type LsToolDetails, type LsToolInput, type LsToolOptions, type ReadOperations, type ReadToolDetails, type ReadToolInput, type ReadToolOptions, type ToolsOptions, type TruncationOptions, type TruncationResult, truncateHead, truncateLine, truncateTail, type WriteOperations, type WriteToolInput, type WriteToolOptions, withFileMutationQueue, } from "./core/tools/index.ts";
 export { jaccard, runSkillAudit, type SkillAuditReport, type SkillSummary, tokenize, } from "./core/tools/skill-audit.ts";
 export { hasProjectTrustInputs, type ProjectTrustDecision, ProjectTrustStore } from "./core/trust-manager.ts";
@@ -32,5 +42,5 @@ export { parseFrontmatter, stripFrontmatter } from "./utils/frontmatter.ts";
 export { convertToPng } from "./utils/image-convert.ts";
 export { formatDimensionNote, type ResizedImage, resizeImage } from "./utils/image-resize.ts";
 export { getShellConfig } from "./utils/shell.ts";
-export { type AcquireWorkRunOptions, acquireWorkRun, createWorkRunId, getProcessWorkRun, getWorkRoot, getWorkRunDir, getWorkTenantDir, PI_WORK_ROOT_ENV, pruneWorkTenant, type WorkRetentionOptions, type WorkRunLease, } from "./utils/work-directory.ts";
+export { type AcquireWorkRunOptions, acquireWorkRun, assertPortablePathSegment, boundedWorkRetention, createWorkRunId, getProcessWorkRun, getWorkRoot, getWorkRunDir, getWorkTenantDir, PI_WORK_ROOT_ENV, pruneWorkTenant, type WorkRetentionOptions, type WorkRunLease, } from "./utils/work-directory.ts";
 //# sourceMappingURL=index.d.ts.map