knodin 0.7.5 → 0.8.2

package/dist/src/execution-profile.js

@@ -22,12 +22,15 @@ function sandboxLiteral(value) {
 }
 function macosPolicy(repo, _executable) {
     const protectedRoots = ["/Users", "/Volumes", "/Network", "/private/tmp", "/private/var/folders"];
+    const protectedSubpaths = protectedRoots
+        .map((item) => `(subpath ${sandboxLiteral(item)})`)
+        .join(" ");
     return [
         "(version 1)",
         "(allow default)",
         "(deny network*)",
         "(deny process-fork)",
-        `(deny file-read* ${protectedRoots.map((item) => `(subpath ${sandboxLiteral(item)})`).join(" ")})`,
+        `(deny file-read* ${protectedSubpaths})`,
         "(deny file-write*)",
         `(allow file-read* file-write* (subpath ${sandboxLiteral(repo)}) (literal "/dev/null"))`,
     ].join(" ");
@@ -54,10 +57,10 @@ function unavailable(profile, warning) {
 }
 function validateProfile(profileName, value) {
     if (!value || typeof value !== "object")
-        throw new Error(`execution profile ${profileName} is invalid`);
+        throw new Error(`execution profile $profileNameis invalid`);
     const profile = value;
     if (!path.isAbsolute(profile.executable ?? ""))
-        throw new Error(`execution profile ${profileName}: executable must be absolute`);
+        throw new Error(`execution profile $profileName: executable must be absolute`);
     if (!Array.isArray(profile.args) ||
         profile.args.some((arg) => typeof arg !== "string" || arg.includes("\0")))
         throw new Error(`execution profile ${profileName}: args must be a NUL-free string array`);
@@ -161,13 +164,15 @@ export async function runExecutionProfile(options) {
         retain: true,
     });
     const finalReason = reason;
-    const status = finalReason === "timeout"
-        ? "timed-out"
-        : finalReason === "output-limit"
-            ? "output-limit"
-            : closed.code === 0
-                ? "completed"
-                : "failed";
+    // A non-zero exit only reads as "failed" once the bounded-run reasons that
+    // preempt it (deadline, output cap) have been ruled out.
+    let status;
+    if (finalReason === "timeout")
+        status = "timed-out";
+    else if (finalReason === "output-limit")
+        status = "output-limit";
+    else
+        status = closed.code === 0 ? "completed" : "failed";
     const result = {
         schemaVersion: 1,
         status,

package/dist/src/failure-diagnosis.js

@@ -540,6 +540,12 @@ function diagnosisStatus(resolvedCount, unresolvedCount, inputComplete, contextT
         return "partial";
     return "resolved";
 }
+/** No diagnostics means nothing was assessed; a partial status must not read as exact. */
+function confidenceLevel(diagnosticCount, status) {
+    if (diagnosticCount === 0)
+        return "refused";
+    return status === "resolved" ? "exact" : "qualified";
+}
 export async function diagnoseFailure(graph, repo, request) {
     const maxDiagnostics = integer("maxDiagnostics", request.maxDiagnostics, DEFAULT_DIAGNOSTICS, 1, MAX_DIAGNOSTICS);
     const diagnosticOffset = integer("diagnosticOffset", request.diagnosticOffset, 0, 0, 1_000_000);
@@ -620,7 +626,7 @@ export async function diagnoseFailure(graph, repo, request) {
         },
         freshness: health.freshness,
         confidence: {
-            level: diagnostics.length === 0 ? "refused" : status === "resolved" ? "exact" : "qualified",
+            level: confidenceLevel(diagnostics.length, status),
             reasons: confidenceReasons,
         },
         omissions: {

package/dist/src/graph-layout.js

@@ -0,0 +1,173 @@
+/**
+ * Deterministic force-directed layout.
+ *
+ * Coordinates are computed here, at artifact-generation time, rather than by a
+ * script in the rendered page. That keeps a generated artifact reproducible:
+ * the same graph over the same evidence lays out identically, so its SHA-256 is
+ * stable and the output is snapshot-testable. It also means the artifact needs
+ * no JavaScript and no external library, which keeps it self-contained.
+ *
+ * The simulation is a bounded Fruchterman-Reingold: repulsion between every
+ * pair, attraction along every edge, and a linearly decaying temperature that
+ * caps per-iteration displacement. Iteration count is fixed rather than
+ * convergence-driven so that runtime is a function of graph size alone.
+ */
+import { mulberry32, seedFromString } from "./deterministic-random.js";
+/** Square viewport side, in user units, that coordinates are fitted into. */
+const VIEWPORT = 1000;
+/** Fixed iteration count. Bounded work; not a convergence guarantee. */
+const ITERATIONS = 300;
+/** Fraction of the viewport a node may move on the first iteration. */
+const INITIAL_TEMPERATURE = 0.1;
+/** Minimum separation used when two nodes land on the same point. */
+const EPSILON = 0.01;
+/**
+ * Lays out `nodes` connected by `edges` inside a square viewport.
+ *
+ * `seed` should be derived from repository-scoped evidence (a commit id, say)
+ * so that unchanged evidence reproduces an identical layout. Edges naming a
+ * node that is not in `nodes` are ignored rather than throwing: callers cap
+ * node and edge counts independently, and a dangling edge is a truncation
+ * artifact, not a caller error.
+ */
+export function layoutGraph(nodes, edges, seed) {
+    if (nodes.length === 0)
+        return { positions: [], viewport: VIEWPORT };
+    if (nodes.length === 1) {
+        return {
+            positions: [{ id: nodes[0].id, x: VIEWPORT / 2, y: VIEWPORT / 2 }],
+            viewport: VIEWPORT,
+        };
+    }
+    const random = mulberry32(seedFromString(seed));
+    const index = new Map();
+    for (let position = 0; position < nodes.length; position++)
+        index.set(nodes[position].id, position);
+    // Seeded initial placement. A deterministic ring with a jittered radius
+    // avoids the degenerate all-collinear start that a pure grid produces.
+    const xs = new Float64Array(nodes.length);
+    const ys = new Float64Array(nodes.length);
+    for (let i = 0; i < nodes.length; i++) {
+        const angle = (2 * Math.PI * i) / nodes.length;
+        const radius = (VIEWPORT / 2) * (0.35 + 0.6 * random());
+        xs[i] = VIEWPORT / 2 + radius * Math.cos(angle);
+        ys[i] = VIEWPORT / 2 + radius * Math.sin(angle);
+    }
+    // Resolve edges to index pairs once; drop any endpoint we do not hold.
+    const links = [];
+    for (const edge of edges) {
+        const from = index.get(edge.from);
+        const to = index.get(edge.to);
+        if (from === undefined || to === undefined || from === to)
+            continue;
+        links.push([from, to]);
+    }
+    // Ideal edge length: spread nodes evenly over the viewport area.
+    const k = Math.sqrt((VIEWPORT * VIEWPORT) / nodes.length);
+    const dx = new Float64Array(nodes.length);
+    const dy = new Float64Array(nodes.length);
+    const state = { count: nodes.length, xs, ys, dx, dy };
+    for (let iteration = 0; iteration < ITERATIONS; iteration++) {
+        dx.fill(0);
+        dy.fill(0);
+        accumulateRepulsion(state, k);
+        accumulateAttraction(state, links, k);
+        // Linear cooling caps displacement and lets the layout settle.
+        applyDisplacement(state, VIEWPORT * INITIAL_TEMPERATURE * (1 - iteration / ITERATIONS));
+    }
+    return { positions: fitToViewport(nodes, xs, ys), viewport: VIEWPORT };
+}
+/**
+ * Repulsion between every pair. O(n^2): callers cap node count, and the cap is
+ * small enough that a Barnes-Hut tree would cost more than it saves.
+ */
+function accumulateRepulsion({ count, xs, ys, dx, dy }, k) {
+    for (let i = 0; i < count; i++) {
+        for (let j = i + 1; j < count; j++) {
+            let deltaX = xs[i] - xs[j];
+            let deltaY = ys[i] - ys[j];
+            let distance = Math.sqrt(deltaX * deltaX + deltaY * deltaY);
+            if (distance < EPSILON) {
+                // Coincident nodes: nudge along a deterministic direction so the
+                // pair separates instead of dividing by ~zero forever.
+                deltaX = EPSILON;
+                deltaY = 0;
+                distance = EPSILON;
+            }
+            const force = (k * k) / distance;
+            const unitX = (deltaX / distance) * force;
+            const unitY = (deltaY / distance) * force;
+            dx[i] += unitX;
+            dy[i] += unitY;
+            dx[j] -= unitX;
+            dy[j] -= unitY;
+        }
+    }
+}
+/** Attraction along every resolved edge, pulling its endpoints together. */
+function accumulateAttraction({ xs, ys, dx, dy }, links, k) {
+    for (const [from, to] of links) {
+        const deltaX = xs[from] - xs[to];
+        const deltaY = ys[from] - ys[to];
+        const distance = Math.max(Math.sqrt(deltaX * deltaX + deltaY * deltaY), EPSILON);
+        const force = (distance * distance) / k;
+        const unitX = (deltaX / distance) * force;
+        const unitY = (deltaY / distance) * force;
+        dx[from] -= unitX;
+        dy[from] -= unitY;
+        dx[to] += unitX;
+        dy[to] += unitY;
+    }
+}
+/**
+ * Moves every node along its accumulated displacement, capped at `temperature`
+ * so late iterations refine rather than reshuffle.
+ */
+function applyDisplacement({ count, xs, ys, dx, dy }, temperature) {
+    for (let i = 0; i < count; i++) {
+        const magnitude = Math.max(Math.sqrt(dx[i] * dx[i] + dy[i] * dy[i]), EPSILON);
+        const step = Math.min(magnitude, temperature);
+        xs[i] += (dx[i] / magnitude) * step;
+        ys[i] += (dy[i] / magnitude) * step;
+    }
+}
+/**
+ * Rescales raw simulation output into the viewport with a uniform margin,
+ * preserving aspect ratio so the drawing is not distorted. Coordinates are
+ * rounded to two decimals: enough precision to draw, few enough digits to keep
+ * the artifact small and its bytes stable.
+ */
+function fitToViewport(nodes, xs, ys) {
+    const margin = VIEWPORT * 0.04;
+    let minX = Number.POSITIVE_INFINITY;
+    let maxX = Number.NEGATIVE_INFINITY;
+    let minY = Number.POSITIVE_INFINITY;
+    let maxY = Number.NEGATIVE_INFINITY;
+    for (let i = 0; i < nodes.length; i++) {
+        if (xs[i] < minX)
+            minX = xs[i];
+        if (xs[i] > maxX)
+            maxX = xs[i];
+        if (ys[i] < minY)
+            minY = ys[i];
+        if (ys[i] > maxY)
+            maxY = ys[i];
+    }
+    const spanX = maxX - minX;
+    const spanY = maxY - minY;
+    const usable = VIEWPORT - 2 * margin;
+    // One shared scale keeps the aspect ratio; a zero span means every node
+    // collapsed onto one axis, so that axis simply centres.
+    const scale = Math.min(spanX > EPSILON ? usable / spanX : Number.POSITIVE_INFINITY, spanY > EPSILON ? usable / spanY : Number.POSITIVE_INFINITY);
+    const effective = Number.isFinite(scale) ? scale : 1;
+    const offsetX = margin + (usable - spanX * effective) / 2;
+    const offsetY = margin + (usable - spanY * effective) / 2;
+    return nodes.map((node, i) => ({
+        id: node.id,
+        x: round2((xs[i] - minX) * effective + offsetX),
+        y: round2((ys[i] - minY) * effective + offsetY),
+    }));
+}
+function round2(value) {
+    return Math.round(value * 100) / 100;
+}

package/dist/src/index-activity.js

@@ -1,8 +1,9 @@
 import child_process from "node:child_process";
 import fs from "node:fs";
 import path from "node:path";
+import { resolveStateDir } from "./engine/state-paths.js";
 function activityPath(repo) {
-    return path.join(path.resolve(repo), ".knodin", "index-activity.json");
+    return path.join(resolveStateDir(repo), "index-activity.json");
 }
 const ACTIVITY_CLOCK_SKEW_MS = 2_000;
 const MAX_ACTIVITY_AGE_MS = 7 * 24 * 60 * 60 * 1_000;

package/dist/src/init.js

@@ -3,7 +3,9 @@ import crypto from "node:crypto";
 import fs from "node:fs";
 import path from "node:path";
 import { configureProjectAgents, } from "./agent-integration.js";
+import { compareBytes } from "./compare.js";
 import { isIndexableSourcePath } from "./engine/source-policy.js";
+import { lookupMirror } from "./engine/state-paths.js";
 import { inspectLefthookIntegration, installHookManagerIntegration, isActiveLefthookHook, } from "./hook-manager-integration.js";
 import { registerInitializedWorktree } from "./worktree-lifecycle.js";
 const MANAGED_MARKER = "KNODIN MANAGED HOOK";
@@ -131,11 +133,12 @@ function configureMutationAuditTargets(repo) {
     const managedHooks = path.join(common, "knodin-hooks");
     add({ absolute: defaultHooks, label: ".git/hooks" });
     add({ absolute: managedHooks, label: ".git/knodin-hooks" });
-    const effectiveLabel = path.resolve(effectiveHooks) === path.resolve(defaultHooks)
-        ? ".git/hooks"
-        : path.resolve(effectiveHooks) === path.resolve(managedHooks)
-            ? ".git/knodin-hooks"
-            : "effective-git-hooks";
+    const resolvedEffectiveHooks = path.resolve(effectiveHooks);
+    let effectiveLabel = "effective-git-hooks";
+    if (resolvedEffectiveHooks === path.resolve(defaultHooks))
+        effectiveLabel = ".git/hooks";
+    else if (resolvedEffectiveHooks === path.resolve(managedHooks))
+        effectiveLabel = ".git/knodin-hooks";
     add({ absolute: effectiveHooks, label: effectiveLabel });
     for (const hookRoot of [
         { absolute: defaultHooks, label: ".git/hooks" },
@@ -225,21 +228,24 @@ function mutationSnapshot(targets, allowOversized = false) {
     return snapshot;
 }
 function filesystemChanges(before, after) {
-    return [...new Set([...before.keys(), ...after.keys()])].sort().flatMap((changedPath) => {
+    return [...new Set([...before.keys(), ...after.keys()])]
+        .sort(compareBytes)
+        .flatMap((changedPath) => {
         const prior = before.get(changedPath);
         const current = after.get(changedPath);
         if (prior === current)
             return [];
-        return [
-            {
-                path: changedPath,
-                action: prior === undefined ? "created" : current === undefined ? "removed" : "modified",
-            },
-        ];
+        let action = "modified";
+        if (prior === undefined)
+            action = "created";
+        else if (current === undefined)
+            action = "removed";
+        return [{ path: changedPath, action }];
     });
 }
+const SHELL_QUOTE_ESCAPE = String.raw `'\''`;
 function shellQuote(value) {
-    return `'${value.replaceAll("'", `'\\''`)}'`;
+    return `'${value.replaceAll("'", SHELL_QUOTE_ESCAPE)}'`;
 }
 function nulPaths(repo, args) {
     const separator = args.indexOf("--");
@@ -310,7 +316,7 @@ export async function refreshFromGitEvent(repo, event, index) {
         }
         const eligible = [...new Set(changed.map((file) => file.replaceAll("\\", "/")))]
             .filter(isIndexableSourcePath)
-            .sort();
+            .sort(compareBytes);
         if (eligible.length > 0)
             await index(resolvedRepo, eligible);
         return eligible;
@@ -322,7 +328,7 @@ export async function refreshFromGitEvent(repo, event, index) {
 }
 function backgroundScript(command) {
     const invocation = command.map(shellQuote).join(" ");
-    return `#!/bin/sh
+    return String.raw `#!/bin/sh
 # knodin packaged background refresh. Generated by knodin init.
 set -u
 REPO_ROOT="$(git rev-parse --show-toplevel 2>/dev/null || true)"
@@ -342,9 +348,9 @@ if [ "$#" -gt 0 ]; then
   EVENT_AT="$(date -u +%Y-%m-%dT%H:%M:%SZ)"
   {
     for EVENT_ARG in "$@"; do
-      printf '%s\\n' "$EVENT_ARG"
+      printf '%s\n' "$EVENT_ARG"
     done
-    printf 'sequence=%s\\nworktree=%s\\nat=%s\\n' "$EVENT_SEQUENCE" "$EVENT_WORKTREE" "$EVENT_AT"
+    printf 'sequence=%s\nworktree=%s\nat=%s\n' "$EVENT_SEQUENCE" "$EVENT_WORKTREE" "$EVENT_AT"
   } > "$EVENT_TMP"
   mv "$EVENT_TMP" "$EVENT_TMP.event"
 fi
@@ -361,7 +367,7 @@ if ! mkdir "$LOCK_DIR" 2>/dev/null; then
     exit 0
   fi
 fi
-printf '%s\\n' "$$" > "$LOCK_DIR/pid"
+printf '%s\n' "$$" > "$LOCK_DIR/pid"
 trap 'rm -rf "$LOCK_DIR"; rm -f "$FAILURE_TMP"' EXIT HUP INT TERM
 LOG_PATH="$REPO_ROOT/.knodin/indexer.log"
 if [ -f "$LOG_PATH" ]; then
@@ -384,7 +390,7 @@ while :; do
   elif [ "$KIND" = "rewrite" ]; then
     ${invocation} --repo "$REPO_ROOT" hook-refresh rewrite "$ARG1" --json >> "$LOG_PATH" 2>&1
   else
-    printf 'knodin background refresh: invalid queued event %s\\n' "$KIND" >> "$LOG_PATH"
+    printf 'knodin background refresh: invalid queued event %s\n' "$KIND" >> "$LOG_PATH"
     false
   fi
   STATUS=$?
@@ -393,9 +399,9 @@ while :; do
     rm -f "$EVENT" "$FAILURE_PATH"
   else
     {
-      printf 'knodin background refresh failed with exit code %s.\\n' "$STATUS"
-      printf 'Pending event retained at %s.\\n' "$EVENT"
-      printf 'See .knodin/indexer.log for details.\\n'
+      printf 'knodin background refresh failed with exit code %s.\n' "$STATUS"
+      printf 'Pending event retained at %s.\n' "$EVENT"
+      printf 'See .knodin/indexer.log for details.\n'
     } > "$FAILURE_TMP"
     mv -f "$FAILURE_TMP" "$FAILURE_PATH"
     exit "$STATUS"
@@ -450,13 +456,14 @@ function drainQueuedLifecycleEvents(repo, backgroundPath) {
     return { state: "fresh", queuedEvents: 0 };
 }
 function managedHookScript(hookName, originalPath) {
-    const original = originalPath
-        ? originalPath.startsWith("repo:")
+    let original = "";
+    if (originalPath)
+        original = originalPath.startsWith("repo:")
             ? `"$REPO_ROOT"/${shellQuote(originalPath.slice("repo:".length))}`
-            : shellQuote(originalPath)
-        : "";
+            : shellQuote(originalPath);
+    const rewriteRedirect = hookName === "post-rewrite" ? ' < "$REWRITE_INPUT"' : "";
     const runOriginal = originalPath
-        ? `KNODIN_WRAPPER_ACTIVE=1 ${original} "$@"${hookName === "post-rewrite" ? ' < "$REWRITE_INPUT"' : ""} || ORIGINAL_STATUS=$?`
+        ? `KNODIN_WRAPPER_ACTIVE=1 ${original} "$@"${rewriteRedirect} || ORIGINAL_STATUS=$?`
         : ":";
     let trigger = "";
     if (hookName === "post-commit")
@@ -664,14 +671,14 @@ async function prepareHookInstallation(repo) {
     }
     return { hooksDir, trackedHooksDir: relative };
 }
-const NUDGE_SCRIPT = `#!/bin/sh
+const NUDGE_SCRIPT = String.raw `#!/bin/sh
 # Example Claude Code hook: suggest local graph context for broad manual searches.
 read -r INPUT_PAYLOAD
 case "$INPUT_PAYLOAD" in
   *grep*|*find*|*Glob*|*ReadFile*) REASON="For cold or unfamiliar work, call the connected knodin MCP gateway's context or explain operation before broad traversal; use the CLI only as a fallback." ;;
   *) REASON="Proceeding with tool execution." ;;
 esac
-printf '{"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"allow","permissionDecisionReason":"%s"}}\\n' "$REASON"
+printf '{"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"allow","permissionDecisionReason":"%s"}}\n' "$REASON"
 `;
 export const SETTINGS_TEMPLATE = `{
   "comment": "Template only: opt in to local knodin context nudges.",
@@ -733,11 +740,11 @@ async function installManagedAgentInstructions(repo, fileName = "AGENTS.md") {
     const canonicalEnd = "<!-- knodin:end -->";
     const start = existing.indexOf(canonicalStart);
     const end = existing.indexOf(canonicalEnd);
-    const next = start >= 0 && end >= start
-        ? `${existing.slice(0, start)}${KNODIN_AGENT_INSTRUCTIONS}${existing.slice(end + canonicalEnd.length).replace(/^\r?\n/, "")}`
-        : existing.length > 0
-            ? `${existing.trimEnd()}\n\n${KNODIN_AGENT_INSTRUCTIONS}`
-            : KNODIN_AGENT_INSTRUCTIONS;
+    let next = KNODIN_AGENT_INSTRUCTIONS;
+    if (start >= 0 && end >= start)
+        next = `${existing.slice(0, start)}${KNODIN_AGENT_INSTRUCTIONS}${existing.slice(end + canonicalEnd.length).replace(/^\r?\n/, "")}`;
+    else if (existing.length > 0)
+        next = `${existing.trimEnd()}\n\n${KNODIN_AGENT_INSTRUCTIONS}`;
     if (next === existing)
         return null;
     await fs.promises.writeFile(instructionsPath, next, "utf-8");
@@ -772,8 +779,32 @@ function isTracked(repo, relativePath) {
         return false;
     }
 }
+const EXCLUDE_BLOCK_START = "# knodin:start\n";
+const EXCLUDE_BLOCK_END = "\n# knodin:end";
+/**
+ * Drop the first knodin-owned exclude block, replacing it with the single
+ * newline the block's leading line terminator contributed. A literal scan keeps
+ * this linear: a start marker with no following end marker can never be rescued
+ * by a later start marker, because every later body begins further right.
+ */
+function withoutManagedExcludeBlock(content) {
+    let start = content.indexOf(EXCLUDE_BLOCK_START);
+    while (start > 0 && content[start - 1] !== "\n")
+        start = content.indexOf(EXCLUDE_BLOCK_START, start + 1);
+    if (start < 0)
+        return content;
+    const end = content.indexOf(EXCLUDE_BLOCK_END, start + EXCLUDE_BLOCK_START.length);
+    if (end < 0)
+        return content;
+    let after = end + EXCLUDE_BLOCK_END.length;
+    if (content[after] === "\n")
+        after += 1;
+    return `${content.slice(0, start > 0 ? start - 1 : 0)}\n${content.slice(after)}`;
+}
 async function excludeUntrackedPaths(repo, candidates) {
-    const safe = [...new Set(candidates)].filter((candidate) => !isTracked(repo, candidate)).sort();
+    const safe = [...new Set(candidates)]
+        .filter((candidate) => !isTracked(repo, candidate))
+        .sort(compareBytes);
     if (safe.length === 0)
         return [];
     const rawExcludePath = runGit(repo, ["rev-parse", "--git-path", "info/exclude"]).trim();
@@ -790,7 +821,7 @@ async function excludeUntrackedPaths(repo, candidates) {
     }
     const startMarker = "# knodin:start";
     const endMarker = "# knodin:end";
-    const outside = existing.replace(/(?:^|\n)# knodin:start\n[\s\S]*?\n# knodin:end\n?/, "\n");
+    const outside = withoutManagedExcludeBlock(existing);
     const outsideLines = new Set(outside.split(/\r?\n/));
     const owned = safe.filter((candidate) => !outsideLines.has(candidate));
     const prefix = outside && !outside.endsWith("\n") ? `${outside}\n` : outside;
@@ -813,7 +844,7 @@ async function removeManagedExcludes(repo) {
             return;
         throw error;
     }
-    const next = existing.replace(/(?:^|\n)# knodin:start\n[\s\S]*?\n# knodin:end\n?/, "\n");
+    const next = withoutManagedExcludeBlock(existing);
     await fs.promises.writeFile(excludePath, next, "utf-8");
 }
 async function removeManagedPersonalArtifacts(repo, allowTrackedTransition = false) {
@@ -871,12 +902,10 @@ async function removeManagedPersonalArtifacts(repo, allowTrackedTransition = fal
             else if (next === head.trim())
                 await fs.promises.writeFile(gitIgnorePath, head, "utf-8");
         }
-        else {
-            if (next)
-                await fs.promises.writeFile(gitIgnorePath, `${next}\n`, "utf-8");
-            else
-                await fs.promises.rm(gitIgnorePath, { force: true });
-        }
+        else if (next)
+            await fs.promises.writeFile(gitIgnorePath, `${next}\n`, "utf-8");
+        else
+            await fs.promises.rm(gitIgnorePath, { force: true });
     }
     catch {
         // Missing or user-modified files are intentionally preserved.
@@ -1021,6 +1050,17 @@ export async function initializeRepository(repo, options) {
     if (runGit(resolvedRepo, ["rev-parse", "--is-inside-work-tree"]).trim() !== "true") {
         throw new Error(`knodin init: not a Git worktree: ${resolvedRepo}`);
     }
+    // A mirror is a shallow clone, so the worktree check above PASSES for one and
+    // init would go on to write .gitignore and install lifecycle hooks into a tree
+    // that is supposed to stay byte-identical to the remote. `knodin remote list`
+    // prints the clone path, which makes cd-ing there and running init a natural
+    // mistake rather than a contrived one. The next refresh hard-resets the clone
+    // and silently discards whatever was installed, leaving hooks that point at
+    // files which no longer exist.
+    const mirror = lookupMirror(resolvedRepo);
+    if (mirror) {
+        throw new Error(`knodin init: ${resolvedRepo} is a read-only mirror of ${mirror.url}, not a checkout. Mirrors carry no lifecycle hooks by design — their graph is built by \`knodin remote add\`/\`refresh\` and stored outside the clone. Nothing to initialize here.`);
+    }
     if (!path.isAbsolute(options.command[0])) {
         throw new Error("knodin init: packaged runtime command must be an absolute path");
     }
@@ -1092,6 +1132,7 @@ export async function initializeRepository(repo, options) {
     const projectPathByAgent = {
         codex: ".codex/config.toml",
         gemini: ".gemini/settings.json",
+        copilot: ".vscode/mcp.json",
         antigravity: ".agents/mcp_config.json",
     };
     const blockedAgents = [];
@@ -1102,7 +1143,7 @@ export async function initializeRepository(repo, options) {
         const cleanup = configureProjectAgents({
             repo: resolvedRepo,
             scope: "cli-only",
-            agents: ["claude", "codex", "gemini", "antigravity"],
+            agents: ["claude", "codex", "gemini", "copilot", "antigravity"],
             run: options.runAgentCommand,
         });
         if (cleanup.failed.length > 0)
@@ -1169,7 +1210,7 @@ export async function initializeRepository(repo, options) {
         const managerExcludes = await excludeUntrackedPaths(resolvedRepo, [
             hookManagerIntegration.localConfig,
         ]);
-        excluded = [...new Set([...excluded, ...managerExcludes])].sort();
+        excluded = [...new Set([...excluded, ...managerExcludes])].sort(compareBytes);
     }
     registerInitializedWorktree(resolvedRepo);
     const detectedFilesystemChanges = filesystemChanges(beforeMutation, mutationSnapshot(mutationTargets, true));

package/dist/src/lifecycle-health.js

@@ -1,6 +1,8 @@
 import childProcess from "node:child_process";
 import fs from "node:fs";
 import path from "node:path";
+import { compareBytes } from "./compare.js";
+import { isMirror, resolveDbPath } from "./engine/state-paths.js";
 import { inspectLefthookIntegration, isActiveLefthookHook } from "./hook-manager-integration.js";
 const MANAGED_MARKER = "KNODIN MANAGED HOOK";
 const HOOK_NAMES = ["post-commit", "post-checkout", "post-merge", "post-rewrite"];
@@ -44,7 +46,8 @@ function readPendingEvent(repo) {
         const next = fs
             .readdirSync(directory)
             .filter((entry) => entry.endsWith(".event"))
-            .sort((left, right) => left.localeCompare(right))[0];
+            // Byte order: `[0]` picks which queued event is reported as pending.
+            .sort(compareBytes)[0];
         return next ? readEvent(path.join(directory, next)) : null;
     }
     catch {
@@ -90,6 +93,18 @@ function activeHooksDirectory(repo) {
     const output = childProcess.execFileSync("git", ["rev-parse", "--path-format=absolute", "--git-path", "hooks"], { cwd: repo, encoding: "utf-8", stdio: ["ignore", "pipe", "ignore"] });
     return output.trim();
 }
+/**
+ * Classifies how lifecycle hooks reach knodin. Both routes present reads as
+ * "mixed" rather than picking a winner, because that combination is what a
+ * partially-migrated repository looks like and the caller must be able to say so.
+ */
+function hookRouting(wrappers, managerNative) {
+    if (wrappers > 0 && managerNative > 0)
+        return "mixed";
+    if (wrappers > 0)
+        return "managed-wrapper";
+    return managerNative > 0 ? "manager-native" : "unavailable";
+}
 function inspectManagedHooks(repo, hooksDirectory) {
     const activeHooks = [];
     const missingHooks = [];
@@ -118,13 +133,7 @@ function inspectManagedHooks(repo, hooksDirectory) {
         activeHooks,
         missingHooks,
         hookManager: lefthook.configured ? "lefthook" : null,
-        routing: wrappers > 0 && managerNative > 0
-            ? "mixed"
-            : wrappers > 0
-                ? "managed-wrapper"
-                : managerNative > 0
-                    ? "manager-native"
-                    : "unavailable",
+        routing: hookRouting(wrappers, managerNative),
     };
 }
 function readRefreshFailure(repo) {
@@ -142,7 +151,30 @@ function readRefreshFailure(repo) {
 /** Read-only proof that committed Git activity can still reach knodin's indexer. */
 export function inspectLifecycleHealth(repoPath) {
     const repo = path.resolve(repoPath);
-    if (!fs.existsSync(path.join(repo, ".knodin", "db.sqlite"))) {
+    // A mirror deliberately has no lifecycle hooks: its working tree is replaced
+    // wholesale on refresh and nothing of ours may live inside it. Judging it
+    // against hook health would report "degraded" and demand `knodin init` for
+    // every mirror, forever — a permanent false alarm that teaches callers to
+    // ignore genuine repair prompts. Its freshness comes from the recorded
+    // snapshot, not from Git events.
+    if (isMirror(repo)) {
+        return {
+            status: "healthy",
+            refreshCapable: false,
+            hooksDirectory: null,
+            activeHooks: [],
+            missingHooks: [],
+            issues: [],
+            queuedEvents: 0,
+            processor: { state: "idle", pid: null },
+            pendingEvent: null,
+            lastEvent: null,
+            lastError: null,
+            hookManager: null,
+            routing: "unavailable",
+        };
+    }
+    if (!fs.existsSync(resolveDbPath(repo))) {
         return {
             status: "unconfigured",
             refreshCapable: false,