@sayknow-cli/utils 0.7.10 → 0.7.12

package/dist/types/broken-pipe.d.ts

@@ -10,9 +10,10 @@ export declare function isKnownSinkPeerClosedError(error: unknown): boolean;
  */
 export declare function isBrokenPipeError(error: unknown): boolean;
 /**
- * A classifier for process-level stdout `EPIPE` errors. Its direct-write
- * evidence is private to each factory instance, so only the owner that
- * intercepted `process.stdout.write` can mark an error for this classifier.
+ * A classifier for process-level stdout peer-closed errors (`EPIPE`, `EIO`,
+ * `EBADF`). Its direct-write evidence is private to each factory instance, so
+ * only the owner that intercepted `process.stdout.write` can mark an error
+ * for this classifier.
  */
 export interface ProcessStdoutEpipeClassifier {
     markDirectProcessStdoutWriteError(error: unknown): void;

package/dist/types/canonical-log-dir.d.ts

@@ -0,0 +1,20 @@
+interface ProjectEnvSnapshotLike {
+    values: Record<string, string>;
+    dynamic: Set<string>;
+}
+interface CanonicalLogDirInput {
+    home: string;
+    env: Record<string, string | undefined>;
+    projectEnv: ProjectEnvSnapshotLike;
+    xdgEligible: boolean;
+    pathExists?: (target: string) => boolean;
+}
+/**
+ * Resolve the canonical user log directory without mutating the environment.
+ *
+ * The caller supplies filesystem existence checks so this leaf stays free of
+ * filesystem and resolver side effects. Both the production directory resolver
+ * and the test preload use this exact path selection logic.
+ */
+export declare function resolveCanonicalLogsDir(input: CanonicalLogDirInput): string;
+export {};

package/dist/types/cli-metadata.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Pure CLI metadata leaf.
+ *
+ * The actual `skc` entry (`packages/coding-agent/src/cli.ts`) must stay inert on
+ * import: no directory resolution, logger construction, NSS lookup, native load
+ * or environment probing may run before argv routing. `dirs.ts` performs all of
+ * those at module scope, so the handful of constants the entry really needs live
+ * here and `dirs.ts` re-exports them for its existing callers.
+ *
+ * Only build-time package metadata may be imported here.
+ */
+/** App name (e.g. "skc") */
+export declare const APP_NAME: string;
+/** Version (e.g. "1.0.0") */
+export declare const VERSION: string;
+/** Minimum Bun version */
+export declare const MIN_BUN_VERSION: string;
+/**
+ * Build the diagnostic shown when the Bun runtime executing `skc` is older
+ * than {@link MIN_BUN_VERSION}. This is the most common Windows native-install
+ * failure (issue #525): `bun install -g sayknow-cli` probes a recent Bun while
+ * the `skc` launcher resolves an older Bun still on PATH. The message names the
+ * exact detected runtime path and gives a platform-specific upgrade + PATH fix
+ * instead of a bare `bun upgrade`.
+ *
+ * Pure and platform-parameterized so it can be unit-tested cross-platform.
+ */
+export declare function formatBunRuntimeError(opts: {
+    currentVersion: string;
+    minVersion: string;
+    execPath?: string;
+    platform?: NodeJS.Platform;
+}): string;

package/dist/types/cli.d.ts

@@ -6,6 +6,8 @@ export interface FlagDescriptor<K extends "string" | "boolean" | "integer" = "st
     multiple?: boolean;
     options?: readonly string[];
     required?: boolean;
+    /** The string value may be omitted; parsers decide whether to consume it. */
+    optionalValue?: boolean;
 }
 export interface ArgDescriptor {
     kind: "string";
@@ -21,6 +23,8 @@ interface FlagInput {
     multiple?: boolean;
     options?: readonly string[];
     required?: boolean;
+    /** The string value may be omitted; parsers decide whether to consume it. */
+    optionalValue?: boolean;
 }
 interface ArgInput {
     description?: string;
@@ -107,6 +111,14 @@ export interface CommandEntry {
     name: string;
     load: () => Promise<CommandCtor>;
     aliases?: string[];
+    /** Owns parsing, help, loading and failures for this family when supplied. */
+    dispatch?: (argv: string[], context: CommandEntryContext) => Promise<void>;
+}
+export interface CommandEntryContext {
+    bin: string;
+    version: string;
+    /** Canonical registered entry name, including when invoked through an alias. */
+    command: string;
 }
 export interface RunOptions {
     bin: string;

package/dist/types/crash-fingerprint.d.ts

@@ -0,0 +1,82 @@
+/** Algorithm version recorded beside every emitted fingerprint. */
+export declare const CRASH_FINGERPRINT_VERSION = 1;
+/** Hex length of a published fingerprint (128 bits). */
+export declare const CRASH_FINGERPRINT_HEX_LENGTH = 32;
+/** Matches exactly a published fingerprint. */
+export declare const CRASH_FINGERPRINT_PATTERN: RegExp;
+/** Marker used for the machine-readable identity line of each crash record. */
+export declare const CRASH_RECORD_MARKER = "skc-crash-record.v1";
+/** Marker embedded in an external issue body, outside crash-derived blocks. */
+export declare const CRASH_ISSUE_MARKER_PREFIX = "skc-crash-fp.v1:";
+/** Literal frame used when a stack carries no in-app frame at all. */
+export declare const NO_APP_FRAME = "<no-app-frame>";
+export interface CrashFingerprintInput {
+    readonly name: string;
+    readonly message: string;
+    readonly stack: string;
+}
+export interface CrashFingerprint {
+    /** 32 lowercase hex characters. */
+    readonly fingerprint: string;
+    /** Algorithm version (`fpv`). */
+    readonly version: number;
+    readonly errorName: string;
+    /** Normalized, placeholder-substituted message class (safe to display). */
+    readonly messageClass: string;
+    /** Normalized in-app frames that participated in the digest. */
+    readonly frames: readonly string[];
+}
+export interface CrashFingerprintOptions {
+    /** Install root used to relativize in-app frames. Defaults to the SKC install root. */
+    readonly installRoot?: string;
+    /** Home directory used for `<home>` substitution. Defaults to `os.homedir()`. */
+    readonly homeDir?: string;
+}
+/**
+ * Replace absolute path-like tokens with `<home>` / `<path>`.
+ *
+ * Semantically meaningful codes are untouched: this rule only fires on tokens
+ * that are recognizably absolute filesystem paths.
+ */
+export declare function replaceAbsolutePaths(text: string, homeDir?: string): string;
+/**
+ * Typed message normalization.
+ *
+ * Deliberately *not* "strip all digits": HTTP statuses, exit codes and errno
+ * names are the difference between distinct crash classes, so runs of three or
+ * fewer digits and alphabetic error codes survive verbatim (`404` stays
+ * distinct from `500`). Only high-entropy identifiers are collapsed.
+ */
+export declare function normalizeCrashMessage(message: string, options?: CrashFingerprintOptions): string;
+/**
+ * Normalized in-app frames, newest first, capped at three.
+ *
+ * A frame is `<install-root-relative path>#<function>` with no line or column
+ * numbers. Stacks with no in-app frame yield the single literal
+ * `<no-app-frame>`; distinct roots can merge under that literal, which is an
+ * accepted and documented v1 property.
+ */
+export declare function normalizeCrashFrames(stack: string, options?: CrashFingerprintOptions): string[];
+/** Compute the v1 fingerprint of an already-captured fatal diagnostic. */
+export declare function computeCrashFingerprint(input: CrashFingerprintInput, options?: CrashFingerprintOptions): CrashFingerprint;
+/**
+ * Compute the stable identity used for a handled tool error.
+ *
+ * Tool failures often carry command output or other per-occurrence detail in
+ * their message. That text is useful in the record body but is not the failure
+ * identity: handled errors group by error class and the first in-app frame
+ * where the failure originated, rather than the full wrapper stack.
+ */
+export declare function computeHandledErrorFingerprint(input: CrashFingerprintInput, options?: CrashFingerprintOptions): CrashFingerprint;
+/** The machine-readable identity line appended to every new crash record. */
+export declare function formatCrashRecordMarker(fingerprint: string, version: number, recordId: string): string;
+export interface CrashRecordMarker {
+    readonly fingerprint: string;
+    readonly version: number;
+    readonly recordId: string;
+}
+/**
+ * Parse an identity line. Records written before this feature carry no marker
+ * and are therefore `unmatchable`: this parser never guesses at them.
+ */
+export declare function parseCrashRecordMarker(line: string): CrashRecordMarker | undefined;

package/dist/types/crash-journal.d.ts

@@ -0,0 +1,84 @@
+/** Hard cap for one journal line, including its newline. */
+export declare const CRASH_EVENT_MAX_BYTES = 512;
+/** Journal line format tag. */
+export declare const CRASH_EVENT_KIND = "skc-crash-event.v1";
+/** Preview cap for the message class carried by an event. */
+export declare const CRASH_EVENT_MESSAGE_MAX_BYTES = 256;
+/** Bounded execution provenance carried only on newly written occurrences. */
+export type CrashProvenance = "product" | "eval" | "bun_test";
+/**
+ * Classify only process-level harness modes that are explicit and stable.
+ * Everything else is product provenance, including source checkouts, CLI
+ * invocations, SDK/ACP hosts, and native-loader failures.
+ */
+export declare function detectCrashProvenance(argv?: readonly string[], env?: NodeJS.ProcessEnv, execArgv?: readonly string[]): CrashProvenance;
+export type CrashEvent = CrashOccurrenceEvent | CrashRefusedEvent | CrashReportedEvent | CrashRelayedEvent | CrashAcknowledgedEvent | CrashNudgedEvent;
+export interface CrashOccurrenceEvent {
+    readonly kind: "occurrence";
+    readonly fingerprint: string;
+    readonly fpv: number;
+    readonly recordId: string;
+    readonly at: number;
+    readonly errorName: string;
+    readonly messageClass: string;
+    /** Legacy events omit this and are treated as product crashes. */
+    readonly provenance?: CrashProvenance;
+}
+export interface CrashRefusedEvent {
+    readonly kind: "refused";
+    readonly fingerprint: string;
+    readonly fpv: number;
+    readonly recordId: string;
+    readonly contractVersion: string;
+    readonly at: number;
+}
+export interface CrashReportedEvent {
+    readonly kind: "reported";
+    readonly fingerprint: string;
+    readonly at: number;
+    readonly issueUrl: string;
+    /** Set when the submission was a "+1" comment rather than a new issue. */
+    readonly commented?: boolean;
+}
+export interface CrashRelayedEvent {
+    readonly kind: "relayed";
+    readonly fingerprint: string;
+    readonly at: number;
+    /** Sentry event id accepted upstream: 32 lowercase hex. */
+    readonly eventId: string;
+    /** Exact occurrence record represented by the accepted envelope. Absent on legacy pre-record-id relay lines. */
+    readonly recordId?: string;
+}
+export interface CrashAcknowledgedEvent {
+    readonly kind: "acknowledged";
+    readonly fingerprint: string;
+    readonly at: number;
+}
+export interface CrashNudgedEvent {
+    readonly kind: "nudged";
+    readonly at: number;
+}
+/**
+ * Serialize one event to a single journal line (newline included), bounded to
+ * `CRASH_EVENT_MAX_BYTES`. Oversized message previews are shortened, and if the
+ * line still does not fit the preview is dropped entirely rather than the event.
+ */
+export declare function formatCrashEventLine(event: CrashEvent): string;
+/** Parse one journal line. Anything unexpected yields `undefined`, never a throw. */
+export declare function parseCrashEventLine(line: string): CrashEvent | undefined;
+/**
+ * Append one event synchronously with `O_APPEND`. Never throws.
+ *
+ * No parse, no lock, no rename, no read: the only I/O is one bounded write to
+ * an append-only file, so concurrent writers interleave whole lines instead of
+ * corrupting each other's records.
+ */
+export declare function appendCrashEvent(event: CrashEvent, journalPath: string): boolean;
+/**
+ * Fatal-path entry point: at most one journal append per process lifetime.
+ *
+ * A crash raised while handling a crash must not spend the process's remaining
+ * moments on journal bookkeeping, so the latch is never cleared — the process
+ * is exiting anyway. Returns whether this call wrote a line.
+ */
+export declare function appendFatalCrashEvent(event: CrashEvent, journalPath: string): boolean;

package/dist/types/crash-redaction.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Best-effort credential scrubbing for durable crash records.
+ *
+ * This is a *persistence-time* scrub: it keeps obvious credential shapes out of
+ * a file SKC keeps indefinitely. It is explicitly NOT a privacy guarantee and
+ * must never be treated as one for data that leaves the machine — outbound
+ * text goes through `sanitizeExternalCrashV1` instead.
+ */
+/** Whether a field name ends in a credential label recognized by the redactor. */
+export declare function isCredentialKey(key: string): boolean;
+/**
+ * Scrub credential material from crash text before it is persisted.
+ * Covers bearer/basic-style headers, key=value or JSON key forms of common
+ * credential names, and well-known vendor token shapes. Normal messages and
+ * stack frames are untouched; matches are replaced in place so surrounding
+ * diagnostic context survives.
+ */
+export declare function redactCrashSecrets(text: string): string;
+/** Every placeholder `redactCrashSecrets` can emit. Used by downstream normalizers. */
+export declare const CRASH_REDACTION_MARKERS: readonly string[];

package/dist/types/dirs.d.ts

@@ -5,37 +5,38 @@
  * config root and SKC_CODING_AGENT_DIR (legacy alias PI_CODING_AGENT_DIR) to
  * override the agent directory.
  *
- * On Linux, if XDG_DATA_HOME / XDG_STATE_HOME / XDG_CACHE_HOME environment
- * variables are set, paths are redirected to XDG-compliant locations under
- * $XDG_*_HOME/skc/. This requires running `skc config migrate` first to
- * move data to the new locations. No filesystem existence checks are performed
- * — if the env var is set, skc trusts that the migration has been done.
+ * On Linux and macOS, a category (data, state, cache) is redirected to
+ * $XDG_*_HOME/skc/ only when the trusted XDG_*_HOME variable is set, the
+ * $XDG_*_HOME/skc directory already exists (`skc config init-xdg` creates it),
+ * and the agent directory is the default. Otherwise paths stay under the config
+ * root. `init-xdg` only creates the directories; existing data is not moved.
  */
-/** App name (e.g. "skc") */
-export declare const APP_NAME: string;
+import { canonicalEnvKey, type ProjectEnvSnapshot } from "./env-file";
+/**
+ * Entry metadata lives in the pure `cli-metadata` leaf so the actual CLI entry can
+ * import it without loading this module's load-time directory resolution. These
+ * re-exports keep the existing `@sayknow-cli/utils/dirs` surface unchanged.
+ */
+export { APP_NAME, formatBunRuntimeError, MIN_BUN_VERSION, VERSION } from "./cli-metadata";
+export { canonicalEnvKey };
 /** Config directory name (e.g. ".skc") */
 export declare const CONFIG_DIR_NAME: string;
-/** Version (e.g. "1.0.0") */
-export declare const VERSION: string;
-/** Minimum Bun version */
-export declare const MIN_BUN_VERSION: string;
 /**
- * Build the diagnostic shown when the Bun runtime executing `skc` is older
- * than {@link MIN_BUN_VERSION}. This is the most common Windows native-install
- * failure (issue #525): `bun install -g sayknow-cli` probes a recent Bun while
- * the `skc` launcher resolves an older Bun still on PATH. The message names the
- * exact detected runtime path and gives a platform-specific upgrade + PATH fix
- * instead of a bare `bun upgrade`.
- *
- * Pure and platform-parameterized so it can be unit-tested cross-platform.
+ * On macOS, strip /private prefix only when both paths resolve to the same location.
+ * This preserves aliases like /private/tmp -> /tmp without rewriting unrelated paths.
  */
-export declare function formatBunRuntimeError(opts: {
-    currentVersion: string;
-    minVersion: string;
-    execPath?: string;
-    platform?: NodeJS.Platform;
-}): string;
+export declare function standardizeMacOSPath(p: string): string;
 export declare function resolveEquivalentPath(inputPath: string): string;
+/**
+ * Return a stable key for comparing existing filesystem paths.
+ *
+ * Windows path spelling is not a safe identity: most directories are
+ * case-insensitive, while directories can opt into case-sensitive names. Use
+ * the filesystem object's identity when it is available instead of folding
+ * path text. If the path does not exist or the filesystem has no usable inode,
+ * retain the resolved spelling so distinct case-sensitive paths never alias.
+ */
+export declare function pathIdentityKey(inputPath: string): string;
 export declare function normalizePathForComparison(inputPath: string, platform?: NodeJS.Platform): string;
 /** Return whether a relative path crosses above its root or is unexpectedly absolute. */
 export declare function relativePathEscapesRoot(relative: string): boolean;
@@ -45,15 +46,54 @@ export declare function relativePathWithinRoot(root: string, candidate: string):
 export declare function getProjectDir(): string;
 /** Set the project directory. */
 export declare function setProjectDir(dir: string): void;
-export declare function getConfigDirName(): string;
-/** Get the config agent directory name relative to home (e.g. ".skc/agent" or PI_CONFIG_DIR + "/agent"). */
 export declare function getConfigAgentDirName(): string;
+/**
+ * Project dotenv as captured when this module loaded.
+ * A later edit or delete of those files does not change the returned provenance.
+ */
+export declare function loadedProjectEnvSnapshot(): ProjectEnvSnapshot;
 /** Get the config root directory (~/.skc). */
 export declare function getConfigRootDir(): string;
-/** Set the coding agent directory. Creates a fresh resolver, invalidating all cached paths. */
+/**
+ * The authoritative home for user-scope state.
+ *
+ * Provenance-checked and resolved at call time: a home established or changed
+ * after this module loaded is honored, while a home the project dotenv could
+ * have planted is rejected in favor of the OS account database. See
+ * {@link resolveTrustedHome}.
+ */
+export declare function getTrustedHomeDir(): string;
+/** Trusted config root, resolved at call time; preserves the configured nested config-dir name. */
+export declare function getTrustedConfigRootDir(): string;
+/**
+ * Set the coding agent directory. Creates a fresh resolver, invalidating all
+ * cached paths.
+ *
+ * This also exports `SKC_CODING_AGENT_DIR`, so child processes inherit the same
+ * selection and resolve the same storage lane.
+ */
 export declare function setAgentDir(dir: string): void;
+/**
+ * Rebuild the resolver from the current trusted environment. Callers that
+ * temporarily used {@link setAgentDir} must first restore the original
+ * SKC_CODING_AGENT_DIR / PI_CODING_AGENT_DIR values, then call this function;
+ * an originally absent override remains absent and keeps following HOME.
+ */
+export declare function resetAgentDirFromEnvironment(): void;
 /** Get the agent config directory (~/.skc/agent). */
 export declare function getAgentDir(): string;
+/** Resolver-owned profile classification, stable across HOME refreshes. */
+export declare function getAgentProfileAuthority(): "default" | "custom";
+export declare function getConfigDirName(): string;
+/**
+ * Join a file under the provenance-checked agent directory, never the XDG
+ * state category. Automatic crash relay must not follow `XDG_STATE_HOME`:
+ * a checkout `.env` can set that variable and create `$XDG_STATE_HOME/skc`,
+ * which the ordinary state resolver would then treat as the crash store.
+ */
+export declare function getTrustedAgentFile(filename: string): string;
+/** Whether the current checkout declares an environment key in its `.env`. */
+export declare function isProjectEnvDeclaration(name: string): boolean;
 /** Get the project-local config directory (.skc). */
 export declare function getProjectAgentDir(cwd?: string): string;
 /** Get the reports directory (~/.skc/reports). */
@@ -62,17 +102,43 @@ export declare function getReportsDir(): string;
 export declare function getLogsDir(): string;
 /** Get the path to a dated log file (~/.skc/logs/skc.YYYY-MM-DD.log). */
 export declare function getLogPath(date?: Date): string;
+/**
+ * The logs directory the process actually reads and writes.
+ *
+ * A trusted `SKC_LOG_DIR` redirects the sink — the test preload pins it to a
+ * per-process temp directory so `bun test` stops appending fixture
+ * `level:error` records to the operator's shared log (issue #5618) — and
+ * everything else falls back to {@link getLogsDir}.
+ *
+ * The override is provenance-checked through the same {@link trustedValue} rule
+ * as the config and agent directories: Bun loads `cwd/.env` into `process.env`
+ * before any module runs, so a repository could otherwise redirect where the
+ * operator's production logs are written. A dynamic (`$`/backtick) declaration
+ * is rejected there too, which fails closed onto the canonical path.
+ *
+ * This is deliberately *not* folded into {@link getLogsDir}: that function's
+ * config-root semantics are pinned by tests, and the preload sets `SKC_LOG_DIR`
+ * for every test process, so folding the override in would move it under every
+ * test. Writers and readers must both come through here instead — the split
+ * between the two is what let the transport and the log readers disagree.
+ */
+export declare function getEffectiveLogsDir(): string;
+/** Get the dated log file under {@link getEffectiveLogsDir}. */
+export declare function getEffectiveLogPath(date?: Date): string;
 /**
  * Get the plugins directory (~/.skc/plugins or its XDG equivalent).
  *
  * No-arg form (production callers) goes through the XDG-aware DirResolver so
- * reads and writes always agree. The optional `home` parameter is for test
- * isolation: when it differs from `os.homedir()` it short-circuits the resolver
- * and returns `<home>/<configDir>/plugins` so tests with a temp HOME get a
- * deterministic path. Passing `os.homedir()` explicitly is identical to the
- * no-arg form — XDG semantics are preserved.
+ * reads and writes always agree. The optional `home` parameter names an explicit
+ * home: when it differs from the authoritative home resolved right now it
+ * short-circuits the resolver and returns `<home>/<configDir>/plugins`, giving
+ * callers that carry their own home (and tests with a temp HOME) a deterministic
+ * path. Passing the authoritative home explicitly is identical to the no-arg
+ * form — XDG semantics are preserved.
  */
 export declare function getPluginsDir(home?: string): string;
+/** Get the default-profile plugin directory without ambient profile authority. */
+export declare function getDefaultPluginsDir(): string;
 /** Where npm installs packages (~/.skc/plugins/node_modules). */
 export declare function getPluginsNodeModules(): string;
 /** Plugin manifest (~/.skc/plugins/package.json). */
@@ -113,10 +179,14 @@ export declare function getGpuCachePath(): string;
  * cache file without touching the rest of the config root.
  */
 export declare function getGithubCacheDbPath(): string;
+/** Get the durable tool-choice capability cache path. */
+export declare function getToolChoiceCapabilityCachePath(): string;
 /** Get the resolved Claude Code client-version cache path (~/.skc/cache/claude-code-version.json). */
 export declare function getClaudeCodeVersionCachePath(): string;
 /** Get the natives directory (~/.skc/natives). */
 export declare function getNativesDir(): string;
+/** Get the local tool-issue report database path (~/.skc/tool-issues.db). */
+export declare function getToolIssuesDbPath(): string;
 /** Get the stats database path (~/.skc/stats.db). */
 export declare function getStatsDbPath(): string;
 /** Get the autoresearch state directory (~/.skc/autoresearch). */
@@ -137,6 +207,10 @@ export declare function getModelDbPath(agentDir?: string): string;
 export declare function getSessionsDir(agentDir?: string): string;
 /** Get the content-addressed blob store directory (~/.skc/agent/blobs). */
 export declare function getBlobsDir(agentDir?: string): string;
+/** Get the resident-text cache root for a profile agent directory. */
+export declare function getResidentCacheRootDir(profileAgentDir: string): string;
+/** Get the managed cold-history sidecar cache root for a profile agent directory. */
+export declare function getSidecarCacheRootDir(profileAgentDir: string): string;
 /** Get the custom themes directory (~/.skc/agent/themes). */
 export declare function getCustomThemesDir(agentDir?: string): string;
 /** Get the tools directory (~/.skc/agent/tools). */
@@ -153,6 +227,16 @@ export declare function getMemoriesDir(agentDir?: string): string;
 export declare function getTerminalSessionsDir(agentDir?: string): string;
 /** Get the crash log path (~/.skc/agent/skc-crash.log). */
 export declare function getCrashLogPath(agentDir?: string): string;
+/** Get the crash event journal path (~/.skc/agent/skc-crash-events.jsonl). */
+export declare function getCrashEventsPath(agentDir?: string): string;
+/** Get the compacted crash signature index path (~/.skc/agent/skc-crash-index.json). */
+export declare function getCrashIndexPath(agentDir?: string): string;
+/** Get the handled error log path (~/.skc/agent/skc-error.log). */
+export declare function getHandledErrorLogPath(agentDir?: string): string;
+/** Get the handled error event journal path (~/.skc/agent/skc-error-events.jsonl). */
+export declare function getHandledErrorEventsPath(agentDir?: string): string;
+/** Get the compacted handled error signature index path (~/.skc/agent/skc-error-index.json). */
+export declare function getHandledErrorIndexPath(agentDir?: string): string;
 /** Get the debug log path (~/.skc/agent/skc-debug.log). */
 export declare function getDebugLogPath(agentDir?: string): string;
 /** Get the project-level Python modules directory (.skc/modules). */
@@ -161,7 +245,14 @@ export declare function getProjectModulesDir(cwd?: string): string;
 export declare function getProjectPromptsDir(cwd?: string): string;
 /** Get the project-level plugin overrides path (.skc/plugin-overrides.json). */
 export declare function getProjectPluginOverridesPath(cwd?: string): string;
-/** Get the primary MCP config file path (first candidate). */
-export declare function getMCPConfigPath(scope: "user" | "project", cwd?: string): string;
+/**
+ * Get the primary MCP config file path (first candidate).
+ *
+ * User scope lives in the agent directory, so a profile override
+ * (`--agent-dir`, `SKC_CODING_AGENT_DIR`, `setAgentDir()`) moves it. Pass
+ * `agentDir` to resolve the scope of a session whose agent directory differs
+ * from the process-wide one.
+ */
+export declare function getMCPConfigPath(scope: "user" | "project", cwd?: string, agentDir?: string): string;
 /** Get the SSH config file path. */
-export declare function getSSHConfigPath(scope: "user" | "project", cwd?: string): string;
+export declare function getSSHConfigPath(scope: "user" | "project", cwd?: string, agentDir?: string): string;

package/dist/types/env-file.d.ts

@@ -17,5 +17,64 @@ export declare function parseShellEnvFile(filePath: string): Record<string, stri
  * Ignores lines that are empty or start with '#'. Trims whitespace.
  * Allows values to be quoted with single or double quotes.
  * Returns an object of key-value pairs.
+ *
+ * The trust guards (`trustedAgentDirOverrideFor`, `trustedConfigDirName`,
+ * `filterCredentialInheritedEnv`) decide provenance by comparing
+ * `process.env` against this parse, so the accepted syntax must be a superset
+ * of what Bun's own dotenv loader honors in `cwd/.env`: `export KEY=value`,
+ * whitespace around `=` or `:`, and `#` comments after unquoted values, including
+ * a backslash before `#` (quotes keep their `#`). Values that Bun would expand
+ * (`$VAR`, `${VAR}`, backticks,
+ * command substitution) are kept as their literal text: the trust rule only
+ * needs the parser to see the key at all, and an operator environment value
+ * cannot equal attacker-written expansion text, so a literal parse stays
+ * conservative.
  */
 export declare function parseEnvFile(filePath: string): Record<string, string>;
+/** Parse dotenv content that has already been read from a trusted file. */
+export declare function parseEnvFileContent(content: string): Record<string, string>;
+/**
+ * What the caller's checkout declares through its dotenv files.
+ *
+ * `values` is the merged declaration set, later layers winning. `dynamic` holds
+ * the keys whose surviving declaration is one Bun expands at load time, or whose
+ * raw text is quoted in a way this line parser does not decode. Provenance
+ * refuses those keys instead of comparing a value Bun may have loaded differently.
+ */
+export interface ProjectEnvSnapshot {
+    values: Record<string, string>;
+    dynamic: Set<string>;
+    /** True when at least one project dotenv layer could not be read safely. */
+    incomplete?: boolean;
+}
+export interface ProjectEnvSnapshotOptions {
+    /** Maximum bytes read from each dotenv layer; unsafe files mark the snapshot incomplete. */
+    maxFileBytes?: number;
+}
+/**
+ * Windows environment variable names are case-insensitive, so a project dotenv
+ * line `userprofile=...` is what `process.env.USERPROFILE` resolves to. Every
+ * provenance lookup is spelled in upper case, so the snapshot must be keyed the
+ * same way or the declaration is invisible to the guard while still being live
+ * in the process. POSIX names are case-sensitive and must not fold.
+ */
+export declare function canonicalEnvKey(name: string): string;
+/**
+ * The layered dotenv declarations Bun overlays into `process.env` for a cwd.
+ *
+ * Lives in this leaf module so every consumer shares ONE notion of provenance.
+ * `dirs.ts` resolves the config, agent and log directories from it, and
+ * `scripts/test-preload.ts` decides test isolation from it — a second, narrower
+ * reader (only `cwd/.env`, its own regex, its own dynamic test) is how a
+ * `SKC_LOG_DIR` declared in `.env.local` / `.env.$NODE_ENV` came to be honored
+ * by the preload and then rejected in production, silently routing test log
+ * records to the operator's canonical sink. This module imports only `node:fs`,
+ * `node:path` and the import-free `./spawn-env`, so importing it has no side
+ * effects and cannot freeze resolver state the way importing `dirs.ts` would.
+ *
+ * `.env.local` is deliberately skipped when `NODE_ENV === "test"`, matching the
+ * convention that a local override file is not part of a test run.
+ */
+/** Files Bun overlays for a cwd. Unset NODE_ENV selects the development layer. */
+export declare function projectEnvLayerFiles(nodeEnv: string | undefined): string[];
+export declare function projectEnvSnapshot(cwd?: string, options?: ProjectEnvSnapshotOptions): ProjectEnvSnapshot;

package/dist/types/env.d.ts

@@ -1,5 +1,10 @@
 export { filterProcessEnv, isSafeEnvName, isSafeEnvValue } from "./spawn-env";
 export { isValidEnvName, parseEnvFile, parseShellEnvFile } from "./env-file";
+/** Project dotenv as it was when this module loaded, before a later `chdir` or file delete. */
+export declare function startupProjectEnvSnapshot(): {
+    values: Record<string, string>;
+    dynamic: Set<string>;
+};
 export declare function $inheritedEnv(name: string): string | undefined;
 /**
  * Intentional re-export of Bun.env.
@@ -25,13 +30,26 @@ export declare function $pickenv(...keys: string[]): string | undefined;
  * only use values explicitly inherited from the launching shell or SKC/user-owned config files.
  */
 export declare function $credentialEnv(name: string): string | undefined;
+/**
+ * Resolve a credential that may rotate in the trusted agent `.env` while this
+ * process remains alive.
+ *
+ * Presence in the agent file establishes that file as the credential's
+ * authority, even when the launching shell inherited an older value. This is
+ * what lets an atomic token rotation repair a long-lived shell instead of
+ * falling back to its revoked snapshot. Removal is authoritative too, so a
+ * deleted token cannot silently reappear from that snapshot. Project `.env`
+ * files are never consulted; shell values retain their normal precedence for
+ * names the agent file does not own.
+ */
+export declare function $rotatingCredentialEnv(name: string): string | undefined;
 /**
  * Resolve the first credential env value from the given keys, excluding cwd/.env overlays.
  */
 export declare function $pickCredentialEnv(...keys: string[]): string | undefined;
 /**
  * Parses a positive decimal integer from `$env[name]`.
- * Empty, invalid, NaN, zero, or negative values return `defaultValue`.
+ * Empty, invalid, unsafe, zero, or negative values return `defaultValue`.
  */
 export declare function $envpos(name: string, defaultValue: number): number;
 /** True when `BUN_ENV` or `NODE_ENV` is the string `test`. */

package/dist/types/error-classification.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Cross-package classification for errors that describe an expected outcome
+ * rather than an unexpected failure.
+ *
+ * The symbol is registered globally so the marker survives package duplication
+ * and worker/VM boundaries without relying on a particular Error constructor.
+ */
+export declare const DESIGNED_ERROR: unique symbol;
+/** Mark an Error as a designed outcome before it crosses package boundaries. */
+export declare function markDesignedError<T extends Error>(error: T): T;
+/** Return true when a throwable carries the trusted designed-outcome marker. */
+export declare function isDesignedError(error: unknown): boolean;