@vibe-agent-toolkit/cli 0.2.0-rc.11 → 0.2.0-rc.12

package/dist/utils/command-refusal.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Which REFUSAL a thrown value is — the one place a command's catch learns
+ * whether the run failed on the invocation, the project, the environment, or
+ * a defect in VAT.
+ *
+ * 🔑 **Dispatch on a code, never on a message.** A user's mistake is thrown as
+ * a {@link CommandRefusalError} carrying its refusal code, or as a library
+ * `VatError` whose `code` is mapped below; an unreadable input is coded
+ * `INPUT_UNREADABLE` at the site that reads it. Everything else — an uncoded
+ * errno included — a `TypeError`, a resolver bug, an invariant a
+ * driver broke — is `INTERNAL_ERROR`, published with its stack. A blanket
+ * `catch` that relabels "anything thrown here" as the user's fault is exactly
+ * what this module exists to make unnecessary: it would publish VAT's own
+ * defects as usage mistakes.
+ *
+ * Kept apart from the document writer so a helper that only needs to REFUSE
+ * (`project-root-policy.ts`, `check-supervisor.ts`) does not load the
+ * published-shape registry to do it.
+ */
+import { type RefusalCode } from '@vibe-agent-toolkit/schema';
+import { VatError } from '@vibe-agent-toolkit/utils';
+/** A refusal a command raises on purpose, carrying WHICH refusal. */
+export declare class CommandRefusalError extends VatError {
+    readonly refusal: RefusalCode;
+    constructor(refusal: RefusalCode, message: string, options?: ErrorOptions);
+}
+/**
+ * Which refusal a thrown value is.
+ *
+ * Read by brand and `code`, not by `instanceof`, for the reason `isVatError`
+ * gives: a `dist` copy of the class never matches a `src` instance.
+ *
+ * @param error - What the command's catch received
+ * @returns A {@link CommandRefusalError}'s own code; for a classified filesystem fault
+ *   (`FsFaultError`, or a wrapper coded `FS_FAULT` that carries one), the schema table's row for its side, class and origin; a mapped
+ *   library code; otherwise `INTERNAL_ERROR`. ⛔ No errno walk: an uncoded errno is not
+ *   known to be about the user's INPUT — an output write, a temp directory, VAT's own
+ *   shipped asset — so it is a defect report, with its stack, until the site that made
+ *   the call classifies it.
+ */
+export declare function refusalCodeOf(error: unknown): RefusalCode;
+/**
+ * A refusal's published message: `message`, followed by the table row's remedy when
+ * `error` is a classified filesystem fault — whose own message says only what the OS
+ * refused, since the remedy is the table's to state. Never appended twice.
+ *
+ * @param message - The message the refusal already carries
+ * @param error - The thrown value it came from
+ */
+export declare function withFsFaultRemedy(message: string, error: unknown): string;
+/**
+ * The human sentence a thrown value carries: an `Error`'s message, or the
+ * value itself spelled out.
+ *
+ * @param error - Anything a catch received
+ */
+export declare function errorMessageOf(error: unknown): string;
+//# sourceMappingURL=command-refusal.d.ts.map

package/dist/utils/command-refusal.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"command-refusal.d.ts","sourceRoot":"","sources":["../../src/utils/command-refusal.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAqBH,OAAO,EAAkB,KAAK,WAAW,EAAE,MAAM,4BAA4B,CAAC;AAC9E,OAAO,EAiBL,QAAQ,EACT,MAAM,2BAA2B,CAAC;AAQnC,qEAAqE;AACrE,qBAAa,mBAAoB,SAAQ,QAAQ;IAC/C,QAAQ,CAAC,OAAO,EAAE,WAAW,CAAC;gBAElB,OAAO,EAAE,WAAW,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,YAAY;CAI1E;AAwED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,WAAW,CAQzD;AAeD;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,MAAM,CAKzE;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAErD"}

package/dist/utils/command-refusal.js

@@ -0,0 +1,170 @@
+/**
+ * Which REFUSAL a thrown value is — the one place a command's catch learns
+ * whether the run failed on the invocation, the project, the environment, or
+ * a defect in VAT.
+ *
+ * 🔑 **Dispatch on a code, never on a message.** A user's mistake is thrown as
+ * a {@link CommandRefusalError} carrying its refusal code, or as a library
+ * `VatError` whose `code` is mapped below; an unreadable input is coded
+ * `INPUT_UNREADABLE` at the site that reads it. Everything else — an uncoded
+ * errno included — a `TypeError`, a resolver bug, an invariant a
+ * driver broke — is `INTERNAL_ERROR`, published with its stack. A blanket
+ * `catch` that relabels "anything thrown here" as the user's fault is exactly
+ * what this module exists to make unnecessary: it would publish VAT's own
+ * defects as usage mistakes.
+ *
+ * Kept apart from the document writer so a helper that only needs to REFUSE
+ * (`project-root-policy.ts`, `check-supervisor.ts`) does not load the
+ * published-shape registry to do it.
+ */
+import { AGENT_MANIFEST_INVALID_CODE, AGENT_MANIFEST_NOT_FOUND_CODE, AGENT_MANIFEST_UNREADABLE_CODE } from '@vibe-agent-toolkit/agent-config';
+import { AGENT_PACKAGE_ROOT_MISSING_CODE, GIT_SUBPATH_INVALID_CODE, SKILL_TEST_REFUSAL_BY_ERROR_CODE, } from '@vibe-agent-toolkit/agent-skills';
+import { API_REQUEST_CODE, API_TRANSPORT_CODE, CLAUDE_USER_STATE_UNREADABLE_CODE, ORG_API_KEY_MISSING_CODE, PLUGIN_KEY_INVALID_CODE, } from '@vibe-agent-toolkit/claude-marketplace';
+import { CONFIG_LOAD_CODE, LINK_AUTH_CONFIG_CODE, OKF_UNKNOWN_BUNDLE_CODE, PROJECTION_STATEMENT_REFUSED_CODE, } from '@vibe-agent-toolkit/resources';
+import { fsFaultRefusal } from '@vibe-agent-toolkit/schema';
+import { ARCHIVE_ENTRY_UNREADABLE_CODE, ARCHIVE_REFUSED_CODE, ASSET_REFERENCE_UNREADABLE_CODE, COPY_LINK_ESCAPES_SOURCE_CODE, DIRECTORY_WALK_REVISITED_CODE, FS_FAULT_CODE, isFsFaultError, isVatError, RAG_DATABASE_UNREADABLE_CODE, RAG_INDEX_EMPTY_CODE, TREE_DEST_HOLDS_SOURCE_CODE, TREE_DEST_NOT_OWNED_CODE, TREE_DEST_OCCUPIED_CODE, TREE_ROLLBACK_INCOMPLETE_CODE, TREE_SOURCE_HOLDS_DEST_CODE, VatError, } from '@vibe-agent-toolkit/utils';
+import { GIT_SNAPSHOT_UNREADABLE_CODE } from '@vibe-agent-toolkit/utils/git';
+import { YAML_EDIT_INPUT_REFUSED_CODE } from '@vibe-agent-toolkit/utils/yaml';
+import { AGENT_NAME_ESCAPES_SCOPE_CODE, PLUGIN_SYMLINK_REFUSED_CODE } from './command-error-codes.js';
+const COMMAND_REFUSAL = 'COMMAND_REFUSAL';
+/** A refusal a command raises on purpose, carrying WHICH refusal. */
+export class CommandRefusalError extends VatError {
+    refusal;
+    constructor(refusal, message, options) {
+        super(COMMAND_REFUSAL, message, options);
+        this.refusal = refusal;
+    }
+}
+/** Library errors whose `code` already says which refusal they are. */
+const REFUSAL_BY_ERROR_CODE = {
+    // A config file that exists and does not parse or validate (resources' parser and the CLI loader).
+    [CONFIG_LOAD_CODE]: 'CONFIG_INVALID',
+    // A bundle argument the project does not declare under `okf.bundles`.
+    [OKF_UNKNOWN_BUNDLE_CODE]: 'USAGE_INVALID',
+    // An archive VAT will not read or extract (`ArchiveRefusedError`): not an archive, past a limit, or holding
+    // an entry the one entry policy refuses — a link, a device, a name outside the archive, two entries one name.
+    [ARCHIVE_REFUSED_CODE]: 'INPUT_UNREADABLE',
+    // One entry of an opened archive that does not inflate or hold what it declares (`ArchiveEntryReadError`).
+    [ARCHIVE_ENTRY_UNREADABLE_CODE]: 'INPUT_UNREADABLE',
+    // A symlink inside a tree being copied that points outside it (`CopyLinkEscapesSourceError`): the input's link.
+    [COPY_LINK_ESCAPES_SOURCE_CODE]: 'INPUT_UNREADABLE',
+    // An entry of a tree being copied that the OS would not list, stat or read (or a dangling link): the input's.
+    // A bare specifier whose package is installed but unreadable (a malformed package.json): the input, not "missing".
+    [ASSET_REFERENCE_UNREADABLE_CODE]: 'INPUT_UNREADABLE',
+    // A symlink that leads a following walk back into a directory it already entered: the input's loop.
+    [DIRECTORY_WALK_REVISITED_CODE]: 'INPUT_UNREADABLE',
+    // A git URL's `#ref:subpath` naming a path the clone does not hold, or one escaping it.
+    [GIT_SUBPATH_INVALID_CODE]: 'USAGE_INVALID',
+    // A `resources.linkAuth` provider that does not compile (`LinkAuthConfigError`): the config's mistake.
+    [LINK_AUTH_CONFIG_CODE]: 'CONFIG_INVALID',
+    // An agent path or name that names no manifest — the argument is the mistake.
+    [AGENT_MANIFEST_NOT_FOUND_CODE]: 'USAGE_INVALID',
+    // An agent manifest the OS refuses, or whose content is not YAML.
+    [AGENT_MANIFEST_UNREADABLE_CODE]: 'INPUT_UNREADABLE',
+    // An agent manifest `loadAgentManifest` read and the schema rejects: the adopter's config.
+    [AGENT_MANIFEST_INVALID_CODE]: 'CONFIG_INVALID',
+    // `vat agent install|uninstall` with a name that is not one entry under the scope root.
+    [AGENT_NAME_ESCAPES_SCOPE_CODE]: 'USAGE_INVALID',
+    // `vat agent build` with no --output and no package.json around the agent to put the default in.
+    [AGENT_PACKAGE_ROOT_MISSING_CODE]: 'USAGE_INVALID',
+    // A SQL statement the projection store refused — the statement the operator passed is wrong.
+    [PROJECTION_STATEMENT_REFUSED_CODE]: 'USAGE_INVALID',
+    // A Claude Code registry or settings file whose content VAT cannot use: not JSON, the wrong shape.
+    [CLAUDE_USER_STATE_UNREADABLE_CODE]: 'INPUT_UNREADABLE',
+    // A plugin key argument that is not `<plugin>@<marketplace>`.
+    [PLUGIN_KEY_INVALID_CODE]: 'USAGE_INVALID',
+    // A plugin source holding a symlink no bundle can ship (`PluginSymlinkRefusedError`): the input, not VAT.
+    [PLUGIN_SYMLINK_REFUSED_CODE]: 'INPUT_UNREADABLE',
+    // An adopter's YAML (their config) that the surgical editor cannot take the edit into: not YAML, or the wrong shape at the path.
+    [YAML_EDIT_INPUT_REFUSED_CODE]: 'CONFIG_INVALID',
+    // A git snapshot refused because a file in the repository is unreadable: the input, named, not VAT.
+    [GIT_SNAPSHOT_UNREADABLE_CODE]: 'INPUT_UNREADABLE',
+    // An org command run without the key its endpoint authenticates with: nothing was sent.
+    [ORG_API_KEY_MISSING_CODE]: 'USAGE_INVALID',
+    // The Anthropic API answered with a non-success status (`ApiRequestError`)…
+    [API_REQUEST_CODE]: 'EXTERNAL_API_FAILED',
+    // …or never answered at all (`ApiTransportError`).
+    [API_TRANSPORT_CODE]: 'EXTERNAL_API_FAILED',
+    // `vat rag query` over an index with no chunk table (rag-lancedb's query): nothing to search.
+    // The constant lives in utils so this map need not load the optional backend that throws it.
+    [RAG_INDEX_EMPTY_CODE]: 'INPUT_UNREADABLE',
+    // A RAG database LanceDB cannot open or read (a table's manifest or data files are damaged).
+    [RAG_DATABASE_UNREADABLE_CODE]: 'INPUT_UNREADABLE',
+    // The tree-change planner's preflight, before anything is written. Something in the way of a destination
+    // the user named — anything at a `must-be-free` one, or what a `vat-made` one's recogniser disowns (an
+    // explicit `-o` holding what VAT did not produce) — is the invocation's to fix: `--force`, or another path.
+    // Never inferred from an errno: an `EEXIST` at the moment of a write is the table's RUN_INCOMPLETE.
+    [TREE_DEST_OCCUPIED_CODE]: 'USAGE_INVALID',
+    [TREE_DEST_NOT_OWNED_CODE]: 'USAGE_INVALID',
+    // A copy whose source and destination hold one another: the paths the user passed are the mistake.
+    [TREE_SOURCE_HOLDS_DEST_CODE]: 'USAGE_INVALID',
+    [TREE_DEST_HOLDS_SOURCE_CODE]: 'USAGE_INVALID',
+    // A change failed and could not be fully undone: the user's previous tree is under a parked name, named.
+    [TREE_ROLLBACK_INCOMPLETE_CODE]: 'RUN_INCOMPLETE',
+    // `vat skill test run`: why the harness could not run, decided beside its error classes.
+    ...SKILL_TEST_REFUSAL_BY_ERROR_CODE,
+};
+/**
+ * Which refusal a thrown value is.
+ *
+ * Read by brand and `code`, not by `instanceof`, for the reason `isVatError`
+ * gives: a `dist` copy of the class never matches a `src` instance.
+ *
+ * @param error - What the command's catch received
+ * @returns A {@link CommandRefusalError}'s own code; for a classified filesystem fault
+ *   (`FsFaultError`, or a wrapper coded `FS_FAULT` that carries one), the schema table's row for its side, class and origin; a mapped
+ *   library code; otherwise `INTERNAL_ERROR`. ⛔ No errno walk: an uncoded errno is not
+ *   known to be about the user's INPUT — an output write, a temp directory, VAT's own
+ *   shipped asset — so it is a defect report, with its stack, until the site that made
+ *   the call classifies it.
+ */
+export function refusalCodeOf(error) {
+    if (isVatError(error, COMMAND_REFUSAL))
+        return error.refusal;
+    const fault = classifiedFaultOf(error);
+    if (fault !== undefined)
+        return fsFaultRefusal(fault.side, fault.faultClass, fault.origin).refusal;
+    if (isVatError(error) && Object.hasOwn(REFUSAL_BY_ERROR_CODE, error.code)) {
+        return REFUSAL_BY_ERROR_CODE[error.code] ?? 'INTERNAL_ERROR';
+    }
+    return 'INTERNAL_ERROR';
+}
+/**
+ * The classified fault `error` stands for: itself, or — for a wrapper that kept the
+ * fault's own `FS_FAULT` code (`ConfigLoadError`, which a caller may tolerate by
+ * type) — the fault it carries as its `cause`. A wrapper never re-codes a fault, so
+ * its refusal is the fault's.
+ */
+function classifiedFaultOf(error) {
+    if (isFsFaultError(error))
+        return error;
+    if (!isVatError(error, FS_FAULT_CODE))
+        return undefined;
+    const { cause } = error;
+    return isFsFaultError(cause) ? cause : undefined;
+}
+/**
+ * A refusal's published message: `message`, followed by the table row's remedy when
+ * `error` is a classified filesystem fault — whose own message says only what the OS
+ * refused, since the remedy is the table's to state. Never appended twice.
+ *
+ * @param message - The message the refusal already carries
+ * @param error - The thrown value it came from
+ */
+export function withFsFaultRemedy(message, error) {
+    const fault = classifiedFaultOf(error);
+    if (fault === undefined)
+        return message;
+    const { remedy } = fsFaultRefusal(fault.side, fault.faultClass, fault.origin);
+    return message.includes(remedy) ? message : `${message}. ${remedy}`;
+}
+/**
+ * The human sentence a thrown value carries: an `Error`'s message, or the
+ * value itself spelled out.
+ *
+ * @param error - Anything a catch received
+ */
+export function errorMessageOf(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+//# sourceMappingURL=command-refusal.js.map

package/dist/utils/command-refusal.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"command-refusal.js","sourceRoot":"","sources":["../../src/utils/command-refusal.ts"],"names":[],"mappings":"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"}

package/dist/utils/commander-ending.d.ts

@@ -0,0 +1,40 @@
+/**
+ * The exit code a commander ending takes — the one ending of a `vat` run that
+ * happens before any verb's writer exists.
+ */
+import { type ExitCodeValue } from '@vibe-agent-toolkit/schema';
+/**
+ * Map a commander termination to the exit code VAT's contract promises.
+ *
+ * A USAGE mistake — a flag this program does not declare, a verb it does not
+ * know, a missing or invalid argument — ends on `ExitCode.ERROR`, and the
+ * reason is not style. Commander's default for a usage mistake is
+ * `process.exit(1)`, so `vat resources check --json` (the option is
+ * `--format json`) exited **1** — which, read against the contract the command
+ * itself prints, asserts that at least one check was violated. Nothing had
+ * run. A CI wrapper spelled `if [ $? -ne 0 ]; then report_findings` therefore
+ * reported findings that were never computed. The same hole swallowed a
+ * mistyped verb (`vat resources chekc`) and every unknown option on every
+ * command.
+ *
+ * Commander reports BOTH successful and failing terminations through the same
+ * `CommanderError`: `--help` and `--version` carry `exitCode` 0, while an
+ * unknown option, an unknown command and `help({ error: true })` carry non-zero.
+ * Anything non-zero is a usage mistake by construction — commander raises these
+ * only while parsing, before any action runs — so it maps to `ERROR`.
+ *
+ * ⚠️ **Help and `--version` are NOT usage mistakes.** They terminate through
+ * the same `_exit` path with code 0 and must stay `OK`; only a non-zero
+ * commander ending is remapped.
+ *
+ * 🪤 Do NOT switch on `error.code` (`commander.unknownOption`, `commander.help`,
+ * …). The unknown-COMMAND path arrives as `commander.help` with exitCode 1,
+ * because the `command:*` handler renders help with `{ error: true }` — so the
+ * code string says "help" for a case that is emphatically not one. The exit
+ * code commander already computed is the honest discriminator; the string is not.
+ *
+ * @param commanderExitCode - The `exitCode` commander put on its CommanderError
+ * @returns `OK` for a successful ending, `ERROR` otherwise
+ */
+export declare function exitCodeForCommanderEnding(commanderExitCode: number): ExitCodeValue;
+//# sourceMappingURL=commander-ending.d.ts.map

package/dist/utils/commander-ending.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"commander-ending.d.ts","sourceRoot":"","sources":["../../src/utils/commander-ending.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAY,KAAK,aAAa,EAAE,MAAM,4BAA4B,CAAC;AAE1E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,wBAAgB,0BAA0B,CAAC,iBAAiB,EAAE,MAAM,GAAG,aAAa,CAEnF"}

package/dist/utils/commander-ending.js

@@ -0,0 +1,42 @@
+/**
+ * The exit code a commander ending takes — the one ending of a `vat` run that
+ * happens before any verb's writer exists.
+ */
+import { ExitCode } from '@vibe-agent-toolkit/schema';
+/**
+ * Map a commander termination to the exit code VAT's contract promises.
+ *
+ * A USAGE mistake — a flag this program does not declare, a verb it does not
+ * know, a missing or invalid argument — ends on `ExitCode.ERROR`, and the
+ * reason is not style. Commander's default for a usage mistake is
+ * `process.exit(1)`, so `vat resources check --json` (the option is
+ * `--format json`) exited **1** — which, read against the contract the command
+ * itself prints, asserts that at least one check was violated. Nothing had
+ * run. A CI wrapper spelled `if [ $? -ne 0 ]; then report_findings` therefore
+ * reported findings that were never computed. The same hole swallowed a
+ * mistyped verb (`vat resources chekc`) and every unknown option on every
+ * command.
+ *
+ * Commander reports BOTH successful and failing terminations through the same
+ * `CommanderError`: `--help` and `--version` carry `exitCode` 0, while an
+ * unknown option, an unknown command and `help({ error: true })` carry non-zero.
+ * Anything non-zero is a usage mistake by construction — commander raises these
+ * only while parsing, before any action runs — so it maps to `ERROR`.
+ *
+ * ⚠️ **Help and `--version` are NOT usage mistakes.** They terminate through
+ * the same `_exit` path with code 0 and must stay `OK`; only a non-zero
+ * commander ending is remapped.
+ *
+ * 🪤 Do NOT switch on `error.code` (`commander.unknownOption`, `commander.help`,
+ * …). The unknown-COMMAND path arrives as `commander.help` with exitCode 1,
+ * because the `command:*` handler renders help with `{ error: true }` — so the
+ * code string says "help" for a case that is emphatically not one. The exit
+ * code commander already computed is the honest discriminator; the string is not.
+ *
+ * @param commanderExitCode - The `exitCode` commander put on its CommanderError
+ * @returns `OK` for a successful ending, `ERROR` otherwise
+ */
+export function exitCodeForCommanderEnding(commanderExitCode) {
+    return commanderExitCode === 0 ? ExitCode.OK : ExitCode.ERROR;
+}
+//# sourceMappingURL=commander-ending.js.map

package/dist/utils/commander-ending.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"commander-ending.js","sourceRoot":"","sources":["../../src/utils/commander-ending.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,QAAQ,EAAsB,MAAM,4BAA4B,CAAC;AAE1E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,MAAM,UAAU,0BAA0B,CAAC,iBAAyB;IAClE,OAAO,iBAAiB,KAAK,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC;AAChE,CAAC"}

package/dist/utils/config-loader.d.ts

@@ -5,24 +5,29 @@
  * - VAT_TEST_CONFIG: Override config file path for testing (absolute path)
  */
 import { type ProjectConfig } from '@vibe-agent-toolkit/resources';
-import { VatError } from '@vibe-agent-toolkit/utils';
+import { type FsSide, VatError } from '@vibe-agent-toolkit/utils';
 /**
- * A `vibe-agent-toolkit.config.yaml` exists but failed to parse or validate.
+ * A `vibe-agent-toolkit.config.yaml` exists but could not be read, parsed or validated.
  *
  * Distinct from "no config found" (which surfaces as `undefined`): a *broken*
  * config is a hard error the user must fix, not something to silently treat as
  * absent. Commands that resolve a skill through a config (`vat skill review`,
  * `vat skill test`) should surface this; a bulk linter (`vat audit`) may catch
- * it and fall back to config-free validation.
+ * it and fall back to config-free validation. It carries its cause's code —
+ * `CONFIG_LOAD`, or `FS_FAULT` with the classified fault as its `cause` — so the
+ * refusal it becomes is decided by what failed, not by where it was caught.
  */
 export declare class ConfigLoadError extends VatError {
     readonly projectRoot: string;
-    constructor(projectRoot: string, cause: unknown);
+    constructor(projectRoot: string, cause: VatError);
 }
 /**
  * Load and validate project configuration
  *
  * @param projectRoot - Project root directory
+ * @param projectSide - The calling verb's side for a path in the project it does not declare an input:
+ *   `destination` for a verb that writes into the project (`build`), `source` for one that only reads it.
+ *   A refusal on the way to the config, or of the listing that confirms it absent, lands there.
  * @returns Validated configuration or undefined if not found
  * @throws Error if config file exists but is invalid
  *
@@ -33,14 +38,14 @@ export declare class ConfigLoadError extends VatError {
  * @example
  * ```typescript
  * // Normal usage
- * const config = loadConfig('/path/to/project');
+ * const config = loadConfig('/path/to/project', 'source');
  *
  * // Test usage with override
  * process.env.VAT_TEST_CONFIG = '/path/to/test/fixtures/config.yaml';
- * const config = loadConfig('/any/path'); // Uses override path
+ * const config = loadConfig('/any/path', 'source'); // Uses override path
  * ```
  */
-export declare function loadConfig(projectRoot: string): ProjectConfig | undefined;
+export declare function loadConfig(projectRoot: string, projectSide: FsSide): ProjectConfig | undefined;
 /**
  * Get the directory containing a config file path.
  */
@@ -67,5 +72,5 @@ export declare function resetLoadedConfigCache(): void;
  * Callers that intentionally tolerate a broken config (e.g. `vat audit`, a bulk
  * linter that should still validate the skill itself) catch `ConfigLoadError`.
  */
-export declare function loadConfigCached(projectRoot: string): ProjectConfig | undefined;
+export declare function loadConfigCached(projectRoot: string, projectSide: FsSide): ProjectConfig | undefined;
 //# sourceMappingURL=config-loader.d.ts.map

package/dist/utils/config-loader.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"config-loader.d.ts","sourceRoot":"","sources":["../../src/utils/config-loader.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAKH,OAAO,EAAuD,KAAK,aAAa,EAAE,MAAM,+BAA+B,CAAC;AACxH,OAAO,EAAY,QAAQ,EAAE,MAAM,2BAA2B,CAAC;AAY/D;;;;;;;;GAQG;AACH,qBAAa,eAAgB,SAAQ,QAAQ;IAC3C,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;gBACjB,WAAW,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO;CAKhD;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,UAAU,CAAC,WAAW,EAAE,MAAM,GAAG,aAAa,GAAG,SAAS,CAgDzE;AAED;;GAEG;AACH,wBAAgB,YAAY,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,CAEvD;AAqBD;;;;;GAKG;AACH,wBAAgB,sBAAsB,IAAI,IAAI,CAM7C;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,gBAAgB,CAAC,WAAW,EAAE,MAAM,GAAG,aAAa,GAAG,SAAS,CAgB/E"}
+{"version":3,"file":"config-loader.d.ts","sourceRoot":"","sources":["../../src/utils/config-loader.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,OAAO,EAKL,KAAK,aAAa,EACnB,MAAM,+BAA+B,CAAC;AACvC,OAAO,EAAmB,KAAK,MAAM,EAA6I,QAAQ,EAAE,MAAM,2BAA2B,CAAC;AAiB9N;;;;;;;;;;GAUG;AACH,qBAAa,eAAgB,SAAQ,QAAQ;IAC3C,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;gBACjB,WAAW,EAAE,MAAM,EAAE,KAAK,EAAE,QAAQ;CAIjD;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,UAAU,CAAC,WAAW,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,aAAa,GAAG,SAAS,CAsD9F;AAuBD;;GAEG;AACH,wBAAgB,YAAY,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,CAEvD;AAqBD;;;;;GAKG;AACH,wBAAgB,sBAAsB,IAAI,IAAI,CAM7C;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,gBAAgB,CAAC,WAAW,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,aAAa,GAAG,SAAS,CAmBpG"}

package/dist/utils/config-loader.js

@@ -4,40 +4,46 @@
  * Environment Variables:
  * - VAT_TEST_CONFIG: Override config file path for testing (absolute path)
  */
-import { readFileSync, existsSync } from 'node:fs';
 import { dirname } from 'node:path';
-import { parseConfigAllowingUnknownKeys, ProjectConfigSchema } from '@vibe-agent-toolkit/resources';
-import { safePath, VatError } from '@vibe-agent-toolkit/utils';
+import { CONFIG_LOAD_CODE, parseConfigAllowingUnknownKeys, ProjectConfigSchema, readConfigTextSync, } from '@vibe-agent-toolkit/resources';
+import { classifyFsFault, isFsFaultError, isUnresolvableLinkError, isVatError, refusedPathOf, requireConfirmedAbsent, requireFollowedStatSync, safePath, sideWithin, VatError } from '@vibe-agent-toolkit/utils';
 import * as yaml from 'yaml';
+import { errorMessageOf } from './command-refusal.js';
+import { noticeToOperator, resetUnscopedNoticeLedger } from './operator-notices.js';
 const CONFIG_FILENAME = 'vibe-agent-toolkit.config.yaml';
 /**
- * Config paths already warned about for unknown keys, so one config governing
- * many skills produces one line rather than one per skill. Cleared with the
- * config cache, which is what a test isolating a fixture resets.
+ * Whether `error` is one of the two config failures {@link ConfigLoadError} stands
+ * for: `CONFIG_LOAD` (does not parse or validate), or the OS refusing the read — a
+ * classified `source` fault whose origin is the config.
  */
-const warnedConfigPaths = new Set();
+function isConfigFailure(error) {
+    return isVatError(error, CONFIG_LOAD_CODE) || (isFsFaultError(error) && error.origin === 'config');
+}
 /**
- * A `vibe-agent-toolkit.config.yaml` exists but failed to parse or validate.
+ * A `vibe-agent-toolkit.config.yaml` exists but could not be read, parsed or validated.
  *
  * Distinct from "no config found" (which surfaces as `undefined`): a *broken*
  * config is a hard error the user must fix, not something to silently treat as
  * absent. Commands that resolve a skill through a config (`vat skill review`,
  * `vat skill test`) should surface this; a bulk linter (`vat audit`) may catch
- * it and fall back to config-free validation.
+ * it and fall back to config-free validation. It carries its cause's code —
+ * `CONFIG_LOAD`, or `FS_FAULT` with the classified fault as its `cause` — so the
+ * refusal it becomes is decided by what failed, not by where it was caught.
  */
 export class ConfigLoadError extends VatError {
     projectRoot;
     constructor(projectRoot, cause) {
-        super('CONFIG_LOAD', cause instanceof Error ? cause.message : String(cause));
+        super(cause.code, cause.message, { cause });
         this.projectRoot = projectRoot;
-        if (cause instanceof Error)
-            this.cause = cause;
     }
 }
 /**
  * Load and validate project configuration
  *
  * @param projectRoot - Project root directory
+ * @param projectSide - The calling verb's side for a path in the project it does not declare an input:
+ *   `destination` for a verb that writes into the project (`build`), `source` for one that only reads it.
+ *   A refusal on the way to the config, or of the listing that confirms it absent, lands there.
  * @returns Validated configuration or undefined if not found
  * @throws Error if config file exists but is invalid
  *
@@ -48,21 +54,25 @@ export class ConfigLoadError extends VatError {
  * @example
  * ```typescript
  * // Normal usage
- * const config = loadConfig('/path/to/project');
+ * const config = loadConfig('/path/to/project', 'source');
  *
  * // Test usage with override
  * process.env.VAT_TEST_CONFIG = '/path/to/test/fixtures/config.yaml';
- * const config = loadConfig('/any/path'); // Uses override path
+ * const config = loadConfig('/any/path', 'source'); // Uses override path
  * ```
  */
-export function loadConfig(projectRoot) {
+export function loadConfig(projectRoot, projectSide) {
     // Override for testing: VAT_TEST_CONFIG provides explicit config path
-    const configPath = process.env['VAT_TEST_CONFIG'] ?? safePath.join(projectRoot, CONFIG_FILENAME);
-    if (!existsSync(configPath)) {
+    const override = process.env['VAT_TEST_CONFIG'];
+    const configPath = override ?? safePath.join(projectRoot, CONFIG_FILENAME);
+    // The override is the operator's own path (its own `within`); the config sits beneath the project root.
+    // A probe the OS refuses is a fault, never "no config here".
+    const within = override ?? projectRoot;
+    if (!configPresent(configPath, within, projectSide)) {
         return undefined;
     }
     try {
-        const content = readFileSync(configPath, 'utf-8');
+        const content = readConfigTextSync(configPath);
         const parsed = yaml.parse(content);
         // Validate with canonical schema from resources package.
         //
@@ -79,25 +89,51 @@ export function loadConfig(projectRoot) {
         // was in. Warned once per config path, because `loadConfigCached` will
         // otherwise re-warn for every skill under one project.
         return parseConfigAllowingUnknownKeys(ProjectConfigSchema, parsed, (message) => {
-            if (warnedConfigPaths.has(configPath))
-                return;
-            warnedConfigPaths.add(configPath);
-            process.stderr.write(`${message}\n`);
+            // Through the one notice route, once per config path per notice scope: one config
+            // governing many skills is one line, not one per skill, and a supervised child's
+            // invoking process loaded this same config and printed this same line already.
+            noticeToOperator('config', message, configPath);
         }, { configPath });
     }
     catch (error) {
-        if (error instanceof Error) {
-            // `cause` is load-bearing, not decoration: callers decide whether to
-            // degrade or abort by asking `isFilesystemAccessError`, which reads the
-            // errno off the error. Re-wrapping without it produced a plain Error with
-            // no `code`, so an unreadable config read as "a bug in VAT" and aborted the
-            // whole run — the exact failure `vat audit`'s guard exists to prevent,
-            // reintroduced by a message-formatting layer.
-            throw new Error(`Failed to load config: ${error.message}`, { cause: error });
-        }
+        // `cause` is load-bearing, not decoration: callers decide whether to
+        // degrade or abort by asking `fsFaultOf`, which reads the
+        // errno off the cause chain. `CONFIG_LOAD` (does not parse or validate)
+        // keeps its code; a read the OS refused is already a classified fault and
+        // propagates as itself, never re-coded; anything else — a VAT defect —
+        // stays uncoded and surfaces as one.
+        if (isFsFaultError(error))
+            throw error;
+        const message = `Failed to load config: ${errorMessageOf(error)}`;
+        if (isVatError(error, CONFIG_LOAD_CODE))
+            throw new VatError(CONFIG_LOAD_CODE, message, { cause: error });
+        if (error instanceof yaml.YAMLError)
+            throw new VatError(CONFIG_LOAD_CODE, message, { cause: error });
         throw error;
     }
 }
+/**
+ * Whether the config resolves to something, its links read beneath `within` first. A probe the OS
+ * refuses (or a chain naming a network path) is the config's source fault, classified as its read
+ * is (origin `config`), never "no config here". "Absent" is believed only once the directory's
+ * listing agrees: a wrong "no config" silently runs the verb with none, which does less. The config
+ * is the input; every other path refused on the way to it, or listed to confirm it absent, is on the
+ * verb's own side for the project (`projectSide`).
+ */
+function configPresent(configPath, within, projectSide) {
+    const ctx = { origin: 'config', action: 'find the project config', path: configPath };
+    const sideOf = sideWithin(configPath, 'source', projectSide);
+    try {
+        requireFollowedStatSync(configPath, within);
+        return true;
+    }
+    catch (error) {
+        if (!isUnresolvableLinkError(error))
+            throw classifyFsFault(error, { ...ctx, side: sideOf(refusedPathOf(error, configPath)) });
+        requireConfirmedAbsent(configPath, error, ctx, { follows: true, sideOf });
+        return false;
+    }
+}
 /**
  * Get the directory containing a config file path.
  */
@@ -116,9 +152,9 @@ export function getConfigDir(configPath) {
  */
 const loadedConfigCache = new Map();
 /**
- * Companion cache for {@link loadConfigCached}: a broken config's
- * {@link ConfigLoadError}, keyed by `projectRoot`, so a broken config re-throws
- * the same error on every skill in a scan without re-parsing.
+ * Companion cache for {@link loadConfigCached}: what a failed load threw, keyed
+ * by `projectRoot` and the verb's `projectSide` (a refusal's side is the verb's), so a broken config re-throws the same error on every skill
+ * in a scan without re-parsing.
  */
 const loadErrorCache = new Map();
 /**
@@ -130,9 +166,9 @@ const loadErrorCache = new Map();
 export function resetLoadedConfigCache() {
     loadedConfigCache.clear();
     loadErrorCache.clear();
-    // The warn-once ledger is part of this cache's state: a test that resets the
-    // caches and re-loads the same fixture expects to see the warning again.
-    warnedConfigPaths.clear();
+    // The warn-once ledger outside every notice scope is part of this cache's state: a test that
+    // resets the caches and re-loads the same fixture expects to see the warning again.
+    resetUnscopedNoticeLedger();
 }
 /**
  * Cached variant of {@link loadConfig} keyed by `projectRoot`.
@@ -149,24 +185,27 @@ export function resetLoadedConfigCache() {
  * Callers that intentionally tolerate a broken config (e.g. `vat audit`, a bulk
  * linter that should still validate the skill itself) catch `ConfigLoadError`.
  */
-export function loadConfigCached(projectRoot) {
-    const cachedError = loadErrorCache.get(projectRoot);
+export function loadConfigCached(projectRoot, projectSide) {
+    const errorKey = `${projectSide}\0${projectRoot}`;
+    const cachedError = loadErrorCache.get(errorKey);
     if (cachedError !== undefined)
         throw cachedError;
     const cached = loadedConfigCache.get(projectRoot);
     if (cached !== undefined)
         return cached ?? undefined;
     try {
-        const config = loadConfig(projectRoot);
+        const config = loadConfig(projectRoot, projectSide);
         loadedConfigCache.set(projectRoot, config ?? null);
         return config;
     }
     catch (err) {
-        // loadConfig returns undefined when the file is ABSENT and only throws when
-        // it EXISTS but is broken — so reaching here means a genuinely broken config.
-        const configErr = err instanceof ConfigLoadError ? err : new ConfigLoadError(projectRoot, err);
-        loadErrorCache.set(projectRoot, configErr);
-        throw configErr;
+        // 🔑 Only a CODED config failure becomes a `ConfigLoadError` — the one a
+        // caller like `vat audit` may tolerate. Anything else (a `TypeError`, an
+        // invariant) is cached and rethrown UNCHANGED, so it surfaces as the defect
+        // it is instead of being relabelled a broken config by its throw site.
+        const thrown = isConfigFailure(err) ? new ConfigLoadError(projectRoot, err) : err;
+        loadErrorCache.set(errorKey, thrown);
+        throw thrown;
     }
 }
 //# sourceMappingURL=config-loader.js.map