@zq-silk/yui 2.3.0 → 2.5.0

package/dist/repository/gitWorkspace.js

@@ -5,7 +5,13 @@ import { dirname, isAbsolute, join, relative, resolve } from "node:path";
 import { promisify } from "node:util";
 import { cleanupFailure } from "../workspace/cleanupInspection.js";
 import { externalProgramConfigViolations } from "../artifacts/managedGit.js";
+import { compatibleGitArguments, gitOutputLine, supportedGit } from "./gitCompatibility.js";
+import { gitPath, readGitWorktrees } from "./gitWorktreeInventory.js";
 const executeFile = promisify(execFile);
+const isolatedFetchOptions = [
+    "--no-tags", "--no-prune", "--no-prune-tags", "--no-recurse-submodules",
+    "--no-auto-gc", "--no-write-commit-graph", "--no-write-fetch-head", "--refmap="
+];
 /** Observed partial effects, not a rollback or permission to replay a refresh. */
 export class GitWorkspaceRefreshError extends Error {
     result;
@@ -160,13 +166,13 @@ export class NodeGitWorkspace {
         const remote = safeRemote(input.remoteUrl);
         const configuredBranch = await safeFetchBranch(input.branch);
         const branch = configuredBranch === "HEAD"
-            ? await resolveRemoteHeadBranch(remote)
+            ? await resolveRemoteHeadBranch(remote, repositoryPath)
             : configuredBranch;
         const fetchedRef = remoteBaselineRef(remote, branch);
         try {
             await git([
                 "-C", repositoryPath,
-                "fetch", "--no-tags", "--no-write-fetch-head",
+                "fetch", ...isolatedFetchOptions,
                 remote,
                 `refs/heads/${branch}:${fetchedRef}`
             ]);
@@ -212,8 +218,7 @@ export class NodeGitWorkspace {
             // An empty refmap disables opportunistic tracking updates even when the
             // Project URL is a named remote. Ignore configured prune/submodule effects.
             await git([
-                "-C", initial.root, "fetch", "--no-tags", "--no-prune", "--no-prune-tags",
-                "--no-recurse-submodules", "--no-auto-maintenance", "--no-write-fetch-head", "--refmap=",
+                "-C", initial.root, "fetch", ...isolatedFetchOptions,
                 remote, `refs/heads/${stableBranch}:${temporaryRef}`
             ]);
             fetchedCommit = await resolveFetchedCommit(initial.root, temporaryRef);
@@ -239,11 +244,11 @@ export class NodeGitWorkspace {
                 // Verify the stable branch and CAS the one configured destination in
                 // the same Git transaction. HEAD/index/worktree still use normal ff.
                 await git(["-C", initial.root, "update-ref", "--stdin"], { input: [
-                        "start", "option no-deref",
+                        "option no-deref",
                         `verify refs/heads/${stableBranch} ${fetchedCommit}`,
                         "option no-deref",
                         `update ${mapping.ref} ${fetchedCommit} ${old}`,
-                        "prepare", "commit", ""
+                        ""
                     ].join("\n") });
                 tracking = {
                     status: previous === fetchedCommit ? "current" : "updated",
@@ -305,15 +310,15 @@ export class NodeGitWorkspace {
     async resolveRemoteBaseline(input) {
         const remote = safeRemote(input.remoteUrl);
         const configuredRef = await safeFetchBranch(input.developmentRef);
+        const repository = await this.inspect(input.repositoryPath, "HEAD");
         const branch = configuredRef === "HEAD"
-            ? await resolveRemoteHeadBranch(remote)
+            ? await resolveRemoteHeadBranch(remote, repository.root)
             : configuredRef;
-        const repository = await this.inspect(input.repositoryPath, "HEAD");
         const temporaryRef = remoteBaselineRef(remote, branch);
         try {
             await git([
                 "-C", repository.root,
-                "fetch", "--no-tags", "--no-write-fetch-head",
+                "fetch", ...isolatedFetchOptions,
                 remote,
                 `refs/heads/${branch}:${temporaryRef}`
             ]);
@@ -321,7 +326,7 @@ export class NodeGitWorkspace {
                 "-C", repository.root,
                 "rev-parse", "--verify", "--end-of-options", `${temporaryRef}^{commit}`
             ]);
-            const advertisedCommit = await resolveRemoteBranchCommit(remote, branch);
+            const advertisedCommit = await resolveRemoteBranchCommit(remote, branch, repository.root);
             if (fetchedCommit.toLowerCase() !== advertisedCommit) {
                 throw new Error(`Project remote development branch changed while it was fetched: ${branch}.`);
             }
@@ -341,8 +346,10 @@ export class NodeGitWorkspace {
         }
     }
     async clone(input) {
+        supportedGit();
         const remote = safeRemote(input.remoteUrl);
-        const destination = resolve(requireText(input.destination, "Project destination"));
+        requireText(input.destination, "Project destination");
+        const destination = resolve(input.destination);
         if (await pathKind(destination) !== undefined) {
             throw new Error(`Project destination already exists: ${destination}.`);
         }
@@ -415,10 +422,8 @@ export class NodeGitWorkspace {
     async inspect(repositoryPath, baseRef = "HEAD") {
         const requested = await canonicalDirectory(repositoryPath, "Project");
         const ref = safeRef(baseRef);
-        const root = await canonicalDirectory(await gitLine(["-C", requested, "rev-parse", "--show-toplevel"]), "Project root");
-        const gitDirectory = await canonicalDirectory(await gitLine([
-            "-C", root, "rev-parse", "--path-format=absolute", "--git-common-dir"
-        ]), "Git common directory");
+        const root = await canonicalDirectory(await gitPath(requested, ["--show-toplevel"]), "Project root");
+        const gitDirectory = await canonicalDirectory(await gitPath(root, ["--git-common-dir"]), "Git common directory");
         const baseCommit = await gitLine([
             "-C", root, "rev-parse", "--verify", "--end-of-options", `${ref}^{commit}`
         ]);
@@ -485,7 +490,7 @@ export class NodeGitWorkspace {
                 const importedRef = `${importRoot}/${index}`;
                 await git([
                     "-C", destination.root,
-                    "fetch", "--no-tags", "--no-write-fetch-head", "--",
+                    "fetch", ...isolatedFetchOptions, "--",
                     source.root, `${snapshot.ref}:${importedRef}`
                 ]);
                 const imported = await resolveRefCommit(destination.root, importedRef);
@@ -567,36 +572,11 @@ export class NodeGitWorkspace {
         const excluded = input.excludeWorktreePath === undefined
             ? undefined
             : await realpath(resolve(input.excludeWorktreePath)).catch(() => undefined);
-        const porcelain = await git(["-C", root, "worktree", "list", "--porcelain"]);
-        const records = [];
-        let current = { prunable: false };
-        for (const line of porcelain.split("\n")) {
-            if (line.length === 0) {
-                const path = current.path;
-                if (path !== undefined) {
-                    records.push({ path, branch: current.branch, prunable: current.prunable });
-                }
-                current = { prunable: false };
-                continue;
-            }
-            if (line.startsWith("worktree ")) {
-                current.path = line.slice("worktree ".length);
-            }
-            else if (line.startsWith("branch ")) {
-                current.branch = line.slice("branch ".length);
-            }
-            else if (line.startsWith("prunable")) {
-                current.prunable = true;
-            }
-        }
-        const lastPath = current.path;
-        if (lastPath !== undefined) {
-            records.push({ path: lastPath, branch: current.branch, prunable: current.prunable });
-        }
+        const records = await readGitWorktrees(root);
         for (const record of records) {
             // A dead registration (its directory is gone) occupies nothing; a
             // worktree on another ref or a detached HEAD does not occupy this one.
-            if (record.prunable || record.branch !== wanted)
+            if ((record.prunable && !record.locked) || record.branch !== wanted)
                 continue;
             // git reports canonical absolute paths; compare canonicals so a
             // symlinked workspace root cannot make the recorded worktree look
@@ -724,11 +704,7 @@ export class NodeGitWorkspace {
     }
     async listWorktrees(repositoryPath) {
         const root = await canonicalDirectory(repositoryPath, "Project");
-        const output = await git(["-C", root, "worktree", "list", "--porcelain"]);
-        return output
-            .split(/\r?\n/u)
-            .filter((line) => line.startsWith("worktree "))
-            .map((line) => line.slice("worktree ".length).trim());
+        return (await readGitWorktrees(root)).map(entry => entry.path);
     }
     async listCommitsBetween(input) {
         const root = await canonicalDirectory(input.repositoryPath, "Project");
@@ -919,9 +895,8 @@ export class NodeGitWorkspace {
         await assertExpectedBranch(expected, input.branch);
         if (!await this.inspectClean(expected))
             return "dirty";
-        const worktrees = (await git(["-C", expected, "worktree", "list", "--porcelain", "-z"]))
-            .split("\0").filter(line => line.startsWith("worktree "));
-        if (worktrees.length !== 1 || worktrees[0] !== `worktree ${expected}`) {
+        const worktrees = await readGitWorktrees(expected);
+        if (worktrees.length !== 1 || worktrees[0].path !== expected) {
             cleanupFailure("git-worktree-registrations", "Task clone still owns Git worktree registrations; retained.", 1, worktrees.length);
         }
         return "clean";
@@ -1051,16 +1026,14 @@ async function removeMissingWorktreeRegistration(repositoryRoot, path, branch, a
     await git(["-C", repositoryRoot, "worktree", "remove", "--force", "--", path]);
 }
 async function inspectMissingWorktreeRegistration(repositoryRoot, path, branch, allowDetached = false) {
-    const records = (await git(["-C", repositoryRoot, "worktree", "list", "--porcelain", "-z"])).split("\0\0");
-    const fields = records.map(record => record.split("\0")).find(record => record.includes(`worktree ${path}`));
-    if (fields === undefined)
+    const entry = (await readGitWorktrees(repositoryRoot)).find(record => record.path === path);
+    if (entry === undefined)
         return false;
-    const pinnedDetached = allowDetached && fields.includes("detached")
+    const pinnedDetached = allowDetached && entry.detached
         && await gitSucceeds(["-C", repositoryRoot, "show-ref", "--verify", "--quiet", `refs/heads/${branch}`])
-        && fields.includes(`HEAD ${await resolveRefCommit(repositoryRoot, `refs/heads/${branch}`)}`);
-    if ((!fields.includes(`branch refs/heads/${branch}`) && !pinnedDetached) || fields.some(field => field.startsWith("locked"))) {
-        cleanupFailure("git-registration-mismatch", "Missing worktree has uncertain or locked Git ownership; metadata retained.", { branch, locked: false }, { branch: fields.find(field => field.startsWith("branch "))?.slice(7) ?? null,
-            locked: fields.some(field => field.startsWith("locked")) });
+        && entry.head === await resolveRefCommit(repositoryRoot, `refs/heads/${branch}`);
+    if ((entry.branch !== `refs/heads/${branch}` && !pinnedDetached) || entry.locked) {
+        cleanupFailure("git-registration-mismatch", "Missing worktree has uncertain or locked Git ownership; metadata retained.", { branch, locked: false }, { branch: entry.branch ?? null, locked: entry.locked });
     }
     return true;
 }
@@ -1103,8 +1076,7 @@ async function assertExpectedBranch(path, expected, allowRebase = false) {
         // Rebase temporarily detaches HEAD. Git's per-worktree metadata must still
         // identify this exact Integration branch; unrelated detachment is invalid.
         for (const backend of ["rebase-merge", "rebase-apply"]) {
-            const headNamePath = await gitLine(["-C", path, "rev-parse", "--path-format=absolute",
-                "--git-path", `${backend}/head-name`]);
+            const headNamePath = await gitPath(path, ["--git-path", `${backend}/head-name`]);
             let headName;
             try {
                 headName = (await readFile(headNamePath, "utf8")).trim();
@@ -1135,10 +1107,10 @@ async function assertOwnedWorktree(project, container, path) {
     assertContained(container, canonicalPath);
     if (canonicalPath !== path)
         throw new Error("Managed worktree resolves through a symbolic link.");
-    const root = await canonicalDirectory(await gitLine(["-C", path, "rev-parse", "--show-toplevel"]), "Managed worktree root");
+    const root = await canonicalDirectory(await gitPath(path, ["--show-toplevel"]), "Managed worktree root");
     if (root !== path)
         throw new Error("Managed worktree root does not match its deterministic path.");
-    const common = await canonicalDirectory(await gitLine(["-C", path, "rev-parse", "--path-format=absolute", "--git-common-dir"]), "Managed Git common directory");
+    const common = await canonicalDirectory(await gitPath(path, ["--git-common-dir"]), "Managed Git common directory");
     if (common !== project.gitDirectory) {
         cleanupFailure("workspace-identity-mismatch", "Managed worktree belongs to another project.", "Task main Git common directory", "different Git common directory");
     }
@@ -1162,7 +1134,7 @@ async function inspectExactRecordedWorktree(input) {
     if (path !== expectedPath) {
         throw new Error("Recorded managed worktree resolves through a symbolic link.");
     }
-    const root = await canonicalDirectory(await gitLine(["-C", path, "rev-parse", "--show-toplevel"]), "Recorded managed worktree root");
+    const root = await canonicalDirectory(await gitPath(path, ["--show-toplevel"]), "Recorded managed worktree root");
     if (root !== path) {
         throw new Error("Recorded managed worktree root does not match its deterministic path.");
     }
@@ -1170,7 +1142,7 @@ async function inspectExactRecordedWorktree(input) {
     if (branch !== input.branch) {
         throw new Error(`Recorded managed worktree is on an unexpected branch: ${branch}.`);
     }
-    const gitDirectory = await canonicalDirectory(await gitLine(["-C", path, "rev-parse", "--path-format=absolute", "--git-common-dir"]), "Recorded managed Git common directory");
+    const gitDirectory = await canonicalDirectory(await gitPath(path, ["--git-common-dir"]), "Recorded managed Git common directory");
     const destination = await new NodeGitWorkspace().inspect(input.repositoryPath);
     const head = await resolveRefCommit(path, "HEAD");
     const retained = await resolveRefCommit(destination.root, `refs/heads/${input.branch}`);
@@ -1267,8 +1239,8 @@ async function cleanupContainer(path) {
     }
 }
 async function canonicalDirectory(path, label) {
-    const value = requireText(path, label);
-    const canonical = await realpath(isAbsolute(value) ? value : resolve(value));
+    requireText(path, label);
+    const canonical = await realpath(isAbsolute(path) ? path : resolve(path));
     return canonical;
 }
 function managedPath(container, directory) {
@@ -1307,7 +1279,7 @@ async function readWorktreeStatus(path) {
     return readStatusGit(path, ["status", "--porcelain=v1", "--untracked-files=all"]);
 }
 async function readStatusGit(path, args) {
-    return git(["--no-optional-locks", "-c", "core.fsmonitor=false",
+    return git(["--no-optional-locks", "-c", "core.fsmonitor=",
         "-c", "protocol.allow=never", "-c", "protocol.file.allow=never",
         "-C", path, ...args], { environment: { GIT_NO_LAZY_FETCH: "1" } });
 }
@@ -1353,8 +1325,10 @@ async function assertStatusProgramsAbsent(path) {
     }
 }
 async function git(args, options = {}) {
+    const program = supportedGit();
+    const invocation = compatibleGitArguments(args);
     try {
-        const execution = executeFile("git", [...args], {
+        const execution = executeFile(program.path, invocation, {
             encoding: "utf8",
             maxBuffer: 1024 * 1024,
             timeout: 30_000,
@@ -1375,6 +1349,7 @@ async function git(args, options = {}) {
     }
 }
 async function gitSucceeds(args) {
+    supportedGit();
     try {
         await git(args);
         return true;
@@ -1384,7 +1359,7 @@ async function gitSucceeds(args) {
     }
 }
 async function gitLine(args) {
-    const lines = (await git(args)).trimEnd().split("\n");
+    const lines = gitOutputLine(await git(args)).split("\n");
     if (lines.length !== 1 || lines[0]?.length === 0 || lines[0]?.includes("\0")) {
         throw new Error("Git returned invalid output.");
     }
@@ -1533,6 +1508,7 @@ function safeRef(value) {
     return ref;
 }
 async function safeFetchBranch(value) {
+    supportedGit();
     const configuredRef = safeRef(value);
     if (configuredRef === "HEAD")
         return configuredRef;
@@ -1624,7 +1600,8 @@ function isCommit(value) {
     return /^[a-f0-9]{40}(?:[a-f0-9]{24})?$/iu.test(value);
 }
 function safeRemote(value) {
-    const remote = requireText(value, "Git remote URL");
+    requireText(value, "Git remote URL");
+    const remote = value;
     if (remote.startsWith("-") || /[\r\n]/.test(remote)) {
         throw new Error("Git remote URL is invalid.");
     }

package/dist/repository/gitWorktreeInventory.js

@@ -0,0 +1,121 @@
+import { execFile } from "node:child_process";
+import { lstat, readFile, readdir, realpath } from "node:fs/promises";
+import { basename, dirname, join, resolve } from "node:path";
+import { promisify } from "node:util";
+import { gitOutputLine, supportedGit } from "./gitCompatibility.js";
+const execute = promisify(execFile);
+async function run(args) {
+    return (await execute(supportedGit().path, args, {
+        encoding: "utf8", timeout: 10_000, maxBuffer: 1024 * 1024
+    })).stdout;
+}
+export async function gitPath(cwd, args) {
+    return resolve(cwd, gitOutputLine(await run(["-C", cwd, "rev-parse", ...args])));
+}
+async function exists(path) {
+    try {
+        await lstat(path);
+        return true;
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return false;
+        throw error;
+    }
+}
+/**
+ * Old porcelain omits locks and does not delimit/quote arbitrary paths. Read
+ * Git's worktree administrative records instead. These are observations only:
+ * never write/prune them, and never infer ownership merely from a directory.
+ * Mutating consumers still check the recorded owner and ask Git to remove it.
+ */
+export async function readGitWorktrees(cwd) {
+    const common = await realpath(await gitPath(cwd, ["--git-common-dir"]));
+    const result = [];
+    // This is also Git's own main-worktree listing convention (including bare
+    // and separate-git-dir repositories), not a claim of managed ownership.
+    const main = basename(common) === ".git" ? dirname(common) : common;
+    result.push(await inspect(common, main, false));
+    const directory = join(common, "worktrees");
+    let entries;
+    try {
+        entries = await readdir(directory, { withFileTypes: true });
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return result;
+        throw error;
+    }
+    for (const entry of entries) {
+        if (!entry.isDirectory())
+            throw new Error(`Uncertain Git worktree administration: ${join(directory, entry.name)}; retained.`);
+        const admin = join(directory, entry.name);
+        const pointer = gitOutputLine(await readFile(join(admin, "gitdir"), "utf8"));
+        if (basename(pointer) !== ".git") {
+            throw new Error(`Invalid Git worktree back-pointer: ${admin}; retained.`);
+        }
+        // Relative back-pointers are based at the administrative directory,
+        // not the caller's cwd (Git's worktree.useRelativePaths setting).
+        const path = dirname(resolve(admin, pointer));
+        const adminCommon = await realpath(resolve(cwd, gitOutputLine(await run([
+            "-C", cwd, `--git-dir=${admin}`, "rev-parse", "--git-common-dir"
+        ]))));
+        if (adminCommon !== common)
+            throw new Error(`Git worktree common directory mismatch: ${admin}; retained.`);
+        if (await exists(path)) {
+            const actual = await realpath(await gitPath(path, ["--git-dir"]));
+            if (actual !== admin)
+                throw new Error(`Git worktree back-pointer mismatch: ${path}; retained.`);
+        }
+        result.push(await inspect(admin, path, true));
+    }
+    if (new Set(result.map(entry => entry.path)).size !== result.length) {
+        throw new Error("Duplicate Git worktree registrations; retained.");
+    }
+    return result;
+}
+async function inspect(admin, path, linked) {
+    // Ask Git rather than parsing HEAD: Git owns ref storage (including newer
+    // backends), symbolic resolution and per-worktree pseudorefs.
+    let branch;
+    try {
+        branch = gitOutputLine(await run([`--git-dir=${admin}`, "symbolic-ref", "--quiet", "HEAD"]));
+    }
+    catch (error) {
+        if (error.code !== 1)
+            throw error;
+    }
+    if (branch !== undefined && !branch.startsWith("refs/")) {
+        throw new Error(`Invalid Git worktree HEAD: ${admin}; retained.`);
+    }
+    let head;
+    try {
+        head = gitOutputLine(await run([`--git-dir=${admin}`, "rev-parse", "--verify", "HEAD"]));
+        if (!/^[a-f0-9]{40}(?:[a-f0-9]{24})?$/iu.test(head))
+            throw new Error("Invalid Git HEAD");
+    }
+    catch (error) {
+        // A genuinely unborn branch (main or linked) is valid discovery, not cleanup proof.
+        if (branch === undefined)
+            throw error;
+        try {
+            await run([`--git-dir=${admin}`, "show-ref", "--verify", "--quiet", branch]);
+        }
+        catch (missing) {
+            if (missing.code === 1) {
+                return {
+                    path, branch, detached: false, prunable: !await exists(path),
+                    locked: linked && await exists(join(admin, "locked"))
+                };
+            }
+            throw missing;
+        }
+        throw error;
+    }
+    return {
+        path, ...(head === undefined ? {} : { head }),
+        ...(branch === undefined ? {} : { branch }),
+        detached: branch === undefined, prunable: !await exists(path),
+        locked: linked && await exists(join(admin, "locked"))
+    };
+}

package/dist/repository/project.js

@@ -63,13 +63,17 @@ export function assertProjectActive(project, action) {
         throw new Error(`Project is retired and cannot ${action}: ${project.id}.`);
     }
 }
-export function addProjectKnowledge(project, id, title, body, now, provenance) {
+export function addProjectKnowledge(project, id, title, body, now, provenance, applicability = {}) {
     const timestamp = now.toISOString();
     const knowledge = {
-        schemaVersion: 1,
+        schemaVersion: 2,
+        version: 1,
+        history: [],
         id: requireIdentity(id, "Project knowledge id"),
         title: requireText(title, "Project knowledge title"),
         body: requireText(body, "Project knowledge body"),
+        ...(applicability.scope === undefined ? {} : { scope: requireText(applicability.scope, "Knowledge scope") }),
+        ...(applicability.expiresWhen === undefined ? {} : { expiresWhen: requireText(applicability.expiresWhen, "Knowledge expiry condition") }),
         status: "active",
         ...(provenance === undefined ? {} : { provenance: validateKnowledgeProvenance(provenance) }),
         createdAt: timestamp,
@@ -114,19 +118,34 @@ export function updateProjectKnowledge(project, id, patch, now) {
         if (entry.status === "retired") {
             throw new Error(`Project knowledge is retired: ${knowledgeId}.`);
         }
-        return {
-            ...entry,
+        const { scope: _scope, expiresWhen: _expiresWhen, ...base } = entry;
+        const scope = patch.scope === undefined ? entry.scope
+            : patch.scope === null ? undefined : requireText(patch.scope, "Knowledge scope");
+        const expiresWhen = patch.expiresWhen === undefined ? entry.expiresWhen
+            : patch.expiresWhen === null ? undefined : requireText(patch.expiresWhen, "Knowledge expiry condition");
+        const next = {
+            ...base,
+            ...(scope === undefined ? {} : { scope }),
+            ...(expiresWhen === undefined ? {} : { expiresWhen }),
             title: patch.title === undefined
                 ? entry.title
                 : requireText(patch.title, "Project knowledge title"),
             body: patch.body === undefined
                 ? entry.body
                 : requireText(patch.body, "Project knowledge body"),
+            ...(patch.provenance === undefined ? {} : { provenance: validateKnowledgeProvenance(patch.provenance) }),
             updatedAt: now.toISOString()
         };
+        if (next.title === entry.title && next.body === entry.body
+            && next.scope === entry.scope && next.expiresWhen === entry.expiresWhen
+            && JSON.stringify(next.provenance) === JSON.stringify(entry.provenance))
+            return entry;
+        return { ...next, version: entry.version + 1, history: [...entry.history, knowledgeRevision(entry)] };
     });
     if (!found)
         throw new Error(`Project knowledge not found: ${knowledgeId}.`);
+    if (knowledge.every((entry, index) => entry === project.knowledge[index]))
+        return project;
     return validateProject({ ...project, knowledge, updatedAt: now.toISOString() });
 }
 export function retireProjectKnowledge(project, id, now) {
@@ -136,31 +155,42 @@ export function retireProjectKnowledge(project, id, now) {
         if (entry.id !== knowledgeId)
             return entry;
         found = true;
+        if (entry.status === "retired")
+            return entry;
         return {
             ...entry,
+            version: entry.version + 1,
+            history: [...entry.history, knowledgeRevision(entry)],
             status: "retired",
             updatedAt: now.toISOString()
         };
     });
     if (!found)
         throw new Error(`Project knowledge not found: ${knowledgeId}.`);
+    if (knowledge.every((entry, index) => entry === project.knowledge[index]))
+        return project;
     return validateProject({ ...project, knowledge, updatedAt: now.toISOString() });
 }
+function knowledgeRevision(entry) {
+    const { schemaVersion: _schema, id: _id, history: _history, createdAt: _created, ...revision } = entry;
+    return revision;
+}
 /**
  * Stable dedup fingerprint for a promotion candidate. Two proposals with the
- * same source identity, title, and body are the same conclusion regardless of
- * who proposed them or when.
+ * same source, content, applicability and replacement intent are identical.
+ * Trim outer whitespace only; preserve case, internal whitespace and Unicode.
+ * A JSON tuple avoids collisions between user-supplied identity delimiters.
  */
 export function knowledgeProposalFingerprint(input) {
-    const sourceKey = [
-        input.projectId,
-        input.source.taskId,
-        input.source.decisionId ?? "",
-        input.source.milestoneId ?? "",
-        input.source.commitSha ?? ""
-    ].join("|");
+    const optional = (value) => value === undefined ? null : requireText(value, "Knowledge fingerprint field");
     return createHash("sha256")
-        .update(`${sourceKey}\u0000${input.title}\u0000${input.body}`)
+        .update(JSON.stringify([
+        "knowledge-proposal-v2", requireText(input.projectId, "Project id"),
+        requireText(input.source.taskId, "Source Task"), optional(input.source.decisionId),
+        optional(input.source.milestoneId), optional(input.source.commitSha),
+        requireText(input.title, "Knowledge title"), requireText(input.body, "Knowledge body"),
+        optional(input.scope), optional(input.expiresWhen), optional(input.supersedesKnowledgeId)
+    ]))
         .digest("hex");
 }
 /** Digest of the cited source evidence, so a later Agent can verify it. */
@@ -334,17 +364,18 @@ export function validateProject(project) {
     requireGitRef(project.developmentBranch, "Project development branch");
     const knowledgeIds = new Set();
     for (const entry of project.knowledge) {
-        if (entry.schemaVersion !== 1)
-            throw new Error("Project knowledge must use schemaVersion 1.");
+        if (entry.schemaVersion !== 2)
+            throw new Error("Project knowledge must use schemaVersion 2.");
         requireIdentity(entry.id, "Project knowledge id");
-        requireText(entry.title, "Project knowledge title");
-        requireText(entry.body, "Project knowledge body");
-        if (!["active", "retired"].includes(entry.status)) {
-            throw new Error("Project knowledge status is invalid.");
-        }
-        if (entry.provenance !== undefined) {
-            validateKnowledgeProvenance(entry.provenance);
+        validateKnowledgeRevision(entry);
+        if (!Array.isArray(entry.history) || entry.history.length !== entry.version - 1) {
+            throw new Error("Project knowledge history must contain every prior version.");
         }
+        entry.history.forEach((revision, index) => {
+            validateKnowledgeRevision(revision);
+            if (revision.version !== index + 1)
+                throw new Error("Project knowledge history is out of order.");
+        });
         requireTimestamp(entry.createdAt, "Project knowledge createdAt");
         requireTimestamp(entry.updatedAt, "Project knowledge updatedAt");
         if (knowledgeIds.has(entry.id))
@@ -363,6 +394,21 @@ export function validateProject(project) {
     requireTimestamp(project.updatedAt, "Project updatedAt");
     return project;
 }
+function validateKnowledgeRevision(entry) {
+    if (!Number.isSafeInteger(entry.version) || entry.version < 1)
+        throw new Error("Invalid knowledge version.");
+    requireText(entry.title, "Project knowledge title");
+    requireText(entry.body, "Project knowledge body");
+    if (entry.scope !== undefined)
+        requireText(entry.scope, "Knowledge scope");
+    if (entry.expiresWhen !== undefined)
+        requireText(entry.expiresWhen, "Knowledge expiry condition");
+    if (!["active", "retired"].includes(entry.status))
+        throw new Error("Project knowledge status is invalid.");
+    if (entry.provenance !== undefined)
+        validateKnowledgeProvenance(entry.provenance);
+    requireTimestamp(entry.updatedAt, "Project knowledge updatedAt");
+}
 function validateKnowledgeProvenance(provenance) {
     requireIdentity(provenance.taskId, "Knowledge provenance task id");
     if (provenance.decisionId !== undefined) {
@@ -394,8 +440,8 @@ function validateKnowledgeProvenance(provenance) {
     return provenance;
 }
 function validateKnowledgeProposal(proposal, projectId) {
-    if (proposal.schemaVersion !== 1) {
-        throw new Error("Knowledge proposal must use schemaVersion 1.");
+    if (proposal.schemaVersion !== 2) {
+        throw new Error("Knowledge proposal must use schemaVersion 2.");
     }
     requireIdentity(proposal.id, "Knowledge proposal id");
     if (proposal.projectId !== projectId) {
@@ -403,6 +449,9 @@ function validateKnowledgeProposal(proposal, projectId) {
     }
     requireText(proposal.title, "Knowledge proposal title");
     requireText(proposal.body, "Knowledge proposal body");
+    if (proposal.fingerprint !== knowledgeProposalFingerprint(proposal)) {
+        throw new Error("Knowledge proposal fingerprint does not match its content.");
+    }
     if (!["pending", "accepted", "rejected"].includes(proposal.status)) {
         throw new Error("Knowledge proposal status is invalid.");
     }

package/dist/resources/resourceDiscovery.js

@@ -10,6 +10,7 @@ import { execFile } from "node:child_process";
 import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
 import { basename, join, resolve } from "node:path";
 import { promisify } from "node:util";
+import { readGitWorktrees } from "../repository/gitWorktreeInventory.js";
 import { managedProjectPath } from "../repository/project.js";
 import { managedRuntimeRoot } from "../storage/homeLayout.js";
 import { isResourceQuarantinePath } from "./resourceRegistry.js";
@@ -54,8 +55,7 @@ export function parseGitWorktreePorcelain(output) {
 }
 async function listGitWorktrees(repositoryPath) {
     try {
-        const { stdout } = await executeFile("git", ["-C", repositoryPath, "worktree", "list", "--porcelain"], { timeout: 10_000 });
-        return parseGitWorktreePorcelain(stdout);
+        return await readGitWorktrees(repositoryPath);
     }
     catch (error) {
         throw new Error(`Failed to list Git worktrees for ${repositoryPath}: `