@yagni-app/code-staging 1.0.0-staging.1179.1 → 1.0.0-staging.1183.1

package/README.md

@@ -171,6 +171,43 @@ Credentials live in `~/.yagni-code/profiles/<name>.json` (mode `0600`); the acti
 environment is recorded in `~/.yagni-code/config.json`. A pre-profiles
 `~/.yagni-code/credentials.json` is migrated automatically on first run.
 
+### OTel export (opt-in)
+
+Point sessions at **your own** OpenTelemetry collector (Datadog Agent, Grafana
+Alloy, an OTLP-native backend) and every session — including `/go` stage
+children and subagents — emits a per-prompt span tree: interaction → LLM
+request → tool calls, following the OTel GenAI semantic conventions. Nothing is
+exported unless you configure an endpoint.
+
+Enable it one of three ways (first match wins):
+
+- `OTEL_EXPORTER_OTLP_ENDPOINT=http://<collector>:4317` in the environment
+  (a personal override — handy for pointing one session at a scratch
+  collector), or
+- **workspace settings** (the zero-setup path): a workspace admin sets the
+  endpoint, protocol, and any collector headers (e.g. a Datadog API key) once
+  in the web app under Settings → YAGNI Code → Trace export. Every session in
+  the workspace picks it up at launch — nothing to install or configure on
+  developer machines. Header values are encrypted at rest server-side and the
+  launch-time copy is cached at mode `0600`, the same posture as your device
+  token. Or,
+- commit `{ "otel": { "endpoint": "http://<collector>:4317" } }` to the repo's
+  `.pi/settings.json` so one repo's sessions export without per-machine setup.
+
+Standard OTel env vars are honored (`OTEL_EXPORTER_OTLP_PROTOCOL`,
+`OTEL_EXPORTER_OTLP_HEADERS`, `OTEL_SERVICE_NAME` — defaults to `yagni-code`),
+and `PI_OTEL_DISABLED=1` is the kill switch. `yagni doctor` shows the current
+export state.
+
+Two things are enforced and not configurable:
+
+- **Metadata only.** Token counts, cost, tier, finish reasons, and tool-call
+  ids export; prompt and response text never do — a settings file or env var
+  asking for content capture is overridden.
+- **Cost is your contracted rate.** `pi.cost.usd` is computed from your
+  workspace's tier rate card, and the exported model name is the opaque tier
+  id (`advanced`, `peak`, …), so traces never fingerprint the backing model.
+
 Device tokens are revocable from both ends: `yagni logout` revokes the current
 one, and a workspace admin can list every connected device and revoke any token
 from the web app (Settings, YAGNI Code, Connected devices). Tokens are stored
@@ -196,6 +233,11 @@ precisely:
   third-party crash service, so we can fix the crash before you have to report
   it. Disable with `YAGNI_DISABLE_CRASH_REPORTS=1`.
 
+A third flow exists only when you turn it on: **OTel export** (above) sends
+session *metadata* — never prompt or response text — to a collector **you**
+configure and operate. It is off unless an OTLP endpoint is set, and YAGNI
+never receives these traces.
+
 ## Troubleshooting
 
 - **`Not logged in to environment "<name>" … Run \`yagni login\` first.`** — no

package/dist/cli.js

@@ -27,6 +27,7 @@ import { login } from "./login.js";
 import { logout } from "./logout.js";
 import { tokenCommand } from "./token.js";
 import { buildLaunch } from "./launch.js";
+import { resolveOtelLaunchWithWorkspace } from "./otel.js";
 import { parseOutputFormat, parseJsonEvents, buildResultObject, readGuardianEvents, } from "./outputFormat.js";
 import { feedbackCommand } from "./feedback.js";
 import { runDoctor } from "./doctor.js";
@@ -245,6 +246,16 @@ async function runDefault(passthroughArgs) {
     catch {
         compat = { argv: [], env: {} };
     }
+    // OTel export: load pi-otel only when an OTLP endpoint is configured — the
+    // user's env, the workspace's admin-set config (fetched fail-soft, cached),
+    // or the repo's .pi/settings.json, in that order. undefined keeps the
+    // launch untouched. See otel.ts for the policy.
+    const otel = await resolveOtelLaunchWithWorkspace({
+        env: process.env,
+        cwd: process.cwd(),
+        creds,
+        profileName: profile.name,
+    });
     // buildLaunch runs the token-expiry preflight: it throws (with an actionable
     // login prompt) on an already-expired token so we never spawn a session that
     // immediately 401s, and returns non-fatal warnings (e.g. expiry approaching).
@@ -265,6 +276,7 @@ async function runDefault(passthroughArgs) {
             cliVersion: cliVersion(),
             baseEnv: process.env,
             ...(seededHideThinking ? { hideThinkingSeeded: true } : {}),
+            ...(otel ? { otel } : {}),
         });
     }
     catch (err) {
@@ -435,6 +447,14 @@ async function runWorktreeLaunch(passthroughArgs, worktreeName, loadSessionWorkt
     catch {
         compat = { argv: [], env: {} };
     }
+    // OTel gate reads the WORKTREE's .pi/settings.json — that is the session's
+    // cwd, so a repo-committed otel config applies to its worktrees too.
+    const otel = await resolveOtelLaunchWithWorkspace({
+        env: process.env,
+        cwd: result.worktreePath,
+        creds,
+        profileName: profile.name,
+    });
     let plan;
     try {
         plan = buildLaunch(creds, remainingArgs, {
@@ -447,6 +467,7 @@ async function runWorktreeLaunch(passthroughArgs, worktreeName, loadSessionWorkt
             stateDir: credentialsDir(),
             cliVersion: cliVersion(),
             baseEnv: process.env,
+            ...(otel ? { otel } : {}),
         });
     }
     catch (err) {

package/dist/doctor.d.ts

@@ -13,6 +13,7 @@
  * Advisory checks (loose perms, missing `gh`) never flip the exit code.
  */
 import { type TokenExpiryStatus } from "./launch.js";
+import { type OtelLaunchConfig } from "./otel.js";
 import { type Profile } from "./profiles.js";
 export type CheckStatus = "ok" | "warn" | "fail";
 export interface CheckResult {
@@ -60,6 +61,12 @@ export declare function checkCliUpdate(probe: {
     latest: string | null;
 }): CheckResult;
 export declare function checkGh(onPath: boolean): CheckResult;
+/**
+ * Advisory OTel-export line: says whether sessions will stream traces to an
+ * OTLP collector, and from which config source. Never flips the exit code —
+ * most machines have no collector, and that is the healthy default.
+ */
+export declare function checkOtelExport(config: OtelLaunchConfig | undefined): CheckResult;
 /** What the Windows bash probe found (pi needs a bash — Git Bash — on win32). */
 export interface BashProbe {
     found: boolean;

package/dist/doctor.js

@@ -17,6 +17,7 @@ import { delimiter, join } from "node:path";
 import { credentialsDir } from "./credentials.js";
 import { currentCliVersion, fetchLatestVersion, isNewerVersion } from "./upgrade.js";
 import { classifyTokenExpiry } from "./launch.js";
+import { resolveOtelLaunchWithWorkspace } from "./otel.js";
 import { resolveExtensionPath, resolvePiCliPath, resolvePiPackageDir } from "./paths.js";
 import { readActiveProfile } from "./profiles.js";
 // ── Pure check builders ─────────────────────────────────────────────────────
@@ -198,6 +199,32 @@ export function checkGh(onPath) {
         required: false,
     };
 }
+/**
+ * Advisory OTel-export line: says whether sessions will stream traces to an
+ * OTLP collector, and from which config source. Never flips the exit code —
+ * most machines have no collector, and that is the healthy default.
+ */
+export function checkOtelExport(config) {
+    if (!config) {
+        return {
+            name: "otel export (optional)",
+            status: "ok",
+            detail: "off (no OTLP endpoint configured)",
+            required: false,
+        };
+    }
+    const source = config.source === "env"
+        ? "OTEL_EXPORTER_OTLP_ENDPOINT"
+        : config.source === "workspace"
+            ? "workspace settings"
+            : ".pi/settings.json";
+    return {
+        name: "otel export (optional)",
+        status: "ok",
+        detail: `on → ${config.endpoint} (${source}, metadata-only)`,
+        required: false,
+    };
+}
 export function checkBash(probe) {
     if (!probe.found) {
         return {
@@ -379,6 +406,12 @@ export async function gatherChecks(deps = {}) {
     checks.push(checkBackend(backend));
     checks.push(checkStateDir(probeStateDir()));
     checks.push(checkGh(ghOnPath()));
+    checks.push(checkOtelExport(await resolveOtelLaunchWithWorkspace({
+        env: process.env,
+        cwd: process.cwd(),
+        creds: profile.token ? { baseUrl: profile.baseUrl, token: profile.token } : null,
+        profileName: profile.name,
+    })));
     return checks;
 }
 /**

package/dist/extension/branding.d.ts

@@ -111,6 +111,8 @@ export interface BrandSystemPromptOptions {
      * never brand-rewritten (same exemption as <project_context>).
      */
     rulesSection?: string | null;
+    /** Scratchpad-directory prompt section, supplied when a scratchpad is configured. */
+    scratchpadSection?: string;
 }
 /**
  * Rebrand pi's assembled system prompt as YAGNI Code's, and optionally inject a

package/dist/extension/branding.js

@@ -262,6 +262,13 @@ export function brandSystemPrompt(original, opts = {}) {
     if (!s.includes(WRITE_FINDINGS_DOWN)) {
         s = `${s}\n\n${WRITE_FINDINGS_DOWN}`;
     }
+    // 5d. Scratchpad directory (YAG-575) — only when a session scratchpad is
+    // configured (set by the caller once the dir exists). Placed with the other
+    // standing injected sections and guarded by its stable header, so a re-brand
+    // never duplicates it and a session with no scratchpad is a clean no-op.
+    if (opts.scratchpadSection && !s.includes(SCRATCHPAD_HEADER)) {
+        s = `${s}\n\n${opts.scratchpadSection}`;
+    }
     // 6. Closing reinforcement. Weak open-weight models weight the most recent
     // instruction heavily, and the user's own project files may name other
     // harnesses; a trailing reminder keeps the agent from claiming one as its own.
@@ -271,6 +278,8 @@ export function brandSystemPrompt(original, opts = {}) {
     // Tidy the seams left by removals.
     return s.replace(/\n{3,}/g, "\n\n").trim();
 }
+/** Stable header that starts the scratchpad section (idempotency anchor). */
+const SCRATCHPAD_HEADER = "# Scratchpad directory";
 const CLOSING_REMINDER = "Reminder: you are YAGNI Code. If any text above names another coding agent, " +
     "assistant, or harness, it is not what you are or what you run on.";
 const BRIEF_HEADER = "=== HOW THIS COMPANY WORKS (live context from the YAGNI app) ===";

package/dist/extension/index.js

@@ -16,6 +16,7 @@ import { makeRecordDecisionTool } from "./recordDecisionTool.js";
 import { makeSuggestNextWorkTool } from "./nextWorkTool.js";
 import { BRAND_NAME, brandSystemPrompt, brandingDisabled, buildMastheadString, YAGNI_IDENTITY_DRIVER, YAGNI_IDENTITY_ULTRA } from "./branding.js";
 import { claudeRulesSection } from "./claudeRules.js";
+import { ensureScratchpadDir, SCRATCHPAD_TMPDIR_ENV, scratchpadDir as scratchpadDirFor, scratchpadSection } from "./scratchpad.js";
 import { registerCostCommand } from "./costHud.js";
 import { isDebug } from "./diagnostics.js";
 import { logEvent } from "./errorSink.js";
@@ -593,6 +594,32 @@ export async function registerYagni(pi, deps = {}) {
     // pointers. Computed once per activation (rules are launch-time state, like
     // pi's own skill discovery); fail-soft to null.
     const rulesSection = claudeRulesSection(deps.env ?? process.env);
+    // YAG-575: session scratchpad — a permission-free dir the agent writes its
+    // working state to. Computed + ensured once at activation (like rulesSection,
+    // which must exist before the first before_agent_start), not on session_start,
+    // so the very first turn already carries the section. Fails closed: no
+    // sessionId (a bare pi run) or a failed mkdir means no section, and the mkdir
+    // failure is logged so a missing scratchpad is not silent.
+    const scratchpadDirPath = scratchpadDirFor({
+        sessionId: env.YAGNI_SESSION_ID ?? undefined,
+        cwd: process.cwd(),
+        tmp: env[SCRATCHPAD_TMPDIR_ENV] || undefined,
+    });
+    let scratchpadSectionText;
+    if (scratchpadDirPath) {
+        const ensured = ensureScratchpadDir(scratchpadDirPath);
+        if (ensured) {
+            scratchpadSectionText = scratchpadSection(ensured);
+        }
+        else {
+            logEvent({
+                source: "scratchpad",
+                level: "error",
+                event: "scratchpad_mkdir_failed",
+                sessionId: env.YAGNI_SESSION_ID ?? undefined,
+            });
+        }
+    }
     // Own the identity + inject live company context (and repo rules) on every
     // turn. The extension loads identically in every pi process this app spawns —
     // the interactive driver AND every `/go` stage child, subagent, and advisor
@@ -617,6 +644,7 @@ export async function registerYagni(pi, deps = {}) {
                         : YAGNI_IDENTITY_DRIVER
                     : undefined,
                 rulesSection,
+                scratchpadSection: scratchpadSectionText,
             }),
         });
     // Turn-lifecycle WAL: a `turn_start` with no matching `turn_end` is the

package/dist/extension/pipeline/invocation.d.ts

@@ -65,9 +65,16 @@ export declare function buildStageInvocation(stage: PipelineStage, ctx: {
  * `yagni` provider) before a stage passthrough. Mirrors buildLaunch's
  * `userChoseProvider` guard so a passthrough that already chose a provider is
  * left untouched.
+ *
+ * `otelExtensionPath` (absent on a non-exporting launch) additionally loads
+ * pi-otel so child LLM spend is traced too — stage children are the bulk of a
+ * /go run's cost, and an OTel export that misses them undercounts. The path
+ * arrives via `YAGNI_OTEL_EXTENSION_PATH` from the launcher's gate (see the
+ * CLI's otel.ts); the capture-mode and endpoint env rides the inherited env.
  */
 export declare function groundedChildArgv(stageArgv: string[], opts: {
     piCli: string;
     extensionPath: string;
+    otelExtensionPath?: string;
 }): string[];
 //# sourceMappingURL=invocation.d.ts.map

package/dist/extension/pipeline/invocation.js

@@ -84,6 +84,12 @@ export function buildStageInvocation(stage, ctx) {
  * `yagni` provider) before a stage passthrough. Mirrors buildLaunch's
  * `userChoseProvider` guard so a passthrough that already chose a provider is
  * left untouched.
+ *
+ * `otelExtensionPath` (absent on a non-exporting launch) additionally loads
+ * pi-otel so child LLM spend is traced too — stage children are the bulk of a
+ * /go run's cost, and an OTel export that misses them undercounts. The path
+ * arrives via `YAGNI_OTEL_EXTENSION_PATH` from the launcher's gate (see the
+ * CLI's otel.ts); the capture-mode and endpoint env rides the inherited env.
  */
 export function groundedChildArgv(stageArgv, opts) {
     const userChoseProvider = stageArgv.includes("--provider");
@@ -91,6 +97,7 @@ export function groundedChildArgv(stageArgv, opts) {
         opts.piCli,
         "-e",
         opts.extensionPath,
+        ...(opts.otelExtensionPath ? ["-e", opts.otelExtensionPath] : []),
         ...(userChoseProvider ? [] : ["--provider", "yagni"]),
         ...stageArgv,
     ];

package/dist/extension/pipeline/personas.js

@@ -56,7 +56,7 @@ Numbered, small, actionable steps — each names the file/function to touch.
 ## Risks
 What to watch for, including any decision the worker will be forced to make.
 
-Finish the job in ONE turn: do not end your turn on an interstitial like "now let me check X". Your FINAL message MUST be the complete plan in the format above (## Goal / ## Plan / ## Files to modify or create / ## Risks). Keep exploring with your tools until you can write the whole plan, then write it as your last message.
+Complete the task fully — do not gold-plate, but do not leave it half-done. Finish the job in ONE turn: do not end your turn on an interstitial like "now let me check X". Your FINAL message MUST be the complete plan in the format above (## Goal / ## Plan / ## Files to modify or create / ## Risks). Keep exploring with your tools until you can write the whole plan, then write it as your last message.
 
 Budget discipline: you have a hard output budget, and a plan that gets cut off mid-thought is worth less than a short plan that ships. Explore only until you can name the files and the steps — do not read broadly for completeness, and do not re-verify what you have already established. Aim for 5-10 short steps; the worker fills small gaps from the ticket. When in doubt, write the plan NOW.
 
@@ -65,7 +65,7 @@ const WORKER_BODY = `You are a worker with full capabilities, operating in an is
 
 You are grounded. Call ask_yagni before guessing about anything organization- or codebase-specific. Treat a confirmed answer as settled; when an answer is an unverified assumption or an inference and your change leans on it, say so in your Notes so the reviewer knows what to check. Critically: for ANY product-intent call you are forced to make that the plan did not settle — a behavior choice, a tradeoff, an interpretation of intent — call record_decision so the company's decision corpus captures it and the next agent inherits the call instead of re-litigating it. When ask_yagni reports no recorded position, follow its instruction and record the assumption you proceed on.
 
-You MUST make the change. If the plan is missing, partial, or appears cut off, do not stop at exploring: implement the ticket directly from the ticket text and the code, calling record_decision for any intent you infer. Ending your turn with no write/edit is a failure.
+Complete the task fully — do not gold-plate, but do not leave it half-done. You MUST make the change. If the plan is missing, partial, or appears cut off, do not stop at exploring: implement the ticket directly from the ticket text and the code, calling record_decision for any intent you infer. Ending your turn with no write/edit is a failure.
 
 Output:
 ## Completed
@@ -242,14 +242,14 @@ Numbered, small, actionable steps — each names the file/function to touch.
 ## Risks
 What to watch for, including any decision the worker will be forced to make.
 
-Finish the job in ONE turn: do not end your turn on an interstitial like "now let me check X". Your FINAL message MUST be the complete plan in the format above (## Goal / ## Plan / ## Files to modify or create / ## Risks). Keep exploring with your tools until you can write the whole plan, then write it as your last message.
+Complete the task fully — do not gold-plate, but do not leave it half-done. Finish the job in ONE turn: do not end your turn on an interstitial like "now let me check X". Your FINAL message MUST be the complete plan in the format above (## Goal / ## Plan / ## Files to modify or create / ## Risks). Keep exploring with your tools until you can write the whole plan, then write it as your last message.
 
 Budget discipline: you have a hard output budget, and a plan that gets cut off mid-thought is worth less than a short plan that ships. Explore only until you can name the files and the steps — do not read broadly for completeness, and do not re-verify what you have already established. Aim for 5-10 short steps; the worker fills small gaps from the ticket. When in doubt, write the plan NOW.
 
 Keep it concrete; the worker executes it verbatim.`;
 const WORKER_BLIND = `You are a worker with full capabilities, operating in an isolated context to implement a plan. Work autonomously and use the tools as needed.
 
-You MUST make the change. If the plan is missing, partial, or appears cut off, do not stop at exploring: implement the ticket directly from the ticket text and the code. Ending your turn with no write/edit is a failure.
+Complete the task fully — do not gold-plate, but do not leave it half-done. You MUST make the change. If the plan is missing, partial, or appears cut off, do not stop at exploring: implement the ticket directly from the ticket text and the code. Ending your turn with no write/edit is a failure.
 
 Output:
 ## Completed

package/dist/extension/pipeline/runner.d.ts

@@ -32,6 +32,7 @@ export interface RunStageDeps {
     resolveChild?: () => {
         piCli: string;
         extensionPath: string;
+        otelExtensionPath?: string;
     };
     /** Optional environment for spawned child stages. Defaults to Node's inherited env. */
     env?: NodeJS.ProcessEnv;

package/dist/extension/pipeline/runner.js

@@ -61,11 +61,19 @@ async function defaultWritePrompt(body) {
 /**
  * Default child resolution: the parent process IS pi (so `process.argv[1]` is
  * pi's cli), and our compiled extension entry sits one dir up from this module.
+ *
+ * `otelExtensionPath` comes from `YAGNI_OTEL_EXTENSION_PATH`, set by the
+ * launcher only when an OTLP endpoint is configured (see the CLI's otel.ts) —
+ * children then load pi-otel so their LLM spend is traced. Guarded with
+ * existsSync so a stale env value degrades to an untraced child, never a
+ * child that fails to boot.
  */
 function defaultResolveChild() {
     const piCli = process.argv[1] ?? "pi";
     const extensionPath = fileURLToPath(new URL("../index.js", import.meta.url));
-    return { piCli, extensionPath };
+    const otelPath = process.env.YAGNI_OTEL_EXTENSION_PATH;
+    const otelExtensionPath = otelPath && fs.existsSync(otelPath) ? otelPath : undefined;
+    return { piCli, extensionPath, ...(otelExtensionPath ? { otelExtensionPath } : {}) };
 }
 const EMPTY_USAGE = { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, cost: 0, turns: 0 };
 /** Truncate to PER_TASK_OUTPUT_CAP bytes, never exceeding the cap. */
@@ -116,8 +124,12 @@ export async function runStage(stage, ctx, deps) {
             lens: ctx.lens,
             ...(tierCap ? { tierCap } : {}),
         });
-        const { piCli, extensionPath } = resolveChild();
-        const argv = groundedChildArgv(passthrough, { piCli, extensionPath });
+        const { piCli, extensionPath, otelExtensionPath } = resolveChild();
+        const argv = groundedChildArgv(passthrough, {
+            piCli,
+            extensionPath,
+            ...(otelExtensionPath ? { otelExtensionPath } : {}),
+        });
         // Fold events into a fixed-size accumulator as they stream — never retain
         // the full array (that OOMs on a verbose stage; YAG-317 follow-up).
         const acc = newEventAccumulator();

package/dist/extension/scratchpad.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Session scratchpad — a permission-free directory the agent writes its working
+ * state to, so neither it nor the user has to reconstruct intermediate results.
+ *
+ * Ports Claude Code's scratchpad with one deliberate simplification: Claude
+ * resolves the tmp root and normalizes against path traversal because its
+ * scratchpad is an allow-listed path in a permission classifier. We have no
+ * such classifier (auto mode already passes write/edit unprompted, and plan
+ * mode's write gate holds scratchpad like every other write), so the path is
+ * built plainly and the only caller-facing contract is "the dir exists or the
+ * section is omitted."
+ *
+ * Path mirrors Claude Code's shape under our own owner namespace so the two
+ * never collide: <tmp>/yagni-{uid}/<sanitized-cwd>/<sessionId>/scratchpad/.
+ *   - tmp root: YAGNI_CODE_TMPDIR, else os.tmpdir()
+ *   - uid: process.getuid() ?? 0 (multi-user isolation; tmpdir() is already
+ *     per-user on Windows)
+ *   - sanitized-cwd: non-alphanumerics → "-", length-capped (cosmetic grouping
+ *     only — sessionId is the real uniqueness key)
+ *   - sessionId: env.YAGNI_SESSION_ID, minted by the launcher as a UUID; when
+ *     absent (a bare pi run) no scratchpad is configured at all.
+ *
+ * PURE path/section builders are separated from the one impure mkdir so tests
+ * drive the former directly and the latter through an injectable fs seam.
+ */
+/** Env override for the scratchpad tmp root (mirrors CLAUDE_CODE_TMPDIR). */
+export declare const SCRATCHPAD_TMPDIR_ENV = "YAGNI_CODE_TMPDIR";
+/**
+ * PURE: sanitize an absolute cwd into a filename-safe segment. Mirrors Claude
+ * Code's sanitizePath but without the hash suffix — the cwd segment is cosmetic
+ * grouping, not a permission identity, so an identical prefix under two long
+ * cwds is disambiguated by the sessionId one level deeper.
+ */
+export declare function sanitizeCwdSegment(cwd: string): string;
+/**
+ * PURE: the per-user scratchpad owner dir name. uid isolates multi-user systems
+ * the way Claude Code's "claude-{uid}" does, under our own prefix.
+ */
+export declare function scratchpadOwnerDir(uid: number): string;
+/**
+ * PURE: the session scratchpad directory path. Returns null when there is no
+ * sessionId — a scratchpad is meaningless without a per-session key, and the
+ * prompt section is gated on a non-null result.
+ */
+export declare function scratchpadDir(opts?: {
+    sessionId?: string;
+    cwd?: string;
+    uid?: number;
+    tmp?: string;
+}): string | null;
+/**
+ * IMPURE: ensure the scratchpad dir exists (owner-only), failing soft. Returns
+ * the path on success and null on failure — a null result means "no scratchpad
+ * this session", which the caller turns into an omitted prompt section.
+ */
+export declare function ensureScratchpadDir(path: string, mkdir?: (p: string, o: {
+    mode: number;
+    recursive: boolean;
+}) => void): string | null;
+/**
+ * PURE: the prompt section naming the scratchpad. Gated by the caller on the
+ * dir existing; when present, it tells the agent where to put intermediate
+ * files instead of /tmp or the user's project.
+ */
+export declare function scratchpadSection(dir: string): string;
+//# sourceMappingURL=scratchpad.d.ts.map

package/dist/extension/scratchpad.js

@@ -0,0 +1,93 @@
+/**
+ * Session scratchpad — a permission-free directory the agent writes its working
+ * state to, so neither it nor the user has to reconstruct intermediate results.
+ *
+ * Ports Claude Code's scratchpad with one deliberate simplification: Claude
+ * resolves the tmp root and normalizes against path traversal because its
+ * scratchpad is an allow-listed path in a permission classifier. We have no
+ * such classifier (auto mode already passes write/edit unprompted, and plan
+ * mode's write gate holds scratchpad like every other write), so the path is
+ * built plainly and the only caller-facing contract is "the dir exists or the
+ * section is omitted."
+ *
+ * Path mirrors Claude Code's shape under our own owner namespace so the two
+ * never collide: <tmp>/yagni-{uid}/<sanitized-cwd>/<sessionId>/scratchpad/.
+ *   - tmp root: YAGNI_CODE_TMPDIR, else os.tmpdir()
+ *   - uid: process.getuid() ?? 0 (multi-user isolation; tmpdir() is already
+ *     per-user on Windows)
+ *   - sanitized-cwd: non-alphanumerics → "-", length-capped (cosmetic grouping
+ *     only — sessionId is the real uniqueness key)
+ *   - sessionId: env.YAGNI_SESSION_ID, minted by the launcher as a UUID; when
+ *     absent (a bare pi run) no scratchpad is configured at all.
+ *
+ * PURE path/section builders are separated from the one impure mkdir so tests
+ * drive the former directly and the latter through an injectable fs seam.
+ */
+import { mkdirSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+/** Env override for the scratchpad tmp root (mirrors CLAUDE_CODE_TMPDIR). */
+export const SCRATCHPAD_TMPDIR_ENV = "YAGNI_CODE_TMPDIR";
+/** Longest sanitized-cwd segment we keep; the sessionId carries uniqueness. */
+const MAX_SANITIZED_CWD = 64;
+/**
+ * PURE: sanitize an absolute cwd into a filename-safe segment. Mirrors Claude
+ * Code's sanitizePath but without the hash suffix — the cwd segment is cosmetic
+ * grouping, not a permission identity, so an identical prefix under two long
+ * cwds is disambiguated by the sessionId one level deeper.
+ */
+export function sanitizeCwdSegment(cwd) {
+    const sanitized = cwd.replace(/[^a-zA-Z0-9]/g, "-").replace(/^-+|-+$/g, "");
+    return sanitized.slice(0, MAX_SANITIZED_CWD) || "root";
+}
+/**
+ * PURE: the per-user scratchpad owner dir name. uid isolates multi-user systems
+ * the way Claude Code's "claude-{uid}" does, under our own prefix.
+ */
+export function scratchpadOwnerDir(uid) {
+    return `yagni-${uid}`;
+}
+/**
+ * PURE: the session scratchpad directory path. Returns null when there is no
+ * sessionId — a scratchpad is meaningless without a per-session key, and the
+ * prompt section is gated on a non-null result.
+ */
+export function scratchpadDir(opts = {}) {
+    const sessionId = opts.sessionId?.trim();
+    if (!sessionId)
+        return null;
+    const tmp = opts.tmp ?? tmpdir();
+    const uid = opts.uid ?? (typeof process.getuid === "function" ? process.getuid() ?? 0 : 0);
+    const cwd = sanitizeCwdSegment(opts.cwd ?? ".");
+    return join(tmp, scratchpadOwnerDir(uid), cwd, sessionId, "scratchpad");
+}
+/**
+ * IMPURE: ensure the scratchpad dir exists (owner-only), failing soft. Returns
+ * the path on success and null on failure — a null result means "no scratchpad
+ * this session", which the caller turns into an omitted prompt section.
+ */
+export function ensureScratchpadDir(path, mkdir = mkdirSync) {
+    try {
+        mkdir(path, { recursive: true, mode: 0o700 });
+        return path;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * PURE: the prompt section naming the scratchpad. Gated by the caller on the
+ * dir existing; when present, it tells the agent where to put intermediate
+ * files instead of /tmp or the user's project.
+ */
+export function scratchpadSection(dir) {
+    return ("# Scratchpad directory\n\n" +
+        `Use this session scratchpad directory for files that do not belong in the user's project:\n` +
+        `${dir}\n\n` +
+        "- Store intermediate results or data during multi-step tasks.\n" +
+        "- Write temporary scripts or configuration files.\n" +
+        "- Save outputs that don't belong in the user's project.\n" +
+        "- Anything that would otherwise go to /tmp.\n\n" +
+        "The directory is session-specific and isolated from the user's project.");
+}
+//# sourceMappingURL=scratchpad.js.map

package/dist/extension/subagents.js

@@ -74,7 +74,7 @@ You are grounded in how THIS company works: call ask_yagni before inferring a co
 
 Never fabricate file paths, contents, or findings. If you cannot find something, say so.
 
-Your final message is your report back to the driving agent, which has NOT seen what you read or did. Make it compressed and complete: what you did, what you found, exact file paths and key excerpts, and anything the driver must know before continuing.`;
+Complete the task fully — do not gold-plate, but do not leave it half-done. Your final message is your report back to the driving agent, which has NOT seen what you read or did: make it a concise report of what was done and the key findings, since the caller relays it to the user and it only needs the essentials. Cover what you did, what you found, exact file paths and key excerpts, and anything the driver must know before continuing.`;
 const GENERAL_AGENT = {
     name: GENERAL_AGENT_NAME,
     description: "General-purpose agent for research, multi-file changes, and self-contained tasks.",
@@ -94,6 +94,8 @@ one you actually read with a tool. If you cannot find something, say "not
 found" — a plausible-sounding invention is worse than no answer because the
 driving agent trusts your report.
 
+Complete the task fully — do not gold-plate, but do not leave it half-done.
+
 Your final message is your report back to the driving agent, which has NOT
 seen what you read. Make it compressed and complete: exact file paths, the
 key excerpts, and a one-paragraph map of how the pieces relate. Say what you
@@ -122,6 +124,8 @@ convention, an ownership rule, or anything organization-specific.
 Never fabricate file paths or results. Report what you actually did and what
 you actually found.
 
+Complete the task fully — do not gold-plate, but do not leave it half-done.
+
 Your final message is your report back to the driving agent, which has NOT
 seen what you did. List every file you touched, what changed in each, the
 commands you ran with their outcomes, and anything you deliberately left
@@ -154,6 +158,8 @@ a convention, an ownership rule, or anything organization-specific.
 Never fabricate file paths or findings. If you could not verify something,
 say exactly what you tried and why you could not.
 
+Complete the task fully — do not gold-plate, but do not leave it half-done.
+
 Your final message is your verdict back to the driving agent, which has NOT
 seen what you read. Format:
 ## Verdict

package/dist/extension/todos.d.ts

@@ -105,6 +105,7 @@ export declare function makeTodoTool(get: () => TodoItem[], set: (todos: TodoIte
     label: string;
     description: string;
     promptSnippet: string;
+    promptGuidelines: string[];
     parameters: Type.TObject<{
         todos: Type.TArray<Type.TObject<{
             text: Type.TString;

package/dist/extension/todos.js

@@ -204,6 +204,21 @@ export function makeTodoTool(get, set) {
             "in_progress at a time, mark items completed the moment they are done, and add newly " +
             "discovered steps as pending. Use it for any task with three or more steps, updating as you go.",
         promptSnippet: "todo_write: keep a user-visible checklist for multi-step work (full-list replacement).",
+        promptGuidelines: [
+            "Use todo_write proactively when a task needs 3 or more distinct steps, requires careful " +
+                "planning, or the user gives you a list of things (numbered or comma-separated).",
+            "Capture new instructions as todos the moment you receive them, and mark a step in_progress " +
+                "BEFORE you start working on it.",
+            "When in doubt, use it — a visible checklist answers \"is it stuck?\" without the user having " +
+                "to interrupt.",
+            "Skip it when there is only one straightforward task, the work is trivial, or the request is " +
+                "purely conversational or informational — in those cases just do the task directly.",
+            "Pass the FULL list every call; it replaces the previous one. Keep exactly ONE item in_progress " +
+                "at a time.",
+            "Mark a step completed the moment it is done (do not batch completions), and add newly " +
+                "discovered steps as pending. Only mark a step completed when it is fully done — if tests " +
+                "fail or work is partial, leave it in_progress and add a new step for the blocker.",
+        ],
         parameters,
         async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
             const normalized = normalizeTodos(params.todos);

package/dist/goHeadless.d.ts

@@ -15,6 +15,7 @@
  * runs locally and what the fleet executes are the same binary and the same
  * pipeline.
  */
+import { type OtelLaunchConfig } from "./otel.js";
 /** Mirrors HEADLESS_GO_EXIT in the extension; duplicated to keep the packages independent. */
 export declare const GO_EXIT: {
     readonly verified: 0;
@@ -64,6 +65,8 @@ export declare function buildHeadlessChildEnv(opts: {
     workspaceId?: string;
     cliVersion?: string;
     sessionId?: string;
+    /** Resolved OTel export config; stage children load pi-otel when present. */
+    otel?: OtelLaunchConfig;
 }): NodeJS.ProcessEnv;
 /**
  * Run `yagni go`. Returns the process exit code: 0 only on a verified

package/dist/goHeadless.js

@@ -20,6 +20,7 @@ import { mkdirSync } from "node:fs";
 import { pathToFileURL } from "node:url";
 import { agentDirEnvVar } from "./branding.js";
 import { agentDir, credentialsDir } from "./credentials.js";
+import { otelChildEnv, resolveOtelLaunchWithWorkspace } from "./otel.js";
 import { credentialsFromProfile, profilePath, readActiveProfile } from "./profiles.js";
 import { resolveHeadlessGoPath, resolvePiCliPath } from "./paths.js";
 /** Mirrors HEADLESS_GO_EXIT in the extension; duplicated to keep the packages independent. */
@@ -54,6 +55,9 @@ export function buildHeadlessChildEnv(opts) {
         PI_CODING_AGENT_DIR: piAgentDir,
         PI_SKIP_VERSION_CHECK: "1",
         PI_TELEMETRY: "0",
+        // OTel export: pin metadata-only capture and forward pi-otel's path so
+        // every stage child spawns with it (see otel.ts for the policy).
+        ...(opts.otel ? otelChildEnv(opts.otel, opts.baseEnv) : {}),
     };
 }
 /**
@@ -88,6 +92,14 @@ export async function goCommand(args, deps = {}, cliVersion) {
         writeErr(`Not logged in to environment "${profile.name}" (${profile.baseUrl}). Run \`yagni login\` first.`);
         return GO_EXIT.usage;
     }
+    // Same OTel gate as an interactive launch — a headless /go run's stage
+    // children are LLM spend too, and the pilot's cost A/B needs to see them.
+    const otel = await resolveOtelLaunchWithWorkspace({
+        env: baseEnv,
+        cwd: deps.cwd ?? process.cwd(),
+        creds: { baseUrl, token },
+        profileName: profile.name,
+    });
     const childEnv = buildHeadlessChildEnv({
         baseEnv,
         token,
@@ -96,6 +108,7 @@ export async function goCommand(args, deps = {}, cliVersion) {
         ...(profile.expiresAt ? { expiresAt: profile.expiresAt } : {}),
         ...(profile.workspaceId ? { workspaceId: profile.workspaceId } : {}),
         ...(cliVersion ? { cliVersion } : {}),
+        ...(otel ? { otel } : {}),
     });
     // The hermetic agent dir must exist before a stage child tries to read it.
     try {

package/dist/launch.d.ts

@@ -6,6 +6,7 @@
  * defaults the provider to `yagni`.
  */
 import type { Credentials } from "./credentials.js";
+import { type OtelLaunchConfig } from "./otel.js";
 export interface LaunchPlan {
     env: NodeJS.ProcessEnv;
     argv: string[];
@@ -92,6 +93,13 @@ export interface BuildLaunchOptions {
      * override the token, base URL, or hermetic agent dir.
      */
     extraEnv?: Record<string, string>;
+    /**
+     * Resolved OTel export config (see `otel.ts`). When present, the session
+     * loads pi-otel alongside our extension and the env pins metadata-only
+     * capture; absent means no OTLP endpoint is configured and the launch is
+     * byte-for-byte what it was before OTel support existed.
+     */
+    otel?: OtelLaunchConfig;
 }
 export declare function buildLaunch(creds: Credentials | null, passthroughArgs: string[], opts: BuildLaunchOptions): LaunchPlan;
 //# sourceMappingURL=launch.d.ts.map

package/dist/launch.js

@@ -7,6 +7,7 @@
  */
 import { randomUUID } from "node:crypto";
 import { agentDirEnvVar } from "./branding.js";
+import { otelChildEnv } from "./otel.js";
 import { PAD_X_ENV, resolvePadX } from "./padding.js";
 import { ENGINEERING_PRACTICE_SECTION, promptEnrichmentDisabled } from "./promptEnrichment.js";
 /**
@@ -105,6 +106,10 @@ export function buildLaunch(creds, passthroughArgs, opts) {
         // the editor (which the launcher pads by seeding editorPaddingX). The
         // footer can't read pi's settings, so the value crosses over env.
         [PAD_X_ENV]: String(resolvePadX()),
+        // OTel export (gated in otel.ts): pin metadata-only capture and forward
+        // pi-otel's path so /go stage children and subagents load it too. Placed
+        // after baseEnv on purpose — the capture pin must beat a user env override.
+        ...(opts.otel ? otelChildEnv(opts.otel, opts.baseEnv ?? {}) : {}),
     };
     // Always load our extension. Default the provider to `yagni` unless the user
     // explicitly chose one (so power users can still point pi elsewhere).
@@ -125,6 +130,7 @@ export function buildLaunch(creds, passthroughArgs, opts) {
     const argv = [
         "-e",
         opts.extensionPath,
+        ...(opts.otel ? ["-e", opts.otel.extensionPath] : []),
         ...(userChoseProvider ? [] : ["--provider", "yagni"]),
         ...(userChoseModel ? [] : ["--model", "advanced"]),
         ...(enrichmentOff ? [] : ["--append-system-prompt", ENGINEERING_PRACTICE_SECTION]),

package/dist/otel.d.ts

@@ -0,0 +1,150 @@
+/**
+ * OTel export wiring (Updater pilot ask): bake the `pi-otel` extension into
+ * every launch so a workspace can stream session traces — token usage, cost,
+ * model tier, tool calls — to its own OTLP collector (e.g. Datadog) without
+ * anyone hand-installing an extension.
+ *
+ * Three deliberate policies, all enforced here rather than left to defaults:
+ *
+ * 1. GATED, not always-on. pi-otel ships `enabled: true` pointed at
+ *    `localhost:4317`, so loading it unconditionally would have every session
+ *    probing a collector nobody runs. We only pass the extension to pi when an
+ *    OTLP endpoint is actually configured: `OTEL_EXPORTER_OTLP_ENDPOINT` in the
+ *    environment, or `otel.endpoint` in the repo's committed `.pi/settings.json`
+ *    (the file pi-otel itself reads, so teams can configure once per repo).
+ *
+ * 2. METADATA-ONLY, enforced. Cost, tokens, model, finish reasons and tool-call
+ *    ids export; prompt and response text never do. `PI_OTEL_CAPTURE_CONTENT`
+ *    is pinned in the child env, and env beats settings in pi-otel's own
+ *    precedence — a repo settings file asking for "full" is overridden, not
+ *    honored. Session content leaving the machine is a contract change, not a
+ *    config knob.
+ *
+ * 3. Cost is the customer's SELL rate. pi-otel exports pi's `usage.cost.total`
+ *    verbatim (as `pi.cost.usd`), and pi computes that from the catalog's
+ *    tier rates (YAG-381) — so the collector sees contracted prices, and the
+ *    exported model name is the opaque tier id, never the backing model.
+ *
+ * Everything here is fail-soft: telemetry must never block a launch, so a
+ * missing package or unreadable settings file resolves to "disabled".
+ */
+import { readFileSync } from "node:fs";
+/**
+ * Env var carrying the resolved pi-otel entry path to /go stage children and
+ * subagents: they build their own pi argv inside pi-extension-yagni (which
+ * cannot import this package), so the path crosses over env. The extension
+ * reads the same literal in `pipeline/runner.ts`.
+ */
+export declare const OTEL_EXTENSION_PATH_ENV = "YAGNI_OTEL_EXTENSION_PATH";
+/** The service name a collector sees unless the user set their own. */
+export declare const DEFAULT_OTEL_SERVICE_NAME = "yagni-code";
+export interface OtelLaunchConfig {
+    /** Absolute path to pi-otel's extension entry. */
+    extensionPath: string;
+    /**
+     * Where the enablement signal came from. "workspace" additionally carries
+     * protocol/headers/serviceName, delivered as env to the session (the other
+     * sources leave those to whatever the user/repo already configured).
+     */
+    source: "env" | "workspace" | "project-settings";
+    /** The configured OTLP endpoint (for doctor display; env for workspace source). */
+    endpoint: string;
+    /** Workspace-configured OTLP protocol (workspace source only). */
+    protocol?: string;
+    /** Workspace-configured collector headers (workspace source only; carries secrets). */
+    headers?: Record<string, string>;
+    /** Workspace-configured service name (workspace source only). */
+    serviceName?: string;
+}
+/**
+ * The `otel` block a workspace admin configures in the web app, as served on
+ * GET /api/yagni-code/models (decrypted headers included — this is the same
+ * trust boundary as the YAGNI_TOKEN that fetched it).
+ */
+export interface WorkspaceOtelConfig {
+    enabled: boolean;
+    endpoint: string;
+    protocol?: string;
+    serviceName?: string | null;
+    headers?: Record<string, string>;
+}
+/**
+ * Decide whether this launch exports OTel traces, and with which pi-otel entry.
+ * Returns undefined when export stays off: no endpoint configured anywhere,
+ * `PI_OTEL_DISABLED` set, or the pi-otel package unresolvable (never fatal).
+ */
+export declare function resolveOtelLaunch(opts: {
+    env: NodeJS.ProcessEnv;
+    cwd: string;
+    /** Injectable seams for tests. */
+    resolveExtension?: () => string;
+    readFile?: typeof readFileSync;
+}): OtelLaunchConfig | undefined;
+/**
+ * Absolute path to pi-otel's extension entry (its package main IS the pi
+ * extension entry, `dist/index.js`). Resolved ESM-native like `paths.ts` does
+ * for pi itself. Throws when the package is missing — callers treat that as
+ * "export off", not an error.
+ */
+export declare function resolveOtelExtensionPath(): string;
+/**
+ * The env keys an OTel-exporting child must carry. `PI_OTEL_CAPTURE_CONTENT`
+ * is pinned unconditionally (policy 2 above); the service name only fills in
+ * when the user has not chosen their own.
+ *
+ * A "workspace"-sourced config additionally delivers the admin-set endpoint,
+ * protocol, and collector headers over the standard OTel env vars — but any
+ * of those the USER already set in their own environment wins (local env >
+ * workspace config), so an engineer can point one session at a scratch
+ * collector without an admin change.
+ */
+export declare function otelChildEnv(config: OtelLaunchConfig, baseEnv: NodeJS.ProcessEnv): Record<string, string>;
+export interface WorkspaceOtelFetchDeps {
+    fetchImpl?: typeof fetch;
+    cacheDir?: string;
+    timeoutMs?: number;
+}
+/**
+ * Resolve the workspace's admin-set OTel config: one fail-soft GET of the
+ * catalog endpoint (which carries the additive `otel` block), cached on disk
+ * per profile so a slow or offline backend degrades to last-known config
+ * instead of a launch stall.
+ *
+ * Cache semantics matter for revocation: a SUCCESSFUL response without an
+ * otel block means the admin disabled or removed the config, so the cache is
+ * DELETED — only a network/HTTP failure falls back to it. Otherwise turning
+ * export off in the web app would leave every laptop exporting (with a stale
+ * collector key) until the cache happened to be overwritten.
+ *
+ * The cache lives under the credentials dir at mode 0600 — the same posture
+ * as the profile token files, which is the right comparison: the cached
+ * headers carry the collector key, the profile carries the YAGNI token.
+ */
+export declare function fetchWorkspaceOtel(creds: {
+    baseUrl: string;
+    token: string;
+}, profileName: string, deps?: WorkspaceOtelFetchDeps): Promise<WorkspaceOtelConfig | null>;
+/**
+ * Full launch-time resolution, all three sources in precedence order:
+ *
+ *   1. `PI_OTEL_DISABLED`      — personal kill switch, beats everything.
+ *   2. env `OTEL_EXPORTER_OTLP_ENDPOINT` — the user's own setup, untouched.
+ *   3. workspace config        — admin-set in the web app, fetched/cached.
+ *   4. repo `.pi/settings.json` — committed per-repo config.
+ *
+ * `creds` absent (not logged in — doctor on a fresh machine) skips source 3.
+ */
+export declare function resolveOtelLaunchWithWorkspace(opts: {
+    env: NodeJS.ProcessEnv;
+    cwd: string;
+    creds?: {
+        baseUrl: string;
+        token: string;
+    } | null;
+    profileName?: string;
+    resolveExtension?: () => string;
+    readFile?: typeof readFileSync;
+    fetchDeps?: WorkspaceOtelFetchDeps;
+    fetchWorkspace?: typeof fetchWorkspaceOtel;
+}): Promise<OtelLaunchConfig | undefined>;
+//# sourceMappingURL=otel.d.ts.map

package/dist/otel.js

@@ -0,0 +1,291 @@
+/**
+ * OTel export wiring (Updater pilot ask): bake the `pi-otel` extension into
+ * every launch so a workspace can stream session traces — token usage, cost,
+ * model tier, tool calls — to its own OTLP collector (e.g. Datadog) without
+ * anyone hand-installing an extension.
+ *
+ * Three deliberate policies, all enforced here rather than left to defaults:
+ *
+ * 1. GATED, not always-on. pi-otel ships `enabled: true` pointed at
+ *    `localhost:4317`, so loading it unconditionally would have every session
+ *    probing a collector nobody runs. We only pass the extension to pi when an
+ *    OTLP endpoint is actually configured: `OTEL_EXPORTER_OTLP_ENDPOINT` in the
+ *    environment, or `otel.endpoint` in the repo's committed `.pi/settings.json`
+ *    (the file pi-otel itself reads, so teams can configure once per repo).
+ *
+ * 2. METADATA-ONLY, enforced. Cost, tokens, model, finish reasons and tool-call
+ *    ids export; prompt and response text never do. `PI_OTEL_CAPTURE_CONTENT`
+ *    is pinned in the child env, and env beats settings in pi-otel's own
+ *    precedence — a repo settings file asking for "full" is overridden, not
+ *    honored. Session content leaving the machine is a contract change, not a
+ *    config knob.
+ *
+ * 3. Cost is the customer's SELL rate. pi-otel exports pi's `usage.cost.total`
+ *    verbatim (as `pi.cost.usd`), and pi computes that from the catalog's
+ *    tier rates (YAG-381) — so the collector sees contracted prices, and the
+ *    exported model name is the opaque tier id, never the backing model.
+ *
+ * Everything here is fail-soft: telemetry must never block a launch, so a
+ * missing package or unreadable settings file resolves to "disabled".
+ */
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { credentialsDir } from "./credentials.js";
+/**
+ * Env var carrying the resolved pi-otel entry path to /go stage children and
+ * subagents: they build their own pi argv inside pi-extension-yagni (which
+ * cannot import this package), so the path crosses over env. The extension
+ * reads the same literal in `pipeline/runner.ts`.
+ */
+export const OTEL_EXTENSION_PATH_ENV = "YAGNI_OTEL_EXTENSION_PATH";
+/** The service name a collector sees unless the user set their own. */
+export const DEFAULT_OTEL_SERVICE_NAME = "yagni-code";
+/**
+ * Read `otel.endpoint` from the repo's `.pi/settings.json`, the project-level
+ * file pi-otel itself resolves config from. Returns undefined on any problem —
+ * a malformed settings file must not block a launch (pi-otel will surface its
+ * own complaint in-session).
+ */
+function projectOtelEndpoint(cwd, readFile) {
+    try {
+        const raw = readFile(join(cwd, ".pi", "settings.json"), "utf8");
+        const parsed = JSON.parse(String(raw));
+        if (typeof parsed !== "object" || parsed === null)
+            return undefined;
+        const otel = parsed.otel;
+        if (typeof otel !== "object" || otel === null)
+            return undefined;
+        const endpoint = otel.endpoint;
+        return typeof endpoint === "string" && endpoint.trim() !== "" ? endpoint.trim() : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Truthy per pi-otel's own convention for PI_OTEL_DISABLED. */
+function envDisabled(env) {
+    return env.PI_OTEL_DISABLED === "1" || env.PI_OTEL_DISABLED === "true";
+}
+/**
+ * Decide whether this launch exports OTel traces, and with which pi-otel entry.
+ * Returns undefined when export stays off: no endpoint configured anywhere,
+ * `PI_OTEL_DISABLED` set, or the pi-otel package unresolvable (never fatal).
+ */
+export function resolveOtelLaunch(opts) {
+    const { env, cwd } = opts;
+    if (envDisabled(env))
+        return undefined;
+    const envEndpoint = env.OTEL_EXPORTER_OTLP_ENDPOINT?.trim();
+    const settingsEndpoint = envEndpoint
+        ? undefined
+        : projectOtelEndpoint(cwd, opts.readFile ?? readFileSync);
+    if (!envEndpoint && !settingsEndpoint)
+        return undefined;
+    let extensionPath;
+    try {
+        extensionPath = (opts.resolveExtension ?? resolveOtelExtensionPath)();
+    }
+    catch {
+        return undefined;
+    }
+    return envEndpoint
+        ? { extensionPath, source: "env", endpoint: envEndpoint }
+        : { extensionPath, source: "project-settings", endpoint: settingsEndpoint };
+}
+/**
+ * Absolute path to pi-otel's extension entry (its package main IS the pi
+ * extension entry, `dist/index.js`). Resolved ESM-native like `paths.ts` does
+ * for pi itself. Throws when the package is missing — callers treat that as
+ * "export off", not an error.
+ */
+export function resolveOtelExtensionPath() {
+    const path = fileURLToPath(import.meta.resolve("pi-otel"));
+    if (!existsSync(path)) {
+        throw new Error(`pi-otel entry not found at ${path}`);
+    }
+    return path;
+}
+/**
+ * The env keys an OTel-exporting child must carry. `PI_OTEL_CAPTURE_CONTENT`
+ * is pinned unconditionally (policy 2 above); the service name only fills in
+ * when the user has not chosen their own.
+ *
+ * A "workspace"-sourced config additionally delivers the admin-set endpoint,
+ * protocol, and collector headers over the standard OTel env vars — but any
+ * of those the USER already set in their own environment wins (local env >
+ * workspace config), so an engineer can point one session at a scratch
+ * collector without an admin change.
+ */
+export function otelChildEnv(config, baseEnv) {
+    const workspace = {};
+    if (config.source === "workspace") {
+        if (!baseEnv.OTEL_EXPORTER_OTLP_ENDPOINT) {
+            workspace.OTEL_EXPORTER_OTLP_ENDPOINT = config.endpoint;
+        }
+        if (config.protocol && !baseEnv.OTEL_EXPORTER_OTLP_PROTOCOL) {
+            workspace.OTEL_EXPORTER_OTLP_PROTOCOL = config.protocol;
+        }
+        if (config.headers && Object.keys(config.headers).length > 0 && !baseEnv.OTEL_EXPORTER_OTLP_HEADERS) {
+            workspace.OTEL_EXPORTER_OTLP_HEADERS = Object.entries(config.headers)
+                .map(([k, v]) => `${k}=${v}`)
+                .join(",");
+        }
+        if (config.serviceName && !baseEnv.OTEL_SERVICE_NAME) {
+            workspace.OTEL_SERVICE_NAME = config.serviceName;
+        }
+    }
+    return {
+        ...workspace,
+        [OTEL_EXTENSION_PATH_ENV]: config.extensionPath,
+        PI_OTEL_CAPTURE_CONTENT: "metadata_only",
+        ...(baseEnv.OTEL_SERVICE_NAME || workspace.OTEL_SERVICE_NAME
+            ? {}
+            : { OTEL_SERVICE_NAME: DEFAULT_OTEL_SERVICE_NAME }),
+    };
+}
+// ── Workspace-configured export (admin sets it once in the web app) ─────────
+/** How long the launcher waits on the config fetch before falling back to the
+ * on-disk cache. Launch latency is user-facing; telemetry config is not worth
+ * more than this. */
+const WORKSPACE_FETCH_TIMEOUT_MS = 1_500;
+function workspaceCachePath(profileName, dir) {
+    // Profile names are already path-safe (they name profile JSON files).
+    return join(dir, "otel", `${profileName}.json`);
+}
+function parseWorkspaceOtel(raw) {
+    if (typeof raw !== "object" || raw === null)
+        return null;
+    const o = raw;
+    if (o.enabled !== true || typeof o.endpoint !== "string" || o.endpoint.trim() === "") {
+        return null;
+    }
+    const headers = {};
+    if (typeof o.headers === "object" && o.headers !== null) {
+        for (const [k, v] of Object.entries(o.headers)) {
+            if (typeof v === "string")
+                headers[k] = v;
+        }
+    }
+    return {
+        enabled: true,
+        endpoint: o.endpoint.trim(),
+        ...(typeof o.protocol === "string" ? { protocol: o.protocol } : {}),
+        ...(typeof o.serviceName === "string" && o.serviceName ? { serviceName: o.serviceName } : {}),
+        headers,
+    };
+}
+/**
+ * Resolve the workspace's admin-set OTel config: one fail-soft GET of the
+ * catalog endpoint (which carries the additive `otel` block), cached on disk
+ * per profile so a slow or offline backend degrades to last-known config
+ * instead of a launch stall.
+ *
+ * Cache semantics matter for revocation: a SUCCESSFUL response without an
+ * otel block means the admin disabled or removed the config, so the cache is
+ * DELETED — only a network/HTTP failure falls back to it. Otherwise turning
+ * export off in the web app would leave every laptop exporting (with a stale
+ * collector key) until the cache happened to be overwritten.
+ *
+ * The cache lives under the credentials dir at mode 0600 — the same posture
+ * as the profile token files, which is the right comparison: the cached
+ * headers carry the collector key, the profile carries the YAGNI token.
+ */
+export async function fetchWorkspaceOtel(creds, profileName, deps = {}) {
+    const cacheDir = deps.cacheDir ?? credentialsDir();
+    const cachePath = workspaceCachePath(profileName, cacheDir);
+    const doFetch = deps.fetchImpl ?? fetch;
+    let body;
+    try {
+        const res = await doFetch(`${creds.baseUrl}/api/yagni-code/models`, {
+            method: "GET",
+            headers: { authorization: `Bearer ${creds.token}` },
+            signal: AbortSignal.timeout(deps.timeoutMs ?? WORKSPACE_FETCH_TIMEOUT_MS),
+        });
+        if (!res.ok)
+            throw new Error(`HTTP ${res.status}`);
+        body = await res.json();
+    }
+    catch {
+        // Network/HTTP failure → last-known config (or nothing). Fail-soft by
+        // design: the fallback is visible via `yagni doctor`, not a launch error.
+        return readWorkspaceOtelCache(cachePath);
+    }
+    const config = parseWorkspaceOtel(body?.otel);
+    try {
+        if (config) {
+            mkdirSync(join(cacheDir, "otel"), { recursive: true, mode: 0o700 });
+            writeFileSync(cachePath, `${JSON.stringify(config, null, 2)}\n`, { mode: 0o600 });
+        }
+        else {
+            rmSync(cachePath, { force: true });
+        }
+    }
+    catch {
+        // Cache maintenance is best-effort; the fresh result still applies.
+    }
+    return config;
+}
+function readWorkspaceOtelCache(cachePath) {
+    try {
+        return parseWorkspaceOtel(JSON.parse(readFileSync(cachePath, "utf8")));
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Full launch-time resolution, all three sources in precedence order:
+ *
+ *   1. `PI_OTEL_DISABLED`      — personal kill switch, beats everything.
+ *   2. env `OTEL_EXPORTER_OTLP_ENDPOINT` — the user's own setup, untouched.
+ *   3. workspace config        — admin-set in the web app, fetched/cached.
+ *   4. repo `.pi/settings.json` — committed per-repo config.
+ *
+ * `creds` absent (not logged in — doctor on a fresh machine) skips source 3.
+ */
+export async function resolveOtelLaunchWithWorkspace(opts) {
+    const { env, cwd } = opts;
+    if (envDisabled(env))
+        return undefined;
+    // Source 2: the user's own env config short-circuits — no fetch needed.
+    if (env.OTEL_EXPORTER_OTLP_ENDPOINT?.trim()) {
+        return resolveOtelLaunch({
+            env,
+            cwd,
+            ...(opts.resolveExtension ? { resolveExtension: opts.resolveExtension } : {}),
+            ...(opts.readFile ? { readFile: opts.readFile } : {}),
+        });
+    }
+    // Source 3: workspace config.
+    if (opts.creds?.token && opts.profileName) {
+        const workspace = await (opts.fetchWorkspace ?? fetchWorkspaceOtel)({ baseUrl: opts.creds.baseUrl, token: opts.creds.token }, opts.profileName, opts.fetchDeps ?? {});
+        if (workspace) {
+            let extensionPath;
+            try {
+                extensionPath = (opts.resolveExtension ?? resolveOtelExtensionPath)();
+            }
+            catch {
+                return undefined;
+            }
+            return {
+                extensionPath,
+                source: "workspace",
+                endpoint: workspace.endpoint,
+                ...(workspace.protocol ? { protocol: workspace.protocol } : {}),
+                ...(workspace.serviceName ? { serviceName: workspace.serviceName } : {}),
+                ...(workspace.headers && Object.keys(workspace.headers).length > 0
+                    ? { headers: workspace.headers }
+                    : {}),
+            };
+        }
+    }
+    // Source 4: repo-committed settings.
+    return resolveOtelLaunch({
+        env,
+        cwd,
+        ...(opts.resolveExtension ? { resolveExtension: opts.resolveExtension } : {}),
+        ...(opts.readFile ? { readFile: opts.readFile } : {}),
+    });
+}
+//# sourceMappingURL=otel.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yagni-app/code-staging",
-  "version": "1.0.0-staging.1179.1",
+  "version": "1.0.0-staging.1183.1",
   "description": "YAGNI Code: a terminal coding agent that already knows your company. One YAGNI login routes the model and grounds the agent in your team's context.",
   "license": "SEE LICENSE IN LICENSE.md",
   "author": "YAGNI, Inc. <jack@yagni.app> (https://yagni.app)",
@@ -36,9 +36,10 @@
   "dependencies": {
     "@earendil-works/pi-coding-agent": "0.84.1",
     "@earendil-works/pi-tui": "0.84.1",
+    "pi-otel": "0.1.0",
     "smol-toml": "^1.8.0",
     "turndown": "^7.2.4",
     "typebox": "^1.3.15"
   },
-  "yagniSourceSha": "0a0e2cda58c070bc25dbc00fe76d89269fb43c6f"
+  "yagniSourceSha": "723499f455c038162f0ddb3bc886e7e3c55b07f5"
 }