Fix second-round review findings in agents validation and static analysis

- Run validateAgentsConfig() outside the VALIDATE_MANIFEST guard: Vite
  compiles import.meta.env.DEV to false in production server/edge
  bundles, which stripped the security validation and let a typo'd
  policy fail open again.
- Mask comments before locating the manifest capabilities block so a
  block-commented example cannot shadow the live registry in verify.
- Resolve the default-exported capability to the module-scope binding
  (brace-depth 0), not a shadowed inner declaration.
- Make template-literal scanning interpolation-aware so a nested
  template in run() no longer truncates extraction and silently
  privatizes an exposed capability.
- Extend the typegen collision guard to basename collisions between the
  declaration and capabilities outputs.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: JoviDeCroock

packages/capabilities/src/static.ts

@@ -54,9 +54,15 @@ function findDefaultExportedCallParen(searchable: string): number {
     // `=` inside `=>`.
     const decl = new RegExp(
       `\\b(?:const|let|var)\\s+${id}\\b[^;]*?=\\s*defineCapability\\s*(?:<[^(]*?>)?\\s*\\(`,
-    ).exec(searchable);
-    if (decl && decl.index != null) {
-      return decl.index + decl[0].length - 1;
+      "g",
+    );
+    // The default export refers to the MODULE-scope binding; a shadowed
+    // declaration inside a function must not win. Prefer the match at brace
+    // depth 0.
+    for (const match of searchable.matchAll(decl)) {
+      if (match.index != null && braceDepthAt(searchable, match.index) === 0) {
+        return match.index + match[0].length - 1;
+      }
     }
   }
 
@@ -68,6 +74,20 @@ function findDefaultExportedCallParen(searchable: string): number {
   return -1;
 }
 
+/**
+ * Brace/paren/bracket nesting depth at `index` in an already comment- and
+ * string-masked source. Depth 0 means module scope.
+ */
+function braceDepthAt(searchable: string, index: number): number {
+  let depth = 0;
+  for (let cursor = 0; cursor < index; cursor += 1) {
+    const char = searchable[cursor];
+    if (char === "{" || char === "(" || char === "[") depth += 1;
+    else if (char === "}" || char === ")" || char === "]") depth -= 1;
+  }
+  return depth;
+}
+
 /** Local binding name of a module's default export, or null. */
 function defaultExportLocalName(searchable: string): string | null {
   const idMatch = /export\s+default\s+([A-Za-z_$][A-Za-z0-9_$]*)\b/.exec(searchable);
@@ -307,6 +327,7 @@ function findQuotedObjectProperty(source: string, key: string): number | null {
 /** Index of the closing quote of the string starting at `start`. */
 function findStringEnd(source: string, start: number): number {
   const quote = source[start];
+  if (quote === "`") return findTemplateEnd(source, start);
   for (let index = start + 1; index < source.length; index += 1) {
     const char = source[index];
     if (char === "\\") {
@@ -318,6 +339,45 @@ function findStringEnd(source: string, start: number): number {
   return -1;
 }
 
+/**
+ * Index of the closing backtick of the template literal starting at `start`.
+ * Tracks `${ ... }` interpolations (including nested strings and templates
+ * inside them) so an inner backtick or `}` does not end the template early.
+ */
+function findTemplateEnd(source: string, start: number): number {
+  for (let index = start + 1; index < source.length; index += 1) {
+    const char = source[index];
+    if (char === "\\") {
+      index += 1;
+      continue;
+    }
+    if (char === "`") return index;
+    if (char === "$" && source[index + 1] === "{") {
+      let depth = 1;
+      index += 2;
+      while (index < source.length && depth > 0) {
+        const inner = source[index];
+        if (inner === "\\") {
+          index += 2;
+          continue;
+        }
+        if (inner === '"' || inner === "'" || inner === "`") {
+          const end = findStringEnd(source, index);
+          if (end === -1) return -1;
+          index = end + 1;
+          continue;
+        }
+        if (inner === "{") depth += 1;
+        else if (inner === "}") depth -= 1;
+        index += 1;
+      }
+      if (depth > 0) return -1;
+      index -= 1;
+    }
+  }
+  return -1;
+}
+
 function findMatchingBrace(source: string, start: number, open: string, close: string): number {
   let depth = 0;
   for (let index = start; index < source.length; index += 1) {

packages/capabilities/test/static.test.ts

@@ -74,6 +74,39 @@ describe("capability static extraction", () => {
     expect(extractDefineCapabilityArgs(source)).toContain('title: "Only call"');
   });
 
+  it("resolves the module-scope binding, not a shadowed inner declaration", () => {
+    const source = `
+      function make() {
+        const cap = defineCapability({ title: "Inner helper", run() {} });
+        return cap;
+      }
+      const cap = defineCapability({ title: "Module scope", run() {} });
+      export default cap;
+    `;
+
+    const args = extractDefineCapabilityArgs(source);
+    expect(args).toContain('title: "Module scope"');
+    expect(args).not.toContain('title: "Inner helper"');
+  });
+
+  it("does not truncate at a nested template literal in run()", () => {
+    const source = `
+      export default defineCapability({
+        title: "Templates",
+        run({ input }) {
+          const inner = \`prefix \${\`nested \${input.name}\`} suffix\`;
+          return { message: inner };
+        },
+        effect: "read",
+        expose: { http: true },
+      });
+    `;
+
+    const args = extractDefineCapabilityArgs(source);
+    expect(args).toContain('effect: "read"');
+    expect(args).toContain("expose:");
+  });
+
   it("does not truncate at a brace inside a regex literal", () => {
     const source = `
       export default defineCapability({

packages/cli/src/commands/typegen.ts

@@ -132,11 +132,15 @@ export async function runTypegen(options: TypegenOptions): Promise<TypegenResult
         "so the generated capability types would never apply. Pick a different --capabilities-out.",
     );
   }
-  if (capabilitiesPath === declarationPath) {
+  if (
+    capabilitiesPath === declarationPath ||
+    outputsCollide(declarationPath, capabilitiesPath) ||
+    outputsCollide(capabilitiesPath, declarationPath)
+  ) {
     throw new Error(
-      `Capabilities output ${options.capabilitiesOut} is the same file as the declaration output ` +
-        `${options.declarationOut}; the two generated files would overwrite each other. ` +
-        "Pick a different --capabilities-out.",
+      `Capabilities output ${options.capabilitiesOut} collides with the declaration output ` +
+        `${options.declarationOut} — identical paths overwrite each other, and TypeScript drops ` +
+        "a .d.ts input that sits next to a same-named .ts file. Pick a different --capabilities-out.",
     );
   }
   const outputs = [

packages/cli/src/manifest.ts

@@ -106,11 +106,15 @@ export function extractRegistryEntries(
   source: string,
   key: string,
 ): { name: string; path: string }[] {
-  const block = findNamedBlock(source, key, "{", "}");
-  if (!block) return [];
-  // Mask comments before matching so commented-out registrations are not
+  // Mask comments BEFORE locating the block so a block-commented example
+  // (`/* capabilities: { ... } */`) cannot be selected instead of the live
+  // registry, and commented-out registrations inside the live block are not
   // treated as registered (mirrors the analyzer in @pracht/capabilities).
-  const inner = maskComments(source.slice(block.openIndex + 1, block.closeIndex));
+  // Masking preserves offsets, so slicing the masked source is safe.
+  const masked = maskComments(source);
+  const block = findNamedBlock(masked, key, "{", "}");
+  if (!block) return [];
+  const inner = masked.slice(block.openIndex + 1, block.closeIndex);
   const entries: { name: string; path: string }[] = [];
   // Keys may be bare identifiers (shells, middleware) or quoted strings —
   // capability names like "notes.search" require quoting.

packages/cli/test/verification-capabilities.test.ts

@@ -118,6 +118,32 @@ describe("collectCapabilityChecks", () => {
     );
   });
 
+  it("reads the live registry when a block-commented example precedes it", () => {
+    const checks: Check[] = [];
+    collectCapabilityChecks(
+      createProject({
+        capability: capabilitySource(COMPLETE_FIELDS),
+        middlewareBlock: [
+          "  /*",
+          "  capabilities: {",
+          '    "notes.fake": () => import("./capabilities/notes-fake.ts"),',
+          "  },",
+          "  */",
+        ].join("\n"),
+      }),
+      checks,
+    );
+
+    // The commented example must not shadow the live registry: the real
+    // capability is analyzed (its OK check appears) and the fake one is not.
+    expect(checks.map((check) => check.message)).toContainEqual(
+      expect.stringContaining("declares a complete exposed contract"),
+    );
+    expect(checks.map((check) => check.message)).not.toContainEqual(
+      expect.stringContaining("notes.fake"),
+    );
+  });
+
   it("does not count a commented-out registration", () => {
     const checks: Check[] = [];
     collectCapabilityChecks(

packages/framework/src/app.ts

@@ -181,9 +181,15 @@ export function resolveApp(app: PrachtApp): ResolvedPrachtApp {
         );
       }
     }
-    validateAgentsConfig(app.agents);
   }
 
+  // Security validation, deliberately OUTSIDE the VALIDATE_MANIFEST guard:
+  // Vite compiles `import.meta.env.DEV` to `false` in production server/edge
+  // bundles, which would strip a dev-only check and let a typo'd policy
+  // (e.g. "requre") silently fail open at dispatch. This runs once per
+  // manifest resolution, so the cost is negligible.
+  validateAgentsConfig(app.agents);
+
   for (const node of app.routes) {
     flattenRouteNode(app, node, inherited, routes);
   }