gsd-pi 2.76.0 → 2.77.0-dev.1d17f366c

package/src/resources/extensions/gsd/tests/turn-epoch.test.ts

@@ -0,0 +1,162 @@
+// Project: gsd-pi — Tests for the auto/turn-epoch stale-write guard.
+
+import test from "node:test";
+import assert from "node:assert/strict";
+
+import {
+  _resetTurnEpoch,
+  bumpTurnGeneration,
+  describeTurnEpoch,
+  getCurrentTurnGeneration,
+  isStaleWrite,
+  runWithTurnGeneration,
+} from "../auto/turn-epoch.ts";
+
+test("turn-epoch: generation starts at 0 and bumps monotonically", () => {
+  _resetTurnEpoch();
+  assert.equal(getCurrentTurnGeneration(), 0);
+  assert.equal(bumpTurnGeneration("test-a"), 1);
+  assert.equal(bumpTurnGeneration("test-b"), 2);
+  assert.equal(getCurrentTurnGeneration(), 2);
+});
+
+test("turn-epoch: isStaleWrite returns false when no turn context captured", () => {
+  _resetTurnEpoch();
+  bumpTurnGeneration("no-context");
+  // Called outside runWithTurnGeneration — safe default is false.
+  assert.equal(isStaleWrite("out-of-band"), false);
+});
+
+test("turn-epoch: isStaleWrite returns false inside a fresh turn", () => {
+  _resetTurnEpoch();
+  const captured = getCurrentTurnGeneration();
+  runWithTurnGeneration(captured, () => {
+    assert.equal(isStaleWrite("fresh"), false);
+  });
+});
+
+test("turn-epoch: isStaleWrite returns true after the epoch bumps mid-turn", () => {
+  _resetTurnEpoch();
+  const captured = getCurrentTurnGeneration();
+  runWithTurnGeneration(captured, () => {
+    bumpTurnGeneration("recovery-fires");
+    assert.equal(isStaleWrite("stale"), true);
+  });
+});
+
+test("turn-epoch: nested turns each see their own captured generation", () => {
+  _resetTurnEpoch();
+  const outerGen = getCurrentTurnGeneration();
+  runWithTurnGeneration(outerGen, () => {
+    assert.equal(isStaleWrite("outer-fresh"), false);
+    bumpTurnGeneration("bump-between");
+    const innerGen = getCurrentTurnGeneration();
+    runWithTurnGeneration(innerGen, () => {
+      // Inner context saw the bumped generation at capture time — fresh.
+      assert.equal(isStaleWrite("inner-fresh"), false);
+    });
+    // Back to outer context — still stale because outerGen < current.
+    assert.equal(isStaleWrite("outer-after-bump"), true);
+  });
+});
+
+test("turn-epoch: describeTurnEpoch surfaces captured vs current", () => {
+  _resetTurnEpoch();
+  bumpTurnGeneration("seed");
+  const captured = getCurrentTurnGeneration();
+  runWithTurnGeneration(captured, () => {
+    let snapshot = describeTurnEpoch();
+    assert.equal(snapshot.captured, captured);
+    assert.equal(snapshot.current, captured);
+    assert.equal(snapshot.stale, false);
+
+    bumpTurnGeneration("supersede");
+    snapshot = describeTurnEpoch();
+    assert.equal(snapshot.captured, captured);
+    assert.equal(snapshot.current, captured + 1);
+    assert.equal(snapshot.stale, true);
+  });
+
+  // Outside the turn — captured is null, stale is false.
+  const outside = describeTurnEpoch();
+  assert.equal(outside.captured, null);
+  assert.equal(outside.stale, false);
+});
+
+test("turn-epoch: AsyncLocalStorage propagates across awaits", async () => {
+  _resetTurnEpoch();
+  const captured = getCurrentTurnGeneration();
+  await runWithTurnGeneration(captured, async () => {
+    await Promise.resolve();
+    await new Promise((r) => setTimeout(r, 1));
+    bumpTurnGeneration("async-bump");
+    await Promise.resolve();
+    assert.equal(isStaleWrite("post-await"), true);
+  });
+});
+
+// ─── Source-level invariant checks for recoverTimedOutUnit ──────────────────
+//
+// The recoverTimedOutUnit function has two branch families:
+// - ADVANCE branches: the unit is done, loop moves on — these MUST bump.
+// - STEERING branches: the same LLM turn is kept alive with a steering
+//   message — these MUST NOT bump (otherwise the retry's legitimate writes
+//   get marked stale).
+//
+// The whole function must contain zero raw `resolveAgentEnd` calls with the
+// "timeout-recovery" _synthetic marker — all advance paths go through
+// bumpAndResolveSynthetic. And there must be no top-level bump call.
+
+test("recoverTimedOutUnit: no raw `resolveAgentEnd({ _synthetic: \"timeout-recovery\" })` calls remain", async () => {
+  const fs = await import("node:fs");
+  const path = await import("node:path");
+  const url = await import("node:url");
+  const here = path.dirname(url.fileURLToPath(import.meta.url));
+  const src = fs.readFileSync(
+    path.join(here, "..", "auto-timeout-recovery.ts"),
+    "utf-8",
+  );
+  const rawSyntheticResolve =
+    /resolveAgentEnd\s*\(\s*\{\s*messages:\s*\[\s*\]\s*,\s*_synthetic:\s*["']timeout-recovery/;
+  assert.equal(
+    rawSyntheticResolve.test(src),
+    false,
+    "auto-timeout-recovery.ts must funnel advance paths through bumpAndResolveSynthetic — a raw resolveAgentEnd with _synthetic:\"timeout-recovery\" would leak orphan writes",
+  );
+});
+
+test("recoverTimedOutUnit: no top-level bumpTurnGeneration — steering branches must not supersede", async () => {
+  const fs = await import("node:fs");
+  const path = await import("node:path");
+  const url = await import("node:url");
+  const here = path.dirname(url.fileURLToPath(import.meta.url));
+  const src = fs.readFileSync(
+    path.join(here, "..", "auto-timeout-recovery.ts"),
+    "utf-8",
+  );
+  // The only bump surface allowed is via bumpAndResolveSynthetic (advance
+  // paths) — a direct bumpTurnGeneration call in this file would bump even
+  // when the function later decides to take a steering retry branch.
+  assert.equal(
+    /\bbumpTurnGeneration\s*\(/.test(src),
+    false,
+    "auto-timeout-recovery.ts must not call bumpTurnGeneration directly — use bumpAndResolveSynthetic so bump and supersede are atomic and tied to advance-only branches",
+  );
+});
+
+test("recoverTimedOutUnit: bumpAndResolveSynthetic appears exactly four times (one per advance branch)", async () => {
+  const fs = await import("node:fs");
+  const path = await import("node:path");
+  const url = await import("node:url");
+  const here = path.dirname(url.fileURLToPath(import.meta.url));
+  const src = fs.readFileSync(
+    path.join(here, "..", "auto-timeout-recovery.ts"),
+    "utf-8",
+  );
+  const matches = src.match(/bumpAndResolveSynthetic\s*\(/g) ?? [];
+  assert.equal(
+    matches.length,
+    4,
+    `expected 4 advance-branch supersede sites (durableComplete, execute-task-exhausted, artifact-already-exists, non-execute-exhausted); found ${matches.length}`,
+  );
+});

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

@@ -3,12 +3,16 @@ import assert from "node:assert/strict";
 
 import type {
   AuditEventEnvelope,
+  UokDispatchEnvelope,
   GateResult,
   TurnContract,
   TurnResult,
   UokNodeKind,
+  WriteRecord,
+  WriterToken,
 } from "../uok/contracts.ts";
 import { buildAuditEnvelope } from "../uok/audit.ts";
+import { buildDispatchEnvelope, explainDispatch } from "../uok/dispatch-envelope.ts";
 
 test("uok contracts serialize/deserialize turn envelopes", () => {
   const contract: TurnContract = {
@@ -84,3 +88,50 @@ test("uok audit envelope includes trace/turn/causality fields", () => {
   assert.equal(event.causedBy, "turn-start");
   assert.equal(event.payload.status, "completed");
 });
+
+test("uok dispatch envelope carries scheduler reason and constraints", () => {
+  const envelope: UokDispatchEnvelope = buildDispatchEnvelope({
+    action: "dispatch",
+    node: {
+      kind: "unit",
+      dependsOn: ["plan-gate"],
+      reads: ["M001-ROADMAP.md"],
+      writes: ["M001/S01/T01-SUMMARY.md"],
+    },
+    unitType: "execute-task",
+    unitId: "M001/S01/T01",
+    prompt: "do work",
+    reasonCode: "dependency",
+    summary: "all dependencies are closed and output path is available",
+    evidence: { readyTaskCount: 1 },
+  });
+
+  assert.equal(envelope.nodeKind, "unit");
+  assert.equal(envelope.reason.reasonCode, "dependency");
+  assert.deepEqual(envelope.constraints?.dependsOn, ["plan-gate"]);
+  assert.ok(explainDispatch(envelope).includes("execute-task M001/S01/T01"));
+});
+
+test("uok writer records serialize sequence metadata", () => {
+  const token: WriterToken = {
+    tokenId: "token-1",
+    traceId: "trace-1",
+    turnId: "turn-1",
+    acquiredAt: new Date().toISOString(),
+    owner: "uok",
+  };
+
+  const record: WriteRecord = {
+    writerToken: token,
+    sequence: { traceId: token.traceId, turnId: token.turnId, sequence: 7 },
+    category: "audit",
+    operation: "append",
+    path: ".gsd/audit/events.jsonl",
+    ts: new Date().toISOString(),
+  };
+
+  const roundTrip = JSON.parse(JSON.stringify(record)) as WriteRecord;
+  assert.equal(roundTrip.writerToken.tokenId, "token-1");
+  assert.equal(roundTrip.sequence.sequence, 7);
+  assert.equal(roundTrip.category, "audit");
+});

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

@@ -5,6 +5,7 @@ import {
   selectConflictFreeBatch,
   selectReactiveDispatchBatch,
   buildSidecarQueueNodes,
+  buildExecutionGraphSnapshot,
   scheduleSidecarQueue,
 } from "../uok/execution-graph.ts";
 
@@ -67,3 +68,18 @@ test("uok execution graph sidecar scheduler preserves deterministic queue order"
     queue.map((item) => item.unitId),
   );
 });
+
+test("uok execution graph snapshot captures deterministic order and conflicts", () => {
+  const snapshot = buildExecutionGraphSnapshot(
+    [
+      { id: "b", kind: "unit", dependsOn: ["a"], writes: ["src/shared.ts"] },
+      { id: "a", kind: "unit", dependsOn: [], writes: ["src/a.ts"] },
+      { id: "c", kind: "verification", dependsOn: [], writes: ["src/shared.ts"] },
+    ],
+    "before-unit",
+  );
+
+  assert.equal(snapshot.phase, "before-unit");
+  assert.deepEqual(snapshot.order, ["a", "b", "c"]);
+  assert.ok(snapshot.conflicts.some((c) => c.file === "src/shared.ts"));
+});

package/src/resources/extensions/gsd/tests/uok-loop-adapter-writer.test.ts

@@ -0,0 +1,65 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import { existsSync, mkdtempSync, readFileSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import { createTurnObserver } from "../uok/loop-adapter.ts";
+import { hasActiveWriterToken, resetWriterTokensForTests } from "../uok/writer.ts";
+
+function readAuditPayloads(basePath: string): Array<Record<string, unknown>> {
+  const path = join(basePath, ".gsd", "audit", "events.jsonl");
+  if (!existsSync(path)) return [];
+  return readFileSync(path, "utf-8")
+    .split("\n")
+    .filter(Boolean)
+    .map((line) => JSON.parse(line) as { payload?: Record<string, unknown> })
+    .map((event) => event.payload ?? {});
+}
+
+test("uok turn observer adds writer sequence metadata to audit events", (t) => {
+  const basePath = mkdtempSync(join(tmpdir(), "gsd-uok-loop-writer-"));
+  resetWriterTokensForTests();
+  t.after(() => {
+    resetWriterTokensForTests();
+    rmSync(basePath, { recursive: true, force: true });
+  });
+
+  const observer = createTurnObserver({
+    basePath,
+    gitAction: "status-only",
+    gitPush: false,
+    enableAudit: true,
+    enableGitops: false,
+  });
+
+  observer.onTurnStart({
+    basePath,
+    traceId: "trace-1",
+    turnId: "turn-1",
+    iteration: 1,
+    unitType: "execute-task",
+    unitId: "M001/S01/T01",
+    startedAt: new Date().toISOString(),
+  });
+  assert.equal(hasActiveWriterToken(basePath, "turn-1"), true);
+
+  observer.onTurnResult({
+    traceId: "trace-1",
+    turnId: "turn-1",
+    iteration: 1,
+    unitType: "execute-task",
+    unitId: "M001/S01/T01",
+    status: "completed",
+    failureClass: "none",
+    phaseResults: [],
+    startedAt: new Date().toISOString(),
+    finishedAt: new Date().toISOString(),
+  });
+
+  assert.equal(hasActiveWriterToken(basePath, "turn-1"), false);
+  const payloads = readAuditPayloads(basePath);
+  assert.equal(payloads[0]?.writeSequence, 1);
+  assert.equal(payloads[1]?.writeSequence, 2);
+  assert.equal(typeof payloads[0]?.writerTokenId, "string");
+});

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

@@ -0,0 +1,42 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, readFileSync, rmSync, appendFileSync, mkdirSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import { buildParityReport, parseParityEvents, writeParityReport } from "../uok/parity-report.ts";
+
+test("uok parity report summarizes paths, statuses, and fallback use", () => {
+  const events = parseParityEvents([
+    JSON.stringify({ path: "uok-kernel", phase: "enter" }),
+    JSON.stringify({ path: "uok-kernel", phase: "exit", status: "ok" }),
+    JSON.stringify({ path: "legacy-fallback", phase: "enter" }),
+    JSON.stringify({ path: "legacy-fallback", phase: "exit", status: "error", error: "boom" }),
+  ].join("\n"));
+
+  const report = buildParityReport(events, "/tmp/uok-parity.jsonl");
+  assert.equal(report.totalEvents, 4);
+  assert.equal(report.paths["uok-kernel"], 2);
+  assert.equal(report.fallbackInvocations, 2);
+  assert.deepEqual(report.criticalMismatches, ["boom"]);
+});
+
+test("uok parity report writes runtime report artifact", (t) => {
+  const basePath = mkdtempSync(join(tmpdir(), "gsd-uok-parity-"));
+  t.after(() => {
+    rmSync(basePath, { recursive: true, force: true });
+  });
+
+  const runtime = join(basePath, ".gsd", "runtime");
+  mkdirSync(runtime, { recursive: true });
+  appendFileSync(
+    join(runtime, "uok-parity.jsonl"),
+    `${JSON.stringify({ path: "uok-kernel", phase: "exit", status: "ok" })}\n`,
+    "utf-8",
+  );
+
+  const report = writeParityReport(basePath);
+  assert.equal(report.totalEvents, 1);
+  const saved = JSON.parse(readFileSync(join(runtime, "uok-parity-report.json"), "utf-8"));
+  assert.equal(saved.statuses.ok, 1);
+});

package/src/resources/extensions/gsd/tests/uok-plan-v2-wiring.test.ts

@@ -13,7 +13,11 @@ import {
   openDatabase,
 } from "../gsd-db.ts";
 import type { GSDState, Phase } from "../types.ts";
-import { ensurePlanV2Graph } from "../uok/plan-v2.ts";
+import {
+  ensurePlanV2Graph,
+  hasFinalizedMilestoneContext,
+  isMissingFinalizedContextResult,
+} from "../uok/plan-v2.ts";
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const gsdDir = join(__dirname, "..");
@@ -88,7 +92,7 @@ test.afterEach(() => {
   tempDirs.clear();
 });
 
-test("guided flow enforces plan-v2 gate before execution-oriented dispatch", () => {
+test("guided flow keeps plan-v2 fail-closed handling for non-recoverable failures", () => {
   const source = readFileSync(join(gsdDir, "guided-flow.ts"), "utf-8");
   assert.ok(
     source.includes("needsPlanV2Gate") &&
@@ -98,6 +102,17 @@ test("guided flow enforces plan-v2 gate before execution-oriented dispatch", ()
   );
 });
 
+test("guided flow routes recoverable missing finalized context to discuss-milestone", () => {
+  const source = readFileSync(join(gsdDir, "guided-flow.ts"), "utf-8");
+  assert.ok(
+    source.includes('PlanV2GateDecision = "pass" | "recover-missing-context" | "block"') &&
+    source.includes("isMissingFinalizedContextResult(compiled)") &&
+    source.includes('planV2GateDecision === "recover-missing-context"') &&
+    source.includes("buildDiscussMilestonePrompt"),
+    "guided flow should redispatch missing finalized context to discuss-milestone instead of fail-closing",
+  );
+});
+
 test("plan-v2 gate fails closed for execution phase when finalized context is missing", () => {
   const basePath = createBasePath();
   seedGraphRows();
@@ -107,6 +122,31 @@ test("plan-v2 gate fails closed for execution phase when finalized context is mi
   const compiled = ensurePlanV2Graph(basePath, buildState("executing"));
   assert.equal(compiled.ok, false);
   assert.match(compiled.reason ?? "", /CONTEXT\.md/i);
+  assert.equal(isMissingFinalizedContextResult(compiled), true);
+});
+
+test("plan-v2 gate accepts finalized context from project-root fallback", () => {
+  const projectRoot = createBasePath();
+  const worktreeBase = createBasePath();
+  seedGraphRows();
+
+  writeMilestoneFile(projectRoot, "CONTEXT", "Finalized context in project root.");
+  writeMilestoneFile(worktreeBase, "CONTEXT-DRAFT", "Draft context in worktree.");
+
+  const prevProjectRoot = process.env.GSD_PROJECT_ROOT;
+  process.env.GSD_PROJECT_ROOT = projectRoot;
+  try {
+    const compiled = ensurePlanV2Graph(worktreeBase, buildState("executing"));
+    assert.equal(compiled.ok, true);
+    assert.equal(compiled.finalizedContextIncluded, true);
+    assert.equal(hasFinalizedMilestoneContext(worktreeBase, MILESTONE_ID), true);
+  } finally {
+    if (prevProjectRoot === undefined) {
+      delete process.env.GSD_PROJECT_ROOT;
+    } else {
+      process.env.GSD_PROJECT_ROOT = prevProjectRoot;
+    }
+  }
 });
 
 test("plan-v2 compiler writes pipeline metadata for clarify/research/draft stages", () => {

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

@@ -0,0 +1,75 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import {
+  acquireWriterToken,
+  hasActiveWriterToken,
+  nextWriteRecord,
+  releaseWriterToken,
+  resetWriterTokensForTests,
+} from "../uok/writer.ts";
+
+test("uok writer enforces one active token per turn", (t) => {
+  const basePath = mkdtempSync(join(tmpdir(), "gsd-uok-writer-"));
+  resetWriterTokensForTests();
+  t.after(() => {
+    resetWriterTokensForTests();
+    rmSync(basePath, { recursive: true, force: true });
+  });
+
+  const token = acquireWriterToken({
+    basePath,
+    traceId: "trace-1",
+    turnId: "turn-1",
+  });
+  assert.equal(hasActiveWriterToken(basePath, "turn-1"), true);
+  assert.throws(
+    () => acquireWriterToken({ basePath, traceId: "trace-1", turnId: "turn-1" }),
+    /already active/,
+  );
+
+  releaseWriterToken(basePath, token);
+  assert.equal(hasActiveWriterToken(basePath, "turn-1"), false);
+});
+
+test("uok writer produces monotonic sequence records across turns", (t) => {
+  const basePath = mkdtempSync(join(tmpdir(), "gsd-uok-writer-seq-"));
+  resetWriterTokensForTests();
+  t.after(() => {
+    resetWriterTokensForTests();
+    rmSync(basePath, { recursive: true, force: true });
+  });
+
+  const token1 = acquireWriterToken({
+    basePath,
+    traceId: "trace-1",
+    turnId: "turn-1",
+  });
+  const first = nextWriteRecord({
+    basePath,
+    token: token1,
+    category: "audit",
+    operation: "append",
+    path: ".gsd/audit/events.jsonl",
+  });
+  releaseWriterToken(basePath, token1);
+
+  const token2 = acquireWriterToken({
+    basePath,
+    traceId: "trace-2",
+    turnId: "turn-2",
+  });
+  const second = nextWriteRecord({
+    basePath,
+    token: token2,
+    category: "gitops",
+    operation: "insert",
+  });
+
+  assert.equal(first.sequence.sequence, 1);
+  assert.equal(second.sequence.sequence, 2);
+  assert.equal(second.sequence.turnId, "turn-2");
+});

package/src/resources/extensions/gsd/tests/validate-extension-package.test.ts

@@ -0,0 +1,168 @@
+// GSD-2 — Tests for validateExtensionPackage (EXTR-02, PKG-05)
+import test from "node:test";
+import assert from "node:assert/strict";
+import { mkdirSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { validateExtensionPackage } from "../commands-extensions.ts";
+
+// ─── Helpers ──────────────────────────────────────────────────────────────────
+
+function makeTempDir(): string {
+  const dir = join(tmpdir(), `validate-ext-test-${Date.now()}-${Math.random().toString(36).slice(2)}`);
+  mkdirSync(dir, { recursive: true });
+  return dir;
+}
+
+function writePackageJson(dir: string, content: Record<string, unknown>): void {
+  writeFileSync(join(dir, "package.json"), JSON.stringify(content, null, 2));
+}
+
+function writeIndexTs(dir: string, content = "export default function() {}"): void {
+  writeFileSync(join(dir, "index.ts"), content);
+}
+
+// ─── Tests ────────────────────────────────────────────────────────────────────
+
+test("validateExtensionPackage: valid package returns { valid: true }", (t) => {
+  // EXTR-02: gsd.extension: true, peerDependencies, pi.extensions
+  const dir = makeTempDir();
+  t.after(() => rmSync(dir, { recursive: true, force: true }));
+
+  writeIndexTs(dir);
+  writePackageJson(dir, {
+    name: "@gsd-extensions/test",
+    version: "1.0.0",
+    gsd: { extension: true },
+    pi: { extensions: ["./index.ts"] },
+    peerDependencies: { "@gsd/pi-coding-agent": "*" },
+    dependencies: { "some-lib": "^1.0.0" },
+  });
+
+  const result = validateExtensionPackage(dir);
+  assert.equal(result.valid, true);
+  assert.deepEqual(result.errors, []);
+});
+
+test("validateExtensionPackage: missing gsd.extension marker returns error", (t) => {
+  const dir = makeTempDir();
+  t.after(() => rmSync(dir, { recursive: true, force: true }));
+
+  writeIndexTs(dir);
+  writePackageJson(dir, {
+    name: "@gsd-extensions/test",
+    version: "1.0.0",
+    pi: { extensions: ["./index.ts"] },
+    peerDependencies: { "@gsd/pi-coding-agent": "*" },
+  });
+
+  const result = validateExtensionPackage(dir);
+  assert.equal(result.valid, false);
+  assert.ok(result.errors.some(e => e.includes("gsd")), `Expected error about gsd, got: ${JSON.stringify(result.errors)}`);
+});
+
+test("validateExtensionPackage: missing pi.extensions returns error", (t) => {
+  const dir = makeTempDir();
+  t.after(() => rmSync(dir, { recursive: true, force: true }));
+
+  writeIndexTs(dir);
+  writePackageJson(dir, {
+    name: "@gsd-extensions/test",
+    version: "1.0.0",
+    gsd: { extension: true },
+    peerDependencies: { "@gsd/pi-coding-agent": "*" },
+  });
+
+  const result = validateExtensionPackage(dir);
+  assert.equal(result.valid, false);
+  assert.ok(result.errors.some(e => e.includes("pi")), `Expected error about pi.extensions, got: ${JSON.stringify(result.errors)}`);
+});
+
+test("validateExtensionPackage: pi.extensions entry path not found returns error", (t) => {
+  const dir = makeTempDir();
+  t.after(() => rmSync(dir, { recursive: true, force: true }));
+
+  // Do NOT create index.ts
+  writePackageJson(dir, {
+    name: "@gsd-extensions/test",
+    version: "1.0.0",
+    gsd: { extension: true },
+    pi: { extensions: ["./index.ts"] },
+    peerDependencies: { "@gsd/pi-coding-agent": "*" },
+  });
+
+  const result = validateExtensionPackage(dir);
+  assert.equal(result.valid, false);
+  assert.ok(result.errors.some(e => e.includes("index.ts")), `Expected error about index.ts, got: ${JSON.stringify(result.errors)}`);
+});
+
+test("validateExtensionPackage: @gsd/* in dependencies (not peerDependencies) returns error", (t) => {
+  const dir = makeTempDir();
+  t.after(() => rmSync(dir, { recursive: true, force: true }));
+
+  writeIndexTs(dir);
+  writePackageJson(dir, {
+    name: "@gsd-extensions/test",
+    version: "1.0.0",
+    gsd: { extension: true },
+    pi: { extensions: ["./index.ts"] },
+    dependencies: { "@gsd/pi-coding-agent": "^2.0.0" },
+  });
+
+  const result = validateExtensionPackage(dir);
+  assert.equal(result.valid, false);
+  assert.ok(result.errors.some(e => e.includes("@gsd/pi-coding-agent")), `Expected error about @gsd/ dep, got: ${JSON.stringify(result.errors)}`);
+});
+
+test("validateExtensionPackage: @gsd/* in devDependencies returns error", (t) => {
+  const dir = makeTempDir();
+  t.after(() => rmSync(dir, { recursive: true, force: true }));
+
+  writeIndexTs(dir);
+  writePackageJson(dir, {
+    name: "@gsd-extensions/test",
+    version: "1.0.0",
+    gsd: { extension: true },
+    pi: { extensions: ["./index.ts"] },
+    peerDependencies: { "@gsd/pi-coding-agent": "*" },
+    devDependencies: { "@gsd/pi-tui": "^2.0.0" },
+  });
+
+  const result = validateExtensionPackage(dir);
+  assert.equal(result.valid, false);
+  assert.ok(
+    result.errors.some(e => e.includes("@gsd/pi-tui") && e.includes("devDependencies")),
+    `Expected error about @gsd/ in devDependencies, got: ${JSON.stringify(result.errors)}`,
+  );
+});
+
+test("validateExtensionPackage: missing package.json returns error", (t) => {
+  const dir = makeTempDir();
+  t.after(() => rmSync(dir, { recursive: true, force: true }));
+
+  // No package.json written
+  const result = validateExtensionPackage(dir);
+  assert.equal(result.valid, false);
+  assert.ok(result.errors.some(e => e.includes("package.json")), `Expected error about package.json, got: ${JSON.stringify(result.errors)}`);
+});
+
+test("validateExtensionPackage: invalid JSON in package.json returns error", (t) => {
+  const dir = makeTempDir();
+  t.after(() => rmSync(dir, { recursive: true, force: true }));
+
+  writeFileSync(join(dir, "package.json"), "{ invalid json :::}");
+
+  const result = validateExtensionPackage(dir);
+  assert.equal(result.valid, false);
+  assert.ok(result.errors.some(e => e.toLowerCase().includes("json")), `Expected JSON error, got: ${JSON.stringify(result.errors)}`);
+});
+
+test("validateExtensionPackage: extracted google-search package passes validation (PKG-05)", (_t) => {
+  // This test runs against the actual extensions/google-search/ directory.
+  // Use process.cwd() (project root) since relative path from import.meta.url
+  // breaks when tests run from dist-test/.
+  const googleSearchDir = join(process.cwd(), "extensions", "google-search");
+
+  const result = validateExtensionPackage(googleSearchDir);
+  assert.equal(result.valid, true, `extensions/google-search/ should be valid, errors: ${JSON.stringify(result.errors)}`);
+});