@open-agent-toolkit/cli 0.2.76 → 0.2.79

package/assets/agents/recon-worker.md

@@ -1,16 +1,17 @@
 ---
 name: recon-worker
-version: 1.0.1
+version: 1.0.2
 description: Executes one bounded recon packet assignment as a non-interactive leaf worker and writes exactly one declared artifact.
 tools: Read, Bash, Grep, Glob, Write, WebSearch, WebFetch
 color: cyan
+is_background: true
 ---
 
 ## Role
 
 You are a non-interactive recon leaf worker. Execute exactly one assignment in
-one declared mode: `map`, `gather`, `compile`, `verify`, `adversary`, `coverage`,
-or `reconcile`. No other mode is valid.
+one declared mode: `map`, `gather`, `compile`, `verify`, `adversary`, or
+`coverage`. No other mode is valid.
 
 The controller maps approved manifest waves to this closed vocabulary:
 
@@ -22,7 +23,6 @@ The controller maps approved manifest waves to this closed vocabulary:
 | `semantic-verification`    | `verify`               |
 | `adversarial`              | `adversary`            |
 | `coverage`                 | `coverage`             |
-| `reconciliation`           | `reconcile`            |
 | `redundant-gather`         | `gather`               |
 | `redundant-verification`   | `verify`               |
 | `contradiction-resolution` | `adversary`            |
@@ -75,7 +75,9 @@ canonical claim status.
 
 Consume only the designated dossiers. Deduplicate their findings into a
 provisional claim-ledger candidate and cite direct input artifacts. Do not
-reopen excluded sources or invent evidence.
+reopen excluded sources or invent evidence. Every persisted display excerpt
+must be an exact contiguous substring of the cited source, except for the
+declared `redacted-exact` representation.
 
 ### `verify`
 
@@ -99,13 +101,6 @@ Compare the declared scope and questions with the permitted ledger projection.
 Emit covered items, missing areas, and material gaps. Do not read gatherer
 reasoning.
 
-### `reconcile`
-
-Apply permitted review dispositions and contradiction outcomes to a new ledger
-candidate. Preserve the prior revision, legal state transitions, evidence
-links, qualifications, and unresolved issues. Never invent evidence or update
-the existing ledger in place.
-
 ## Output
 
 Write one JSON artifact using only the supplied closed schema's fields. A
@@ -121,6 +116,11 @@ Do not add a second mode field or any other unknown field. The controller
 validates `waveId` and `mode`, or `reviewerLane` and `reviewKind`, against the
 approved manifest wave before promoting the artifact.
 
+Before returning, run the supplied deterministic validator against the sole
+unpromoted `writePath`. Correct an invalid candidate within this same accepted
+task and validate it again. If it remains invalid, return terminal
+`PASS_FAILED`; the controller must not retry or replace the worker.
+
 Return only the artifact path and compact outcome. Do not return source bodies,
 worker reasoning, or dossier contents to the controller.
 

package/assets/bundle-metadata.json

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

package/assets/docs/workflows/skills/recon.md

@@ -69,19 +69,21 @@ context source, output directory, or strict authority:
 The default profile is `standard`. Each homogeneous wave has an independently
 selected and approved exact target. Bounded mapping, extraction, citation
 reopening, counterexample search, and mechanical dossier compilation start with
-economical qualified routes. A wave that genuinely requires interpretation or
-reconciliation judgment can use a stronger approved target without raising the
-cost of unrelated evidence waves.
+economical qualified routes. Reconciliation is deterministic controller work
+rather than a separately approved worker target.
 
 | Profile    | Use it for                                  | Required assurance work                                                                                            | Claim ceiling |
 | ---------- | ------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ | ------------- |
 | `quick`    | Bounded orientation                         | Mapping, gathering, compilation, schema validation, and locator validation; no independent semantic pass by design | `supported`   |
-| `standard` | Load-bearing evidence                       | Quick work plus blind semantic verification, adversarial review, coverage, and reconcile                           | `verified`    |
+| `standard` | Load-bearing evidence                       | Quick work plus blind semantic verification, adversarial review, coverage, and deterministic reconciliation        | `verified`    |
 | `thorough` | Expensive failure or correlated blind spots | Standard work plus required redundant gathering and redundant verification                                         | `verified`    |
 
 A thorough run may additionally predeclare an optional, condition-bound
 `contradiction-resolution` evidence wave. It runs only when its approved
 predicate triggers and is not required when that branch is not triggered.
+Gather and redundant-gather waves may partition source work across lanes. Each
+typed review wave uses exactly one lane so deterministic reconciliation has one
+result per review kind, at the fixed path bound by the approved manifest.
 
 The approval manifest shows each wave's exact target, task class, class floor,
 selection rationale, adaptive lane count, conditional rule, concurrency,
@@ -93,11 +95,16 @@ change requires renewed approval; there is no silent substitution after
 approval.
 
 Before any worker launches, recon confirms that the live launch surface can run
-the approved role, model, effort, and authority level. If it cannot, the run
-stays at `awaiting-approval` with a provider/dispatch diagnostic and nothing is
-launched. Deadlines are approved execution limits chosen for the task class,
-not short watchdogs; an accepted lane is never interrupted by hand because a
-displayed deadline elapsed.
+the approved role, model, effort, and authority level. A materialized Cursor
+role file is configuration, not evidence that the current Task catalog exposes
+that role; the live catalog controls eligibility, with the approved generic
+fallback used when needed. If the launch surface cannot run the selected
+target, the run stays at `awaiting-approval` with a provider/dispatch diagnostic
+and nothing is launched. Every Cursor leaf runs in the background so later
+parent-chat messages cannot interrupt multi-minute evidence work. Deadlines are
+approved execution limits chosen for the task class, not short watchdogs; an
+accepted lane is never interrupted by hand because a displayed deadline
+elapsed.
 
 ### Preview and Check Routing
 
@@ -117,29 +124,30 @@ compare the constructed target with that wave's approved exact target:
 node .agents/skills/recon/scripts/prepare-routing.mjs --manifest manifest.json --wave gather-1 --check-target candidate-target.json
 ```
 
-These commands validate structure, approval integrity, and exact identity. They
-do not launch a worker, rank model names, attest actual runtime identity, or
-measure cost.
+These commands validate structure, approval integrity, and exact identity. Like
+the other recon command-line helpers, they use a shared realpath-aware entry
+check, so direct and symlinked invocations execute identically. They do not
+launch a worker, rank model names, attest actual runtime identity, or measure
+cost.
 
 ### Bounded Conditional Evidence
 
-Standard and thorough may predeclare finite conditional
-`contradiction-resolution` evidence waves. A completed predecessor can trigger
-one such wave to seek discriminating evidence; accepted failure, cancellation,
+Standard and thorough may each predeclare at most one conditional
+`contradiction-resolution` evidence wave. A completed predecessor can trigger
+that wave to seek discriminating evidence; accepted failure, cancellation,
 timeout, or missing output cannot trigger a replacement. Triggered,
 not-triggered, and unresolved dispositions remain visible. Both branches feed
-the same single mandatory terminal reconciliation.
+the same deterministic controller reconciliation.
 
 A triggered condition must cite complete, digest-bound evidence from an approved
 predecessor in the same run. Evidence copied from another run cannot activate
 the destination wave and fails packet validation with
 `CONDITION_EVIDENCE_RUN_MISMATCH`.
 
-If a need for stronger reconciliation judgment is foreseeable, select that one
-terminal target before approval. If it appears only after approval, recon
-preserves completed evidence and returns an unresolved, out-of-envelope gap for
-renewed approval or a new run. It never mutates the target, silently retries,
-or launches a second reconciliation.
+If reconciliation exposes a need for new semantic judgment, recon preserves
+completed evidence and returns an unresolved, out-of-envelope gap for renewed
+approval or a new run. It never converts deterministic reconciliation into a
+worker wave or silently retries an accepted worker.
 
 ## Destination Precedence
 
@@ -173,8 +181,8 @@ non-publishable candidate generation withdraws any existing `packet.md`:
 - `claims.json` is the canonical claim ledger.
 - `manifest.json` records request, source, approved execution envelope, and
   gap provenance.
-- `reviews/` contains compact semantic, adversarial, coverage, and
-  reconciliation evidence.
+- `reviews/` contains compact semantic, adversarial, coverage, and the
+  controller-produced reconciliation record.
 - `raw/` contains worker dossiers, candidate artifacts, and safe failure
   diagnostics. It is not normal consumer input.
 
@@ -198,6 +206,20 @@ ledger must reference every completed primary and redundant gather dossier by
 exact path and digest before review briefs are created. Missing provenance fails
 with `MISSING_THOROUGH_GATHER_LEDGER_INPUT`.
 
+Compile workers copy each evidence excerpt as one contiguous exact substring of
+the reopened source. A source-required redaction may replace only the sensitive
+span while preserving the surrounding bytes and recording the redaction. Recon
+does not repair stale locators after compilation. Each accepted worker validates
+its own closed artifact schema once, within the same accepted task, before
+returning. An invalid accepted artifact is terminal; the controller neither
+retries the schema nor substitutes another worker.
+
+When an accepted lane has already written a schema-valid, lane-matching artifact
+at its approved path, that durable artifact remains the result even if the
+provider stream later closes with an error. Recon records the stream failure as
+a provider diagnostic and does not relaunch the lane. A missing or invalid
+artifact remains a failed pass.
+
 The ledger compiler and packet validator enforce categorical referential
 integrity on `synthesis.keyClaimIds` and `synthesis.unresolvedQuestionIds`. Any
 reference to an unknown claim or question ID fails validation with
@@ -228,10 +250,14 @@ the caller assesses sufficiency and conclusions. Stronger profiles can promote
 claims only when their required independent review artifacts validate and were
 written by approved lanes.
 
-When an independent semantic review rejects a proposed claim, the reconciler
-transitions it to `unsupported` rather than deleting it. This preserves the
-claim statement, cited evidence, and transition history in `claims.json`, and
-renders the finding under Contradictions and Qualifications.
+When an independent semantic review rejects a proposed claim, deterministic
+controller reconciliation transitions it to `unsupported` rather than deleting
+it. The controller validates the digest-bound input ledger and required review
+set, writes `raw/drafts/claims-v2.json` and
+`reviews/reconciliation.json`, validates both, then atomically promotes the
+candidate ledger to `claims.json`. This preserves the claim statement, cited
+evidence, and transition history and renders the finding under Contradictions
+and Qualifications.
 
 An adversarial challenge transitions a claim to `contested`. A run with
 contested claims may publish as `complete` when all declared questions and

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.79",
+  "docs-config": "0.2.79",
+  "docs-theme": "0.2.79",
+  "docs-transforms": "0.2.79"
 }

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) {