@open-agent-toolkit/cli 0.2.66 → 0.2.68

package/dist/commands/config/index.js

@@ -11,8 +11,9 @@ import { normalizeDispatchMatrix, validateDispatchRouteTarget, walkDispatchMatri
 import { formatDispatchNotices, terminalReviewerNoticesForMatrix, } from '../../config/dispatch-notices.js';
 import { dispatchPolicyModeDescription, dispatchPolicyPolicyDescription, managedDispatchPolicyValueList, } from '../../config/dispatch-policy-options.js';
 import { parseJsonConfig } from '../../config/json.js';
-import { VALID_DISPATCH_POLICY_MODES, VALID_MANAGED_DISPATCH_POLICIES, MAX_GATE_TIMEOUT_MS, MIN_GATE_TIMEOUT_MS, isValidGateTimeoutMs, normalizeWorkflowPostImplementSequence, readOatConfig, readOatConfigForDefaultScopeRepair, readOatConfigForDocumentationExcludesRepair, readOatConfigForInstructionPointerExcludesRepair, readOatLocalConfig, readUserConfig, writeOatConfig, writeOatLocalConfig, writeUserConfig, } from '../../config/oat-config.js';
-import { resolveEffectiveConfig, } from '../../config/resolve.js';
+import { VALID_DISPATCH_POLICY_MODES, VALID_MANAGED_DISPATCH_POLICIES, MAX_GATE_TIMEOUT_MS, MIN_GATE_TIMEOUT_MS, isValidGateTimeoutMs, normalizeWorkflowPostImplementSequence, readOatConfig, readOatConfigForDefaultScopeRepair, readOatConfigForDocumentationExcludesRepair, readOatConfigForInstructionPointerExcludesRepair, readOatConfigWithWarnings, readOatLocalConfig, readUserConfig, writeOatConfig, writeOatLocalConfig, writeUserConfig, } from '../../config/oat-config.js';
+import { getOwnKey, setOwnKey } from '../../config/own-keys.js';
+import { resolveEffectiveConfig, resolveEnvOverride, } from '../../config/resolve.js';
 import { resolveAssetsRoot } from '../../fs/assets.js';
 import { atomicWriteJson } from '../../fs/io.js';
 import { resolveProjectRoot } from '../../fs/paths.js';
@@ -949,6 +950,7 @@ const DEFAULT_DEPENDENCIES = {
     readOatConfigForDefaultScopeRepair,
     readOatConfigForDocumentationExcludesRepair,
     readOatConfigForInstructionPointerExcludesRepair,
+    readOatConfigWithWarnings,
     writeOatConfig,
     readOatLocalConfig,
     writeOatLocalConfig,
@@ -1258,9 +1260,16 @@ function defaultSurfaceForKey(key) {
 /**
  * Resolve the `--shared` / `--local` / `--user` trio to a single surface.
  *
- * Lifted verbatim out of the `set` action so `unset` enforces the same
- * mutual-exclusion rule through the same code path. The thrown message is
- * byte-identical to the one `set` raised inline, because tests pin it.
+ * `set`, `unset`, and `adopt` all resolve the trio here -- this is the only
+ * copy of the mutual-exclusion rule and of its message. It was lifted verbatim
+ * out of the `set` action so `unset` could share it, and `adopt` was folded on
+ * afterwards.
+ *
+ * The message is pinned in two ways, so changing it means moving all three
+ * commands together: the per-command cases assert it individually, and the
+ * three-command parity case in `index.test.ts` ('set, unset, and adopt reject
+ * the same conflicting surface flags with one message') compares the three
+ * commands' output to each other as well as to the literal.
  */
 function resolveSurfaceFlags(options) {
     const flagsPresent = [options.shared, options.local, options.user].filter(Boolean).length;
@@ -1510,7 +1519,10 @@ function applyWorkflowValue(workflow, key, value) {
         const { provider, tier } = parseDispatchCeilingProviderConfigKey(key);
         const providers = workflow.dispatchCeiling?.providers ?? {};
         if (tier) {
-            const existingProviderValue = providers[provider];
+            // `provider` is a user-supplied config-key segment, so the lookup is
+            // own-key guarded. The computed-key writes below use object-literal
+            // define semantics and are already safe.
+            const existingProviderValue = getOwnKey(providers, provider);
             const existingTierMap = existingProviderValue &&
                 typeof existingProviderValue === 'object' &&
                 !Array.isArray(existingProviderValue)
@@ -1736,20 +1748,24 @@ function buildResolvedConfigAggregate(resolved, key) {
         if (sourceRank[entry.source] > sourceRank[source]) {
             source = entry.source;
         }
+        // Key segments come from resolved config keys, so a provider literally
+        // named `__proto__` reaches this walk. A bare `cursor[part]` descends into
+        // `Object.prototype` and the leaf write then lands on the global
+        // prototype, polluting every object in the process -- not just this map.
         const parts = entryKey.slice(prefix.length).split('.');
         let cursor = value;
         for (const [index, part] of parts.entries()) {
             if (index === parts.length - 1) {
-                cursor[part] = entry.value;
+                setOwnKey(cursor, part, entry.value);
             }
             else {
-                const nested = cursor[part];
+                const nested = getOwnKey(cursor, part);
                 if (typeof nested !== 'object' ||
                     nested === null ||
                     Array.isArray(nested)) {
-                    cursor[part] = {};
+                    setOwnKey(cursor, part, {});
                 }
-                cursor = cursor[part];
+                cursor = getOwnKey(cursor, part);
             }
         }
     }
@@ -2214,8 +2230,16 @@ async function unsetConfigValue(repoRoot, userConfigDir, key, surface, dependenc
         key === 'pjm.remote.schemaVersion') {
         throw new Error(`Config key '${key}' is read-only; unset one of its documented child keys.`);
     }
-    const resolved = await dependencies.resolveEffectiveConfig(repoRoot, userConfigDir, dependencies.processEnv);
-    const envShadowed = resolved.resolved[key]?.source === 'env';
+    // Deliberately not `resolveEffectiveConfig`: its result was used for this one
+    // boolean, and its strict normalization throws on exactly the malformed
+    // stored value `unset` exists to remove. `ENV_OVERRIDE_MAP` covers three
+    // keys, all of which are in `DEFAULT_SHARED_CONFIG` and therefore always
+    // present in the resolved view, and the env branch is checked first there --
+    // so this probe answers identically for every config key. The whole-config
+    // read this replaces was also a validation barrier; that role is reinstated
+    // separately by the targeted barrier below, which reads every surface except
+    // the targeted one (the targeted one is re-normalized on write instead).
+    const envShadowed = resolveEnvOverride(key, dependencies.processEnv) !== undefined;
     if (key === 'activeProject' || key === 'lastPausedProject') {
         throw new Error(`Cannot unset state key '${key}'. Lifecycle state is cleared with: oat config set ${key} ''`);
     }
@@ -2236,6 +2260,44 @@ async function unsetConfigValue(repoRoot, userConfigDir, key, surface, dependenc
         ? defaultSurfaceForKey(key)
         : surface;
     const path = configPathForKey(key);
+    // Targeted strict barrier.
+    //
+    // `resolveEffectiveConfig` used to run at the top of this function, and as a
+    // side effect of resolving it strictly read all three surfaces. That read --
+    // not its return value -- is what made a malformed value anywhere abort
+    // `unset` before it wrote anything. The `envShadowed` probe above no longer
+    // performs it, so the barrier is reinstated here explicitly and narrowly:
+    // every surface OTHER than the targeted one is read strictly, through the
+    // same injected readers `resolveEffectiveConfig` composes, so a malformed
+    // value on an untargeted surface still aborts with the identical
+    // `Invalid <key>` message it produced before.
+    //
+    // The targeted surface is deliberately excluded, and that exclusion is the
+    // whole point of the change: `removeFromSurface` reads it through the
+    // key-specific repair reader -- lenient only for the key being removed -- and
+    // writes it back through `writeOatConfig` / `writeOatLocalConfig` /
+    // `writeUserConfig`, every one of which re-normalizes. A malformed value on
+    // the targeted surface that is NOT the key being removed is therefore still
+    // refused, on the rewrite rather than on a pre-read.
+    if (effectiveSurface !== 'shared') {
+        await dependencies.readOatConfig(repoRoot);
+    }
+    if (effectiveSurface !== 'local') {
+        await dependencies.readOatLocalConfig(repoRoot);
+    }
+    if (effectiveSurface !== 'user') {
+        await dependencies.readUserConfig(userConfigDir);
+    }
+    // The one branch that gets no re-normalization on the way out: the
+    // `pjm.remote` raw-write path in `removeFromSurface` persists through
+    // `atomicWriteJson`, bypassing `writeOatConfig`. So the targeted shared
+    // surface must be read strictly here too. `pjm.remote` children are not among
+    // the malformed-value repair keys this change targets, which is why adding
+    // this read keeps that branch's acceptance set byte-identical to its previous
+    // one rather than narrowing it.
+    if (isPjmRemoteConfigKey(key)) {
+        await dependencies.readOatConfig(repoRoot);
+    }
     const removed = await removeFromSurface(repoRoot, userConfigDir, key, effectiveSurface, path, dependencies);
     // The env guard is scoped to the targeted surface, not to the effective
     // value, so that `unset` mirrors `set`: `set` happily rewrites a stored value
@@ -2302,9 +2364,12 @@ async function removeFromSurface(repoRoot, userConfigDir, key, effectiveSurface,
         // policy.description=none and authority.default=read-only. Removing a
         // leaf from that normalized object and sending it through writeOatConfig
         // would therefore write the leaf straight back while reporting success.
-        // The config has already passed the strict shared-policy reader in
-        // resolveEffectiveConfig, so perform this removal against the validated raw
-        // document and atomically persist only the requested structural change.
+        // The strict shared read happens in `unsetConfigValue`'s targeted barrier
+        // immediately before this call -- this branch depends on it, because
+        // `atomicWriteJson` below bypasses `writeOatConfig`'s normalization, so
+        // nothing downstream would catch a malformed document. Given that read,
+        // perform this removal against the validated raw document and atomically
+        // persist only the requested structural change.
         const repaired = await removeConfigPathOnDisk(configPath, path);
         if (!repaired) {
             return false;
@@ -2424,15 +2489,22 @@ function applyDispatchMatrixRecommendation(workflow, recommendation) {
     const providers = {
         ...recommendation.providers,
     };
+    // `existingProviders` is a `normalizeDispatchMatrix` product, which now
+    // keeps a provider literally named `__proto__` as an own key, so
+    // `Object.entries` yields it here and every access is own-key guarded. The
+    // `{ ...recommendation.providers }` spread above is already safe.
     for (const [provider, existingValue] of Object.entries(existingProviders)) {
-        const recommendedValue = recommendation.providers[provider];
+        const recommendedValue = getOwnKey(recommendation.providers, provider);
         if (recommendedValue &&
             typeof recommendedValue !== 'string' &&
             typeof existingValue !== 'string') {
-            providers[provider] = { ...recommendedValue, ...existingValue };
+            setOwnKey(providers, provider, {
+                ...recommendedValue,
+                ...existingValue,
+            });
         }
         else {
-            providers[provider] = existingValue;
+            setOwnKey(providers, provider, existingValue);
         }
     }
     return {
@@ -2449,11 +2521,10 @@ async function effectiveTerminalReviewerNotices(repoRoot, userConfigDir, depende
     const effectiveProviders = {};
     for (const config of [resolved.user, resolved.shared, resolved.local]) {
         for (const [provider, value] of Object.entries(config.workflow?.dispatchCeiling?.providers ?? {})) {
-            const existing = effectiveProviders[provider];
-            effectiveProviders[provider] =
-                isRecord(existing) && isRecord(value)
-                    ? { ...existing, ...value }
-                    : value;
+            const existing = getOwnKey(effectiveProviders, provider);
+            setOwnKey(effectiveProviders, provider, isRecord(existing) && isRecord(value)
+                ? { ...existing, ...value }
+                : value);
         }
     }
     return terminalReviewerNoticesForMatrix(effectiveProviders);
@@ -2560,6 +2631,32 @@ function formatCatalogDetails(entries) {
     ].join('\n'))
         .join('\n\n');
 }
+/**
+ * The `warnings` field for a JSON document, omitted when there is nothing to
+ * say.
+ *
+ * An always-present `warnings: []` would be new noise on the common path and
+ * would break every existing exact-match assertion on these documents, so the
+ * key appears only when it carries something -- the same shape
+ * `exclusionWarnings` uses in `commands/instructions/sync/sync.ts`.
+ */
+function jsonWarnings(warnings) {
+    return warnings.length > 0 ? { warnings } : {};
+}
+/**
+ * Emit shared-config read warnings on the human channel.
+ *
+ * `logger.warn` is a no-op under `--json` (`ui/logger.ts`), so the JSON
+ * document carries the same strings in its own `warnings` field instead. Each
+ * caller picks exactly one channel, which is why this is only ever reached from
+ * the non-JSON branch: routing both ways would print nothing extra today but
+ * would double-print the moment the logger learned to emit under `--json`.
+ */
+function emitConfigReadWarnings(context, warnings) {
+    for (const warning of warnings) {
+        context.logger.warn(warning);
+    }
+}
 async function runGet(keyArg, context, dependencies) {
     try {
         if (!isConfigKey(keyArg)) {
@@ -2567,14 +2664,21 @@ async function runGet(keyArg, context, dependencies) {
         }
         const repoRoot = await dependencies.resolveProjectRoot(context.cwd);
         const userConfigDir = join(context.home, '.oat');
+        // One read per invocation, not one per resolved layer, so a wrong-typed
+        // key is reported once. A fail-closed key throws here exactly as it would
+        // have thrown inside `resolveEffectiveConfig` below -- same normalizer,
+        // same message -- so error precedence is unchanged.
+        const { warnings } = await dependencies.readOatConfigWithWarnings(repoRoot);
         const value = await getConfigValue(repoRoot, userConfigDir, keyArg, dependencies, context.json);
         if (context.json) {
             context.logger.json({
                 status: 'ok',
                 ...value,
+                ...jsonWarnings(warnings),
             });
         }
         else {
+            emitConfigReadWarnings(context, warnings);
             context.logger.info(formatResolvedValue(value.value) ?? '');
         }
         process.exitCode = 0;
@@ -2694,6 +2798,9 @@ async function runList(context, dependencies) {
     try {
         const repoRoot = await dependencies.resolveProjectRoot(context.cwd);
         const userConfigDir = join(context.home, '.oat');
+        // `list` resolves every key and each resolution re-reads the shared file,
+        // so the warning has to come from this one read rather than from the loop.
+        const { warnings } = await dependencies.readOatConfigWithWarnings(repoRoot);
         const values = [];
         for (const key of await listConfigKeys(repoRoot, userConfigDir, dependencies)) {
             values.push(await getConfigValue(repoRoot, userConfigDir, key, dependencies));
@@ -2702,9 +2809,11 @@ async function runList(context, dependencies) {
             context.logger.json({
                 status: 'ok',
                 values,
+                ...jsonWarnings(warnings),
             });
         }
         else {
+            emitConfigReadWarnings(context, warnings);
             context.logger.info(formatList(values));
         }
         process.exitCode = 0;
@@ -2825,21 +2934,7 @@ export function createConfigCommand(overrides = {}) {
         .action(async (template, options, command) => {
         const context = dependencies.buildCommandContext(readGlobalOptions(command));
         try {
-            const flagsPresent = [
-                options.shared,
-                options.local,
-                options.user,
-            ].filter(Boolean).length;
-            if (flagsPresent > 1) {
-                throw new Error('--shared, --local, and --user flags are mutually exclusive; pass at most one.');
-            }
-            let surface = 'auto';
-            if (options.shared)
-                surface = 'shared';
-            else if (options.local)
-                surface = 'local';
-            else if (options.user)
-                surface = 'user';
+            const surface = resolveSurfaceFlags(options);
             await runAdopt(template, { surface }, context, dependencies);
         }
         catch (error) {

package/dist/commands/docs/index-generate/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/commands/docs/index-generate/index.ts"],"names":[],"mappings":"AAWA,OAAO,EAEL,KAAK,cAAc,EACnB,KAAK,aAAa,EACnB,MAAM,sBAAsB,CAAC;AAE9B,OAAO,EACL,KAAK,SAAS,EAGf,MAAM,oBAAoB,CAAC;AAI5B,OAAO,EAAE,OAAO,EAAU,MAAM,WAAW,CAAC;AAI5C,eAAO,MAAM,uBAAuB,iIAC4F,CAAC;AAuBjI,UAAU,6BAA6B;IACrC,aAAa,EAAE,CACb,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,OAAO,aAAa,EAAE,oBAAoB,KAChD,OAAO,CAAC,OAAO,aAAa,EAAE,UAAU,EAAE,CAAC,CAAC;IACjD,WAAW,EAAE,CAAC,OAAO,EAAE,OAAO,aAAa,EAAE,UAAU,EAAE,KAAK,MAAM,CAAC;IACrE,SAAS,EAAE,CACT,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,cAAc,KACrB,OAAO,CAAC,IAAI,CAAC,CAAC;IACnB,aAAa,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,SAAS,CAAC,CAAC;IACxD,cAAc,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACvE,eAAe,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;IAClD,SAAS,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IAC9C,iBAAiB,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IAC5D,QAAQ,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;IAC5C,iBAAiB,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;CAC7D;AAED,UAAU,yBAAyB;IACjC,mBAAmB,EAAE,CAAC,OAAO,EAAE,aAAa,KAAK,cAAc,CAAC;IAChE,QAAQ,EAAE,6BAA6B,CAAC;CACzC;AAggBD,wBAAgB,8BAA8B,CAC5C,SAAS,GAAE,OAAO,CAAC,yBAAyB,CAAM,GACjD,OAAO,CAgCT"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/commands/docs/index-generate/index.ts"],"names":[],"mappings":"AAWA,OAAO,EAEL,KAAK,cAAc,EACnB,KAAK,aAAa,EACnB,MAAM,sBAAsB,CAAC;AAE9B,OAAO,EACL,KAAK,SAAS,EAGf,MAAM,oBAAoB,CAAC;AAI5B,OAAO,EAAE,OAAO,EAAU,MAAM,WAAW,CAAC;AAI5C,eAAO,MAAM,uBAAuB,iIAC4F,CAAC;AAuBjI,UAAU,6BAA6B;IACrC,aAAa,EAAE,CACb,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,OAAO,aAAa,EAAE,oBAAoB,KAChD,OAAO,CAAC,OAAO,aAAa,EAAE,UAAU,EAAE,CAAC,CAAC;IACjD,WAAW,EAAE,CAAC,OAAO,EAAE,OAAO,aAAa,EAAE,UAAU,EAAE,KAAK,MAAM,CAAC;IACrE,SAAS,EAAE,CACT,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,cAAc,KACrB,OAAO,CAAC,IAAI,CAAC,CAAC;IACnB,aAAa,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,SAAS,CAAC,CAAC;IACxD,cAAc,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACvE,eAAe,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;IAClD,SAAS,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IAC9C,iBAAiB,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IAC5D,QAAQ,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;IAC5C,iBAAiB,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;CAC7D;AAED,UAAU,yBAAyB;IACjC,mBAAmB,EAAE,CAAC,OAAO,EAAE,aAAa,KAAK,cAAc,CAAC;IAChE,QAAQ,EAAE,6BAA6B,CAAC;CACzC;AAomBD,wBAAgB,8BAA8B,CAC5C,SAAS,GAAE,OAAO,CAAC,yBAAyB,CAAM,GACjD,OAAO,CAgCT"}

package/dist/commands/docs/index-generate/index.js

@@ -94,6 +94,28 @@ function isInside(parent, candidate) {
  * dangling-link hops resolved below.
  */
 const MAX_SYMLINK_HOPS = 32;
+/**
+ * The hop-cap refusal, addressed to whoever owns the offending path.
+ *
+ * A derived docs directory is unusable path *configuration*, so it takes
+ * `CONFIGURATION_EXIT_CODE` and the `documentation.root` repair, exactly like
+ * `missingRootError` and the "not a directory" refusal. An explicitly supplied
+ * path stays an actionable flag error.
+ */
+function hopCapError(context) {
+    const preamble = `Refusing to resolve ${context.origin}: its symlink chain exceeds ` +
+        `${MAX_SYMLINK_HOPS} hops. `;
+    if (context.role.kind === 'docs-dir') {
+        if (context.role.derived) {
+            return new CliError(`${preamble}The docs directory is derived from \`documentation.root\` ` +
+                'in .oat/config.json. Repair it with ' +
+                '`oat config set documentation.root <path>`, or pass --docs-dir with a ' +
+                'path that is not a deep symlink chain.', CONFIGURATION_EXIT_CODE);
+        }
+        return new CliError(`${preamble}Pass --docs-dir with a path that is not a deep symlink chain.`, REFUSAL_EXIT_CODE);
+    }
+    return new CliError(`${preamble}Pass --output with a path that is not a deep symlink chain.`, REFUSAL_EXIT_CODE);
+}
 /**
  * Absolute path with symlinks resolved, so a symlinked parent cannot smuggle a
  * write into a protected tree past the lexical containment checks.
@@ -105,7 +127,7 @@ const MAX_SYMLINK_HOPS = 32;
  * relative link destination is joined to the parent's *real* location rather
  * than its lexical spelling.
  */
-async function canonicalize(target, deps, linkHops = 0) {
+async function canonicalize(target, deps, context, linkHops = 0) {
     const absolute = resolve(target);
     try {
         return await deps.realpath(absolute);
@@ -120,7 +142,7 @@ async function canonicalize(target, deps, linkHops = 0) {
     if (parent === absolute) {
         return absolute;
     }
-    const canonicalParent = await canonicalize(parent, deps, linkHops);
+    const canonicalParent = await canonicalize(parent, deps, context, linkHops);
     const candidate = join(canonicalParent, basename(absolute));
     const linkTarget = await deps.readLinkIfSymlink(candidate);
     if (linkTarget === null) {
@@ -128,10 +150,9 @@ async function canonicalize(target, deps, linkHops = 0) {
     }
     if (linkHops >= MAX_SYMLINK_HOPS) {
         // Fail closed: falling through would hand the writer an unresolved link.
-        throw new CliError(`Refusing to resolve ${target}: its symlink chain exceeds ${MAX_SYMLINK_HOPS} hops. ` +
-            'Pass --output with a path that is not a deep symlink chain.', REFUSAL_EXIT_CODE);
+        throw hopCapError(context);
     }
-    return canonicalize(resolve(canonicalParent, linkTarget), deps, linkHops + 1);
+    return canonicalize(resolve(canonicalParent, linkTarget), deps, context, linkHops + 1);
 }
 function trimmed(value) {
     const trimmedValue = value?.trim();
@@ -229,9 +250,9 @@ async function resolveIndexGeneratePaths(context, options, deps) {
     };
 }
 /** `canonicalize`, but an unresolvable path yields null instead of throwing. */
-async function canonicalizeOrNull(target, deps) {
+async function canonicalizeOrNull(target, deps, role) {
     try {
-        return await canonicalize(target, deps);
+        return await canonicalize(target, deps, { role, origin: target });
     }
     catch {
         return null;
@@ -242,20 +263,34 @@ async function canonicalizeIndexGeneratePaths(resolved, deps) {
     const lexicalDocumentationConfig = documentationConfigValue
         ? resolve(resolved.repoRoot, documentationConfigValue)
         : null;
+    // Resolution order is load-bearing: the docs directory is canonicalized
+    // first, and the safety checks below compare against its canonical form.
     return {
-        docsDir: await canonicalize(resolved.docsDir, deps),
-        outputPath: await canonicalize(resolved.outputPath, deps),
+        docsDir: await canonicalize(resolved.docsDir, deps, {
+            role: {
+                kind: 'docs-dir',
+                derived: resolved.docsDirSource !== 'flag',
+            },
+            origin: resolved.docsDir,
+        }),
+        outputPath: await canonicalize(resolved.outputPath, deps, {
+            role: { kind: 'output' },
+            origin: resolved.outputPath,
+        }),
         // An unusable configured root only makes the config write ineligible; it
         // must not fail a run whose paths were both supplied explicitly.
         configuredRoot: resolved.configuredRoot
-            ? await canonicalizeOrNull(resolved.configuredRoot, deps)
+            ? await canonicalizeOrNull(resolved.configuredRoot, deps, {
+                kind: 'other',
+            })
             : null,
         lexicalDocumentationConfig,
         // Falling back to the lexical path keeps the refusal guard intact when the
         // configured tool config cannot be canonicalized.
         documentationConfig: lexicalDocumentationConfig
-            ? ((await canonicalizeOrNull(lexicalDocumentationConfig, deps)) ??
-                lexicalDocumentationConfig)
+            ? ((await canonicalizeOrNull(lexicalDocumentationConfig, deps, {
+                kind: 'other',
+            })) ?? lexicalDocumentationConfig)
             : null,
     };
 }
@@ -364,11 +399,32 @@ async function runIndexGenerate(context, options, deps) {
             entriesGenerated: entries.length,
             docsDir,
             docsDirSource: resolved.docsDirSource,
+            // Exactly the list handed to `deps.generateIndex` above, so a missing
+            // page can be attributed without re-deriving the merge.
+            excludes: resolved.excludes,
             outputPath,
         });
         return;
     }
     context.logger.info(`Generated index with ${entries.length} entries from ${docsDir} → ${outputPath}`);
+    // A bare `0 entries` reads identically for an empty tree, a wrong
+    // `--docs-dir`, and exclusions that swallowed everything. Say which of those
+    // the operator should look at. This reports; it never changes the exit code
+    // or the written file.
+    //
+    // The wording is deliberately observational. This function sees indexed
+    // entries, never pattern matches, so it cannot know an exclusion actually
+    // matched anything: an empty tree with a pattern that matched nothing lands
+    // here too, and blaming the exclusions outright would be false in exactly
+    // that case.
+    if (entries.length === 0) {
+        context.logger.info(resolved.excludes.length > 0
+            ? `No pages were indexed, with ${resolved.excludes.length} exclusion ` +
+                `pattern${resolved.excludes.length === 1 ? '' : 's'} active ` +
+                `(${resolved.excludes.join(', ')}). Check whether ` +
+                '`documentation.excludes` or --exclude is hiding the pages you expect.'
+            : `No pages were indexed: ${docsDir} contained no indexable pages.`);
+    }
 }
 async function runIndexGenerateCommand(context, options, dependencies) {
     try {

package/dist/commands/docs/init/index.d.ts

@@ -21,6 +21,17 @@ interface DocsInitDependencies {
     readOatConfig: (repoRoot: string) => Promise<OatConfig>;
     confirmAction: (message: string, ctx: PromptContext) => Promise<boolean>;
 }
+/**
+ * The AGENTS.md `## Documentation` section for a freshly scaffolded app.
+ *
+ * Each bullet names the file that owns one role, matching what
+ * `buildDocumentationConfig` seeds into `documentation.*`. A Fumadocs app has
+ * two index files -- the authored source page under `docs/` and the app-root
+ * manifest `oat docs generate-index` writes -- and `documentation.index` names
+ * the second, so a single "Index file" bullet pointing at the first documented
+ * a file the config does not name. MkDocs has no generated manifest: its
+ * `documentation.index` is the nav YAML the Config bullet already names.
+ */
 export declare function buildDocsSectionBody(options: DocsInitResolvedOptions): string;
 export declare function createDocsInitCommand(overrides?: Partial<DocsInitDependencies>): Command;
 export {};

package/dist/commands/docs/init/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/commands/docs/init/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,KAAK,cAAc,EACnB,KAAK,aAAa,EACnB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EACL,KAAK,mBAAmB,EAIzB,MAAM,4BAA4B,CAAC;AACpC,OAAO,EAGL,KAAK,aAAa,EAClB,KAAK,YAAY,EAElB,MAAM,iCAAiC,CAAC;AAEzC,OAAO,EACL,KAAK,SAAS,EAGf,MAAM,oBAAoB,CAAC;AAE5B,OAAO,EAAE,OAAO,EAAU,MAAM,WAAW,CAAC;AAG5C,OAAO,EAIL,KAAK,uBAAuB,EAK7B,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAEL,KAAK,sBAAsB,EAC5B,MAAM,gBAAgB,CAAC;AAexB,UAAU,uBAAuB;IAC/B,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,OAAO,EAAE,MAAM,CAAC;IAChB,gBAAgB,EAAE,sBAAsB,CAAC;CAC1C;AAED,UAAU,oBAAoB;IAC5B,mBAAmB,EAAE,CAAC,OAAO,EAAE,aAAa,KAAK,cAAc,CAAC;IAChE,iBAAiB,EAAE,MAAM,OAAO,CAAC,MAAM,CAAC,CAAC;IACzC,eAAe,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,UAAU,GAAG,gBAAgB,CAAC,CAAC;IAC9E,gBAAgB,EAAE,CAChB,OAAO,EAAE,MAAM,EACf,YAAY,EAAE,MAAM,EACpB,GAAG,EAAE,aAAa,KACf,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IAC5B,eAAe,EAAE,CAAC,CAAC,SAAS,MAAM,EAChC,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,YAAY,CAAC,CAAC,CAAC,EAAE,EAC1B,GAAG,EAAE,aAAa,KACf,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC;IACvB,WAAW,EAAE,CACX,OAAO,EAAE,cAAc,EACvB,OAAO,EAAE,uBAAuB,EAChC,UAAU,EAAE,MAAM,KACf,OAAO,CAAC,uBAAuB,GAAG,IAAI,CAAC,CAAC;IAC7C,qBAAqB,EAAE,CACrB,QAAQ,EAAE,MAAM,EAChB,GAAG,EAAE,MAAM,EACX,IAAI,EAAE,MAAM,KACT,OAAO,CAAC,mBAAmB,CAAC,CAAC;IAClC,aAAa,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,SAAS,CAAC,CAAC;IACxD,aAAa,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,aAAa,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;CAC1E;AAqGD,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,uBAAuB,GAAG,MAAM,CAc7E;AA6JD,wBAAgB,qBAAqB,CACnC,SAAS,GAAE,OAAO,CAAC,oBAAoB,CAAM,GAC5C,OAAO,CA6CT"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/commands/docs/init/index.ts"],"names":[],"mappings":"AAEA,OAAO,EAEL,KAAK,cAAc,EACnB,KAAK,aAAa,EACnB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EACL,KAAK,mBAAmB,EAIzB,MAAM,4BAA4B,CAAC;AACpC,OAAO,EAGL,KAAK,aAAa,EAClB,KAAK,YAAY,EAElB,MAAM,iCAAiC,CAAC;AAEzC,OAAO,EACL,KAAK,SAAS,EAGf,MAAM,oBAAoB,CAAC;AAE5B,OAAO,EAAE,OAAO,EAAU,MAAM,WAAW,CAAC;AAG5C,OAAO,EAIL,KAAK,uBAAuB,EAK7B,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAEL,KAAK,sBAAsB,EAC5B,MAAM,gBAAgB,CAAC;AAexB,UAAU,uBAAuB;IAC/B,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,OAAO,EAAE,MAAM,CAAC;IAChB,gBAAgB,EAAE,sBAAsB,CAAC;CAC1C;AAED,UAAU,oBAAoB;IAC5B,mBAAmB,EAAE,CAAC,OAAO,EAAE,aAAa,KAAK,cAAc,CAAC;IAChE,iBAAiB,EAAE,MAAM,OAAO,CAAC,MAAM,CAAC,CAAC;IACzC,eAAe,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,UAAU,GAAG,gBAAgB,CAAC,CAAC;IAC9E,gBAAgB,EAAE,CAChB,OAAO,EAAE,MAAM,EACf,YAAY,EAAE,MAAM,EACpB,GAAG,EAAE,aAAa,KACf,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IAC5B,eAAe,EAAE,CAAC,CAAC,SAAS,MAAM,EAChC,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,YAAY,CAAC,CAAC,CAAC,EAAE,EAC1B,GAAG,EAAE,aAAa,KACf,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC;IACvB,WAAW,EAAE,CACX,OAAO,EAAE,cAAc,EACvB,OAAO,EAAE,uBAAuB,EAChC,UAAU,EAAE,MAAM,KACf,OAAO,CAAC,uBAAuB,GAAG,IAAI,CAAC,CAAC;IAC7C,qBAAqB,EAAE,CACrB,QAAQ,EAAE,MAAM,EAChB,GAAG,EAAE,MAAM,EACX,IAAI,EAAE,MAAM,KACT,OAAO,CAAC,mBAAmB,CAAC,CAAC;IAClC,aAAa,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,SAAS,CAAC,CAAC;IACxD,aAAa,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,aAAa,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;CAC1E;AAqGD;;;;;;;;;;GAUG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,uBAAuB,GAAG,MAAM,CAuB7E;AA6JD,wBAAgB,qBAAqB,CACnC,SAAS,GAAE,OAAO,CAAC,oBAAoB,CAAM,GAC5C,OAAO,CA6CT"}

package/dist/commands/docs/init/index.js

@@ -1,3 +1,4 @@
+import { join } from 'node:path';
 import { buildCommandContext, } from '../../../app/command-context.js';
 import { formatAgentsMdGuidanceResult, formatAgentsMdMutationFailure, upsertAgentsMdSection, } from '../../shared/agents-md.js';
 import { confirmAction, inputWithDefault, selectWithAbort, } from '../../shared/shared.prompts.js';
@@ -90,14 +91,31 @@ const FRAMEWORK_LABELS = {
     fumadocs: 'Fumadocs (Next.js + MDX)',
     mkdocs: 'MkDocs (Python)',
 };
+/**
+ * The AGENTS.md `## Documentation` section for a freshly scaffolded app.
+ *
+ * Each bullet names the file that owns one role, matching what
+ * `buildDocumentationConfig` seeds into `documentation.*`. A Fumadocs app has
+ * two index files -- the authored source page under `docs/` and the app-root
+ * manifest `oat docs generate-index` writes -- and `documentation.index` names
+ * the second, so a single "Index file" bullet pointing at the first documented
+ * a file the config does not name. MkDocs has no generated manifest: its
+ * `documentation.index` is the nav YAML the Config bullet already names.
+ */
 export function buildDocsSectionBody(options) {
     const lines = [
         '## Documentation',
         '',
         `- **Docs root:** \`${options.targetDir}\``,
         `- **Framework:** ${FRAMEWORK_LABELS[options.framework]}`,
-        `- **Index file:** \`${options.targetDir}/docs/index.md\``,
+        `- **Docs source index:** \`${options.targetDir}/docs/index.md\``,
     ];
+    if (options.framework === 'fumadocs') {
+        // Derived exactly like the `documentation.index` seed in `./scaffold`, so
+        // the printed path and the recorded path cannot drift apart.
+        lines.push(`- **Generated index:** \`${join(options.targetDir, 'index.md')}\` — ` +
+            'regenerated by `oat docs generate-index`; do not hand-edit.');
+    }
     if (options.framework === 'mkdocs') {
         lines.push(`- **Config:** \`${options.targetDir}/mkdocs.yml\``);
     }

package/dist/commands/gate/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/commands/gate/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/commands/gate/index.ts"],"names":[],"mappings":"AAaA,OAAO,EAEL,KAAK,cAAc,EACnB,KAAK,aAAa,EACnB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EACL,gBAAgB,EAKhB,KAAK,qBAAqB,EAE3B,MAAM,8BAA8B,CAAC;AAYtC,OAAO,EAWL,KAAK,UAAU,EAIf,KAAK,SAAS,EACd,KAAK,cAAc,EACnB,KAAK,UAAU,EAEhB,MAAM,oBAAoB,CAAC;AAE5B,OAAO,EAOL,KAAK,cAAc,EACpB,MAAM,iBAAiB,CAAC;AAWzB,OAAO,EAEL,KAAK,WAAW,EACjB,MAAM,4BAA4B,CAAC;AACpC,OAAO,EAEL,KAAK,kBAAkB,EACvB,KAAK,kBAAkB,EAExB,MAAM,gCAAgC,CAAC;AAExC,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAGpC,OAAO,EACL,uBAAuB,EAExB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EACL,wBAAwB,EACxB,oBAAoB,EACpB,oBAAoB,EACpB,wBAAwB,EAEzB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAEL,KAAK,iBAAiB,EACtB,KAAK,gBAAgB,EACtB,MAAM,iBAAiB,CAAC;AAEzB,OAAO,EACL,sBAAsB,EAIvB,MAAM,kBAAkB,CAAC;AAG1B,UAAU,uBAAuB;IAC/B,mBAAmB,EAAE,CAAC,OAAO,EAAE,aAAa,KAAK,cAAc,CAAC;IAChE,kBAAkB,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;IACrD,aAAa,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,SAAS,CAAC,CAAC;IACxD,cAAc,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACvE,kBAAkB,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,cAAc,CAAC,CAAC;IAClE,mBAAmB,EAAE,CACnB,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,cAAc,KACnB,OAAO,CAAC,IAAI,CAAC,CAAC;IACnB,cAAc,EAAE,CAAC,aAAa,EAAE,MAAM,KAAK,OAAO,CAAC,UAAU,CAAC,CAAC;IAC/D,eAAe,EAAE,CAAC,aAAa,EAAE,MAAM,EAAE,MAAM,EAAE,UAAU,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAC9E,sBAAsB,EAAE,CACtB,QAAQ,EAAE,MAAM,EAChB,aAAa,EAAE,MAAM,EACrB,GAAG,EAAE,MAAM,CAAC,UAAU,KACnB,OAAO,CAAC,cAAc,CAAC,CAAC;IAC7B,uBAAuB,EAAE,OAAO,uBAAuB,CAAC;IACxD,wBAAwB,EAAE,OAAO,wBAAwB,CAAC;IAC1D,oBAAoB,EAAE,OAAO,oBAAoB,CAAC;IAClD,wBAAwB,EAAE,OAAO,wBAAwB,CAAC;IAC1D,oBAAoB,EAAE,OAAO,oBAAoB,CAAC;IAClD,UAAU,EAAE,CACV,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,MAAM,EAAE,EACd,OAAO,EAAE,iBAAiB,KACvB,OAAO,CAAC,gBAAgB,CAAC,CAAC;IAC/B,sBAAsB,EAAE,OAAO,sBAAsB,CAAC;IACtD,gBAAgB,EAAE,OAAO,gBAAgB,CAAC;IAC1C,UAAU,EAAE,MAAM,CAAC,UAAU,CAAC;IAC9B,kBAAkB,EAAE,CAClB,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,aAAa,EACrB,IAAI,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,KAC5B,OAAO,CAAC,OAAO,CAAC,CAAC;IACtB,mBAAmB,EAAE,CACnB,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,KAC5B,OAAO,CAAC,IAAI,CAAC,CAAC;IACnB,0BAA0B,EAAE,CAC1B,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,qBAAqB,EAC9B,IAAI,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,KAC5B,OAAO,CAAC,OAAO,CAAC,CAAC;IACtB,KAAK,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACrC,eAAe,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;CAC5C;AAuDD,KAAK,iBAAiB,GAClB,KAAK,GACL,QAAQ,GACR,QAAQ,GACR,KAAK,GACL,eAAe,GACf,SAAS,CAAC;AAOd,UAAU,aAAa;IACrB,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;IACjB,YAAY,EAAE,iBAAiB,CAAC;CACjC;AAcD,KAAK,kBAAkB,GAAG,aAAa,GAAG,cAAc,GAAG,MAAM,CAAC;AAClE,KAAK,qBAAqB,GACtB,kBAAkB,GAClB,4BAA4B,GAC5B,2CAA2C,GAC3C,kBAAkB,CAAC;AA4CvB,MAAM,WAAW,kBAAkB;IACjC,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,EAAE,UAAU,CAAC;IACnB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,WAAW,CAAC;IACpB,SAAS,CAAC,EAAE,qBAAqB,CAAC;IAClC,uBAAuB,CAAC,EAAE,OAAO,CAAC;CACnC;AAED,UAAU,oBAAoB;IAC5B,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,EAAE,kBAAkB,CAAC;IAC/B,UAAU,EAAE,kBAAkB,CAAC;IAC/B,MAAM,EAAE,WAAW,CAAC;IACpB,aAAa,EAAE,WAAW,EAAE,CAAC;IAC7B,kBAAkB,CAAC,EAAE,MAAM,EAAE,CAAC;IAC9B,sBAAsB,CAAC,EAAE,MAAM,CAAC;IAChC,kBAAkB,EAAE,OAAO,CAAC;IAC5B,MAAM,EAAE,MAAM,GAAG,OAAO,GAAG,mBAAmB,GAAG,aAAa,GAAG,SAAS,CAAC;CAC5E;AAED,UAAU,qBAAqB;IAC7B,KAAK,EAAE,kBAAkB,CAAC;IAC1B,QAAQ,EAAE,qBAAqB,CAAC;IAChC,QAAQ,EAAE;QACR,KAAK,EAAE,MAAM,CAAC;QACd,UAAU,EAAE,kBAAkB,CAAC;QAC/B,UAAU,EAAE,kBAAkB,CAAC;QAC/B,MAAM,EAAE,WAAW,CAAC;QACpB,MAAM,EAAE,oBAAoB,CAAC,QAAQ,CAAC,CAAC;QACvC,aAAa,EAAE,WAAW,EAAE,CAAC;QAC7B,kBAAkB,CAAC,EAAE,MAAM,EAAE,CAAC;QAC9B,sBAAsB,CAAC,EAAE,MAAM,CAAC;KACjC,CAAC;IACF,QAAQ,EAAE;QACR,MAAM,EAAE,MAAM,CAAC;QACf,OAAO,EAAE,MAAM,CAAC;QAChB,MAAM,EAAE,WAAW,CAAC;QACpB,KAAK,CAAC,EAAE,MAAM,CAAC;KAChB,CAAC;IACF,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAs2CD,wBAAgB,gBAAgB,CAC9B,QAAQ,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC,EAC9C,cAAc,EAAE,MAAM,EACtB,KAAK,EAAE,kBAAkB,EACzB,gBAAgB,CAAC,EAAE,oBAAoB,GACtC,kBAAkB,GAAG,IAAI,CAS3B;AA+xFD,wBAAgB,iBAAiB,CAC/B,SAAS,GAAE,OAAO,CAAC,uBAAuB,CAAM,GAC/C,OAAO,CAsOT"}

package/dist/commands/gate/index.js

@@ -9,6 +9,7 @@ import { getFrontmatterBlock, parseFrontmatterScalarFields, parseGeneratedTime,
 import { readGlobalOptions } from '../shared/shared.utils.js';
 import { parseJsonConfig } from '../../config/json.js';
 import { BUILTIN_EXEC_TARGETS, MAX_GATE_TIMEOUT_MS, MIN_GATE_TIMEOUT_MS, isValidGateTimeoutMs, readOatConfig, readOatLocalConfig, readUserConfig, writeOatConfig, writeOatLocalConfig, writeUserConfig, } from '../../config/oat-config.js';
+import { getOwnKey } from '../../config/own-keys.js';
 import { resolveEffectiveConfig, resolveExecTargetViews, resolveExecTargets, resolveGate, resolveGateWithSource, } from '../../config/resolve.js';
 import { dirExists, fileExists } from '../../fs/io.js';
 import { normalizeToPosixPath, resolveProjectRoot, validateRealPathWithinScope, } from '../../fs/paths.js';
@@ -634,7 +635,11 @@ function unsetSkillGate(config, skillName) {
 }
 function setExecTarget(config, targetId, target) {
     return updateWorkflowGates(config, (gates) => {
-        const existing = gates.execTargets?.[targetId];
+        // `targetId` comes from `oat gate target set <id>`. Without the own-key
+        // guard, an id of `__proto__` reads `Object.prototype`, which is truthy,
+        // so this takes the merge branch and silently omits the `priority: 0`
+        // default the create branch applies.
+        const existing = getOwnKey(gates.execTargets ?? {}, targetId);
         const value = target === null
             ? target
             : existing === null || existing === undefined
@@ -1034,7 +1039,10 @@ async function selectAvailableExecTarget(registry, currentRuntime, avoid, produc
 async function resolveSelectedExecTarget(targets, options, producerIdentity, context, dependencies) {
     const explicitTarget = options.target?.trim();
     if (explicitTarget) {
-        const target = targets[explicitTarget];
+        // `--target <id>` is a free-form user string. Without the own-key read an
+        // id of `__proto__` or `constructor` returns a truthy inherited member and
+        // slips past the unknown-target rejection below.
+        const target = getOwnKey(targets, explicitTarget);
         if (!target) {
             throw new Error(`Unknown exec target "${explicitTarget}".`);
         }

package/dist/commands/instructions/instructions.utils.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"instructions.utils.d.ts","sourceRoot":"","sources":["../../../src/commands/instructions/instructions.utils.ts"],"names":[],"mappings":"AAeA,OAAO,KAAK,EACV,uBAAuB,EACvB,uBAAuB,EACvB,gBAAgB,EAChB,uBAAuB,EACvB,gBAAgB,EAChB,4BAA4B,EAC5B,uBAAuB,EACvB,4BAA4B,EAE5B,mBAAmB,EACpB,MAAM,sBAAsB,CAAC;AAE9B,eAAO,MAAM,uBAAuB,iBAAiB,CAAC;AACtD,eAAO,MAAM,iCAAiC,EAAE,uBACrC,CAAC;AAcZ,UAAU,4BAA4B;IACpC,IAAI,EAAE,gBAAgB,CAAC;IACvB,OAAO,EAAE,gBAAgB,EAAE,CAAC;IAC5B,OAAO,EAAE,uBAAuB,EAAE,CAAC;IACnC,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;IACzB,sBAAsB,CAAC,EAAE,MAAM,EAAE,CAAC;IAClC,iBAAiB,CAAC,EAAE,MAAM,EAAE,CAAC;CAC9B;AAiCD,wBAAgB,8BAA8B,CAC5C,QAAQ,CAAC,EAAE,uBAAuB,GACjC,uBAAuB,CAEzB;AA2ED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,sBAAsB,CACpC,aAAa,GAAE,SAAS,MAAM,EAAO,GACpC,MAAM,EAAE,CAyBV;AAsDD;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAsB,iCAAiC,CACrD,QAAQ,EAAE,MAAM,EAChB,SAAS,GAAE,OAAO,CAAC,4BAA4B,CAAM,GACpD,OAAO,CAAC,4BAA4B,CAAC,CAuEvC;AAgID,wBAAsB,oBAAoB,CACxC,QAAQ,EAAE,MAAM,EAChB,OAAO,GAAE,uBAA4B,EACrC,SAAS,GAAE,OAAO,CAAC,4BAA4B,CAAM,GACpD,OAAO,CAAC,gBAAgB,EAAE,CAAC,CAkO7B;AAED,wBAAgB,wBAAwB,CACtC,OAAO,EAAE,gBAAgB,EAAE,EAC3B,OAAO,EAAE,uBAAuB,EAAE,GACjC,mBAAmB,CAoBrB;AAgBD,wBAAgB,wBAAwB,CAAC,EACvC,IAAI,EACJ,OAAO,EACP,OAAO,EACP,aAAa,EACb,sBAAsB,EACtB,iBAAiB,GAClB,EAAE,4BAA4B,GAAG,uBAAuB,CAgCxD;AAED,wBAAgB,wBAAwB,CACtC,OAAO,EAAE,uBAAuB,EAChC,QAAQ,CAAC,EAAE,MAAM,GAChB,MAAM,CAmCR"}
+{"version":3,"file":"instructions.utils.d.ts","sourceRoot":"","sources":["../../../src/commands/instructions/instructions.utils.ts"],"names":[],"mappings":"AAeA,OAAO,KAAK,EACV,uBAAuB,EACvB,uBAAuB,EACvB,gBAAgB,EAChB,uBAAuB,EACvB,gBAAgB,EAChB,4BAA4B,EAC5B,uBAAuB,EACvB,4BAA4B,EAE5B,mBAAmB,EACpB,MAAM,sBAAsB,CAAC;AAE9B,eAAO,MAAM,uBAAuB,iBAAiB,CAAC;AACtD,eAAO,MAAM,iCAAiC,EAAE,uBACrC,CAAC;AAcZ,UAAU,4BAA4B;IACpC,IAAI,EAAE,gBAAgB,CAAC;IACvB,OAAO,EAAE,gBAAgB,EAAE,CAAC;IAC5B,OAAO,EAAE,uBAAuB,EAAE,CAAC;IACnC,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;IACzB,sBAAsB,CAAC,EAAE,MAAM,EAAE,CAAC;IAClC,iBAAiB,CAAC,EAAE,MAAM,EAAE,CAAC;CAC9B;AAiCD,wBAAgB,8BAA8B,CAC5C,QAAQ,CAAC,EAAE,uBAAuB,GACjC,uBAAuB,CAEzB;AA2ED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,sBAAsB,CACpC,aAAa,GAAE,SAAS,MAAM,EAAO,GACpC,MAAM,EAAE,CAyBV;AA0FD;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAsB,iCAAiC,CACrD,QAAQ,EAAE,MAAM,EAChB,SAAS,GAAE,OAAO,CAAC,4BAA4B,CAAM,GACpD,OAAO,CAAC,4BAA4B,CAAC,CAgGvC;AAgID,wBAAsB,oBAAoB,CACxC,QAAQ,EAAE,MAAM,EAChB,OAAO,GAAE,uBAA4B,EACrC,SAAS,GAAE,OAAO,CAAC,4BAA4B,CAAM,GACpD,OAAO,CAAC,gBAAgB,EAAE,CAAC,CAkO7B;AAED,wBAAgB,wBAAwB,CACtC,OAAO,EAAE,gBAAgB,EAAE,EAC3B,OAAO,EAAE,uBAAuB,EAAE,GACjC,mBAAmB,CAoBrB;AAgBD,wBAAgB,wBAAwB,CAAC,EACvC,IAAI,EACJ,OAAO,EACP,OAAO,EACP,aAAa,EACb,sBAAsB,EACtB,iBAAiB,GAClB,EAAE,4BAA4B,GAAG,uBAAuB,CAgCxD;AAED,wBAAgB,wBAAwB,CACtC,OAAO,EAAE,uBAAuB,EAChC,QAAQ,CAAC,EAAE,MAAM,GAChB,MAAM,CAmCR"}