gsd-pi 2.75.0 → 2.76.0

package/src/resources/extensions/gsd/tests/session-start-footer.test.ts

@@ -0,0 +1,153 @@
+/**
+ * session-start-footer.test.ts
+ *
+ * Verifies that register-hooks.ts suppresses the built-in footer by calling
+ * ctx.ui.setFooter(hideFooter) in both session_start and session_switch when
+ * isAutoActive() is true.
+ *
+ * Testing strategy:
+ *   Two layers:
+ *   1. Source-code regression guard: ensures the guard and setFooter call are
+ *      structurally present in register-hooks.ts for both event handlers.
+ *      (node:test does not support mock.module without --experimental-test-module-mocks,
+ *       so structural analysis is the correct approach here.)
+ *   2. Behavioral integration test: fires the live session_start handler with a
+ *      fake ctx when isAutoActive() is false (its default at test time) and
+ *      confirms setFooter is NOT called — verifying the guard is conditional.
+ *
+ * Relates to #4314.
+ */
+
+import test from "node:test";
+import assert from "node:assert/strict";
+import { mkdirSync, readFileSync, rmSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { tmpdir } from "node:os";
+import { fileURLToPath } from "node:url";
+
+import { registerHooks } from "../bootstrap/register-hooks.ts";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const HOOKS_SOURCE = readFileSync(
+  join(__dirname, "..", "bootstrap", "register-hooks.ts"),
+  "utf-8",
+);
+
+// ─── Source-code regression guards ──────────────────────────────────────────
+
+test("register-hooks.ts imports hideFooter from auto-dashboard", () => {
+  assert.ok(
+    HOOKS_SOURCE.includes('import { hideFooter } from "../auto-dashboard.js"') ||
+    HOOKS_SOURCE.includes("import { hideFooter } from '../auto-dashboard.js'"),
+    "register-hooks.ts must import hideFooter from auto-dashboard.js",
+  );
+});
+
+test("session_start handler calls ctx.ui.setFooter(hideFooter) when isAutoActive()", () => {
+  // Locate the session_start handler body (up to the next pi.on call)
+  const sessionStartIdx = HOOKS_SOURCE.indexOf('"session_start"');
+  assert.ok(sessionStartIdx > -1, "session_start handler must exist");
+
+  const sessionSwitchIdx = HOOKS_SOURCE.indexOf('"session_switch"');
+  assert.ok(sessionSwitchIdx > sessionStartIdx, "session_switch handler must follow session_start");
+
+  const sessionStartBody = HOOKS_SOURCE.slice(sessionStartIdx, sessionSwitchIdx);
+
+  assert.ok(
+    sessionStartBody.includes("isAutoActive()"),
+    "session_start handler must call isAutoActive()",
+  );
+  assert.ok(
+    sessionStartBody.includes("ctx.ui.setFooter(hideFooter)"),
+    "session_start handler must call ctx.ui.setFooter(hideFooter)",
+  );
+
+  // Guard must wrap the setFooter call
+  const guardIdx = sessionStartBody.indexOf("isAutoActive()");
+  const setFooterIdx = sessionStartBody.indexOf("ctx.ui.setFooter(hideFooter)");
+  assert.ok(
+    guardIdx < setFooterIdx,
+    "isAutoActive() guard must appear before ctx.ui.setFooter(hideFooter) in session_start",
+  );
+});
+
+test("session_switch handler calls ctx.ui.setFooter(hideFooter) when isAutoActive()", () => {
+  const sessionSwitchIdx = HOOKS_SOURCE.indexOf('"session_switch"');
+  assert.ok(sessionSwitchIdx > -1, "session_switch handler must exist");
+
+  const beforeAgentStartIdx = HOOKS_SOURCE.indexOf('"before_agent_start"');
+  assert.ok(beforeAgentStartIdx > sessionSwitchIdx, "before_agent_start handler must follow session_switch");
+
+  const sessionSwitchBody = HOOKS_SOURCE.slice(sessionSwitchIdx, beforeAgentStartIdx);
+
+  assert.ok(
+    sessionSwitchBody.includes("isAutoActive()"),
+    "session_switch handler must call isAutoActive()",
+  );
+  assert.ok(
+    sessionSwitchBody.includes("ctx.ui.setFooter(hideFooter)"),
+    "session_switch handler must call ctx.ui.setFooter(hideFooter)",
+  );
+
+  const guardIdx = sessionSwitchBody.indexOf("isAutoActive()");
+  const setFooterIdx = sessionSwitchBody.indexOf("ctx.ui.setFooter(hideFooter)");
+  assert.ok(
+    guardIdx < setFooterIdx,
+    "isAutoActive() guard must appear before ctx.ui.setFooter(hideFooter) in session_switch",
+  );
+});
+
+// ─── Behavioral test: setFooter NOT called when auto-mode is inactive ────────
+
+test("session_start does NOT call setFooter when isAutoActive() is false (default)", async (t) => {
+  const dir = join(
+    tmpdir(),
+    `gsd-footer-test-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`,
+  );
+  mkdirSync(dir, { recursive: true });
+
+  const originalCwd = process.cwd();
+  process.chdir(dir);
+  t.after(() => {
+    process.chdir(originalCwd);
+    try { rmSync(dir, { recursive: true, force: true }); } catch { /* best-effort */ }
+  });
+
+  let setFooterCallCount = 0;
+
+  const handlers = new Map<string, (event: unknown, ctx: any) => Promise<void> | void>();
+  const pi = {
+    on(event: string, handler: (event: unknown, ctx: any) => Promise<void> | void) {
+      handlers.set(event, handler);
+    },
+  } as any;
+
+  registerHooks(pi, []);
+
+  const sessionStart = handlers.get("session_start");
+  assert.ok(sessionStart, "session_start handler must be registered");
+
+  await sessionStart!({}, {
+    hasUI: true,
+    ui: {
+      notify: () => {},
+      setStatus: () => {},
+      setFooter: (_footer: unknown) => {
+        setFooterCallCount++;
+      },
+      setWorkingMessage: () => {},
+      onTerminalInput: () => () => {},
+      setWidget: () => {},
+    },
+    sessionManager: { getSessionId: () => null },
+    model: null,
+  } as any);
+
+  // isAutoActive() is false at test time (no auto session started),
+  // so setFooter must not be called.
+  assert.equal(
+    setFooterCallCount,
+    0,
+    "setFooter must NOT be called when isAutoActive() returns false",
+  );
+});

package/src/resources/extensions/gsd/tests/skip-slice-cascades-tasks.test.ts

@@ -0,0 +1,125 @@
+/**
+ * Regression test for #4375: gsd_skip_slice must cascade "skipped" status to
+ * all non-closed tasks in the slice.
+ *
+ * Without the cascade, executeCompleteMilestone's deep-task check finds
+ * pending tasks inside a skipped slice and refuses to complete the milestone,
+ * causing auto-mode to loop on complete-milestone until stuck-recovery aborts.
+ */
+
+import { describe, test, beforeEach, afterEach } from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, rmSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+
+import {
+  openDatabase,
+  closeDatabase,
+  insertMilestone,
+  insertSlice,
+  insertTask,
+  getSlice,
+  getSliceTasks,
+  updateSliceStatus,
+  updateTaskStatus,
+} from "../gsd-db.ts";
+import { handleSkipSlice } from "../tools/skip-slice.ts";
+
+describe("handleSkipSlice cascades skip to tasks (#4375)", () => {
+  let dir: string;
+  let dbPath: string;
+
+  beforeEach(() => {
+    dir = mkdtempSync(join(tmpdir(), "gsd-skip-cascade-"));
+    dbPath = join(dir, "test.db");
+    openDatabase(dbPath);
+    insertMilestone({ id: "M001", title: "Test", status: "active" });
+    insertSlice({ milestoneId: "M001", id: "S03", title: "Deferred", status: "pending", sequence: 3 });
+    insertTask({ milestoneId: "M001", sliceId: "S03", id: "T01", title: "task 1", status: "pending", sequence: 1 });
+    insertTask({ milestoneId: "M001", sliceId: "S03", id: "T02", title: "task 2", status: "active", sequence: 2 });
+    insertTask({ milestoneId: "M001", sliceId: "S03", id: "T03", title: "task 3", status: "pending", sequence: 3 });
+  });
+
+  afterEach(() => {
+    closeDatabase();
+    rmSync(dir, { recursive: true, force: true });
+  });
+
+  test("sets slice to skipped and cascades pending/active tasks to skipped", () => {
+    const result = handleSkipSlice({ milestoneId: "M001", sliceId: "S03", reason: "deferred" });
+
+    assert.equal(result.error, undefined, `expected success, got error: ${result.error ?? ""}`);
+    assert.equal(result.sliceId, "S03");
+    assert.equal(result.milestoneId, "M001");
+    assert.equal(result.tasksSkipped, 3, "all three non-closed tasks should be cascaded");
+
+    const slice = getSlice("M001", "S03");
+    assert.equal(slice?.status, "skipped", "slice status must be skipped");
+
+    const tasks = getSliceTasks("M001", "S03");
+    for (const t of tasks) {
+      assert.equal(t.status, "skipped", `task ${t.id} must be skipped after cascade`);
+    }
+  });
+
+  test("does not downgrade already-closed tasks", () => {
+    updateTaskStatus("M001", "S03", "T01", "complete", new Date().toISOString());
+
+    const result = handleSkipSlice({ milestoneId: "M001", sliceId: "S03" });
+
+    assert.equal(result.error, undefined);
+    assert.equal(result.tasksSkipped, 2, "only the two non-closed tasks should be cascaded");
+
+    const tasks = getSliceTasks("M001", "S03");
+    const byId = new Map(tasks.map((t) => [t.id, t.status]));
+    assert.equal(byId.get("T01"), "complete", "completed task must not be downgraded");
+    assert.equal(byId.get("T02"), "skipped");
+    assert.equal(byId.get("T03"), "skipped");
+  });
+
+  test("re-running skip on an already-skipped slice heals leftover pending tasks (#4375 recovery)", () => {
+    const first = handleSkipSlice({ milestoneId: "M001", sliceId: "S03" });
+    assert.equal(first.error, undefined);
+    assert.equal(first.tasksSkipped, 3);
+
+    // Simulate historical inconsistent state: slice skipped but a task was
+    // later recreated or reset to pending by some migration/bug path.
+    updateTaskStatus("M001", "S03", "T01", "pending");
+
+    const second = handleSkipSlice({ milestoneId: "M001", sliceId: "S03" });
+    assert.equal(second.error, undefined, "re-running must succeed (no 'already skipped' hard error)");
+    assert.equal(second.tasksSkipped, 1, "only the leftover pending task should be cascaded");
+    assert.equal(second.wasAlreadySkipped, true);
+
+    const tasks = getSliceTasks("M001", "S03");
+    for (const t of tasks) {
+      assert.equal(t.status, "skipped", `task ${t.id} must be skipped after recovery`);
+    }
+  });
+
+  test("refuses to skip an already-complete slice", () => {
+    updateSliceStatus("M001", "S03", "complete");
+
+    const result = handleSkipSlice({ milestoneId: "M001", sliceId: "S03" });
+    assert.ok(result.error, "expected error when slice is already complete");
+    assert.match(result.error!, /already complete/i);
+    assert.equal(result.errorCode, "already_complete");
+  });
+
+  test("refuses to skip a slice in the legacy 'done' status", () => {
+    updateSliceStatus("M001", "S03", "done");
+
+    const result = handleSkipSlice({ milestoneId: "M001", sliceId: "S03" });
+    assert.ok(result.error, "expected error when slice is already done");
+    assert.match(result.error!, /already complete/i);
+    assert.equal(result.errorCode, "already_complete");
+  });
+
+  test("returns error for unknown slice", () => {
+    const result = handleSkipSlice({ milestoneId: "M001", sliceId: "S99" });
+    assert.ok(result.error);
+    assert.match(result.error!, /not found/i);
+    assert.equal(result.errorCode, "slice_not_found");
+  });
+});

package/src/resources/extensions/gsd/tests/slice-context-injection.test.ts

@@ -31,18 +31,30 @@ describe("slice CONTEXT.md injection into prompt builders (#3452)", () => {
       const fnStart = source.indexOf(`export async function ${builder}`);
       assert.ok(fnStart !== -1, `${builder} should exist in auto-prompts.ts`);
 
-      // Get a reasonable chunk after the function start (enough to cover the inlining section)
+      // Get a reasonable chunk after the function start
       const chunk = source.slice(fnStart, fnStart + 3000);
 
+      // ADR-011: buildPlanSlicePrompt / buildRefineSlicePrompt now delegate to
+      // a shared helper (renderSlicePrompt) that performs the slice CONTEXT
+      // resolve. When a builder delegates, scan the helper's body instead.
+      const delegatesToHelper = chunk.includes("renderSlicePrompt(");
+      const bodyToCheck = delegatesToHelper
+        ? (() => {
+            const helperStart = source.indexOf("async function renderSlicePrompt");
+            assert.ok(helperStart !== -1, "renderSlicePrompt helper must exist");
+            return source.slice(helperStart, helperStart + 3000);
+          })()
+        : chunk;
+
       // Must resolve the slice CONTEXT path
       assert.ok(
-        chunk.includes('resolveSliceFile(base, mid,') && chunk.includes('"CONTEXT"'),
-        `${builder} should call resolveSliceFile with "CONTEXT"`,
+        bodyToCheck.includes('resolveSliceFile(base, mid,') && bodyToCheck.includes('"CONTEXT"'),
+        `${builder} should call resolveSliceFile with "CONTEXT" (directly or via renderSlicePrompt)`,
       );
 
       // Must inline it with inlineFileOptional
       assert.ok(
-        chunk.includes('Slice Context'),
+        bodyToCheck.includes("Slice Context"),
         `${builder} should inline slice CONTEXT with a "Slice Context" label`,
       );
     });

package/src/resources/extensions/gsd/tests/stash-queued-context-files.test.ts

@@ -21,6 +21,8 @@ import {
   existsSync,
   readFileSync,
   realpathSync,
+  symlinkSync,
+  lstatSync,
 } from "node:fs";
 import { join } from "node:path";
 import { tmpdir } from "node:os";
@@ -76,6 +78,20 @@ function createTempRepo(): string {
   return dir;
 }
 
+function createTempRepoWithSymlinkedGsd(): { repo: string; stateDir: string } {
+  const repo = realpathSync(mkdtempSync(join(tmpdir(), "wt-symlink-stash-test-")));
+  const stateDir = realpathSync(mkdtempSync(join(tmpdir(), "wt-symlink-state-")));
+  run("git init", repo);
+  run("git config user.email test@test.com", repo);
+  run("git config user.name Test", repo);
+  writeFileSync(join(repo, "README.md"), "# test\n");
+  symlinkSync(stateDir, join(repo, ".gsd"));
+  run("git add README.md", repo);
+  run("git commit -m init", repo);
+  run("git branch -M main", repo);
+  return { repo, stateDir };
+}
+
 function makeRoadmap(
   milestoneId: string,
   title: string,
@@ -259,6 +275,44 @@ test("#2505: mergeMilestoneToMain preserves queued CONTEXT files (not swept into
   }
 });
 
+test("#2505: pre-merge stash handles symlinked .gsd without traversing it", () => {
+  const { repo, stateDir } = createTempRepoWithSymlinkedGsd();
+  try {
+    const wtPath = createAutoWorktree(repo, "M016");
+    const normalizedPath = wtPath.replaceAll("\\", "/");
+    const worktreeName = normalizedPath.split("/").pop() || "M016";
+    const sliceBranch = `slice/${worktreeName}/S01`;
+    run(`git checkout -b "${sliceBranch}"`, wtPath);
+    writeFileSync(join(wtPath, "app.ts"), "export const app = true;\n");
+    run("git add app.ts", wtPath);
+    run('git commit -m "add app feature"', wtPath);
+    run("git checkout milestone/M016", wtPath);
+    run(`git merge --no-ff "${sliceBranch}" -m "merge S01"`, wtPath);
+
+    const queuedDir = join(stateDir, "milestones", "M017");
+    mkdirSync(queuedDir, { recursive: true });
+    writeFileSync(join(queuedDir, "M017-CONTEXT.md"), "# M017: Queued\n");
+
+    // Trigger the pre-merge stash with both tracked and untracked project files.
+    writeFileSync(join(repo, "README.md"), "# test\n\nDirty change.\n");
+    writeFileSync(join(repo, "local-note.txt"), "local scratch\n");
+
+    const result = mergeMilestoneToMain(repo, "M016", makeRoadmap("M016", "App Feature", [
+      { id: "S01", title: "Feature" },
+    ]));
+
+    assert.ok(result.commitMessage.includes("GSD-Milestone: M016"), "merge should succeed");
+    assert.ok(existsSync(join(repo, "app.ts")), "milestone code merged to main");
+    assert.equal(lstatSync(join(repo, ".gsd")).isSymbolicLink(), true, ".gsd symlink remains in place");
+    assert.ok(existsSync(join(queuedDir, "M017-CONTEXT.md")), "queued context remains in external state");
+    assert.equal(readFileSync(join(repo, "README.md"), "utf-8").replace(/\r\n/g, "\n"), "# test\n\nDirty change.\n");
+    assert.equal(readFileSync(join(repo, "local-note.txt"), "utf-8"), "local scratch\n");
+  } finally {
+    rmSync(repo, { recursive: true, force: true });
+    rmSync(stateDir, { recursive: true, force: true });
+  }
+});
+
 test("#2505: back-to-back merges preserve queued CONTEXT files", () => {
   const repo = createTempRepo();
   try {

package/src/resources/extensions/gsd/tests/state-corruption-2945.test.ts

@@ -93,6 +93,8 @@ function makeSliceRow(id: string, overrides: Partial<SliceRow> = {}): SliceRow {
     integration_closure: "",
     observability_impact: "",
     replan_triggered_at: null,
+    is_sketch: 0,
+    sketch_scope: "",
     ...overrides,
   };
 }
@@ -295,6 +297,7 @@ describe("#2945 Bug 3: mergeAndExit must teardown worktree after successful merg
       loadEffectiveGSDPreferences: () => undefined,
       invalidateAllCaches: () => {},
       captureIntegrationBranch: () => {},
+      enterBranchModeForMilestone: () => {},
     };
 
     // Import and create resolver

package/src/resources/extensions/gsd/tests/stuck-detection-coverage.test.ts

@@ -79,6 +79,21 @@ test("Rule 2: interrupted sequence does not trigger", () => {
   );
 });
 
+test("Rule 2b: same unit repeated 3 times in the window triggers stuck even with an intervening unit", () => {
+  const result = detectStuck([
+    { key: "execute-task/M002/S03/T01" },
+    { key: "execute-task/M002/S03/T01" },
+    { key: "reassess-roadmap/M002/S02" },
+    { key: "execute-task/M002/S03/T01" },
+  ]);
+  assert.notEqual(result, null);
+  assert.equal(result!.stuck, true);
+  assert.ok(
+    result!.reason.includes("3 times in last 4 attempts"),
+    `reason was: ${result!.reason}`,
+  );
+});
+
 // ─── Rule 3: Oscillation A→B→A→B ─────────────────────────────────────────────
 
 test("Rule 3: A-B-A-B oscillation triggers stuck", () => {

package/src/resources/extensions/gsd/tests/summary-render-parity.test.ts

@@ -50,6 +50,11 @@ const taskRow: TaskRow = {
   observability_impact: "",
   full_plan_md: "",
   sequence: 1,
+  blocker_source: "",
+  escalation_pending: 0,
+  escalation_awaiting_review: 0,
+  escalation_artifact_path: null,
+  escalation_override_applied_at: null,
 };
 
 const verificationEvidence = [

package/src/resources/extensions/gsd/tests/uok-contracts.test.ts

@@ -64,8 +64,9 @@ test("uok contracts include required DAG node kinds", () => {
     "team-worker",
     "verification",
     "reprocess",
+    "refine",
   ];
-  assert.deepEqual(required.length, 6);
+  assert.deepEqual(required.length, 7);
 });
 
 test("uok audit envelope includes trace/turn/causality fields", () => {

package/src/resources/extensions/gsd/tests/uok-flags.test.ts

@@ -7,6 +7,37 @@ test("uok flags default to enabled when preference is unset", () => {
   const flags = resolveUokFlags(undefined);
   assert.equal(flags.enabled, true);
   assert.equal(flags.legacyFallback, false);
+  assert.equal(flags.gates, true);
+  assert.equal(flags.modelPolicy, true);
+  assert.equal(flags.executionGraph, true);
+  assert.equal(flags.gitops, true);
+  assert.equal(flags.auditUnified, true);
+  assert.equal(flags.planV2, true);
+  assert.equal(flags.gitopsTurnAction, "commit");
+  assert.equal(flags.gitopsTurnPush, false);
+});
+
+test("uok nested flags support explicit opt-out", () => {
+  const flags = resolveUokFlags({
+    uok: {
+      enabled: true,
+      gates: { enabled: false },
+      model_policy: { enabled: false },
+      execution_graph: { enabled: false },
+      gitops: { enabled: false, turn_action: "commit", turn_push: true },
+      audit_unified: { enabled: false },
+      plan_v2: { enabled: false },
+    },
+  });
+  assert.equal(flags.enabled, true);
+  assert.equal(flags.gates, false);
+  assert.equal(flags.modelPolicy, false);
+  assert.equal(flags.executionGraph, false);
+  assert.equal(flags.gitops, false);
+  assert.equal(flags.auditUnified, false);
+  assert.equal(flags.planV2, false);
+  assert.equal(flags.gitopsTurnAction, "commit");
+  assert.equal(flags.gitopsTurnPush, true);
 });
 
 test("uok legacy fallback preference forces legacy path", () => {
@@ -36,4 +67,3 @@ test("uok legacy fallback env var forces legacy path", () => {
     else process.env.GSD_UOK_FORCE_LEGACY = previous;
   }
 });
-

package/src/resources/extensions/gsd/tests/uok-kernel-path.test.ts

@@ -0,0 +1,166 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, readFileSync, rmSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+
+import type { ExtensionAPI, ExtensionContext } from "@gsd/pi-coding-agent";
+
+import { runAutoLoopWithUok } from "../uok/kernel.ts";
+import type { AutoSession } from "../auto/session.ts";
+import type { LoopDeps } from "../auto/loop-deps.ts";
+import { gsdRoot } from "../paths.ts";
+import type { GSDPreferences } from "../preferences.ts";
+
+function makeBasePath(): string {
+  return mkdtempSync(join(tmpdir(), "gsd-uok-kernel-"));
+}
+
+function makeArgs(
+  basePath: string,
+  preferences: GSDPreferences | undefined,
+): {
+  ctx: ExtensionContext;
+  pi: ExtensionAPI;
+  s: AutoSession;
+  deps: LoopDeps;
+  runKernelLoop: (
+    ctx: ExtensionContext,
+    pi: ExtensionAPI,
+    s: AutoSession,
+    deps: LoopDeps,
+  ) => Promise<void>;
+  runLegacyLoop: (
+    ctx: ExtensionContext,
+    pi: ExtensionAPI,
+    s: AutoSession,
+    deps: LoopDeps,
+  ) => Promise<void>;
+  calls: {
+    kernel: number;
+    legacy: number;
+    kernelDeps: LoopDeps | null;
+    legacyDeps: LoopDeps | null;
+  };
+} {
+  const calls = {
+    kernel: 0,
+    legacy: 0,
+    kernelDeps: null as LoopDeps | null,
+    legacyDeps: null as LoopDeps | null,
+  };
+
+  return {
+    ctx: {
+      sessionManager: {
+        getSessionId: (): string => "session-test",
+      },
+    } as unknown as ExtensionContext,
+    pi: {} as unknown as ExtensionAPI,
+    s: {
+      basePath,
+      autoStartTime: 1,
+    } as unknown as AutoSession,
+    deps: {
+      loadEffectiveGSDPreferences: () => ({ preferences }),
+    } as unknown as LoopDeps,
+    runKernelLoop: async (_ctx, _pi, _s, loopDeps): Promise<void> => {
+      calls.kernel += 1;
+      calls.kernelDeps = loopDeps;
+    },
+    runLegacyLoop: async (_ctx, _pi, _s, loopDeps): Promise<void> => {
+      calls.legacy += 1;
+      calls.legacyDeps = loopDeps;
+    },
+    calls,
+  };
+}
+
+function readParityEvents(basePath: string): Array<Record<string, unknown>> {
+  const file = join(gsdRoot(basePath), "runtime", "uok-parity.jsonl");
+  const raw = readFileSync(file, "utf-8").trim();
+  if (raw.length === 0) return [];
+  return raw.split("\n").map(line => JSON.parse(line) as Record<string, unknown>);
+}
+
+test("runAutoLoopWithUok uses kernel path by default and records uok-kernel parity", async () => {
+  const basePath = makeBasePath();
+  try {
+    const args = makeArgs(basePath, {
+      uok: {
+        enabled: true,
+        audit_unified: { enabled: false },
+        gitops: { enabled: false },
+      },
+    });
+    await runAutoLoopWithUok(args);
+
+    assert.equal(args.calls.kernel, 1);
+    assert.equal(args.calls.legacy, 0);
+    assert.ok(args.calls.kernelDeps);
+    assert.notEqual(args.calls.kernelDeps, args.deps);
+    assert.ok(args.calls.kernelDeps?.uokObserver);
+    assert.equal(process.env.GSD_UOK_AUDIT_UNIFIED, "0");
+
+    const events = readParityEvents(basePath);
+    assert.equal(events.length, 2);
+    assert.equal(events[0]?.path, "uok-kernel");
+    assert.equal(events[0]?.phase, "enter");
+    assert.equal(events[1]?.path, "uok-kernel");
+    assert.equal(events[1]?.phase, "exit");
+    assert.equal(events[1]?.status, "ok");
+  } finally {
+    rmSync(basePath, { recursive: true, force: true });
+  }
+});
+
+test("runAutoLoopWithUok uses legacy path when explicit legacy fallback is enabled", async () => {
+  const basePath = makeBasePath();
+  try {
+    const args = makeArgs(basePath, {
+      uok: {
+        enabled: true,
+        legacy_fallback: { enabled: true },
+      },
+    });
+    await runAutoLoopWithUok(args);
+
+    assert.equal(args.calls.kernel, 0);
+    assert.equal(args.calls.legacy, 1);
+    assert.equal(args.calls.legacyDeps, args.deps);
+
+    const events = readParityEvents(basePath);
+    assert.equal(events.length, 2);
+    assert.equal(events[0]?.path, "legacy-fallback");
+    assert.equal(events[1]?.path, "legacy-fallback");
+    assert.equal(events[1]?.status, "ok");
+  } finally {
+    rmSync(basePath, { recursive: true, force: true });
+  }
+});
+
+test("runAutoLoopWithUok respects GSD_UOK_FORCE_LEGACY emergency switch", async () => {
+  const basePath = makeBasePath();
+  const previous = process.env.GSD_UOK_FORCE_LEGACY;
+  process.env.GSD_UOK_FORCE_LEGACY = "1";
+  try {
+    const args = makeArgs(basePath, {
+      uok: {
+        enabled: true,
+      },
+    });
+    await runAutoLoopWithUok(args);
+
+    assert.equal(args.calls.kernel, 0);
+    assert.equal(args.calls.legacy, 1);
+
+    const events = readParityEvents(basePath);
+    assert.equal(events.length, 2);
+    assert.equal(events[0]?.path, "legacy-fallback");
+    assert.equal(events[1]?.path, "legacy-fallback");
+  } finally {
+    if (previous === undefined) delete process.env.GSD_UOK_FORCE_LEGACY;
+    else process.env.GSD_UOK_FORCE_LEGACY = previous;
+    rmSync(basePath, { recursive: true, force: true });
+  }
+});