@praneeth_54/agentdoctor 3.0.0 → 3.0.1

package/dist/cli/commands/learn.js

@@ -2,9 +2,14 @@ import { MockModelProvider, createModelProvider, loadAiConfig } from "../../ai/i
 import { StudentService } from "../../agent/student.js";
 import { parseAgentMode, defaultStudentMode } from "../../agent/modes.js";
 import { EXIT_CODES } from "../../types/index.js";
-import { resolveRepoRoot } from "../../utils/path.js";
+import { resolveCliProjectRoot } from "../safe-root.js";
 export async function runLearnCommand(options) {
-    const root = resolveRepoRoot(options.root ?? process.cwd());
+    const gated = await resolveCliProjectRoot(options.root ?? process.cwd());
+    if (!gated.ok) {
+        console.error(`Error: ${gated.message}`);
+        return gated.code;
+    }
+    const root = gated.root;
     const mode = parseAgentMode(options.mode) ?? defaultStudentMode();
     const provider = options.useMock ? new MockModelProvider() : createModelProvider(loadAiConfig());
     const resolvedMode = options.build

package/dist/cli/commands/mcp.js

@@ -1,13 +1,17 @@
 import { EXIT_CODES } from "../../types/index.js";
-import { resolveRepoRoot } from "../../utils/path.js";
+import { resolveCliProjectRoot } from "../safe-root.js";
 import { runAgentDoctorMcpStdio } from "../../mcp/agentdoctor/server.js";
 /**
  * Start combined AgentDoctor MCP (Brain tools + intelligence tools) over STDIO.
  */
 export async function runMcpCommand(options) {
-    const root = resolveRepoRoot(options.root);
+    const gated = await resolveCliProjectRoot(options.root);
+    if (!gated.ok) {
+        console.error(`Error: ${gated.message}`);
+        return gated.code;
+    }
     await runAgentDoctorMcpStdio({
-        root,
+        root: gated.root,
         buildIfMissing: options.buildIfMissing !== false,
     });
     return EXIT_CODES.SUCCESS;

package/dist/cli/commands/platform.js

@@ -1,13 +1,18 @@
 import { randomUUID } from "node:crypto";
 import { EXIT_CODES } from "../../types/index.js";
-import { resolveRepoRoot } from "../../utils/path.js";
+import { resolveCliProjectRoot } from "../safe-root.js";
 import { analyzeRenameImpact, analyzeTestImpact, appendSessionEvent, buildProvenance, compareCommits, createSession, endSession, evaluateAgentAction, exportSessionMarkdown, formatTestImpactHuman, listSessions, loadSession, persistTestImpactReport, planContext, runPlatformScan, saveProvenance, EVALUATE_ONLY, } from "../../platform/index.js";
 import { buildRepositoryGraph } from "../../platform/graph/build.js";
 function printJson(value) {
     process.stdout.write(`${JSON.stringify(value, null, 2)}\n`);
 }
 export async function runPlatformCommand(options) {
-    const root = resolveRepoRoot(options.root ?? process.cwd());
+    const gated = await resolveCliProjectRoot(options.root ?? process.cwd());
+    if (!gated.ok) {
+        console.error(`Error: ${gated.message}`);
+        return gated.code;
+    }
+    const root = gated.root;
     try {
         switch (options.action) {
             case "scan": {

package/dist/cli/commands/policy-graph-run.js

@@ -3,6 +3,7 @@ import { runControlledCommand } from "../../enforcement/runner.js";
 import { graphBuild, graphRebuild, graphStatus, graphUpdate, } from "../../intelligence/graph/incremental.js";
 import { buildIntelligenceGraph } from "../../intelligence/graph/build.js";
 import { EXIT_CODES } from "../../types/index.js";
+import { resolveCliProjectRoot } from "../safe-root.js";
 function emit(json, value, human) {
     if (json) {
         process.stdout.write(`${JSON.stringify(value, null, 2)}\n`);
@@ -13,6 +14,12 @@ function emit(json, value, human) {
 }
 export async function runGraphSurfaceCommand(options) {
     try {
+        const gated = await resolveCliProjectRoot(options.root);
+        if (!gated.ok) {
+            console.error(`Error: ${gated.message}`);
+            return gated.code;
+        }
+        options = { ...options, root: gated.root };
         const mode = options.mode ?? "auto";
         if (options.action === "status") {
             const status = await graphStatus({ root: options.root });

package/dist/cli/commands/product.js

@@ -1,5 +1,5 @@
 import { EXIT_CODES } from "../../types/index.js";
-import { resolveRepoRoot } from "../../utils/path.js";
+import { resolveCliProjectRoot } from "../safe-root.js";
 import { resolveTargetArgument } from "./scan.js";
 import { traceRequirements, analyzeApiSurface, analyzeDatabaseSchema, analyzeEvents, analyzeDependencies, analyzeCodeHealth, buildSoftwareMap, analyzeWhatIf, loadDecisionLedger, runForensicAnalysis, buildSoftwareDigitalTwin, runEvalLab, diagnoseAgentDoctorSelf, analyzeInfra, buildIncidentHypotheses, readChangeLedger, analyzeSecuritySurface, analyzePrivacySurface, searchSymbolsAndConcepts, buildTechnicalDebtRoadmap, analyzeFeatureIntelligence, buildSoftwareEvolutionTimeline, queryMemory, loadOrganizationModel, analyzeTestBrain, } from "../../product/index.js";
 import { runRoleAgent } from "../../agent/roles.js";
@@ -7,7 +7,12 @@ function printJson(value) {
     process.stdout.write(`${JSON.stringify(value, null, 2)}\n`);
 }
 export async function runProductCommand(options) {
-    const root = resolveRepoRoot(options.root ?? resolveTargetArgument(undefined));
+    const gated = await resolveCliProjectRoot(options.root ?? resolveTargetArgument(undefined));
+    if (!gated.ok) {
+        console.error(`Error: ${gated.message}`);
+        return gated.code;
+    }
+    const root = gated.root;
     try {
         let payload;
         switch (options.action) {
@@ -137,7 +142,12 @@ export async function runProductCommand(options) {
     }
 }
 export async function runChangeLedgerListCommand(options) {
-    const root = resolveRepoRoot(options.root ?? process.cwd());
+    const gated = await resolveCliProjectRoot(options.root);
+    if (!gated.ok) {
+        console.error(`Error: ${gated.message}`);
+        return gated.code;
+    }
+    const root = gated.root;
     const payload = await readChangeLedger(root);
     if (options.json)
         printJson(payload);

package/dist/cli/commands/scan.js

@@ -1,6 +1,7 @@
 import path from "node:path";
 import { evaluateScanPolicy } from "../../core/policy/evaluate.js";
 import { scan } from "../../core/scanner/scan.js";
+import { classifyBroadUserScanRoot } from "../../product/discovery/roots.js";
 import { emitGithubReports } from "../../reporters/github/emit.js";
 import { renderJsonReport } from "../../reporters/json/report.js";
 import { renderTerminalReport } from "../../reporters/terminal/report.js";
@@ -13,6 +14,11 @@ export async function runScanCommand(options) {
         console.error(`Error: not a directory: ${target}`);
         return EXIT_CODES.USAGE_ERROR;
     }
+    const broad = classifyBroadUserScanRoot(target);
+    if (broad.blocked) {
+        console.error(`Error: ${broad.reason}`);
+        return EXIT_CODES.USAGE_ERROR;
+    }
     try {
         const result = await scan({
             cwd: target,

package/dist/cli/commands/start.js

@@ -3,6 +3,7 @@ import { initBrainStore, rebuildBrain, getBrainStatus } from "../../core/brain-c
 import { discoverProjectRoots } from "../../product/discovery/roots.js";
 import { buildProjectDna, persistProjectDna } from "../../product/dna/build.js";
 import { resolveRepoRoot } from "../../utils/path.js";
+import { resolveCliProjectRoot } from "../safe-root.js";
 function printJson(value) {
     process.stdout.write(`${JSON.stringify(value, null, 2)}\n`);
 }
@@ -64,7 +65,12 @@ export async function runStartCommand(options) {
     return EXIT_CODES.SUCCESS;
 }
 export async function runDnaCommand(options) {
-    const root = resolveRepoRoot(options.root ?? process.cwd());
+    const gated = await resolveCliProjectRoot(options.root);
+    if (!gated.ok) {
+        console.error(`Error: ${gated.message}`);
+        return gated.code;
+    }
+    const root = gated.root;
     const dna = options.persist ? await persistProjectDna(root) : await buildProjectDna(root);
     if (options.json) {
         printJson(dna);

package/dist/cli/commands/v2.js

@@ -1,5 +1,5 @@
 import { EXIT_CODES } from "../../types/index.js";
-import { resolveRepoRoot } from "../../utils/path.js";
+import { resolveCliProjectRoot } from "../safe-root.js";
 import { analyzeChanges } from "../../core/changes/analyze.js";
 import { analyzeContextHealth } from "../../core/context-health/analyze.js";
 import { scanSecrets } from "../../core/secrets/scan.js";
@@ -16,7 +16,12 @@ function printJson(value) {
     process.stdout.write(`${JSON.stringify(value, null, 2)}\n`);
 }
 export async function runChangesCommand(options) {
-    const root = resolveRepoRoot(options.root ?? process.cwd());
+    const gated = await resolveCliProjectRoot(options.root ?? process.cwd());
+    if (!gated.ok) {
+        console.error(`Error: ${gated.message}`);
+        return gated.code;
+    }
+    const root = gated.root;
     const report = await analyzeChanges({
         root,
         ...(options.since ? { since: options.since } : {}),
@@ -38,7 +43,12 @@ export async function runChangesCommand(options) {
     return EXIT_CODES.SUCCESS;
 }
 export async function runContextHealthCommand(options) {
-    const root = resolveRepoRoot(options.root ?? process.cwd());
+    const gated = await resolveCliProjectRoot(options.root ?? process.cwd());
+    if (!gated.ok) {
+        console.error(`Error: ${gated.message}`);
+        return gated.code;
+    }
+    const root = gated.root;
     const report = await analyzeContextHealth(root);
     if (options.json)
         printJson(report);
@@ -51,7 +61,12 @@ export async function runContextHealthCommand(options) {
     return EXIT_CODES.SUCCESS;
 }
 export async function runSecretsCommand(options) {
-    const root = resolveRepoRoot(options.root ?? process.cwd());
+    const gated = await resolveCliProjectRoot(options.root ?? process.cwd());
+    if (!gated.ok) {
+        console.error(`Error: ${gated.message}`);
+        return gated.code;
+    }
+    const root = gated.root;
     const report = await scanSecrets({ root, enabled: true });
     if (options.json)
         printJson(report);
@@ -67,8 +82,13 @@ export async function runSecretsCommand(options) {
 }
 export async function runFixUndoCommand(options) {
     try {
+        const gated = await resolveCliProjectRoot(options.root);
+        if (!gated.ok) {
+            console.error(`Error: ${gated.message}`);
+            return gated.code;
+        }
         const record = await undoFix({
-            root: resolveRepoRoot(options.root ?? process.cwd()),
+            root: gated.root,
             auditId: options.auditId,
         });
         process.stdout.write(`Undid Safe Fix audit ${options.auditId} → undo audit ${record.id}\n`);
@@ -80,7 +100,12 @@ export async function runFixUndoCommand(options) {
     }
 }
 export async function runFixHistoryCommand(options) {
-    const audits = await listFixAudits(resolveRepoRoot(options.root ?? process.cwd()));
+    const gated = await resolveCliProjectRoot(options.root);
+    if (!gated.ok) {
+        console.error(`Error: ${gated.message}`);
+        return gated.code;
+    }
+    const audits = await listFixAudits(gated.root);
     if (options.json)
         printJson({ audits });
     else if (audits.length === 0)
@@ -93,7 +118,12 @@ export async function runFixHistoryCommand(options) {
     return EXIT_CODES.SUCCESS;
 }
 export async function runBaselineCommand(options) {
-    const root = resolveRepoRoot(options.root ?? process.cwd());
+    const gated = await resolveCliProjectRoot(options.root ?? process.cwd());
+    if (!gated.ok) {
+        console.error(`Error: ${gated.message}`);
+        return gated.code;
+    }
+    const root = gated.root;
     try {
         if (options.action === "list") {
             const names = await listNamedBaselines(root);
@@ -167,7 +197,12 @@ export async function runBaselineCommand(options) {
     }
 }
 export async function runPackagesCommand(options) {
-    const root = resolveRepoRoot(options.root ?? process.cwd());
+    const gated = await resolveCliProjectRoot(options.root ?? process.cwd());
+    if (!gated.ok) {
+        console.error(`Error: ${gated.message}`);
+        return gated.code;
+    }
+    const root = gated.root;
     const mono = await detectMonorepo(root);
     if (!options.scan) {
         if (options.json)
@@ -200,8 +235,13 @@ export async function runPackagesCommand(options) {
     return EXIT_CODES.SUCCESS;
 }
 export async function runPrReviewCommand(options) {
+    const gated = await resolveCliProjectRoot(options.root);
+    if (!gated.ok) {
+        console.error(`Error: ${gated.message}`);
+        return gated.code;
+    }
     const report = await analyzePullRequest({
-        root: resolveRepoRoot(options.root ?? process.cwd()),
+        root: gated.root,
         dryRun: true,
         ...(options.base ? { baseRef: options.base } : {}),
     });
@@ -215,8 +255,13 @@ export async function runPrReviewCommand(options) {
 }
 export async function runDashboardCommand(options) {
     try {
+        const gated = await resolveCliProjectRoot(options.root);
+        if (!gated.ok) {
+            console.error(`Error: ${gated.message}`);
+            return gated.code;
+        }
         const server = await startDashboardServer({
-            root: resolveRepoRoot(options.root ?? process.cwd()),
+            root: gated.root,
             host: options.host ?? "127.0.0.1",
             port: options.port ?? 8787,
             readOnly: true,
@@ -237,7 +282,12 @@ export async function runDashboardCommand(options) {
     }
 }
 export async function runPluginsCommand(options) {
-    const root = resolveRepoRoot(options.root ?? process.cwd());
+    const gated = await resolveCliProjectRoot(options.root);
+    if (!gated.ok) {
+        console.error(`Error: ${gated.message}`);
+        return gated.code;
+    }
+    const root = gated.root;
     const plugins = await discoverPlugins(root);
     const analyzerResults = options.run ? await runPluginAnalyzers(root) : undefined;
     if (options.json) {

package/dist/cli/commands/verify.js

@@ -1,5 +1,6 @@
 import { evaluateVerifyPolicy } from "../../core/policy/evaluate.js";
 import { verify } from "../../core/verify/verify.js";
+import { classifyBroadUserScanRoot } from "../../product/discovery/roots.js";
 import { emitGithubReports } from "../../reporters/github/emit.js";
 import { renderVerifyJsonReport } from "../../reporters/verify/json.js";
 import { renderVerifyTerminalReport } from "../../reporters/verify/terminal.js";
@@ -15,6 +16,11 @@ export async function runVerifyCommand(options) {
         console.error(`Error: not a directory: ${target}`);
         return EXIT_CODES.USAGE_ERROR;
     }
+    const broad = classifyBroadUserScanRoot(target);
+    if (broad.blocked) {
+        console.error(`Error: ${broad.reason}`);
+        return EXIT_CODES.USAGE_ERROR;
+    }
     try {
         const result = await verify({
             cwd: target,

package/dist/cli/safe-root.d.ts

@@ -0,0 +1,17 @@
+import { type ExitCode } from "../types/index.js";
+export type CliRootOk = {
+    ok: true;
+    root: string;
+};
+export type CliRootErr = {
+    ok: false;
+    message: string;
+    code: ExitCode;
+};
+/**
+ * Resolve a CLI project root and refuse home / Desktop / Downloads / Documents
+ * (and similarly broad user folders) before any recursive intelligence work.
+ */
+export declare function resolveCliProjectRoot(pathArg?: string): Promise<CliRootOk | CliRootErr>;
+/** Sync variant when the path is already known to exist (tests / internal). */
+export declare function assertCliProjectRootSync(pathArg?: string): CliRootOk | CliRootErr;

package/dist/cli/safe-root.js

@@ -0,0 +1,32 @@
+import { classifyBroadUserScanRoot } from "../product/discovery/roots.js";
+import { EXIT_CODES } from "../types/index.js";
+import { isDirectory } from "../utils/fs.js";
+import { resolveRepoRoot } from "../utils/path.js";
+/**
+ * Resolve a CLI project root and refuse home / Desktop / Downloads / Documents
+ * (and similarly broad user folders) before any recursive intelligence work.
+ */
+export async function resolveCliProjectRoot(pathArg) {
+    const root = resolveRepoRoot(pathArg ?? process.cwd());
+    if (!(await isDirectory(root))) {
+        return {
+            ok: false,
+            message: `not a directory: ${root}`,
+            code: EXIT_CODES.USAGE_ERROR,
+        };
+    }
+    const broad = classifyBroadUserScanRoot(root);
+    if (broad.blocked) {
+        return { ok: false, message: broad.reason, code: EXIT_CODES.USAGE_ERROR };
+    }
+    return { ok: true, root };
+}
+/** Sync variant when the path is already known to exist (tests / internal). */
+export function assertCliProjectRootSync(pathArg) {
+    const root = resolveRepoRoot(pathArg ?? process.cwd());
+    const broad = classifyBroadUserScanRoot(root);
+    if (broad.blocked) {
+        return { ok: false, message: broad.reason, code: EXIT_CODES.USAGE_ERROR };
+    }
+    return { ok: true, root };
+}

package/dist/constants.d.ts

@@ -1,5 +1,5 @@
 import type { AgentId } from "./types/index.js";
-export declare const PACKAGE_VERSION = "3.0.0";
+export declare const PACKAGE_VERSION = "3.0.1";
 export declare const DEFAULT_MAX_FILE_SIZE_BYTES: number;
 /** Directories skipped during normal discovery (unless a rule needs them later). */
 export declare const DEFAULT_IGNORE_DIRECTORIES: Set<string>;

package/dist/constants.js

@@ -1,4 +1,4 @@
-export const PACKAGE_VERSION = "3.0.0";
+export const PACKAGE_VERSION = "3.0.1";
 export const DEFAULT_MAX_FILE_SIZE_BYTES = 2 * 1024 * 1024; // 2 MiB
 /** Directories skipped during normal discovery (unless a rule needs them later). */
 export const DEFAULT_IGNORE_DIRECTORIES = new Set([

package/dist/core/brain-cli/service.js

@@ -2,6 +2,7 @@ import fs from "node:fs/promises";
 import path from "node:path";
 import { LocalBrainStore, createBrainQueryEngine, redactBrainForStorage, } from "../understanding/brain/index.js";
 import { compileProjectBrain } from "../../mcp/brain/compile.js";
+import { OWNERSHIP_BOUNDARY_VERSION } from "../../project/ownership.js";
 import { resolveRepoRoot } from "../../utils/path.js";
 import { isDirectory } from "../../utils/fs.js";
 function storeFor(root) {
@@ -16,11 +17,13 @@ export async function getBrainStatus(root) {
     const storeRoot = path.join(resolved, ".agentdoctor", "project-brain");
     try {
         const meta = await store.readMeta();
+        const boundaryOk = meta.ownershipBoundaryVersion === OWNERSHIP_BOUNDARY_VERSION;
+        const hasUsableLatest = boundaryOk && meta.latestSnapshotId !== null;
         return {
             root: resolved,
             storeRoot,
-            hasSnapshot: meta.latestSnapshotId !== null,
-            latestSnapshotId: meta.latestSnapshotId,
+            hasSnapshot: hasUsableLatest,
+            latestSnapshotId: hasUsableLatest ? meta.latestSnapshotId : null,
             snapshotCount: meta.snapshots.length,
             projectName: meta.projectName || null,
             schemaVersion: meta.schemaVersion || null,

package/dist/core/monorepo/detect.js

@@ -1,5 +1,6 @@
 import fs from "node:fs/promises";
 import path from "node:path";
+import { classifyRelativePathOwnership, isUnderNestedRepository } from "../../project/ownership.js";
 import { resolveRepoRoot, toPosixRelative } from "../../utils/path.js";
 async function readJson(file) {
     try {
@@ -99,6 +100,15 @@ export async function detectMonorepo(rootInput) {
                 continue;
             if (seen.has(pkg.absolutePath))
                 continue;
+            const ownership = classifyRelativePathOwnership(pkg.relativePath);
+            if (ownership !== "project_owned") {
+                limitations.push(`Skipped non-owned workspace package: ${pkg.relativePath} (${ownership})`);
+                continue;
+            }
+            if (await isUnderNestedRepository(root, pkg.absolutePath)) {
+                limitations.push(`Skipped nested-repository workspace package: ${pkg.relativePath}`);
+                continue;
+            }
             seen.add(pkg.absolutePath);
             packages.push(pkg);
         }

package/dist/core/secrets/scan.js

@@ -1,5 +1,6 @@
 import fs from "node:fs/promises";
 import path from "node:path";
+import { decideDirectoryTraversal } from "../../project/ownership.js";
 import { readTextFile } from "../../utils/fs.js";
 import { resolveRepoRoot, toPosixRelative } from "../../utils/path.js";
 const SECRET_PATTERNS = [
@@ -94,6 +95,14 @@ async function walkFiles(root, dir, out, limit) {
         if (entry.isSymbolicLink())
             continue;
         if (entry.isDirectory()) {
+            const relativeDir = toPosixRelative(root, absolute);
+            const traversal = await decideDirectoryTraversal({
+                projectRoot: root,
+                absoluteDir: absolute,
+                relativeDir,
+            });
+            if (!traversal.traverse)
+                continue;
             await walkFiles(root, absolute, out, limit);
             continue;
         }

package/dist/core/understanding/brain/storage/store.d.ts

@@ -9,6 +9,8 @@ export interface SnapshotMeta {
     projectName: string;
     brainId: string;
     checksum: string;
+    /** Snapshots without this stamp (or with a mismatch) must not be served as current truth. */
+    ownershipBoundaryVersion?: number;
 }
 export interface BrainStoreMeta {
     storageFormatVersion: BrainStorageFormatVersion;
@@ -16,6 +18,8 @@ export interface BrainStoreMeta {
     projectName: string;
     latestSnapshotId: string | null;
     snapshots: SnapshotMeta[];
+    /** When missing or mismatched, latest brain is treated as stale vs current ownership rules. */
+    ownershipBoundaryVersion?: number;
 }
 export interface SnapshotComparison {
     leftId: string;

package/dist/core/understanding/brain/storage/store.js

@@ -2,6 +2,7 @@ import { createHash } from "node:crypto";
 import fs from "node:fs/promises";
 import path from "node:path";
 import { atomicWriteTextFile } from "../../../../utils/fs.js";
+import { OWNERSHIP_BOUNDARY_VERSION } from "../../../../project/ownership.js";
 import { parseBrainDelta, serializeBrainDelta } from "../delta.js";
 import { checkBrainCompatibility, migrateBrain } from "../migrate.js";
 import { assertBrainContract } from "../contract.js";
@@ -198,6 +199,7 @@ export class LocalBrainStore {
             projectName: brain.metadata.projectName,
             brainId: brain.metadata.brainId,
             checksum: nextChecksum,
+            ownershipBoundaryVersion: OWNERSHIP_BOUNDARY_VERSION,
         };
         const meta = await this.readMeta();
         const snapshots = meta.snapshots.filter((s) => s.id !== snapshotId);
@@ -209,10 +211,15 @@ export class LocalBrainStore {
             projectName: brain.metadata.projectName,
             latestSnapshotId: snapshotId,
             snapshots,
+            ownershipBoundaryVersion: OWNERSHIP_BOUNDARY_VERSION,
         });
         return snapMeta;
     }
     async loadSnapshot(snapshotId) {
+        const meta = await this.readMeta();
+        if (meta.ownershipBoundaryVersion !== OWNERSHIP_BOUNDARY_VERSION) {
+            throw new BrainStorageError(`brain store ownership boundary is stale (have ${String(meta.ownershipBoundaryVersion ?? "missing")}, need ${OWNERSHIP_BOUNDARY_VERSION}); rebuild required`);
+        }
         const target = await assertInsideRootResolved(this.root, this.brainPath(snapshotId));
         let raw;
         try {
@@ -224,9 +231,17 @@ export class LocalBrainStore {
             }
             throw error;
         }
-        const meta = await this.readMeta();
         const snap = meta.snapshots.find((s) => s.id === snapshotId);
         if (snap) {
+            if (snap.ownershipBoundaryVersion !== undefined &&
+                snap.ownershipBoundaryVersion !== OWNERSHIP_BOUNDARY_VERSION) {
+                throw new BrainStorageError(`snapshot ${snapshotId} ownership boundary is stale (have ${snap.ownershipBoundaryVersion}, need ${OWNERSHIP_BOUNDARY_VERSION}); rebuild required`);
+            }
+            // Pre-stamp snapshots created before ownershipBoundaryVersion was recorded are
+            // unsafe to serve once the store claims a current boundary — require rebuild.
+            if (snap.ownershipBoundaryVersion === undefined) {
+                throw new BrainStorageError(`snapshot ${snapshotId} missing ownershipBoundaryVersion; rebuild required`);
+            }
             const actual = checksumPayload(raw);
             if (actual !== snap.checksum) {
                 throw new BrainStorageError(`checksum mismatch for snapshot ${snapshotId}`);
@@ -261,7 +276,12 @@ export class LocalBrainStore {
         return meta.latestSnapshotId;
     }
     async loadLatest() {
-        const id = await this.latestSnapshotId();
+        const meta = await this.readMeta();
+        if (meta.ownershipBoundaryVersion !== OWNERSHIP_BOUNDARY_VERSION) {
+            // Pre-boundary or outdated snapshots must not be served as current project truth.
+            return null;
+        }
+        const id = meta.latestSnapshotId;
         if (!id) {
             return null;
         }

package/dist/dashboard/page.d.ts

@@ -0,0 +1,2 @@
+/** Embedded dashboard HTML. Version injected only from PACKAGE_VERSION. */
+export declare function htmlPage(): string;

package/dist/dashboard/page.js

@@ -0,0 +1,53 @@
+import { PACKAGE_VERSION } from "../constants.js";
+import { DASHBOARD_CSS } from "./ui/styles.js";
+import { DASHBOARD_CLIENT_JS } from "./ui/client.js";
+/** Embedded dashboard HTML. Version injected only from PACKAGE_VERSION. */
+export function htmlPage() {
+    const version = PACKAGE_VERSION;
+    const client = DASHBOARD_CLIENT_JS.replaceAll("%%PACKAGE_VERSION%%", version).replaceAll("</script>", "<\\/script>");
+    return `<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1" />
+  <title>AgentDoctor ${version}</title>
+  <style>${DASHBOARD_CSS}</style>
+</head>
+<body>
+  <div class="app" id="app">
+    <header class="topbar" role="banner">
+      <button type="button" class="btn btn-ghost mobile-nav" id="btnMenu" aria-label="Open navigation">☰</button>
+      <div class="brand">
+        <span class="brand-name">AgentDoctor</span>
+        <span class="brand-ver" id="headerVersion">v${version}</span>
+      </div>
+      <div class="project-chip" title="Active project">
+        <strong id="projectName">Loading…</strong>
+        <span id="projectMeta">Detecting stack…</span>
+      </div>
+      <div class="topbar-spacer"></div>
+      <div class="topbar-actions">
+        <span class="topbar-status" id="topbarStatus" title="Dashboard mode"><span class="status-dot" aria-hidden="true"></span>Local · Read-only</span>
+        <button type="button" class="btn" id="btnCommand" aria-label="Open command palette">Search <span class="kbd">⌘K</span></button>
+        <a class="btn" href="#system">System</a>
+      </div>
+    </header>
+    <aside class="sidebar" id="sidebar" aria-label="Primary">
+      <button type="button" class="btn btn-ghost side-toggle" id="btnCollapse" aria-label="Collapse sidebar">⇄</button>
+      <nav id="sidebarNav"></nav>
+    </aside>
+    <main class="main" role="main">
+      <div class="content" id="pageRoot"></div>
+    </main>
+  </div>
+  <div class="drawer-backdrop" id="drawerBackdrop"></div>
+  <div class="palette" id="palette" role="dialog" aria-modal="true" aria-label="Command palette">
+    <div class="palette-box">
+      <input id="paletteInput" placeholder="Go to page or search project…" aria-label="Command search" />
+      <div class="palette-list" id="paletteList"></div>
+    </div>
+  </div>
+  <script>${client}</script>
+</body>
+</html>`;
+}