@yagni-app/code-staging 1.1.1-staging.1361.1 → 1.1.2-staging.1364.1

package/README.md

@@ -201,6 +201,7 @@ yagni use prod                           # switch back (sticky); prod is the def
 | `YAGNI_DISABLE_UPDATE_CHECK`  | unset                    | `1` silences the new-version notice and the background update check. |
 | `YAGNI_DISABLE_CLAUDE_COMPAT` | unset                    | `1` turns off the zero-config `.claude` assets bridge (skills and commands). |
 | `YAGNI_DISABLE_CRASH_REPORTS` | unset                    | `1` disables crash reporting (see "What leaves your machine"). |
+| `YAGNI_SYSTEM_CA`             | unset                    | `1` makes sessions trust your OS certificate store; `0` also disables the automatic retry (see "Behind a corporate TLS proxy"). |
 
 Credentials live in `~/.yagni-code/profiles/<name>.json` (mode `0600`); the active
 environment is recorded in `~/.yagni-code/config.json`. A pre-profiles
@@ -357,6 +358,61 @@ never receives these traces.
   `yagni login` again.
 - **Talking to staging** — `yagni use staging --base-url https://<staging-host>`,
   then `yagni login`.
+- **`TLS certificate verification failed`, or everything fails while your
+  browser works** — see below.
+
+### Behind a corporate TLS proxy
+
+Zero-trust agents (**Cloudflare WARP**, **Zscaler**, **Netskope**, **GlobalProtect**)
+inspect HTTPS: they terminate the connection and re-sign it with a private root
+CA, which the agent installs into your **operating system's** certificate store.
+
+Your browser, `curl`, `git` and `gh` all read that store, so they keep working.
+Node ships its own bundled CA list and **ignores the OS store unless asked**, so a
+Node CLI is often the only thing on the machine that breaks. You do not need to
+disconnect from the proxy to fix it.
+
+When a `yagni` command fails this way it says so — the real certificate error,
+not `fetch failed` — and retries itself once against your OS store. For your
+sessions, tell Node to trust that store:
+
+```bash
+export NODE_USE_SYSTEM_CA=1          # macOS, Linux
+```
+
+```powershell
+setx NODE_USE_SYSTEM_CA 1            # Windows — then open a new terminal
+```
+
+That trusts your OS store *in addition to* Node's bundled roots, so nothing else
+changes. (`YAGNI_SYSTEM_CA=1` does the same thing scoped to YAGNI Code sessions
+only.) `yagni doctor` prints a **ca trust** row showing which certificate
+sources are actually in effect.
+
+**If that variable appears to do nothing, check `node -v` first.** Node added
+the two mechanisms in different releases:
+
+| Mechanism | Works from |
+| --- | --- |
+| `NODE_OPTIONS=--use-system-ca` | v23.8.0, and v22.19.0 |
+| `NODE_USE_SYSTEM_CA=1` | v22.19.0 and **v24.6.0** |
+
+So on Node **24.0–24.5** the variable is silently ignored while the flag works.
+Use `export NODE_OPTIONS=--use-system-ca` (or `setx NODE_OPTIONS --use-system-ca`)
+on those versions — `yagni doctor` says so explicitly when it spots this.
+
+Two more things worth knowing:
+
+- The PEM-file alternative is `NODE_EXTRA_CA_CERTS` — **plural, with an `S`**.
+  The singular is a no-op, and Node ignores an unreadable path with only a
+  warning, so a typo looks like it worked. `yagni doctor` checks the file loads.
+- On Linux below Node 24, `--use-system-ca` can't read `/etc/ssl/certs`; use
+  `export NODE_EXTRA_CA_CERTS=/etc/ssl/certs/ca-certificates.crt` instead.
+
+`YAGNI_SYSTEM_CA=0` (or `NODE_USE_SYSTEM_CA=0`) switches off the automatic retry
+too, if you want Node's bundled roots and nothing else. Setting
+`NODE_EXTRA_CA_CERTS` does **not** opt out of anything — an extra bundle and the
+OS store are additive, and you usually want both.
 
 ---
 

package/dist/cli.d.ts

@@ -166,6 +166,45 @@ export declare function main(argv: string[]): Promise<number>;
  * test import (argv[1] points at the test runner) does not.
  */
 export declare function isEntrypoint(argv1: string | undefined, moduleUrl: string): boolean;
+/** Whether the retry actually ran, or could not be started at all. */
+type RetryOutcome = {
+    kind: "ran";
+    code: number;
+} | {
+    kind: "unstarted";
+    reason: string;
+};
+/**
+ * The launcher's terminal error path, with one self-healing case.
+ *
+ * `fetch` reports a TLS trust failure as the bare string "fetch failed" and
+ * buries the OpenSSL verify code in `cause`, so the default printer told a user
+ * behind Cloudflare WARP or Zscaler exactly nothing (YAG-604). Here we print the
+ * whole cause chain, and — because Node can read the OS trust store where those
+ * agents install their root, and the user's machine already trusts it — retry
+ * the command once against that store before giving up.
+ *
+ * The original error is printed BEFORE any retry: the retry inherits stdio, so
+ * a child that fails differently would otherwise bury the cert failure that
+ * started all this, and a retry that never starts would print nothing at all.
+ * Note the retry re-runs the whole command, so a command with local side
+ * effects ahead of its first network call repeats them; every command that can
+ * fail this way (`login`, `doctor`, a session launch) reaches the network
+ * before it writes anything, and re-running them is idempotent.
+ */
+export declare function handleFatalError(err: unknown, argv: string[], deps?: {
+    env?: NodeJS.ProcessEnv;
+    stderr?: (msg: string) => void;
+    platform?: NodeJS.Platform;
+    nodeVersion?: string;
+    /** The launcher's own exec flags; a retry already carrying the CA flag is not retried again. */
+    execArgv?: readonly string[];
+    /** This Node's accepted flags (defaults to process.allowedNodeEnvironmentFlags); tests pin it. */
+    allowedFlags?: {
+        has(flag: string): boolean;
+    };
+    reexec?: (argv: string[], env: NodeJS.ProcessEnv) => Promise<RetryOutcome>;
+}): Promise<number>;
 /**
  * Run the launcher as the process entrypoint. Called by the published bin
  * shim (`bin.js`, after the Node version gate) and by the guard below when

package/dist/cli.js

@@ -37,6 +37,7 @@ import { installProcessCrashHandlers } from "./crashReport.js";
 import { currentCliVersion, maybeNudgeAndRefresh, upgradeCommand } from "./upgrade.js";
 import { maybeRefreshAtLaunch } from "./refresh.js";
 import { exitCodeFor, installSignalForwarding } from "./signalForward.js";
+import { altNameRemediation, describeError, findTlsCertError, isTrustStoreFixable, retryCaEnv, retryExecArgv, shouldRetryWithSystemCa, systemCaMechanism, tlsRemediation, } from "./tlsTrust.js";
 import { PAD_X } from "./padding.js";
 import { canPromptWorktreeCleanup, parseWorktreeFlag, validateWorktreeLaunchArgs, } from "./worktreeArgs.js";
 import { promptKeepOrRemoveWorktree } from "./worktreeExitPrompt.js";
@@ -889,6 +890,74 @@ export function isEntrypoint(argv1, moduleUrl) {
     };
     return resolve(argv1) === resolve(fileURLToPath(moduleUrl));
 }
+/** Re-run this exact command in a child that trusts the OS certificate store. */
+function reexecWithSystemCa(argv, env) {
+    const entry = process.argv[1];
+    // No resolvable entry script means nothing to re-exec (an embedded import,
+    // not a real CLI invocation).
+    if (entry === undefined) {
+        return Promise.resolve({ kind: "unstarted", reason: "no entry script to re-run" });
+    }
+    return new Promise((resolve) => {
+        // Carry the parent's exec flags (loaders, --enable-source-maps) so the
+        // retry runs under the same runtime as the command the user typed, plus
+        // --use-system-ca when this binary accepts it: on the command line of the
+        // one process we spawn from process.execPath it is safe, where the same
+        // flag in NODE_OPTIONS would reach every Node descendant, some of which
+        // may run under an older Node that refuses to start on it.
+        const child = spawn(process.execPath, [...retryExecArgv(process.execArgv), entry, ...argv], {
+            stdio: "inherit",
+            env,
+        });
+        child.on("error", (err) => resolve({ kind: "unstarted", reason: err.message }));
+        child.on("exit", (code, signal) => resolve({ kind: "ran", code: exitCodeFor(code, signal) }));
+    });
+}
+/**
+ * The launcher's terminal error path, with one self-healing case.
+ *
+ * `fetch` reports a TLS trust failure as the bare string "fetch failed" and
+ * buries the OpenSSL verify code in `cause`, so the default printer told a user
+ * behind Cloudflare WARP or Zscaler exactly nothing (YAG-604). Here we print the
+ * whole cause chain, and — because Node can read the OS trust store where those
+ * agents install their root, and the user's machine already trusts it — retry
+ * the command once against that store before giving up.
+ *
+ * The original error is printed BEFORE any retry: the retry inherits stdio, so
+ * a child that fails differently would otherwise bury the cert failure that
+ * started all this, and a retry that never starts would print nothing at all.
+ * Note the retry re-runs the whole command, so a command with local side
+ * effects ahead of its first network call repeats them; every command that can
+ * fail this way (`login`, `doctor`, a session launch) reaches the network
+ * before it writes anything, and re-running them is idempotent.
+ */
+export async function handleFatalError(err, argv, deps = {}) {
+    const env = deps.env ?? process.env;
+    const write = deps.stderr ?? ((m) => void process.stderr.write(m));
+    const platform = deps.platform ?? process.platform;
+    const nodeVersion = deps.nodeVersion ?? process.versions.node;
+    const execArgv = deps.execArgv ?? process.execArgv;
+    const allowedFlags = deps.allowedFlags;
+    const tls = findTlsCertError(err);
+    write(`${describeError(err)}\n`);
+    if (tls && shouldRetryWithSystemCa(err, env, execArgv, nodeVersion, allowedFlags)) {
+        const retryEnv = retryCaEnv(env);
+        write(`[yagni] Retrying with your system certificate store ` +
+            `(${systemCaMechanism(retryExecArgv(execArgv, allowedFlags))})…\n`);
+        const outcome = await (deps.reexec ?? reexecWithSystemCa)(argv, retryEnv);
+        // A retry that RAN owns the outcome, including its own remediation block.
+        if (outcome.kind === "ran")
+            return outcome.code;
+        write(`[yagni] Could not start the retry: ${outcome.reason}\n`);
+    }
+    if (tls) {
+        const lines = isTrustStoreFixable(tls.code)
+            ? tlsRemediation(platform, nodeVersion, allowedFlags)
+            : altNameRemediation();
+        write(`${lines.join("\n")}\n`);
+    }
+    return 1;
+}
 /**
  * Run the launcher as the process entrypoint. Called by the published bin
  * shim (`bin.js`, after the Node version gate) and by the guard below when
@@ -902,10 +971,7 @@ export function runAsEntrypoint() {
     installProcessCrashHandlers({ client: "cli", clientVersion: cliVersion() });
     main(process.argv.slice(2))
         .then((code) => process.exit(code))
-        .catch((err) => {
-        process.stderr.write(`${err instanceof Error ? err.message : String(err)}\n`);
-        process.exit(1);
-    });
+        .catch((err) => handleFatalError(err, process.argv.slice(2)).then((code) => process.exit(code), () => process.exit(1)));
 }
 // Only auto-run when invoked as the CLI entry, so tests can import this module
 // (e.g. to exercise wantsHelp) without spawning the agent.

package/dist/doctor.d.ts

@@ -47,9 +47,36 @@ export type BackendProbe = {
 } | {
     kind: "status";
     status: number;
+}
+/** The chain didn't validate: a TLS-inspecting proxy, not a dead network. */
+ | {
+    kind: "tls";
+    code: string;
 } | {
     kind: "network";
 };
+/** What the running process has been told about certificate authorities. */
+export interface CaTrustProbe {
+    /** `NODE_USE_SYSTEM_CA` is on. */
+    systemCa: boolean;
+    /** `NODE_OPTIONS` carries `--use-system-ca` — the version-proof form. */
+    systemCaFlag: boolean;
+    /** Whether this Node honours the variable at all (v22.19+ / v24.6+). */
+    systemCaEnvHonoured: boolean;
+    /** The running Node version, for the "your Node ignores it" message. */
+    nodeVersion: string;
+    /**
+     * Whether buildLaunch will ADD the OS store to a session that this process
+     * did not itself inherit (the YAGNI_SYSTEM_CA=1 opt-in). Strictly "will add":
+     * a user who exported NODE_USE_SYSTEM_CA themselves is reported through
+     * `systemCa` above, not here — the variable passes into the session as-is.
+     */
+    launchAddsSystemCa: boolean;
+    /** The `NODE_EXTRA_CA_CERTS` path, when set. */
+    extraCertsPath?: string;
+    /** Whether that path is actually readable — Node only warns when it isn't. */
+    extraCertsReadable?: boolean;
+}
 /**
  * The Node floor, first in the list because every other check is moot
  * without it: an old Node dies inside pi's HTTP client mid-request (Sentry
@@ -63,6 +90,19 @@ export declare function checkProfileToken(profile: Pick<Profile, "name" | "token
 export declare function checkTokenExpiry(status: TokenExpiryStatus): CheckResult;
 export declare function checkBackend(probe: BackendProbe): CheckResult;
 export declare function checkStateDir(probe: StateDirProbe): CheckResult;
+/**
+ * What this machine trusts, and whether the user's attempt to widen it took.
+ *
+ * Advisory by design: the default (Node's bundled roots, neither variable set)
+ * is correct on an unmanaged machine, so it is never a failure on its own — the
+ * backend check is what goes red when interception actually breaks things. The
+ * row exists because both failure modes here are invisible otherwise: Node
+ * ignores an unreadable `NODE_EXTRA_CA_CERTS` with a warning most users never
+ * see, and the variable is routinely mistyped in the singular (which is exactly
+ * how YAG-604 stayed unsolved — `NODE_EXTRA_CA_CERT` looks right and does
+ * nothing).
+ */
+export declare function checkCaTrust(probe: CaTrustProbe): CheckResult;
 export declare function checkCliUpdate(probe: {
     current: string;
     latest: string | null;
@@ -138,12 +178,17 @@ export interface DoctorDeps {
     probeLatestVersion?: () => Promise<string | null>;
     /** MCP config snapshot (config-only, no connections). */
     probeMcp?: () => Promise<McpProbe>;
+    /** Certificate-authority configuration of the running process. */
+    probeCaTrust?: () => CaTrustProbe;
     /** OTel gate resolution (env / workspace / repo settings); tests stub it. */
     resolveOtel?: (profile: Profile) => Promise<OtelLaunchConfig | undefined>;
     /** OTel export probe: one real record per signal against the session env. */
     probeOtel?: (env: NodeJS.ProcessEnv) => Promise<OtelProbeSignal[]>;
     log?: (msg: string) => void;
 }
+export declare function defaultProbeBackend(baseUrl: string, token: string): Promise<BackendProbe>;
+/** Read the process's CA configuration, checking the extra bundle really loads. */
+export declare function defaultProbeCaTrust(env?: NodeJS.ProcessEnv, nodeVersion?: string): CaTrustProbe;
 /** Whether a `gh` executable is resolvable on PATH (no subprocess spawn). */
 export declare function ghOnPathDefault(env?: NodeJS.ProcessEnv): boolean;
 /**

package/dist/doctor.js

@@ -22,6 +22,7 @@ import { resolveExtensionPath, resolvePiCliPath, resolvePiPackageDir, resolveTel
 import { readActiveProfile } from "./profiles.js";
 import { resolveMcpConfigPath } from "./mcpCommand.js";
 import { MIN_NODE_VERSION, nodeVersionSatisfies } from "./nodeVersion.js";
+import { EXTRA_CA_ENV, SYSTEM_CA_ENV, SYSTEM_CA_FLAG, childCaEnv, findTlsCertError, nodeOptionsHaveSystemCa, systemCaEnabled, systemCaEnvSupported, } from "./tlsTrust.js";
 // ── Pure check builders ─────────────────────────────────────────────────────
 /**
  * The Node floor, first in the list because every other check is moot
@@ -123,6 +124,19 @@ export function checkBackend(probe) {
             required: false,
         };
     }
+    if (probe.kind === "tls") {
+        return {
+            name: "backend",
+            status: "fail",
+            detail: `TLS certificate verification failed (${probe.code})`,
+            hint: `a TLS-inspecting proxy (Cloudflare WARP, Zscaler, Netskope) is re-signing HTTPS — ` +
+                (systemCaEnvSupported()
+                    ? `set ${SYSTEM_CA_ENV}=1 to trust your OS certificate store`
+                    : `set NODE_OPTIONS=${SYSTEM_CA_FLAG} to trust your OS certificate store ` +
+                        `(this Node ignores ${SYSTEM_CA_ENV})`),
+            required: true,
+        };
+    }
     if (probe.kind === "network") {
         return {
             name: "backend",
@@ -183,6 +197,66 @@ export function checkStateDir(probe) {
     }
     return { name: "state dir", status: "ok", detail: `${probe.path} is 0700`, required: false };
 }
+/**
+ * What this machine trusts, and whether the user's attempt to widen it took.
+ *
+ * Advisory by design: the default (Node's bundled roots, neither variable set)
+ * is correct on an unmanaged machine, so it is never a failure on its own — the
+ * backend check is what goes red when interception actually breaks things. The
+ * row exists because both failure modes here are invisible otherwise: Node
+ * ignores an unreadable `NODE_EXTRA_CA_CERTS` with a warning most users never
+ * see, and the variable is routinely mistyped in the singular (which is exactly
+ * how YAG-604 stayed unsolved — `NODE_EXTRA_CA_CERT` looks right and does
+ * nothing).
+ */
+export function checkCaTrust(probe) {
+    // The trap that makes a correct-looking fix do nothing: the variable landed
+    // in v22.19 and v24.6, the flag back in v23.8, so a 24.0-24.5 user who
+    // exported NODE_USE_SYSTEM_CA gets silence and concludes it didn't help.
+    if (probe.systemCa && !probe.systemCaEnvHonoured && !probe.systemCaFlag) {
+        return {
+            name: "ca trust",
+            status: "warn",
+            detail: `${SYSTEM_CA_ENV} is set, but Node v${probe.nodeVersion} ignores it`,
+            hint: `that variable needs Node v24.6.0+ or v22.19.0+ — use NODE_OPTIONS=${SYSTEM_CA_FLAG} instead, which this Node accepts`,
+            required: false,
+        };
+    }
+    if (probe.extraCertsPath !== undefined && probe.extraCertsReadable === false) {
+        return {
+            name: "ca trust",
+            status: "warn",
+            detail: `${EXTRA_CA_ENV} points at ${probe.extraCertsPath}, which can't be read`,
+            hint: `Node ignores an unreadable bundle with only a warning — fix the path, or use ${SYSTEM_CA_ENV}=1 instead`,
+            required: false,
+        };
+    }
+    const sources = [];
+    if (probe.systemCaFlag || (probe.systemCa && probe.systemCaEnvHonoured)) {
+        sources.push("OS certificate store");
+    }
+    if (probe.extraCertsPath !== undefined)
+        sources.push(probe.extraCertsPath);
+    if (sources.length === 0) {
+        // Report what a SESSION gets, not only what doctor itself inherited: with
+        // the opt-in, buildLaunch adds the OS store to the child env, and a bare
+        // "Node's bundled CAs" here would understate the live configuration.
+        return {
+            name: "ca trust",
+            status: "ok",
+            detail: probe.launchAddsSystemCa
+                ? "this process: Node's bundled CAs; sessions also trust the OS store (YAGNI_SYSTEM_CA=1)"
+                : "Node's bundled CAs (no OS store, no extra bundle)",
+            required: false,
+        };
+    }
+    return {
+        name: "ca trust",
+        status: "ok",
+        detail: `bundled CAs + ${sources.join(" + ")}`,
+        required: false,
+    };
+}
 export function checkCliUpdate(probe) {
     if (probe.latest === null) {
         return {
@@ -460,7 +534,7 @@ async function defaultProbeMcp(env = process.env) {
         };
     }
 }
-async function defaultProbeBackend(baseUrl, token) {
+export async function defaultProbeBackend(baseUrl, token) {
     if (!token)
         return { kind: "skipped" };
     try {
@@ -471,9 +545,38 @@ async function defaultProbeBackend(baseUrl, token) {
         });
         return { kind: "status", status: res.status };
     }
+    catch (err) {
+        // `fetch` collapses a certificate failure into "fetch failed" and hides the
+        // verify code in `cause`; separating the two is the whole point of the row.
+        const tls = findTlsCertError(err);
+        return tls ? { kind: "tls", code: tls.code } : { kind: "network" };
+    }
+}
+/** Read the process's CA configuration, checking the extra bundle really loads. */
+export function defaultProbeCaTrust(env = process.env, nodeVersion = process.versions.node) {
+    const base = {
+        systemCa: systemCaEnabled(env),
+        systemCaFlag: nodeOptionsHaveSystemCa(env),
+        systemCaEnvHonoured: systemCaEnvSupported(nodeVersion),
+        nodeVersion,
+        // Exactly what buildLaunch will decide for the session, asked the same way.
+        launchAddsSystemCa: Object.keys(childCaEnv(env)).length > 0,
+    };
+    const extraCertsPath = env[EXTRA_CA_ENV]?.trim();
+    if (!extraCertsPath)
+        return base;
+    let extraCertsReadable = false;
+    try {
+        // A regular file only: readFileSync on a FIFO or device would block doctor
+        // forever, and Node itself would not have loaded such a path either.
+        extraCertsReadable =
+            statSync(extraCertsPath).isFile() &&
+                readFileSync(extraCertsPath, "utf8").includes("BEGIN CERTIFICATE");
+    }
     catch {
-        return { kind: "network" };
+        extraCertsReadable = false;
     }
+    return { ...base, extraCertsPath, extraCertsReadable };
 }
 /** Whether a `gh` executable is resolvable on PATH (no subprocess spawn). */
 export function ghOnPathDefault(env = process.env) {
@@ -527,6 +630,7 @@ export async function gatherChecks(deps = {}) {
     const probeBackend = deps.probeBackend ?? defaultProbeBackend;
     const probeStateDir = deps.probeStateDir ?? defaultProbeStateDir;
     const probeMcp = deps.probeMcp ?? (() => defaultProbeMcp());
+    const probeCaTrust = deps.probeCaTrust ?? (() => defaultProbeCaTrust());
     const ghOnPath = deps.ghOnPath ?? (() => ghOnPathDefault());
     const platform = deps.platform ?? process.platform;
     const probeBash = deps.probeBash ?? (() => bashOnWindowsDefault());
@@ -550,6 +654,7 @@ export async function gatherChecks(deps = {}) {
     if (profile.token) {
         checks.push(checkTokenExpiry(classifyTokenExpiry(profile.expiresAt, now())));
     }
+    checks.push(checkCaTrust(probeCaTrust()));
     const backend = profile.token
         ? await probeBackend(profile.baseUrl, profile.token)
         : { kind: "skipped" };

package/dist/extension/askAdvisorTool.js

@@ -131,7 +131,7 @@ export function makeAskAdvisorTool(opts) {
             "Call ask_advisor only for a genuine judgment fork — an architectural choice, a subtle correctness question, or a second opinion before an approach you would have to unwind. Reading the code is cheaper; do that first.",
             "Ask ONE specific question per consult, and include the excerpts that matter. The advisor reads the repo itself, so point it at the right place rather than pasting everything.",
             "Consults are capped per session. Spend them on the calls you would otherwise get wrong.",
-            "The advice comes back as plain text: act on it, and call record_decision when it settles a product-intent call so the next agent inherits it.",
+            "The advice comes back as plain text: act on it, and call record_decision when it settles a consequential product-intent or architecture call so the next agent inherits it.",
         ]
         : [
             "Call ask_advisor only for a genuine judgment fork — an architectural choice, a subtle correctness question, or a second opinion before an approach you would have to unwind. Reading the code is cheaper; do that first.",

package/dist/extension/askYagniTool.js

@@ -54,7 +54,7 @@ export function makeAskYagniTool(opts) {
             "Call ask_yagni BEFORE guessing about anything organization- or codebase-specific (conventions, policies, architecture, ownership, product decisions).",
             "Pass the user's actual question; add relevant local context (file paths, snippets) in the optional `context` field.",
             "When you use an answer, quote or reference its citations so the user can verify the source.",
-            "Answers carry a standing: treat a confirmed decision as settled; when you lean on an unverified assumption or an inference, say so where the work is reviewed; when there is no recorded position, follow the answer's instruction to record the assumption you proceed on.",
+            "Answers carry a standing: treat a confirmed decision as settled; when you lean on an unverified assumption or an inference, say so where the work is reviewed; when there is no recorded position, follow the answer's instruction: record the assumption you proceed on only when it is a consequential call another engineer would need to know.",
         ],
         parameters,
         // Self-framed: the condensed transcript look has no tinted tool boxes.

package/dist/extension/attribution.d.ts

@@ -0,0 +1,91 @@
+/**
+ * Commit and pull-request attribution settings.
+ *
+ * Mirrors Claude Code's `attribution` settings object so an engineering org
+ * that already labels AI-assisted commits keeps one convention across
+ * harnesses:
+ *
+ *   { "attribution": { "commit": "<trailer text>", "pr": "<PR body line>" } }
+ *
+ * Tiers, later wins per FIELD (a tier may set only `commit` or only `pr`):
+ *   1. Claude Code settings, as a compatibility fallback so an org configured
+ *      for Claude Code needs no second file: ~/.claude/settings.json,
+ *      .claude/settings.json, .claude/settings.local.json. Both the
+ *      `attribution` object and the deprecated `includeCoAuthoredBy: false`
+ *      (which hides both pieces) are honored. Off under the Claude-compat
+ *      kill switch.
+ *   2. YAGNI Code settings: ~/.yagni-code/config.json (user),
+ *      .yagni-code/config.json (project, committed so an org sets it once),
+ *      .yagni-code/config.local.json (local).
+ *
+ * An empty string hides that piece; an absent field keeps the default. The
+ * defaults are the strings automation already keys on — the commit trailer
+ * matches the /go pipeline's provenance block, and the PR line is what an
+ * auto-labeller matches — so they are treated as stable.
+ *
+ * Workspace trust: the project and local tiers (YAGNI's and Claude Code's)
+ * are repo-controlled files, and the text they carry becomes a standing
+ * system-prompt directive, so they apply only once the folder is trusted —
+ * the same gate as project hooks and project allow-rules (a hostile repo
+ * can COMMIT a config.local.json, so local is gated exactly like project).
+ * Untrusted, the user tiers and the defaults stand, and a skipped tier that
+ * actually carried attribution fields leaves a warning so the developer can
+ * see why their repo's trailer did not apply.
+ *
+ * Fail-soft, same posture as the hooks and permission-rule loaders: a
+ * malformed file is skipped whole with a warn (path + error class only,
+ * never file content), and a non-string field is ignored.
+ */
+export interface AttributionSettings {
+    /** The trailer appended to commit messages; "" hides it. */
+    commit: string;
+    /** The line appended to pull request descriptions; "" hides it. */
+    pr: string;
+}
+export declare const DEFAULT_COMMIT_ATTRIBUTION = "Co-Authored-By: YAGNI Code <code@yagni.app>";
+export declare const DEFAULT_PR_ATTRIBUTION = "Generated with [YAGNI Code](https://yagni.app/code)";
+export declare const DEFAULT_ATTRIBUTION: AttributionSettings;
+export type AttributionSource = "claude-user" | "claude-project" | "claude-local" | "user" | "project" | "local";
+export interface AttributionLoad {
+    settings: AttributionSettings;
+    /**
+     * Which tier last set each piece; absent when the default stands. Rides
+     * the boot trail's `attribution_configured` line so support can tell a
+     * repo-set trailer from a personal one without reading the files.
+     */
+    sources: {
+        commit?: AttributionSource;
+        pr?: AttributionSource;
+    };
+    /** Repo tiers that carried attribution but were skipped because the folder is untrusted. */
+    skipped: AttributionSource[];
+    warnings: string[];
+}
+export interface LoadAttributionOptions {
+    /**
+     * Workspace trust (pi's project trust model). `false` skips the project
+     * and local tiers (YAGNI's and Claude Code's); absent reads as trusted,
+     * matching the sandbox's trust probe default.
+     */
+    trusted?: boolean;
+}
+/**
+ * Normalize one configured piece: trim trailing whitespace per line, strip
+ * control characters (a trailer rides a git commit and the system prompt),
+ * and clamp to a few short lines. "" stays "" (the hide signal).
+ */
+export declare function normalizeAttributionText(value: string): string;
+/**
+ * Resolve the attribution settings for a session. Read once at boot (like the
+ * grounding switch); a change lands on the next session start.
+ */
+export declare function loadAttributionSettings(userHome?: string, cwd?: string, env?: NodeJS.ProcessEnv, options?: LoadAttributionOptions): AttributionLoad;
+export declare const ATTRIBUTION_HEADER = "## Commit and pull request attribution";
+/**
+ * The system-prompt section that tells the model what to append. Pure. Null
+ * when both pieces are hidden, so the prompt carries no attribution talk at
+ * all — an org that opted out gets a prompt byte-identical to one that never
+ * had the feature.
+ */
+export declare function attributionPromptSection(settings: AttributionSettings): string | null;
+//# sourceMappingURL=attribution.d.ts.map