@open-agent-toolkit/cli 0.2.76 → 0.2.77

package/assets/bundle-metadata.json

@@ -1,4 +1,4 @@
 {
   "schemaVersion": 1,
-  "oatVersion": "0.2.76"
+  "oatVersion": "0.2.77"
 }

package/assets/public-package-versions.json

@@ -1,6 +1,6 @@
 {
-  "cli": "0.2.76",
-  "docs-config": "0.2.76",
-  "docs-theme": "0.2.76",
-  "docs-transforms": "0.2.76"
+  "cli": "0.2.77",
+  "docs-config": "0.2.77",
+  "docs-theme": "0.2.77",
+  "docs-transforms": "0.2.77"
 }

package/assets/skills/explainer-kit/SKILL.md

@@ -4,7 +4,7 @@ description: Use when building destination-neutral visual explainer artifacts fr
 user-invocable: true
 allowed-tools: Read, Write, Edit, Bash, Grep, Glob, Agent, mcp__*
 metadata:
-  version: 3.0.2
+  version: 3.0.3
 ---
 
 # Explainer Kit

package/assets/skills/explainer-kit/scripts/bundle.mjs

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 
 import { createHash } from 'node:crypto';
+import { realpathSync } from 'node:fs';
 import {
   lstat,
   mkdir,
@@ -20,8 +21,9 @@ import {
   isAbsolute,
   join,
   relative,
+  resolve,
 } from 'node:path';
-import { pathToFileURL } from 'node:url';
+import { fileURLToPath } from 'node:url';
 
 import {
   harvestNumericTokens,
@@ -704,7 +706,29 @@ function bundleError(message) {
   return error;
 }
 
-if (import.meta.url === pathToFileURL(process.argv[1] ?? '').href) {
+/**
+ * Direct invocation, compared as canonical paths on both sides. Comparing a raw
+ * `process.argv[1]` against `import.meta.url` makes this script a silent no-op
+ * that exits 0 whenever the skill is reached through a symlinked install root,
+ * and canonicalizing only one side has the same effect under
+ * `--preserve-symlinks-main`, which keeps the link in `import.meta.url`.
+ * A path that cannot be canonicalized is not a module Node loaded as the entry
+ * point, so a thrown `realpathSync` means "not invoked directly" and returns
+ * `false`; it never masks a direct run.
+ */
+function isDirectInvocation(invokedPath) {
+  if (!invokedPath) return false;
+  try {
+    return (
+      realpathSync(fileURLToPath(import.meta.url)) ===
+      realpathSync(resolve(invokedPath))
+    );
+  } catch {
+    return false;
+  }
+}
+
+if (isDirectInvocation(process.argv[1])) {
   runBundle(process.argv.slice(2)).catch((error) => {
     console.error(error.message);
     process.exitCode = 1;

package/assets/skills/explainer-kit/scripts/record.mjs

@@ -1,9 +1,10 @@
 #!/usr/bin/env node
 
 import { createHash, randomUUID } from 'node:crypto';
+import { realpathSync } from 'node:fs';
 import { access, readFile, readdir, rename, writeFile } from 'node:fs/promises';
-import { join } from 'node:path';
-import { pathToFileURL } from 'node:url';
+import { join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
 
 import { validateContract } from './lib/contracts.mjs';
 import {
@@ -327,7 +328,29 @@ function recordError(code, message) {
   return error;
 }
 
-if (import.meta.url === pathToFileURL(process.argv[1] ?? '').href) {
+/**
+ * Direct invocation, compared as canonical paths on both sides. Comparing a raw
+ * `process.argv[1]` against `import.meta.url` makes this script a silent no-op
+ * that exits 0 whenever the skill is reached through a symlinked install root,
+ * and canonicalizing only one side has the same effect under
+ * `--preserve-symlinks-main`, which keeps the link in `import.meta.url`.
+ * A path that cannot be canonicalized is not a module Node loaded as the entry
+ * point, so a thrown `realpathSync` means "not invoked directly" and returns
+ * `false`; it never masks a direct run.
+ */
+function isDirectInvocation(invokedPath) {
+  if (!invokedPath) return false;
+  try {
+    return (
+      realpathSync(fileURLToPath(import.meta.url)) ===
+      realpathSync(resolve(invokedPath))
+    );
+  } catch {
+    return false;
+  }
+}
+
+if (isDirectInvocation(process.argv[1])) {
   runRecord(process.argv.slice(2)).catch((error) => {
     console.error(`${error.code}: ${error.message}`);
     process.exitCode = 1;

package/assets/skills/explainer-kit/scripts/verify.mjs

@@ -1,9 +1,10 @@
 #!/usr/bin/env node
 
 import { createHash } from 'node:crypto';
+import { realpathSync } from 'node:fs';
 import { mkdir, readFile, rm, writeFile } from 'node:fs/promises';
-import { join } from 'node:path';
-import { pathToFileURL } from 'node:url';
+import { join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
 
 import { writeFailure } from './bundle.mjs';
 import {
@@ -640,7 +641,29 @@ function verifyError(code, message) {
   return error;
 }
 
-if (import.meta.url === pathToFileURL(process.argv[1] ?? '').href) {
+/**
+ * Direct invocation, compared as canonical paths on both sides. Comparing a raw
+ * `process.argv[1]` against `import.meta.url` makes this script a silent no-op
+ * that exits 0 whenever the skill is reached through a symlinked install root,
+ * and canonicalizing only one side has the same effect under
+ * `--preserve-symlinks-main`, which keeps the link in `import.meta.url`.
+ * A path that cannot be canonicalized is not a module Node loaded as the entry
+ * point, so a thrown `realpathSync` means "not invoked directly" and returns
+ * `false`; it never masks a direct run.
+ */
+function isDirectInvocation(invokedPath) {
+  if (!invokedPath) return false;
+  try {
+    return (
+      realpathSync(fileURLToPath(import.meta.url)) ===
+      realpathSync(resolve(invokedPath))
+    );
+  } catch {
+    return false;
+  }
+}
+
+if (isDirectInvocation(process.argv[1])) {
   runVerify(process.argv.slice(2)).catch((error) => {
     console.error(`${error.code ?? 'verify-error'}: ${error.message}`);
     process.exitCode = 1;

package/assets/skills/oat-explainer-kit/SKILL.md

@@ -5,7 +5,7 @@ disable-model-invocation: false
 user-invocable: true
 allowed-tools: Read, Write, Edit, Bash, Grep, Glob, AskUserQuestion
 metadata:
-  version: 1.0.9
+  version: 1.0.10
 ---
 
 # OAT Explainer Kit

package/assets/skills/oat-explainer-kit/scripts/check-terminal-outcome.mjs

@@ -1,4 +1,5 @@
 import { createHash } from 'node:crypto';
+import { realpathSync } from 'node:fs';
 import { lstat, readFile, realpath } from 'node:fs/promises';
 import {
   basename,
@@ -9,7 +10,7 @@ import {
   resolve,
   sep,
 } from 'node:path';
-import { pathToFileURL } from 'node:url';
+import { fileURLToPath } from 'node:url';
 
 import { validateContract } from '../../explainer-kit/scripts/lib/contracts.mjs';
 import { isFlowFailureStage } from '../../explainer-kit/scripts/lib/failure.mjs';
@@ -324,10 +325,29 @@ function recapOutcomeError(message) {
   return error;
 }
 
-if (
-  process.argv[1] &&
-  import.meta.url === pathToFileURL(process.argv[1]).href
-) {
+/**
+ * Direct invocation, compared as canonical paths on both sides. Comparing a raw
+ * `process.argv[1]` against `import.meta.url` makes this script a silent no-op
+ * that exits 0 whenever the skill is reached through a symlinked install root,
+ * and canonicalizing only one side has the same effect under
+ * `--preserve-symlinks-main`, which keeps the link in `import.meta.url`.
+ * A path that cannot be canonicalized is not a module Node loaded as the entry
+ * point, so a thrown `realpathSync` means "not invoked directly" and returns
+ * `false`; it never masks a direct run.
+ */
+function isDirectInvocation(invokedPath) {
+  if (!invokedPath) return false;
+  try {
+    return (
+      realpathSync(fileURLToPath(import.meta.url)) ===
+      realpathSync(resolve(invokedPath))
+    );
+  } catch {
+    return false;
+  }
+}
+
+if (isDirectInvocation(process.argv[1])) {
   main(process.argv.slice(2))
     .then((result) => {
       process.stdout.write(`${JSON.stringify(result)}\n`);

package/assets/skills/oat-project-complete/SKILL.md

@@ -5,7 +5,7 @@ disable-model-invocation: true
 user-invocable: true
 allowed-tools: Read, Write, Bash, AskUserQuestion
 metadata:
-  version: 1.7.12
+  version: 1.7.13
 ---
 
 # Complete Project

package/assets/skills/oat-project-complete/scripts/consume-persisted-recap-intent.mjs

@@ -1,6 +1,7 @@
+import { realpathSync } from 'node:fs';
 import { readdir, realpath } from 'node:fs/promises';
-import { join } from 'node:path';
-import { pathToFileURL } from 'node:url';
+import { join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
 
 import { readPersistedIntent } from '../../oat-explainer-kit/scripts/persist-intent.mjs';
 
@@ -110,10 +111,29 @@ async function main(argv) {
   return consumePersistedRecapIntent({ projectPath: argv[0] });
 }
 
-if (
-  process.argv[1] &&
-  import.meta.url === pathToFileURL(process.argv[1]).href
-) {
+/**
+ * Direct invocation, compared as canonical paths on both sides. Comparing a raw
+ * `process.argv[1]` against `import.meta.url` makes this script a silent no-op
+ * that exits 0 whenever the skill is reached through a symlinked install root,
+ * and canonicalizing only one side has the same effect under
+ * `--preserve-symlinks-main`, which keeps the link in `import.meta.url`.
+ * A path that cannot be canonicalized is not a module Node loaded as the entry
+ * point, so a thrown `realpathSync` means "not invoked directly" and returns
+ * `false`; it never masks a direct run.
+ */
+function isDirectInvocation(invokedPath) {
+  if (!invokedPath) return false;
+  try {
+    return (
+      realpathSync(fileURLToPath(import.meta.url)) ===
+      realpathSync(resolve(invokedPath))
+    );
+  } catch {
+    return false;
+  }
+}
+
+if (isDirectInvocation(process.argv[1])) {
   main(process.argv.slice(2))
     .then((result) => process.stdout.write(`${JSON.stringify(result)}\n`))
     .catch((error) => {

package/assets/skills/oat-project-complete/scripts/execute-synced-archive-entry.mjs

@@ -1,7 +1,8 @@
 import { execFile as execFileCallback } from 'node:child_process';
+import { realpathSync } from 'node:fs';
 import { readFile } from 'node:fs/promises';
-import { isAbsolute, posix, relative, sep } from 'node:path';
-import { pathToFileURL } from 'node:url';
+import { isAbsolute, posix, relative, sep, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
 import { promisify } from 'node:util';
 
 import { validateSyncedArchiveTerminalReport } from './finalize-synced-archive.mjs';
@@ -261,10 +262,29 @@ async function main(argv) {
   });
 }
 
-if (
-  process.argv[1] &&
-  import.meta.url === pathToFileURL(process.argv[1]).href
-) {
+/**
+ * Direct invocation, compared as canonical paths on both sides. Comparing a raw
+ * `process.argv[1]` against `import.meta.url` makes this script a silent no-op
+ * that exits 0 whenever the skill is reached through a symlinked install root,
+ * and canonicalizing only one side has the same effect under
+ * `--preserve-symlinks-main`, which keeps the link in `import.meta.url`.
+ * A path that cannot be canonicalized is not a module Node loaded as the entry
+ * point, so a thrown `realpathSync` means "not invoked directly" and returns
+ * `false`; it never masks a direct run.
+ */
+function isDirectInvocation(invokedPath) {
+  if (!invokedPath) return false;
+  try {
+    return (
+      realpathSync(fileURLToPath(import.meta.url)) ===
+      realpathSync(resolve(invokedPath))
+    );
+  } catch {
+    return false;
+  }
+}
+
+if (isDirectInvocation(process.argv[1])) {
   main(process.argv.slice(2))
     .then((result) => process.stdout.write(`${JSON.stringify(result)}\n`))
     .catch((error) => {

package/assets/skills/oat-project-complete/scripts/finalize-synced-archive.mjs

@@ -92,6 +92,10 @@ async function main(argv) {
     projectName,
     getArchiveReport: async () => {
       try {
+        // Stdin is read to EOF with no timeout. Every caller pipes the archive
+        // report in (`printf '%s\n' "$ARCHIVE_OUTPUT" | node ...`), so EOF
+        // always arrives; a timeout would turn a slow producer into a false
+        // failure, and a caller that leaves stdin open is a caller bug.
         return JSON.parse(readFileSync(0, 'utf8'));
       } catch (error) {
         throw finalizationError(
@@ -119,6 +123,9 @@ async function main(argv) {
  * `--preserve-symlinks-main`, which keeps the link in `import.meta.url`. Either
  * way the caller reads "exited 0" as "verified" — the fail-open shape this
  * finalizer exists to prevent.
+ * A path that cannot be canonicalized is not a module Node loaded as the entry
+ * point, so a thrown `realpathSync` means "not invoked directly" and returns
+ * `false`; it never masks a direct run.
  */
 function isDirectInvocation(invokedPath) {
   if (!invokedPath) return false;

package/assets/skills/oat-project-complete/scripts/parse-completion-retry-fields.mjs

@@ -1,4 +1,6 @@
-import { pathToFileURL } from 'node:url';
+import { realpathSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
 
 const FULL_SHA = /^[0-9a-f]{40}$/;
 const PR_ARTIFACT = /^pr\/project-pr-[^/\s]+\.md$/;
@@ -217,10 +219,29 @@ function main(argv) {
   return parseCompletionRetryFields(argv[0]);
 }
 
-if (
-  process.argv[1] &&
-  import.meta.url === pathToFileURL(process.argv[1]).href
-) {
+/**
+ * Direct invocation, compared as canonical paths on both sides. Comparing a raw
+ * `process.argv[1]` against `import.meta.url` makes this script a silent no-op
+ * that exits 0 whenever the skill is reached through a symlinked install root,
+ * and canonicalizing only one side has the same effect under
+ * `--preserve-symlinks-main`, which keeps the link in `import.meta.url`.
+ * A path that cannot be canonicalized is not a module Node loaded as the entry
+ * point, so a thrown `realpathSync` means "not invoked directly" and returns
+ * `false`; it never masks a direct run.
+ */
+function isDirectInvocation(invokedPath) {
+  if (!invokedPath) return false;
+  try {
+    return (
+      realpathSync(fileURLToPath(import.meta.url)) ===
+      realpathSync(resolve(invokedPath))
+    );
+  } catch {
+    return false;
+  }
+}
+
+if (isDirectInvocation(process.argv[1])) {
   try {
     process.stdout.write(`${main(process.argv.slice(2))}\n`);
   } catch (error) {

package/assets/skills/oat-project-complete/scripts/parse-synced-archive-resume-fields.mjs

@@ -1,4 +1,6 @@
-import { pathToFileURL } from 'node:url';
+import { realpathSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
 
 function fieldsError(message) {
   const error = new Error(message);
@@ -92,10 +94,29 @@ function main(argv) {
   return formatShellAssignments(parseSyncedArchiveResumeFields(result));
 }
 
-if (
-  process.argv[1] &&
-  import.meta.url === pathToFileURL(process.argv[1]).href
-) {
+/**
+ * Direct invocation, compared as canonical paths on both sides. Comparing a raw
+ * `process.argv[1]` against `import.meta.url` makes this script a silent no-op
+ * that exits 0 whenever the skill is reached through a symlinked install root,
+ * and canonicalizing only one side has the same effect under
+ * `--preserve-symlinks-main`, which keeps the link in `import.meta.url`.
+ * A path that cannot be canonicalized is not a module Node loaded as the entry
+ * point, so a thrown `realpathSync` means "not invoked directly" and returns
+ * `false`; it never masks a direct run.
+ */
+function isDirectInvocation(invokedPath) {
+  if (!invokedPath) return false;
+  try {
+    return (
+      realpathSync(fileURLToPath(import.meta.url)) ===
+      realpathSync(resolve(invokedPath))
+    );
+  } catch {
+    return false;
+  }
+}
+
+if (isDirectInvocation(process.argv[1])) {
   try {
     process.stdout.write(`${main(process.argv.slice(2))}\n`);
   } catch (error) {

package/assets/skills/oat-project-complete/scripts/recover-completion-receipts.mjs

@@ -1,6 +1,7 @@
 import { execFile } from 'node:child_process';
-import { basename } from 'node:path';
-import { pathToFileURL } from 'node:url';
+import { realpathSync } from 'node:fs';
+import { basename, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
 import { promisify } from 'node:util';
 
 const execFileAsync = promisify(execFile);
@@ -692,10 +693,29 @@ async function main(argv) {
   return recoverCompletionReceipts(options);
 }
 
-if (
-  process.argv[1] &&
-  import.meta.url === pathToFileURL(process.argv[1]).href
-) {
+/**
+ * Direct invocation, compared as canonical paths on both sides. Comparing a raw
+ * `process.argv[1]` against `import.meta.url` makes this script a silent no-op
+ * that exits 0 whenever the skill is reached through a symlinked install root,
+ * and canonicalizing only one side has the same effect under
+ * `--preserve-symlinks-main`, which keeps the link in `import.meta.url`.
+ * A path that cannot be canonicalized is not a module Node loaded as the entry
+ * point, so a thrown `realpathSync` means "not invoked directly" and returns
+ * `false`; it never masks a direct run.
+ */
+function isDirectInvocation(invokedPath) {
+  if (!invokedPath) return false;
+  try {
+    return (
+      realpathSync(fileURLToPath(import.meta.url)) ===
+      realpathSync(resolve(invokedPath))
+    );
+  } catch {
+    return false;
+  }
+}
+
+if (isDirectInvocation(process.argv[1])) {
   main(process.argv.slice(2))
     .then((result) => {
       process.stdout.write(`${JSON.stringify(result)}\n`);

package/assets/skills/oat-project-complete/scripts/resolve-completion-retry.mjs

@@ -1,6 +1,7 @@
+import { realpathSync } from 'node:fs';
 import { lstat, readdir } from 'node:fs/promises';
-import { join } from 'node:path';
-import { pathToFileURL } from 'node:url';
+import { join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
 
 import {
   detectCompletionReceiptCandidate,
@@ -116,10 +117,29 @@ async function main(argv) {
   return resolveCompletionRetry(parseArguments(argv));
 }
 
-if (
-  process.argv[1] &&
-  import.meta.url === pathToFileURL(process.argv[1]).href
-) {
+/**
+ * Direct invocation, compared as canonical paths on both sides. Comparing a raw
+ * `process.argv[1]` against `import.meta.url` makes this script a silent no-op
+ * that exits 0 whenever the skill is reached through a symlinked install root,
+ * and canonicalizing only one side has the same effect under
+ * `--preserve-symlinks-main`, which keeps the link in `import.meta.url`.
+ * A path that cannot be canonicalized is not a module Node loaded as the entry
+ * point, so a thrown `realpathSync` means "not invoked directly" and returns
+ * `false`; it never masks a direct run.
+ */
+function isDirectInvocation(invokedPath) {
+  if (!invokedPath) return false;
+  try {
+    return (
+      realpathSync(fileURLToPath(import.meta.url)) ===
+      realpathSync(resolve(invokedPath))
+    );
+  } catch {
+    return false;
+  }
+}
+
+if (isDirectInvocation(process.argv[1])) {
   main(process.argv.slice(2))
     .then((result) => {
       process.stdout.write(`${JSON.stringify(result)}\n`);

package/assets/skills/oat-project-complete/scripts/resolve-synced-archive-entry.mjs

@@ -1,6 +1,8 @@
 import { execFile as execFileCallback } from 'node:child_process';
+import { realpathSync } from 'node:fs';
 import { readFile } from 'node:fs/promises';
-import { pathToFileURL } from 'node:url';
+import { resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
 import { promisify } from 'node:util';
 
 const execFile = promisify(execFileCallback);
@@ -149,10 +151,29 @@ async function main(argv) {
   return resolveSyncedArchiveEntry({ ...options, record });
 }
 
-if (
-  process.argv[1] &&
-  import.meta.url === pathToFileURL(process.argv[1]).href
-) {
+/**
+ * Direct invocation, compared as canonical paths on both sides. Comparing a raw
+ * `process.argv[1]` against `import.meta.url` makes this script a silent no-op
+ * that exits 0 whenever the skill is reached through a symlinked install root,
+ * and canonicalizing only one side has the same effect under
+ * `--preserve-symlinks-main`, which keeps the link in `import.meta.url`.
+ * A path that cannot be canonicalized is not a module Node loaded as the entry
+ * point, so a thrown `realpathSync` means "not invoked directly" and returns
+ * `false`; it never masks a direct run.
+ */
+function isDirectInvocation(invokedPath) {
+  if (!invokedPath) return false;
+  try {
+    return (
+      realpathSync(fileURLToPath(import.meta.url)) ===
+      realpathSync(resolve(invokedPath))
+    );
+  } catch {
+    return false;
+  }
+}
+
+if (isDirectInvocation(process.argv[1])) {
   main(process.argv.slice(2))
     .then((result) => process.stdout.write(`${JSON.stringify(result)}\n`))
     .catch((error) => {

package/assets/skills/oat-project-complete/scripts/validate-durable-archive-receipt.mjs

@@ -134,6 +134,10 @@ async function main(argv) {
   if (options.mode === 'receipt') {
     let report;
     try {
+      // Stdin is read to EOF with no timeout. Every caller pipes the archive
+      // report in (`printf '%s\n' "$ARCHIVE_OUTPUT" | node ...`), so EOF
+      // always arrives; a timeout would turn a slow producer into a false
+      // failure, and a caller that leaves stdin open is a caller bug.
       report = JSON.parse(readFileSync(0, 'utf8'));
     } catch (error) {
       throw receiptError(
@@ -158,6 +162,9 @@ async function main(argv) {
  * `--preserve-symlinks-main`, which keeps the link in `import.meta.url`. Either
  * way the caller reads "exited 0" as "verified" — the fail-open shape this
  * validator exists to prevent.
+ * A path that cannot be canonicalized is not a module Node loaded as the entry
+ * point, so a thrown `realpathSync` means "not invoked directly" and returns
+ * `false`; it never masks a direct run.
  */
 function isDirectInvocation(invokedPath) {
   if (!invokedPath) return false;

package/assets/skills/oat-project-complete/scripts/validate-nonarchive-lifecycle-receipt.mjs

@@ -11,6 +11,7 @@ import {
   resolve,
   sep,
 } from 'node:path';
+import { fileURLToPath } from 'node:url';
 
 function fail(message) {
   process.stderr.write(`Invalid non-archive lifecycle receipt: ${message}\n`);
@@ -57,104 +58,134 @@ function gitSucceeds(cwd, args) {
   }
 }
 
-const [recordArgument, commit, projectName] = process.argv.slice(2);
-if (!recordArgument || !/^[0-9a-f]{40}$/.test(commit ?? '') || !projectName) {
-  fail('expected <record-path> <full-commit-sha> <project-name>.');
-}
+function main(argv) {
+  const [recordArgument, commit, projectName] = argv;
+  if (!recordArgument || !/^[0-9a-f]{40}$/.test(commit ?? '') || !projectName) {
+    fail('expected <record-path> <full-commit-sha> <project-name>.');
+  }
 
-const unresolvedRecordPath = resolve(recordArgument);
-if (!existsSync(unresolvedRecordPath)) {
-  fail('record path does not exist; restore the synced discovery record.');
-}
-const recordPath = realpathSync(unresolvedRecordPath);
-const repoRoot = realpathSync(
-  git(dirname(recordPath), ['rev-parse', '--show-toplevel']),
-);
-const recordRelative = relative(repoRoot, recordPath);
-if (
-  recordRelative === '' ||
-  recordRelative === '..' ||
-  recordRelative.startsWith(`..${sep}`) ||
-  isAbsolute(recordRelative)
-) {
-  fail('record path is outside the repository root.');
-}
-const gitRecordPath = recordRelative.split(sep).join('/');
-if (basename(gitRecordPath, extname(gitRecordPath)) !== projectName) {
-  fail('record filename must match the project name.');
-}
-if (!gitSucceeds(repoRoot, ['merge-base', '--is-ancestor', commit, 'HEAD'])) {
-  fail('receipt commit must be an ancestor of the current repository HEAD.');
-}
-const changedPaths = git(repoRoot, [
-  'diff-tree',
-  '--root',
-  '--no-commit-id',
-  '--name-only',
-  '-r',
-  '--format=',
-  commit,
-])
-  .split('\n')
-  .filter(Boolean);
-if (changedPaths.length !== 1 || changedPaths[0] !== gitRecordPath) {
-  fail('receipt commit must change exactly the synced discovery record path.');
-}
-const expectedSubject = `chore(oat): complete synced project ${projectName}`;
-const subject = git(repoRoot, ['show', '-s', '--format=%s', commit]);
-if (subject !== expectedSubject) {
-  fail(`commit subject must be "${expectedSubject}".`);
-}
+  const unresolvedRecordPath = resolve(recordArgument);
+  if (!existsSync(unresolvedRecordPath)) {
+    fail('record path does not exist; restore the synced discovery record.');
+  }
+  const recordPath = realpathSync(unresolvedRecordPath);
+  const repoRoot = realpathSync(
+    git(dirname(recordPath), ['rev-parse', '--show-toplevel']),
+  );
+  const recordRelative = relative(repoRoot, recordPath);
+  if (
+    recordRelative === '' ||
+    recordRelative === '..' ||
+    recordRelative.startsWith(`..${sep}`) ||
+    isAbsolute(recordRelative)
+  ) {
+    fail('record path is outside the repository root.');
+  }
+  const gitRecordPath = recordRelative.split(sep).join('/');
+  if (basename(gitRecordPath, extname(gitRecordPath)) !== projectName) {
+    fail('record filename must match the project name.');
+  }
+  if (!gitSucceeds(repoRoot, ['merge-base', '--is-ancestor', commit, 'HEAD'])) {
+    fail('receipt commit must be an ancestor of the current repository HEAD.');
+  }
+  const changedPaths = git(repoRoot, [
+    'diff-tree',
+    '--root',
+    '--no-commit-id',
+    '--name-only',
+    '-r',
+    '--format=',
+    commit,
+  ])
+    .split('\n')
+    .filter(Boolean);
+  if (changedPaths.length !== 1 || changedPaths[0] !== gitRecordPath) {
+    fail(
+      'receipt commit must change exactly the synced discovery record path.',
+    );
+  }
+  const expectedSubject = `chore(oat): complete synced project ${projectName}`;
+  const subject = git(repoRoot, ['show', '-s', '--format=%s', commit]);
+  if (subject !== expectedSubject) {
+    fail(`commit subject must be "${expectedSubject}".`);
+  }
 
-let committedRecordContents;
-let record;
-try {
-  committedRecordContents = gitRaw(repoRoot, [
-    'show',
-    `${commit}:${gitRecordPath}`,
+  let committedRecordContents;
+  let record;
+  try {
+    committedRecordContents = gitRaw(repoRoot, [
+      'show',
+      `${commit}:${gitRecordPath}`,
+    ]);
+    record = JSON.parse(committedRecordContents);
+  } catch (error) {
+    fail(
+      `committed record is not valid JSON: ${error instanceof Error ? error.message : String(error)}`,
+    );
+  }
+  if (readFileSync(recordPath, 'utf8') !== committedRecordContents) {
+    fail('working-tree record content must exactly match the receipt commit.');
+  }
+  const expectedKeys = new Set([
+    'archiveSnapshot',
+    'completedAt',
+    'createdAt',
+    'ref',
+    'remote',
+    'schemaVersion',
+    'scope',
+    'slug',
+    'status',
   ]);
-  record = JSON.parse(committedRecordContents);
-} catch (error) {
-  fail(
-    `committed record is not valid JSON: ${error instanceof Error ? error.message : String(error)}`,
-  );
-}
-if (readFileSync(recordPath, 'utf8') !== committedRecordContents) {
-  fail('working-tree record content must exactly match the receipt commit.');
+  if (
+    !record ||
+    typeof record !== 'object' ||
+    Array.isArray(record) ||
+    Object.keys(record).some((key) => !expectedKeys.has(key)) ||
+    record.schemaVersion !== 1 ||
+    record.slug !== projectName ||
+    record.scope !== 'synced' ||
+    record.ref !== `refs/oat/projects/${projectName}` ||
+    record.remote !== 'origin' ||
+    record.status !== 'complete' ||
+    typeof record.createdAt !== 'string' ||
+    Number.isNaN(Date.parse(record.createdAt)) ||
+    typeof record.completedAt !== 'string' ||
+    Number.isNaN(Date.parse(record.completedAt)) ||
+    (record.archiveSnapshot !== undefined &&
+      (typeof record.archiveSnapshot !== 'string' ||
+        record.archiveSnapshot.length === 0))
+  ) {
+    fail(
+      'committed record must be a complete synced record with the exact project identity and lifecycle content.',
+    );
+  }
+
+  process.stdout.write(`${commit}\n`);
 }
-const expectedKeys = new Set([
-  'archiveSnapshot',
-  'completedAt',
-  'createdAt',
-  'ref',
-  'remote',
-  'schemaVersion',
-  'scope',
-  'slug',
-  'status',
-]);
-if (
-  !record ||
-  typeof record !== 'object' ||
-  Array.isArray(record) ||
-  Object.keys(record).some((key) => !expectedKeys.has(key)) ||
-  record.schemaVersion !== 1 ||
-  record.slug !== projectName ||
-  record.scope !== 'synced' ||
-  record.ref !== `refs/oat/projects/${projectName}` ||
-  record.remote !== 'origin' ||
-  record.status !== 'complete' ||
-  typeof record.createdAt !== 'string' ||
-  Number.isNaN(Date.parse(record.createdAt)) ||
-  typeof record.completedAt !== 'string' ||
-  Number.isNaN(Date.parse(record.completedAt)) ||
-  (record.archiveSnapshot !== undefined &&
-    (typeof record.archiveSnapshot !== 'string' ||
-      record.archiveSnapshot.length === 0))
-) {
-  fail(
-    'committed record must be a complete synced record with the exact project identity and lifecycle content.',
-  );
+
+/**
+ * Direct invocation, compared as canonical paths on both sides. Comparing a raw
+ * `process.argv[1]` against `import.meta.url` makes this script a silent no-op
+ * that exits 0 whenever the skill is reached through a symlinked install root,
+ * and canonicalizing only one side has the same effect under
+ * `--preserve-symlinks-main`, which keeps the link in `import.meta.url`.
+ * A path that cannot be canonicalized is not a module Node loaded as the entry
+ * point, so a thrown `realpathSync` means "not invoked directly" and returns
+ * `false`; it never masks a direct run.
+ */
+function isDirectInvocation(invokedPath) {
+  if (!invokedPath) return false;
+  try {
+    return (
+      realpathSync(fileURLToPath(import.meta.url)) ===
+      realpathSync(resolve(invokedPath))
+    );
+  } catch {
+    return false;
+  }
 }
 
-process.stdout.write(`${commit}\n`);
+if (isDirectInvocation(process.argv[1])) {
+  main(process.argv.slice(2));
+}

package/assets/skills/oat-project-implement/SKILL.md

@@ -7,7 +7,7 @@ disable-model-invocation: true
 user-invocable: true
 allowed-tools: Read, Write, Bash(git:*), Bash(oat:*), Bash(oat project log:*), Glob, Grep, AskUserQuestion, Task
 metadata:
-  version: 2.3.9
+  version: 2.3.10
 ---
 
 # Implementation Phase

package/assets/skills/oat-project-implement/scripts/capture-dirty-tree.mjs

@@ -1051,6 +1051,9 @@ async function main(argv) {
  * `--preserve-symlinks-main`, which keeps the link in `import.meta.url`. Either
  * way the caller reads "exited 0" as "verified" — the fail-open shape the
  * contracts exist to prevent.
+ * A path that cannot be canonicalized is not a module Node loaded as the entry
+ * point, so a thrown `realpathSync` means "not invoked directly" and returns
+ * `false`; it never masks a direct run.
  */
 function isDirectInvocation(invokedPath) {
   if (!invokedPath) return false;

package/assets/skills/recon/SKILL.md

@@ -6,7 +6,7 @@ disable-model-invocation: true
 user-invocable: true
 allowed-tools: Read, Write, Glob, Grep, Bash, AskUserQuestion, Agent, mcp__*
 metadata:
-  version: 1.1.2
+  version: 1.1.3
 ---
 
 # Recon

package/assets/skills/recon/scripts/create-review-brief.mjs

@@ -1,8 +1,9 @@
 #!/usr/bin/env node
 
+import { realpathSync } from 'node:fs';
 import { mkdir, readFile, writeFile } from 'node:fs/promises';
 import { dirname, relative, resolve } from 'node:path';
-import { pathToFileURL } from 'node:url';
+import { fileURLToPath } from 'node:url';
 
 import { canonicalJson, hashFile } from './lib/canonical-json.mjs';
 import { issue, isObject, validateArtifactShape } from './lib/contracts.mjs';
@@ -441,10 +442,29 @@ async function main(argv) {
   process.stdout.write(`${JSON.stringify(reference, null, 2)}\n`);
 }
 
-if (
-  process.argv[1] &&
-  import.meta.url === pathToFileURL(process.argv[1]).href
-) {
+/**
+ * Direct invocation, compared as canonical paths on both sides. Comparing a raw
+ * `process.argv[1]` against `import.meta.url` makes this script a silent no-op
+ * that exits 0 whenever the skill is reached through a symlinked install root,
+ * and canonicalizing only one side has the same effect under
+ * `--preserve-symlinks-main`, which keeps the link in `import.meta.url`.
+ * A path that cannot be canonicalized is not a module Node loaded as the entry
+ * point, so a thrown `realpathSync` means "not invoked directly" and returns
+ * `false`; it never masks a direct run.
+ */
+function isDirectInvocation(invokedPath) {
+  if (!invokedPath) return false;
+  try {
+    return (
+      realpathSync(fileURLToPath(import.meta.url)) ===
+      realpathSync(resolve(invokedPath))
+    );
+  } catch {
+    return false;
+  }
+}
+
+if (isDirectInvocation(process.argv[1])) {
   main(process.argv.slice(2)).catch((error) => {
     process.stderr.write(`${error instanceof Error ? error.message : error}\n`);
     process.exitCode = 1;

package/assets/skills/recon/scripts/prepare-routing.mjs

@@ -1,7 +1,9 @@
 #!/usr/bin/env node
 
+import { realpathSync } from 'node:fs';
 import { readFile } from 'node:fs/promises';
-import { pathToFileURL } from 'node:url';
+import { resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
 
 import {
   checkApprovedWaveTarget,
@@ -79,7 +81,29 @@ export async function main(argv = process.argv.slice(2)) {
   );
 }
 
-if (import.meta.url === pathToFileURL(process.argv[1] ?? '').href) {
+/**
+ * Direct invocation, compared as canonical paths on both sides. Comparing a raw
+ * `process.argv[1]` against `import.meta.url` makes this script a silent no-op
+ * that exits 0 whenever the skill is reached through a symlinked install root,
+ * and canonicalizing only one side has the same effect under
+ * `--preserve-symlinks-main`, which keeps the link in `import.meta.url`.
+ * A path that cannot be canonicalized is not a module Node loaded as the entry
+ * point, so a thrown `realpathSync` means "not invoked directly" and returns
+ * `false`; it never masks a direct run.
+ */
+function isDirectInvocation(invokedPath) {
+  if (!invokedPath) return false;
+  try {
+    return (
+      realpathSync(fileURLToPath(import.meta.url)) ===
+      realpathSync(resolve(invokedPath))
+    );
+  } catch {
+    return false;
+  }
+}
+
+if (isDirectInvocation(process.argv[1])) {
   main().catch((error) => {
     const code = error instanceof RoutingContractError ? error.code : 'ERROR';
     process.stderr.write(`${code}: ${error.message}\n`);

package/assets/skills/recon/scripts/render-packet.mjs

@@ -1,9 +1,10 @@
 #!/usr/bin/env node
 
 import { createHash, randomUUID } from 'node:crypto';
+import { realpathSync } from 'node:fs';
 import { lstat, open, rename, rm } from 'node:fs/promises';
 import { join, resolve } from 'node:path';
-import { pathToFileURL } from 'node:url';
+import { fileURLToPath } from 'node:url';
 
 import { hashFile } from './lib/canonical-json.mjs';
 import {
@@ -436,10 +437,29 @@ async function main(argv) {
   process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
 }
 
-if (
-  process.argv[1] &&
-  import.meta.url === pathToFileURL(process.argv[1]).href
-) {
+/**
+ * Direct invocation, compared as canonical paths on both sides. Comparing a raw
+ * `process.argv[1]` against `import.meta.url` makes this script a silent no-op
+ * that exits 0 whenever the skill is reached through a symlinked install root,
+ * and canonicalizing only one side has the same effect under
+ * `--preserve-symlinks-main`, which keeps the link in `import.meta.url`.
+ * A path that cannot be canonicalized is not a module Node loaded as the entry
+ * point, so a thrown `realpathSync` means "not invoked directly" and returns
+ * `false`; it never masks a direct run.
+ */
+function isDirectInvocation(invokedPath) {
+  if (!invokedPath) return false;
+  try {
+    return (
+      realpathSync(fileURLToPath(import.meta.url)) ===
+      realpathSync(resolve(invokedPath))
+    );
+  } catch {
+    return false;
+  }
+}
+
+if (isDirectInvocation(process.argv[1])) {
   main(process.argv.slice(2)).catch((error) => {
     process.stderr.write(`${error instanceof Error ? error.message : error}\n`);
     process.exitCode = 1;

package/assets/skills/recon/scripts/validate-artifact.mjs

@@ -1,8 +1,9 @@
 #!/usr/bin/env node
 
+import { realpathSync } from 'node:fs';
 import { mkdir, readFile, rename, writeFile } from 'node:fs/promises';
 import { basename, join, resolve } from 'node:path';
-import { pathToFileURL } from 'node:url';
+import { fileURLToPath } from 'node:url';
 
 import { validateArtifactShape } from './lib/contracts.mjs';
 import {
@@ -85,10 +86,29 @@ async function main(argv) {
   process.exitCode = result.valid ? 0 : 1;
 }
 
-if (
-  process.argv[1] &&
-  import.meta.url === pathToFileURL(process.argv[1]).href
-) {
+/**
+ * Direct invocation, compared as canonical paths on both sides. Comparing a raw
+ * `process.argv[1]` against `import.meta.url` makes this script a silent no-op
+ * that exits 0 whenever the skill is reached through a symlinked install root,
+ * and canonicalizing only one side has the same effect under
+ * `--preserve-symlinks-main`, which keeps the link in `import.meta.url`.
+ * A path that cannot be canonicalized is not a module Node loaded as the entry
+ * point, so a thrown `realpathSync` means "not invoked directly" and returns
+ * `false`; it never masks a direct run.
+ */
+function isDirectInvocation(invokedPath) {
+  if (!invokedPath) return false;
+  try {
+    return (
+      realpathSync(fileURLToPath(import.meta.url)) ===
+      realpathSync(resolve(invokedPath))
+    );
+  } catch {
+    return false;
+  }
+}
+
+if (isDirectInvocation(process.argv[1])) {
   main(process.argv.slice(2)).catch((error) => {
     process.stderr.write(`${error instanceof Error ? error.message : error}\n`);
     process.exitCode = 2;

package/assets/skills/recon/scripts/validate-packet.mjs

@@ -1,8 +1,9 @@
 #!/usr/bin/env node
 
+import { realpathSync } from 'node:fs';
 import { readFile, rm } from 'node:fs/promises';
 import { join, resolve } from 'node:path';
-import { pathToFileURL } from 'node:url';
+import { fileURLToPath } from 'node:url';
 
 import { hashCanonicalJson, hashFile, sha256 } from './lib/canonical-json.mjs';
 import {
@@ -2598,10 +2599,29 @@ async function main(argv) {
   process.exitCode = result.publishable ? 0 : 1;
 }
 
-if (
-  process.argv[1] &&
-  import.meta.url === pathToFileURL(process.argv[1]).href
-) {
+/**
+ * Direct invocation, compared as canonical paths on both sides. Comparing a raw
+ * `process.argv[1]` against `import.meta.url` makes this script a silent no-op
+ * that exits 0 whenever the skill is reached through a symlinked install root,
+ * and canonicalizing only one side has the same effect under
+ * `--preserve-symlinks-main`, which keeps the link in `import.meta.url`.
+ * A path that cannot be canonicalized is not a module Node loaded as the entry
+ * point, so a thrown `realpathSync` means "not invoked directly" and returns
+ * `false`; it never masks a direct run.
+ */
+function isDirectInvocation(invokedPath) {
+  if (!invokedPath) return false;
+  try {
+    return (
+      realpathSync(fileURLToPath(import.meta.url)) ===
+      realpathSync(resolve(invokedPath))
+    );
+  } catch {
+    return false;
+  }
+}
+
+if (isDirectInvocation(process.argv[1])) {
   main(process.argv.slice(2)).catch((error) => {
     process.stderr.write(`${error instanceof Error ? error.message : error}\n`);
     process.exitCode = 2;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@open-agent-toolkit/cli",
-  "version": "0.2.76",
+  "version": "0.2.77",
   "private": false,
   "description": "Open Agent Toolkit CLI",
   "homepage": "https://github.com/voxmedia/open-agent-toolkit/tree/main/packages/cli",
@@ -34,7 +34,7 @@
     "ora": "^9.0.0",
     "yaml": "2.8.2",
     "zod": "^3.25.76",
-    "@open-agent-toolkit/control-plane": "0.2.76"
+    "@open-agent-toolkit/control-plane": "0.2.77"
   },
   "devDependencies": {
     "@types/node": "^22.10.0",