@yagni-app/code-staging 1.0.6-staging.1248.1 → 1.0.6-staging.1255.1

package/README.md

@@ -173,62 +173,87 @@ environment is recorded in `~/.yagni-code/config.json`. A pre-profiles
 
 ### 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 four ways (first match wins):
-
-- `OTEL_EXPORTER_OTLP_ENDPOINT=…` in the environment (a personal override —
-  handy for pointing one session at a scratch collector), or
-- `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=…` in the environment — the per-signal
-  form Claude Code setups use (e.g.
-  `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=https://otlp.datadoghq.com/v1/traces`
-  with `OTEL_EXPORTER_OTLP_TRACES_PROTOCOL=http/protobuf`); the launcher
-  bridges it to the generic var pi-otel reads, so a Claude Code OTel env
-  lights up YAGNI Code traces with no extra config, or
+Point sessions at **your own** OpenTelemetry collector (Datadog, Grafana
+Cloud, a Datadog Agent or Grafana Alloy, any OTLP-native backend) and every
+session — including `/go` stage children and subagents — exports three
+signals in the shape Claude Code's telemetry uses, under a `yagni_code`
+prefix instead of `claude_code`:
+
+- **Traces:** a per-prompt span tree, `yagni_code.interaction` →
+  `yagni_code.llm_request` and `yagni_code.tool`, carrying both the flat
+  Claude Code attributes (`model`, `input_tokens`, `cost_usd`, `tool_name`)
+  and the OTel GenAI conventions (`gen_ai.*`) that LLM-observability
+  products read.
+- **Metrics:** `yagni_code.session.count`, `token.usage` (by `type` and
+  `model`), `cost.usage`, `lines_of_code.count`, `commit.count`,
+  `pull_request.count`, `code_edit_tool.decision`, `active_time.total`.
+- **Log events:** `user_prompt`, `assistant_response`, `api_request`,
+  `api_error`, `tool_result`, `tool_decision`, `permission_mode_changed`
+  (as `event.name`, body `yagni_code.<name>`), with `session.id`,
+  `organization.id`, `terminal.type`, and a per-prompt `prompt.id`.
+
+Nothing is exported unless you configure an endpoint. Enable it one of three
+ways (first match wins):
+
+- the standard OTel env in your shell — the generic
+  `OTEL_EXPORTER_OTLP_ENDPOINT` (a base URL; `/v1/<signal>` is appended for
+  http transports) or the per-signal
+  `OTEL_EXPORTER_OTLP_{TRACES,METRICS,LOGS}_ENDPOINT` a Claude Code setup
+  already carries — so a machine configured for Claude Code lights up with
+  no extra config (with per-signal endpoints only, exactly those signals
+  export; nothing falls back to a localhost 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 and probes the endpoint live (unreachable → a warning with a
-hint, never an exit-code flip).
-
-Two recipes for common collectors:
-
-- **Datadog, direct SaaS (no agent):** endpoint
-  `https://otlp.datadoghq.com/v1/traces` (US1; other sites have their own
-  host — `otlp.us3.datadoghq.com`, `otlp.us5.datadoghq.com`,
-  `otlp.datadoghq.eu`, `otlp.ap1.datadoghq.com`), protocol `http/protobuf`
-  (Datadog's direct trace intake does not accept gRPC), header
-  `dd-api-key=<your Datadog API key>`. Use the full path, not `/v1/` — the
-  endpoint is passed through verbatim, no path is appended for you.
+  in the web app under Settings → YAGNI Code → Telemetry 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" } }` (optionally
+  with `protocol`, `headers`, `serviceName`) to the repo's `.pi/settings.json`
+  so one repo's sessions export without per-machine setup. Header values
+  must not contain commas (they travel as a comma-separated list); one that
+  does is dropped.
+
+The rest of the standard OTel env is honored the way Claude Code honors it:
+`OTEL_EXPORTER_OTLP_PROTOCOL` (and per-signal), `OTEL_EXPORTER_OTLP_HEADERS`
+(and per-signal), `OTEL_SERVICE_NAME` (defaults to `yagni-code`),
+`OTEL_RESOURCE_ATTRIBUTES`, `OTEL_{METRICS,LOGS,TRACES}_EXPORTER=none` to
+switch one signal off, `OTEL_METRIC_EXPORT_INTERVAL` /
+`OTEL_LOGS_EXPORT_INTERVAL`, `OTEL_EXPORTER_OTLP_METRICS_TEMPORALITY_PREFERENCE`
+(default `delta`), and the `OTEL_METRICS_INCLUDE_*` cardinality flags.
+`YAGNI_OTEL_DISABLED=1` is the kill switch. `yagni doctor` shows the current
+export state and sends one real record per signal, printing the collector's
+own verdict (a 403 is a bad key, a 404 a bad path or site).
+
+Three recipes for common collectors:
+
+- **Datadog, direct SaaS (no agent):** endpoint `https://otlp.datadoghq.com`
+  (US1; other sites have their own host — `otlp.us3.datadoghq.com`,
+  `otlp.us5.datadoghq.com`, `otlp.datadoghq.eu`, `otlp.ap1.datadoghq.com`),
+  protocol `http/protobuf` (Datadog's direct intake does not accept gRPC),
+  header `dd-api-key=<your Datadog API key>`. Add `dd-otlp-source=llmobs`
+  (the workspace preset does) to have the traces routed into LLM
+  Observability as well as APM; the launcher scopes that header to the
+  traces request. Traces show in APM under service `yagni-code`, metrics
+  under `yagni_code.*`, events in Log Explorer as `service:yagni-code`.
 - **Datadog Agent:** endpoint `http://<agent-host>:4317`, protocol `grpc`, no
   key (the agent forwards with its own). OTLP ingest ships in the agent but
   is off by default — enable it with
   `otlp_config.receiver.protocols.grpc.endpoint: 0.0.0.0:4317` in
   `datadog.yaml`.
-- **Grafana Cloud:** endpoint `https://otlp-gateway-prod-…-0.grafana.net:443/otlp`,
-  protocol `http/protobuf`, header `authorization=<the raw MTgx… value>` (the
-  `Basic ` scheme is added for you).
+- **Grafana Cloud:** endpoint `https://otlp-gateway-prod-<region>.grafana.net/otlp`
+  (the base URL from your stack's OTLP page — signals go to `/otlp/v1/traces`
+  and friends), protocol `http/protobuf`, header `authorization=<the raw
+  MTgx… value>` (the `Basic ` scheme is added for you).
 
 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
+- **Metadata only.** Token counts, cost, tier, durations, tool names, and
+  payload sizes export; prompt text, model output, tool arguments, and tool
+  results never do — `OTEL_LOG_USER_PROMPTS` and `OTEL_LOG_TOOL_DETAILS` are
+  deliberately not honored.
+- **Cost is your contracted rate.** `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.
 

package/dist/cli.js

@@ -247,10 +247,10 @@ 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.
+    // OTel export: on 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(),

package/dist/doctor.d.ts

@@ -13,7 +13,7 @@
  * Advisory checks (loose perms, missing `gh`) never flip the exit code.
  */
 import { type TokenExpiryStatus } from "./launch.js";
-import { probeOtelEndpoint, type OtelLaunchConfig } from "./otel.js";
+import { type OtelLaunchConfig } from "./otel.js";
 import { type Profile } from "./profiles.js";
 export type CheckStatus = "ok" | "warn" | "fail";
 export interface CheckResult {
@@ -61,16 +61,25 @@ export declare function checkCliUpdate(probe: {
     latest: string | null;
 }): CheckResult;
 export declare function checkGh(onPath: boolean): CheckResult;
+/** One signal's verdict from the extension's probe (see telemetry/probe.ts). */
+export interface OtelProbeSignal {
+    signal: "traces" | "metrics" | "logs";
+    url: string;
+    protocol: string;
+    ok: boolean;
+    error?: string;
+}
 /**
- * Advisory OTel-export line: says whether sessions will stream traces to an
- * OTLP collector, from which config source, and — when a collector is
- * configured — whether the endpoint answers TCP right now (scheme-default
- * ports included: https with no port probes 443). Never flips the exit code —
- * most machines have no collector, and that is the healthy default.
+ * Advisory OTel-export line: says whether sessions will stream telemetry to
+ * an OTLP collector, from which config source, and — when a collector is
+ * configured — whether it ACCEPTED a real record on each signal (a wrong API
+ * key, a wrong path, or a protocol mismatch shows up as the collector's own
+ * error). Never flips the exit code — most machines have no collector, and
+ * that is the healthy default.
  */
 export declare function checkOtelExport(config: OtelLaunchConfig | undefined, deps?: {
-    probeEndpoint?: typeof probeOtelEndpoint;
-    probeTimeoutMs?: number;
+    probe?: (env: NodeJS.ProcessEnv) => Promise<OtelProbeSignal[]>;
+    baseEnv?: NodeJS.ProcessEnv;
 }): Promise<CheckResult>;
 /** Config-only MCP snapshot (no connections — health checks live in `mcp list`/`get`). */
 export interface McpProbe {
@@ -120,6 +129,10 @@ export interface DoctorDeps {
     probeLatestVersion?: () => Promise<string | null>;
     /** MCP config snapshot (config-only, no connections). */
     probeMcp?: () => Promise<McpProbe>;
+    /** 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;
 }
 /** Whether a `gh` executable is resolvable on PATH (no subprocess spawn). */

package/dist/doctor.js

@@ -17,8 +17,8 @@ import { delimiter, join } from "node:path";
 import { credentialsDir } from "./credentials.js";
 import { currentCliVersion, fetchLatestVersion, isNewerVersion } from "./upgrade.js";
 import { classifyTokenExpiry } from "./launch.js";
-import { probeOtelEndpoint, resolveOtelLaunchWithWorkspace, } from "./otel.js";
-import { resolveExtensionPath, resolvePiCliPath, resolvePiPackageDir } from "./paths.js";
+import { otelChildEnv, resolveOtelLaunchWithWorkspace } from "./otel.js";
+import { resolveExtensionPath, resolvePiCliPath, resolvePiPackageDir, resolveTelemetryProbePath } from "./paths.js";
 import { readActiveProfile } from "./profiles.js";
 import { resolveMcpConfigPath } from "./mcpCommand.js";
 // ── Pure check builders ─────────────────────────────────────────────────────
@@ -201,11 +201,22 @@ export function checkGh(onPath) {
     };
 }
 /**
- * Advisory OTel-export line: says whether sessions will stream traces to an
- * OTLP collector, from which config source, and — when a collector is
- * configured — whether the endpoint answers TCP right now (scheme-default
- * ports included: https with no port probes 443). Never flips the exit code —
- * most machines have no collector, and that is the healthy default.
+ * Run the extension's telemetry probe against the exact env a session would
+ * get: one real span, one metric point, one log record, each reported with
+ * the collector's actual verdict. Dynamic import so `doctor` on a machine
+ * with no collector never loads the OTel SDK graph.
+ */
+async function defaultProbeOtel(env) {
+    const mod = (await import(resolveTelemetryProbePath()));
+    return (await mod.probeTelemetryExport(env)).results;
+}
+/**
+ * Advisory OTel-export line: says whether sessions will stream telemetry to
+ * an OTLP collector, from which config source, and — when a collector is
+ * configured — whether it ACCEPTED a real record on each signal (a wrong API
+ * key, a wrong path, or a protocol mismatch shows up as the collector's own
+ * error). Never flips the exit code — most machines have no collector, and
+ * that is the healthy default.
  */
 export async function checkOtelExport(config, deps = {}) {
     if (!config) {
@@ -222,23 +233,32 @@ export async function checkOtelExport(config, deps = {}) {
             ? "workspace settings"
             : ".pi/settings.json";
     const base = `on → ${config.endpoint} (${source}, metadata-only)`;
-    const doProbe = deps.probeEndpoint ?? probeOtelEndpoint;
+    const baseEnv = deps.baseEnv ?? process.env;
+    const env = { ...baseEnv, ...otelChildEnv(config, baseEnv) };
+    const doProbe = deps.probe ?? defaultProbeOtel;
     try {
-        const reachable = await doProbe(config.endpoint, deps.probeTimeoutMs ?? 1_000);
-        return reachable
-            ? {
+        const results = await doProbe(env);
+        const accepted = results.filter((r) => r.ok).map((r) => r.signal);
+        const failed = results.filter((r) => !r.ok);
+        const summary = results.map((r) => `${r.signal} ${r.ok ? "accepted" : "FAILED"}`).join(", ");
+        if (failed.length === 0) {
+            return {
                 name: "otel export (optional)",
                 status: "ok",
-                detail: `${base}, TCP reachable`,
-                required: false,
-            }
-            : {
-                name: "otel export (optional)",
-                status: "warn",
-                detail: `${base}, endpoint not reachable`,
-                hint: "the collector is down, unreachable from this machine, or the URL is wrong — traces will not export until it answers",
+                detail: `${base}; ${summary}`,
                 required: false,
             };
+        }
+        const reasons = failed.map((r) => `${r.signal} → ${r.url} (${r.protocol}): ${r.error ?? "rejected"}`).join("; ");
+        return {
+            name: "otel export (optional)",
+            status: "warn",
+            detail: `${base}; ${summary}`,
+            hint: `${reasons}. A 401/403 means the collector key is wrong, a 404 the path or site is wrong, ` +
+                `a connection error the collector is unreachable from this machine` +
+                (accepted.length > 0 ? `; ${accepted.join(" and ")} still export` : ""),
+            required: false,
+        };
     }
     catch {
         // The probe itself errored (not "endpoint down" — the check could not
@@ -247,8 +267,8 @@ export async function checkOtelExport(config, deps = {}) {
         return {
             name: "otel export (optional)",
             status: "warn",
-            detail: `${base}, reachability probe failed`,
-            hint: "the reachability check could not run (network error) — export is configured but unverified; traces may still export normally",
+            detail: `${base}, export probe failed`,
+            hint: "the export probe could not run (the bundled extension is missing or the OTel SDK failed to load) — export is configured but unverified; sessions may still export normally",
             required: false,
         };
     }
@@ -516,12 +536,17 @@ export async function gatherChecks(deps = {}) {
     checks.push(checkStateDir(probeStateDir()));
     checks.push(checkGh(ghOnPath()));
     checks.push(checkMcpConfig(await probeMcp()));
-    checks.push(await checkOtelExport(await resolveOtelLaunchWithWorkspace({
-        env: process.env,
-        cwd: process.cwd(),
-        creds: profile.token ? { baseUrl: profile.baseUrl, token: profile.token } : null,
-        profileName: profile.name,
-    })));
+    const resolveOtel = deps.resolveOtel ??
+        ((p) => resolveOtelLaunchWithWorkspace({
+            env: process.env,
+            cwd: process.cwd(),
+            creds: p.token ? { baseUrl: p.baseUrl, token: p.token } : null,
+            profileName: p.name,
+        }));
+    checks.push(await checkOtelExport(await resolveOtel(profile), {
+        ...(deps.probeOtel ? { probe: deps.probeOtel } : {}),
+        baseEnv: process.env,
+    }));
     return checks;
 }
 /**

package/dist/extension/condensedTools.d.ts

@@ -24,7 +24,7 @@
  * pattern) so tests run against plain text. Renderer exceptions are swallowed
  * by pi (degrading to the built-in fallback), so everything stays total.
  */
-import { SettingsManager, type ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { SettingsManager, type ExtensionAPI, type ToolDefinition } from "@earendil-works/pi-coding-agent";
 import type { RenderTheme } from "./subagentRender.js";
 import { ToolRunTracker } from "./toolRuns.js";
 /** Lines of write content shown collapsed (mirrors Claude Code's preview). */
@@ -87,6 +87,17 @@ export interface RegisterCondensedToolsDeps {
      * image autoResize. Injectable so tests never touch the config dir.
      */
     loadSettings?: (cwd: string) => SettingsManager;
+    /**
+     * sandbox composition: when present, the bash definition is passed
+     * through this wrap before registration — the sandbox adds its schema field
+     * (dangerouslyDisableSandbox), wrap-on-execute, and violation annotation
+     * while condensed keeps its rendering. The compose fn is built by
+     * sandbox/session.ts (makeSandboxBashComposition) and is a no-op when the
+     * sandbox is disabled. Condensed registers LAST among the bash-defining
+     * sites, so composing HERE is what makes the sandbox actually reach the
+     * model's tool calls.
+     */
+    wrapBash?: (def: ToolDefinition) => ToolDefinition;
 }
 /**
  * Re-register the seven built-ins with condensed renderers. Returns the

package/dist/extension/condensedTools.js

@@ -291,15 +291,23 @@ export function registerCondensedTools(pi, deps = {}) {
     catch {
         toolOptions = { bash: {}, read: {} };
     }
-    const buildDefinitions = (cwd) => ({
-        read: createReadToolDefinition(cwd, toolOptions.read),
-        bash: createBashToolDefinition(cwd, toolOptions.bash),
-        edit: createEditToolDefinition(cwd),
-        write: createWriteToolDefinition(cwd),
-        grep: createGrepToolDefinition(cwd),
-        find: createFindToolDefinition(cwd),
-        ls: createLsToolDefinition(cwd),
-    });
+    const buildDefinitions = (cwd) => {
+        const defs = {
+            read: createReadToolDefinition(cwd, toolOptions.read),
+            bash: createBashToolDefinition(cwd, toolOptions.bash),
+            edit: createEditToolDefinition(cwd),
+            write: createWriteToolDefinition(cwd),
+            grep: createGrepToolDefinition(cwd),
+            find: createFindToolDefinition(cwd),
+            ls: createLsToolDefinition(cwd),
+        };
+        // the sandbox wraps the bash DEFINITION (not the registration
+        // wrapper) so the cwd-delegating execute below still lands on the
+        // sandbox-aware tool for every cwd the session visits.
+        if (defs.bash && deps.wrapBash)
+            defs.bash = deps.wrapBash(defs.bash);
+        return defs;
+    };
     const definitionsByCwd = new Map();
     const definitionsFor = (cwd) => {
         let defs = definitionsByCwd.get(cwd);

package/dist/extension/index.d.ts

@@ -2,6 +2,7 @@ import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { type SpendResponse } from "./costHud.js";
 import { runInitPass as defaultRunInitPass } from "./initPass.js";
 import { startMcp as defaultStartMcp } from "./mcp/startup.js";
+import { type GuardianGateEvent } from "./permission/gate.js";
 import { type FlushOutcome, type SpoolClientOpts } from "./spool.js";
 import { type TokenProvider } from "./tokenProvider.js";
 import { type CatalogResult, type ContextBrief } from "./config.js";
@@ -115,6 +116,15 @@ export declare function buildRunSpendUrl(baseUrl: string, runId: string): string
  * Returns null on anything that doesn't look like the real shape.
  */
 export declare function parseSpendResponse(data: unknown): SpendResponse | null;
+/**
+ * Local trail for EVERY terminal gate outcome (sandbox auto-allow included),
+ * always on so e2e and support can see what the gate did even when the
+ * storage tier is off. Decision K: the always-on line carries outcome
+ * metadata ONLY — no command content. The command prefix and the exec
+ * justification are command/model content and ride the debug tier (never
+ * uploaded by /feedback) plus the opt-in storage stream.
+ */
+export declare function logGateOutcomeTrail(ev: GuardianGateEvent, env: NodeJS.ProcessEnv): void;
 export declare function registerYagni(pi: ExtensionAPI, deps?: RegisterYagniDeps): Promise<void>;
 export default function (pi: ExtensionAPI): Promise<void>;
 export { makeAskYagniTool } from "./askYagniTool.js";

package/dist/extension/index.js

@@ -36,6 +36,9 @@ import { startMcp as defaultStartMcp, wireShutdown, deriveStartupConnectivityNot
 import { registerGoCommand } from "./pipeline/goCommand.js";
 import { registerGoCompareCommand } from "./pipeline/goCompareCommand.js";
 import { DEFAULT_PERMISSION_POLICY, createModeHolder, registerPermissionGate } from "./permission/gate.js";
+import { registerSandbox } from "./sandbox/session.js";
+import { sandboxAutoAllowDecision } from "./sandbox/bash.js";
+import { registerTelemetry } from "./telemetry/register.js";
 import { loadHooksConfig, makeHookRunner, registerHooks } from "./hooks.js";
 import { loadPermissionRules } from "./permissionRules/loadConfig.js";
 import { registerSubagents } from "./subagents.js";
@@ -102,6 +105,39 @@ export function parseSpendResponse(data) {
         return null;
     return d;
 }
+/**
+ * Local trail for EVERY terminal gate outcome (sandbox auto-allow included),
+ * always on so e2e and support can see what the gate did even when the
+ * storage tier is off. Decision K: the always-on line carries outcome
+ * metadata ONLY — no command content. The command prefix and the exec
+ * justification are command/model content and ride the debug tier (never
+ * uploaded by /feedback) plus the opt-in storage stream.
+ */
+export function logGateOutcomeTrail(ev, env) {
+    logEvent({
+        source: "guardian",
+        level: "info",
+        event: "gate_outcome",
+        sessionId: env.YAGNI_SESSION_ID ?? undefined,
+        fields: {
+            outcome: ev.outcome,
+            mode: ev.mode,
+            consulted: ev.consulted,
+        },
+    });
+    if (isDebug(env)) {
+        logEvent({
+            source: "guardian",
+            level: "debug",
+            event: "gate_outcome",
+            sessionId: env.YAGNI_SESSION_ID ?? undefined,
+            fields: {
+                commandPrefix: storagePrefix(ev.command),
+                ...(ev.execJustification ? { execJustification: ev.execJustification } : {}),
+            },
+        });
+    }
+}
 export async function registerYagni(pi, deps = {}) {
     const baseUrl = deps.baseUrl ?? resolveBaseUrl();
     const now = deps.now ?? (() => Date.now());
@@ -379,6 +415,18 @@ export async function registerYagni(pi, deps = {}) {
     // Mutating MCP tools join write/edit/bash in the gate policy: plan mode
     // holds them, review mode confirms them.
     const modeHolder = createModeHolder();
+    // OTel export (traces, metrics, log events; Claude Code parity). A no-op
+    // unless the launcher's gate set YAGNI_OTEL_EXPORT=1 — see the CLI's
+    // otel.ts for the sources and src/telemetry for the exporter.
+    const telemetry = registerTelemetry(pi, { env });
+    {
+        let previousMode = modeHolder.get();
+        modeHolder.onSet((m) => {
+            if (m !== previousMode)
+                telemetry.permissionModeChanged(previousMode, m);
+            previousMode = m;
+        });
+    }
     const footerInvalidateHandle = { invalidateGit: () => { }, requestRender: () => { } };
     const guardianState = makeGuardianState();
     // Disabled by the local env override OR the workspace kill switch
@@ -454,11 +502,35 @@ export async function registerYagni(pi, deps = {}) {
     const hookRunner = evalMode ? null : makeHookRunner({ config: hooksConfig });
     if (!evalMode)
         registerHooks(pi, { config: hooksConfig });
+    // OS-level bash sandboxing. Registers the sandbox-aware bash tool
+    // (dangerouslyDisableSandbox param + wrap + violation annotation) and the
+    // session lifecycle (init/reset, fail-soft unless failIfUnavailable).
+    // Null on unsupported platforms — stock bash stays. Shares the loaded
+    // permission rules so sandbox config and the gate read one rule source.
+    const sandboxHandle = evalMode
+        ? null
+        : registerSandbox(pi, {
+            cwd: process.cwd(),
+            env,
+            hasUI: (ctx) => ctx.hasUI,
+            // Anchors project-protected paths (.yagni-code + its config.json in
+            // denyWrite) and project-sourced permission rules to the repo the
+            // session runs in — same root the gate uses for its rule anchoring.
+            projectRoot: process.cwd(),
+        });
+    if (sandboxHandle)
+        sandboxHandle.setRules(loadedRules.rules);
     registerPermissionGate(pi, {
+        ...(sandboxHandle
+            ? {
+                sandboxAutoAllow: (toolName, params) => sandboxAutoAllowDecision(toolName, params, sandboxHandle.manager, sandboxHandle.settings()),
+            }
+            : {}),
         modeHolder,
         guardianState,
         guardianLimits,
         guardianTier,
+        onToolDecision: (ev) => telemetry.toolDecision(ev),
         ...(loadedRules.rules.length > 0
             ? {
                 permissionRules: loadedRules.rules,
@@ -576,51 +648,50 @@ export async function registerYagni(pi, deps = {}) {
         // rationale. Fire-and-forget: one attempt, short timeout, failures logged
         // fail-soft to the unified sink (source:"guardian") — a storage outage
         // never touches the session.
-        onGuardianEvent: guardianStorageTier === "off" || evalMode
-            ? undefined
-            : (ev) => {
-                void (async () => {
-                    try {
-                        const body = {
-                            sessionId: env.YAGNI_SESSION_ID ?? null,
-                            commandHash: createHash("sha256").update(ev.command).digest("hex"),
-                            commandPrefix: storagePrefix(ev.command),
-                            outcome: ev.outcome,
-                            mode: ev.mode,
-                            ...(ev.execJustification ? { execJustification: ev.execJustification } : {}),
-                            ...(ev.riskLevel ? { riskLevel: ev.riskLevel } : {}),
-                            ...(ev.tier ? { tier: ev.tier } : {}),
-                            ...(ev.durationMs !== undefined ? { durationMs: ev.durationMs } : {}),
-                        };
-                        if (guardianStorageTier === "raw") {
-                            body.command = redactCommand(ev.command);
-                            if (ev.rationale)
-                                body.rationale = redactCommand(ev.rationale);
-                        }
-                        const res = await resilientFetch(`${baseUrl}/api/yagni-code/guardian-events`, {
-                            method: "POST",
-                            headers: {
-                                "content-type": "application/json",
-                                authorization: `Bearer ${getTokenFn() ?? ""}`,
-                                ...attributionHeaders(deps.env),
-                            },
-                            body: JSON.stringify(body),
-                        }, {
-                            fetchImpl: authedFetch,
-                            policy: { maxAttempts: 1, backoffBaseMs: 0, backoffMaxMs: 0, timeoutMs: GUARDIAN_EVENT_TIMEOUT_MS, jitterRatio: 0 },
-                        });
-                        if (!res.ok) {
-                            guardianLogSink({ event: "guardian_event_post_failed", status: res.status });
-                        }
+        onGuardianEvent: (ev) => {
+            logGateOutcomeTrail(ev, env);
+            // Opt-in storage stream (YAG-510): tier decides what leaves the machine.
+            if (guardianStorageTier === "off" || evalMode)
+                return;
+            void (async () => {
+                try {
+                    const body = {
+                        sessionId: env.YAGNI_SESSION_ID ?? null,
+                        commandHash: createHash("sha256").update(ev.command).digest("hex"),
+                        commandPrefix: storagePrefix(ev.command),
+                        outcome: ev.outcome,
+                        mode: ev.mode,
+                        ...(ev.execJustification ? { execJustification: ev.execJustification } : {}),
+                        ...(ev.riskLevel ? { riskLevel: ev.riskLevel } : {}),
+                        ...(ev.tier ? { tier: ev.tier } : {}),
+                        ...(ev.durationMs !== undefined ? { durationMs: ev.durationMs } : {}),
+                    };
+                    if (guardianStorageTier === "raw") {
+                        body.command = redactCommand(ev.command);
+                        if (ev.rationale)
+                            body.rationale = redactCommand(ev.rationale);
                     }
-                    catch {
-                        guardianLogSink({
-                            event: "guardian_event_post_failed",
-                            kind: "network",
-                        });
+                    const res = await resilientFetch(`${baseUrl}/api/yagni-code/guardian-events`, {
+                        method: "POST",
+                        headers: {
+                            "content-type": "application/json",
+                            authorization: `Bearer ${getTokenFn() ?? ""}`,
+                            ...attributionHeaders(deps.env),
+                        },
+                        body: JSON.stringify(body),
+                    }, {
+                        fetchImpl: authedFetch,
+                        policy: { maxAttempts: 1, backoffBaseMs: 0, backoffMaxMs: 0, timeoutMs: GUARDIAN_EVENT_TIMEOUT_MS, jitterRatio: 0 },
+                    });
+                    if (!res.ok) {
+                        guardianLogSink({ event: "guardian_event_post_failed", status: res.status });
                     }
-                })();
-            },
+                }
+                catch {
+                    guardianLogSink({ event: "guardian_event_post_failed", kind: "network" });
+                }
+            })();
+        },
         ...(mcpMutatingSet.size > 0 || mcpOutcome.manager
             ? {
                 policy: {
@@ -852,12 +923,25 @@ export async function registerYagni(pi, deps = {}) {
         try {
             registerCondensedTools(pi, {
                 ...(scratchpadDirPath ? { scratchpadDir: scratchpadDirPath } : {}),
+                // condensed owns the FINAL bash registration (it re-registers
+                // built-ins last), so the sandbox composes INTO it here. Identity when
+                // the sandbox is off.
+                ...(sandboxHandle ? { wrapBash: sandboxHandle.composeBash } : {}),
             });
         }
         catch {
             // Rendering must never break activation; pi's built-ins remain.
         }
     }
+    else if (sandboxHandle && env.YAGNI_CLASSIC_TOOL_ROWS !== "1") {
+        // Condensed inactive (eval mode / desktop): the sandbox's own
+        // registration is the one that reaches the tool registry. NOT under the
+        // classic-rows escape hatch — classic bash must stay pi's stock
+        // registration (the hatch's contract); a competing one would replace
+        // classic rendering with the sandbox's wrap. Desktop/eval still need
+        // the sandbox to reach bash, so the hatch is the one carve-out.
+        sandboxHandle.registerOwnBash();
+    }
     // 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