pi-daddy 0.46.1 → 0.47.0

package/src/governance/auto-mode-policy.ts

@@ -0,0 +1,297 @@
+/** Root-owned live Auto authority. Descendants receive read/admit access, never mutation access. */
+import { randomBytes, randomUUID } from "node:crypto";
+import { chmod, unlink } from "node:fs/promises";
+import { unlinkSync } from "node:fs";
+import { createServer, createConnection, type Socket } from "node:net";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import type {
+  AutoModeReader,
+  AutoModeRef,
+  AutoModeSnapshot,
+  AutoModeSource,
+  PendingApproval,
+} from "../kernel/auto-mode.ts";
+
+const aborted = () => new Error("Auto approval request aborted");
+const unavailable = () => new Error("Auto policy owner is unavailable; no automatic permission was granted");
+const validPending = (value: unknown): value is PendingApproval => {
+  if (!value || typeof value !== "object") return false;
+  const v = value as PendingApproval;
+  return [v.id, v.subject, v.capability].every((x) => typeof x === "string" && x.length > 0 && x.length <= 256);
+};
+export interface AutoModeAuthority extends AutoModeReader {
+  snapshot(): AutoModeSnapshot;
+  set(enabled: boolean, source: AutoModeSource): AutoModeSnapshot;
+}
+
+export async function createAutoModeAuthority(initial: {
+  enabled: boolean;
+  source: AutoModeSource;
+}): Promise<AutoModeAuthority> {
+  const reference = {
+    socketPath: join(tmpdir(), `daddy-auto-${process.pid}-${randomBytes(8).toString("hex")}.sock`),
+    token: randomBytes(24).toString("hex"),
+    ownerId: randomBytes(16).toString("hex"),
+  };
+  let enabled = initial.enabled,
+    source = initial.source,
+    revision = 0,
+    closed = false;
+  const pending = new Map<string, PendingApproval>();
+  const waiters = new Set<() => void>();
+  const sockets = new Set<Socket>();
+  const assertOpen = () => {
+    if (closed) throw unavailable();
+  };
+  const snapshot = (): AutoModeSnapshot => {
+    assertOpen();
+    return {
+      enabled,
+      source,
+      revision,
+      ownerId: reference.ownerId,
+      pendingApprovals: [...pending.values()].map((v) => ({ ...v })),
+    };
+  };
+  const waitEnabled = async (signal: AbortSignal): Promise<void> => {
+    assertOpen();
+    if (signal.aborted) throw aborted();
+    if (enabled) return;
+    await new Promise<void>((resolve, reject) => {
+      const clean = () => {
+        waiters.delete(wake);
+        signal.removeEventListener("abort", cancel);
+      };
+      const wake = () => {
+        clean();
+        closed ? reject(unavailable()) : resolve();
+      };
+      const cancel = () => {
+        clean();
+        reject(aborted());
+      };
+      waiters.add(wake);
+      signal.addEventListener("abort", cancel, { once: true });
+      if (signal.aborted) cancel();
+    });
+  };
+  const trackPending = (approval: PendingApproval) => {
+    assertOpen();
+    if (!validPending(approval)) throw new Error("Invalid pending approval");
+    const key = randomUUID();
+    pending.set(key, { ...approval });
+    return () => {
+      pending.delete(key);
+    };
+  };
+  const server = createServer((socket) => {
+    sockets.add(socket);
+    socket.setEncoding("utf8");
+    socket.setTimeout(2000, () => socket.destroy());
+    const controller = new AbortController();
+    let input = "",
+      handled = false,
+      untrack: (() => void) | undefined;
+    socket.on("error", () => {});
+    socket.once("close", () => {
+      sockets.delete(socket);
+      controller.abort();
+      untrack?.();
+    });
+    const reply = (value: unknown) => {
+      if (!socket.destroyed) socket.end(JSON.stringify(value) + "\n");
+    };
+    socket.on("data", (chunk) => {
+      if (handled) {
+        socket.destroy();
+        return;
+      }
+      input += chunk;
+      if (input.length > 4096) {
+        socket.destroy();
+        return;
+      }
+      if (!input.includes("\n")) return;
+      handled = true;
+      try {
+        const request = JSON.parse(input.slice(0, input.indexOf("\n")));
+        if (request.token !== reference.token || request.ownerId !== reference.ownerId)
+          throw new Error("Unauthorized Auto policy request");
+        assertOpen();
+        if (request.action === "read") reply({ ok: true, value: snapshot() });
+        else if (request.action === "admit") reply({ ok: true, value: enabled });
+        else if (request.action === "wait") {
+          socket.setTimeout(0);
+          void waitEnabled(controller.signal)
+            .then(() => reply({ ok: true }))
+            .catch((error) => reply({ ok: false, error: String(error) }));
+        } else if (request.action === "pending" && validPending(request.approval)) {
+          socket.setTimeout(0);
+          untrack = trackPending(request.approval);
+        } else throw new Error("Unknown Auto policy action");
+      } catch (error) {
+        reply({ ok: false, error: String(error) });
+      }
+    });
+  });
+  await new Promise<void>((resolve, reject) => {
+    server.once("error", reject);
+    server.listen(reference.socketPath, resolve);
+  });
+  try {
+    await chmod(reference.socketPath, 0o600);
+  } catch (error) {
+    server.close();
+    await unlink(reference.socketPath).catch(() => {});
+    throw error;
+  }
+  server.unref();
+  const exit = () => {
+    try {
+      unlinkSync(reference.socketPath);
+    } catch {}
+  };
+  process.once("exit", exit);
+  return {
+    reference,
+    snapshot,
+    read: async () => snapshot(),
+    waitEnabled,
+    trackPending,
+    admit: async (signal) => {
+      assertOpen();
+      if (signal?.aborted) throw aborted();
+      return enabled;
+    },
+    set: (next, from) => {
+      assertOpen();
+      enabled = next;
+      source = from;
+      revision++;
+      if (enabled) for (const wake of [...waiters]) wake();
+      return snapshot();
+    },
+    close: async () => {
+      if (closed) return;
+      closed = true;
+      enabled = false;
+      for (const wake of [...waiters]) wake();
+      for (const socket of sockets) socket.destroy();
+      pending.clear();
+      process.off("exit", exit);
+      await new Promise<void>((resolve) => server.close(() => resolve()));
+      await unlink(reference.socketPath).catch((error) => {
+        if (error.code !== "ENOENT") throw error;
+      });
+    },
+  };
+}
+
+function request(ref: AutoModeRef, action: "read" | "admit" | "wait", signal?: AbortSignal): Promise<unknown> {
+  return new Promise((resolve, reject) => {
+    if (signal?.aborted) {
+      reject(aborted());
+      return;
+    }
+    const socket = createConnection(ref.socketPath);
+    let output = "",
+      settled = false;
+    const finish = (error?: Error, value?: unknown) => {
+      if (settled) return;
+      settled = true;
+      signal?.removeEventListener("abort", cancel);
+      socket.destroy();
+      error ? reject(error) : resolve(value);
+    };
+    const cancel = () => finish(aborted());
+    signal?.addEventListener("abort", cancel, { once: true });
+    socket.setEncoding("utf8");
+    socket.setTimeout(2000, () => finish(unavailable()));
+    socket.once("error", () => finish(unavailable()));
+    socket.once("connect", () => {
+      if (action === "wait") socket.setTimeout(0);
+      socket.write(JSON.stringify({ ...ref, action }) + "\n");
+    });
+    socket.on("data", (chunk) => {
+      output += chunk;
+      if (output.length > 256 * 1024) finish(new Error("Auto policy response too large"));
+    });
+    socket.once("end", () => {
+      try {
+        const reply = JSON.parse(output);
+        if (reply.ok !== true) throw new Error(reply.error ?? "Auto policy request failed");
+        finish(undefined, reply.value);
+      } catch (error) {
+        finish(error instanceof Error ? error : unavailable());
+      }
+    });
+    socket.once("close", () => {
+      if (!settled) finish(unavailable());
+    });
+  });
+}
+
+export function connectAutoMode(reference: AutoModeRef): AutoModeReader {
+  let closed = false;
+  const active = new Set<AbortController>();
+  const pending = new Set<Socket>();
+  const call = async (action: "read" | "admit" | "wait", signal?: AbortSignal) => {
+    if (closed) throw unavailable();
+    const controller = new AbortController();
+    active.add(controller);
+    const abort = () => controller.abort();
+    signal?.addEventListener("abort", abort, { once: true });
+    if (signal?.aborted) abort();
+    try {
+      return await request(reference, action, controller.signal);
+    } finally {
+      active.delete(controller);
+      signal?.removeEventListener("abort", abort);
+    }
+  };
+  return {
+    reference,
+    read: async () => {
+      const value = (await call("read")) as AutoModeSnapshot;
+      if (
+        !value ||
+        value.ownerId !== reference.ownerId ||
+        typeof value.enabled !== "boolean" ||
+        !["default", "environment", "session"].includes(value.source) ||
+        !Number.isSafeInteger(value.revision) ||
+        value.revision < 0 ||
+        !Array.isArray(value.pendingApprovals) ||
+        !value.pendingApprovals.every(validPending)
+      )
+        throw unavailable();
+      return value;
+    },
+    admit: async (signal) => {
+      const value = await call("admit", signal);
+      if (typeof value !== "boolean") throw unavailable();
+      return value;
+    },
+    waitEnabled: async (signal) => {
+      await call("wait", signal);
+    },
+    trackPending: (approval) => {
+      if (closed) throw unavailable();
+      if (!validPending(approval)) throw new Error("Invalid pending approval");
+      const socket = createConnection(reference.socketPath);
+      pending.add(socket);
+      socket.once("error", () => {});
+      socket.once("close", () => pending.delete(socket));
+      socket.once("connect", () => socket.write(JSON.stringify({ ...reference, action: "pending", approval }) + "\n"));
+      return () => {
+        pending.delete(socket);
+        socket.destroy();
+      };
+    },
+    close: async () => {
+      closed = true;
+      for (const controller of active) controller.abort();
+      for (const socket of pending) socket.destroy();
+    },
+  };
+}

package/src/governance/execution-retention.ts

@@ -96,6 +96,9 @@ export const retentionConfigurationDigest = (configuration: unknown): string =>
  * A bounded, coalescing observation queue. No worker-control path awaits publication. A failed or stalled
  * archive never changes required ledger/lease semantics. `flush` is exclusively for external archival at
  * quiescence; it is NOT called by the spawner. Missing terminal publication means incomplete observation.
+ * Streams checkpoint at doubling byte milestones and once at finish: total stream blob bytes are below
+ * three times each stream's largest retained prefix, rather than one cumulative copy per chunk. A crash can lose the newest
+ * suffix since the last checkpoint; running manifests mark that lag. Existing archive files are untouched.
  */
 export function beginExecutionRetention(identity: RetentionIdentity, directory = process.env[ENV_EXECUTION_ARCHIVE]) {
   const archiveId = randomUUID();
@@ -143,6 +146,7 @@ export function beginExecutionRetention(identity: RetentionIdentity, directory =
   };
   const buffers = new Map<keyof typeof manifest.content, Buffer>();
   const written = new Set<string>();
+  const streamCheckpoints = new Map<"stdout" | "stderr", RetainedContent>();
   let total = 0;
   let dirty = false;
   let running: Promise<void> | undefined;
@@ -161,6 +165,9 @@ export function beginExecutionRetention(identity: RetentionIdentity, directory =
   const loss = (reason: string) => {
     if (!manifest.coverage.losses.includes(reason)) manifest.coverage.losses.push(reason);
   };
+  const clearLoss = (reason: string) => {
+    manifest.coverage.losses = manifest.coverage.losses.filter((value) => value !== reason);
+  };
   const release = () => {
     if (admitted && !released) {
       active--;
@@ -178,6 +185,13 @@ export function beginExecutionRetention(identity: RetentionIdentity, directory =
         const checkpoint: ExecutionRetentionManifest = JSON.parse(JSON.stringify(manifest));
         const contents = [...buffers];
         for (const [kind, bytes] of contents) {
+          const stream = kind === "stdout" || kind === "stderr" ? kind : undefined;
+          const previous = stream && streamCheckpoints.get(stream);
+          if (previous && checkpoint.state !== "terminal" && bytes.length < previous.bytes! * 2) {
+            checkpoint.content[kind] = previous;
+            if (bytes.length !== previous.bytes) checkpoint.coverage.losses.push(`${kind}-checkpoint-lagging`);
+            continue;
+          }
           const sha256 = digest(bytes);
           const name = `${kind}-${sha256}.bin`;
           if (!written.has(name)) {
@@ -185,6 +199,7 @@ export function beginExecutionRetention(identity: RetentionIdentity, directory =
             written.add(name);
           }
           checkpoint.content[kind] = { status: "retained", path: name, sha256, bytes: bytes.length };
+          if (stream) streamCheckpoints.set(stream, checkpoint.content[kind]);
         }
         await writeFile(
           join(root!, "manifest.pending"),
@@ -263,6 +278,15 @@ export function beginExecutionRetention(identity: RetentionIdentity, directory =
           manifest.native.branchLeafId = observation.branchLeafId;
           buffers.delete("session");
           if (captured.bytes && observation === captured.observation) buffers.set("session", captured.bytes);
+          if (buffers.has("session") && observation.status === "verified") {
+            clearLoss("native-session-content-unavailable");
+            if (manifest.coverage.losses.includes("native-session-read-failed")) {
+              clearLoss("native-session-read-failed");
+              loss("native-session-read-failed-earlier");
+            }
+          } else loss("native-session-content-unavailable");
+          if (observation.branchState === "observed") clearLoss("active-branch-unknown");
+          else loss("active-branch-unknown");
           if (observation.reason) loss(observation.reason);
           schedule();
         }

package/src/governance/ledger-events.ts

@@ -212,8 +212,9 @@ export interface SessionConfigEvent extends Omit<LedgerEventBase, "correlation">
   event: "session_config";
   episodeId: string;
   outcome: "kept" | "changed";
-  trigger: "first-delegation" | "grants-models";
+  trigger: "first-delegation" | "grants-models" | "auto-mode";
   overrides: Record<string, { model: string; thinking: string }>;
+  autoMode?: { enabled: boolean; source: "default" | "environment" | "session"; revision: number };
 }
 
 export type RuntimeLedgerEvent =
@@ -244,6 +245,26 @@ export function buildSessionConfigEvent(args: {
   });
 }
 
+/** Auto authorization changes are explicit session facts, never fabricated prompt approvals. */
+export function buildAutoModeConfigEvent(args: {
+  episodeId: string;
+  enabled: boolean;
+  source: "default" | "environment" | "session";
+  revision: number;
+  now: Date;
+}): SessionConfigEvent {
+  return assertLedgerV3Wire({
+    ledgerVersion: LEDGER_VERSION,
+    event: "session_config",
+    ts: args.now.toISOString(),
+    episodeId: args.episodeId,
+    outcome: "changed",
+    trigger: "auto-mode",
+    overrides: {},
+    autoMode: { enabled: args.enabled, source: args.source, revision: args.revision },
+  });
+}
+
 export function buildEpisodeOutcomeEvent(args: {
   episodeId: string;
   commit: string;

package/src/governance/ledger-report.ts

@@ -211,8 +211,8 @@ export async function verifyLedger(path: string): Promise<LedgerReport> {
         executors: { herdr: 0, process: 0, unknown: 0 },
         definitions: [],
         approvals: {
-          bySource: { prompt: 0, session: 0, persisted: 0, inherited: 0 },
-          distinctBySource: { prompt: 0, session: 0, persisted: 0, inherited: 0 },
+          bySource: { prompt: 0, session: 0, persisted: 0, inherited: 0, auto: 0 },
+          distinctBySource: { prompt: 0, session: 0, persisted: 0, inherited: 0, auto: 0 },
           unattributed: 0,
           humanDenied: 0,
           humanDeniedPairs: 0,
@@ -243,13 +243,14 @@ export async function verifyLedger(path: string): Promise<LedgerReport> {
   let retired = 0;
   let escalationAttempts = 0;
   const executors = { herdr: 0, process: 0, unknown: 0 };
-  const bySource: Record<ApprovalSource, number> = { prompt: 0, session: 0, persisted: 0, inherited: 0 };
+  const bySource: Record<ApprovalSource, number> = { prompt: 0, session: 0, persisted: 0, inherited: 0, auto: 0 };
   // `capability@subject` seen per source, so the report can state a bound as well as a raw count.
   const distinct: Record<ApprovalSource, Set<string>> = {
     prompt: new Set(),
     session: new Set(),
     persisted: new Set(),
     inherited: new Set(),
+    auto: new Set(),
   };
   let unattributed = 0;
   let humanDenied = 0;
@@ -386,6 +387,7 @@ export async function verifyLedger(path: string): Promise<LedgerReport> {
         session: distinct.session.size,
         persisted: distinct.persisted.size,
         inherited: distinct.inherited.size,
+        auto: distinct.auto.size,
       },
       unattributed,
       humanDenied,

package/src/governance/ledger-v3-validation.ts

@@ -21,7 +21,7 @@ export function isRetiredLedgerEvent(event: { event?: unknown }): boolean {
 
 const SHA256_RE = /^[a-f0-9]{64}$/i;
 const EXECUTORS = new Set(["process", "herdr"]);
-const APPROVAL_SOURCES = new Set(["prompt", "session", "persisted", "inherited"]);
+const APPROVAL_SOURCES = new Set(["prompt", "session", "persisted", "inherited", "auto"]);
 const APPROVAL_SCOPES = new Set(["once", "session", "always"]);
 const GATE_OUTCOMES = new Set(["declined", "dismissed", "expired", "aborted", "no-ui", "error"]);
 const LEASE_OUTCOMES = new Set([
@@ -146,7 +146,7 @@ const FIELDS = {
     "outcome",
     "newCeiling",
   ]),
-  session_config: new Set(["ledgerVersion", "event", "ts", "episodeId", "outcome", "trigger", "overrides"]),
+  session_config: new Set(["ledgerVersion", "event", "ts", "episodeId", "outcome", "trigger", "overrides", "autoMode"]),
   episode_outcome: new Set([
     "ledgerVersion",
     "event",
@@ -537,7 +537,7 @@ export function validateLedgerV3Event(event: LedgerV3Object): string | null {
     if (
       !isEpisodeId(event.episodeId) ||
       !["kept", "changed"].includes(String(event.outcome)) ||
-      !["first-delegation", "grants-models"].includes(String(event.trigger)) ||
+      !["first-delegation", "grants-models", "auto-mode"].includes(String(event.trigger)) ||
       !isLedgerObject(event.overrides) ||
       !Object.entries(event.overrides).every(
         ([name, value]) =>
@@ -549,6 +549,20 @@ export function validateLedgerV3Event(event: LedgerV3Object): string | null {
       )
     )
       return "session config fields are invalid";
+    if (event.trigger === "auto-mode") {
+      const auto = event.autoMode;
+      if (
+        event.outcome !== "changed" ||
+        Object.keys(event.overrides).length !== 0 ||
+        !isLedgerObject(auto) ||
+        Object.keys(auto).length !== 3 ||
+        typeof auto.enabled !== "boolean" ||
+        !["default", "environment", "session"].includes(String(auto.source)) ||
+        !Number.isSafeInteger(auto.revision) ||
+        (auto.revision as number) < 0
+      )
+        return "auto mode config fields are invalid";
+    } else if (event.autoMode !== undefined) return "auto mode config requires its own trigger";
     return null;
   }
   if (kind === "episode_outcome") return validateEpisodeOutcome(event);

package/src/governance/ledger.ts

@@ -414,6 +414,7 @@ export {
   buildEpisodeCostGateEvent,
   buildEpisodeOutcomeEvent,
   buildSessionConfigEvent,
+  buildAutoModeConfigEvent,
   buildWorkspaceLeaseEvent,
   type CapabilityDecisionEvent,
   type EpisodeCostGateEvent,

package/src/kernel/approval.ts

@@ -18,7 +18,7 @@ export const APPROVAL_SCOPES = ["once", "session", "always"] as const;
 export type ApprovalScope = (typeof APPROVAL_SCOPES)[number];
 
 /** Where a yes came from, for the ledger. These call for different follow-ups, so they stay distinct. */
-export const APPROVAL_SOURCES = ["prompt", "session", "persisted", "inherited"] as const;
+export const APPROVAL_SOURCES = ["prompt", "session", "persisted", "inherited", "auto"] as const;
 export type ApprovalSource = (typeof APPROVAL_SOURCES)[number];
 
 /** Which call site is asking. Determines the scopes offered — see `offeredScopes`. */

package/src/kernel/auto-mode.ts

@@ -0,0 +1,56 @@
+/** Live session permission policy. This does not widen a grant or convey stored approval. */
+export type AutoModeSource = "default" | "environment" | "session";
+export interface PendingApproval {
+  id: string;
+  subject: string;
+  capability: string;
+}
+export interface AutoModeSnapshot {
+  enabled: boolean;
+  source: AutoModeSource;
+  ownerId: string;
+  revision: number;
+  pendingApprovals: PendingApproval[];
+}
+export interface AutoModeRef {
+  socketPath: string;
+  token: string;
+  ownerId: string;
+}
+export interface AutoModeReader {
+  readonly reference: AutoModeRef;
+  read(): Promise<AutoModeSnapshot>;
+  /** Linearization point: only a current ON answer admits new work. No approval is banked. */
+  admit(signal?: AbortSignal): Promise<boolean>;
+  /** Notification only. A waiter must read again and later admit its own operation. */
+  waitEnabled(signal: AbortSignal): Promise<void>;
+  trackPending(approval: PendingApproval): () => void;
+  close(): Promise<void>;
+}
+export function parseAutoModeDefault(raw: string | undefined): { enabled: boolean; source: AutoModeSource } {
+  if (raw === undefined) return { enabled: false, source: "default" };
+  if (raw === "0" || raw === "1") return { enabled: raw === "1", source: "environment" };
+  throw new Error("PI_DADDY_AUTO_MODE must be literal 1 or 0 (unset defaults to OFF)");
+}
+export function parseAutoModeRef(raw: string): AutoModeRef {
+  let ref: AutoModeRef;
+  try {
+    ref = JSON.parse(raw);
+  } catch {
+    throw new Error("PI_DADDY_AUTO_MODE_REF is malformed");
+  }
+  if (
+    !ref ||
+    typeof ref !== "object" ||
+    Object.keys(ref).sort().join(",") !== "ownerId,socketPath,token" ||
+    typeof ref.socketPath !== "string" ||
+    !ref.socketPath.startsWith("/") ||
+    ref.socketPath.length > 107 ||
+    typeof ref.token !== "string" ||
+    !/^[a-f0-9]{48}$/.test(ref.token) ||
+    typeof ref.ownerId !== "string" ||
+    !/^[a-f0-9]{32}$/.test(ref.ownerId)
+  )
+    throw new Error("PI_DADDY_AUTO_MODE_REF is malformed");
+  return ref;
+}

package/src/kernel/delegate-types.ts

@@ -1,3 +1,4 @@
+import type { AutoModeRef } from "./auto-mode.ts";
 /**
  * The shapes `planDelegation` consumes and produces. Split out of `./delegate.ts` only to stay under the
  * 400-line module ceiling this project enforces mechanically; `./delegate.ts` re-exports all three, so
@@ -58,6 +59,7 @@ export interface DelegationRequest {
 }
 
 export interface DelegationContext {
+  autoModeRef?: AutoModeRef;
   ownGrant: Capability[];
   /** Stable identity shared by the root session and every descendant. */
   episodeId?: string;

package/src/kernel/delegate.ts

@@ -26,6 +26,7 @@ import {
   ENV_PARENT_ID,
   inheritableGrant,
   workspacePinEnv,
+  autoModeEnv,
 } from "./propagation.ts";
 import { DELEGATE_SUBJECT, inheritApprovals, type InheritableApproval } from "./approval.ts";
 import { explainDoubledNamespace, suggestForUnknown, unknownCapabilities, type Catalog } from "./catalog.ts";
@@ -421,7 +422,7 @@ export function planDelegation(request: DelegationRequest, ctx: DelegationContex
   // spelled once in `childEnv` and not here is a rule that does not hold on the path a delegated child
   // actually takes. Without this a routed grandchild inherits no pin and can route nowhere — fail-closed,
   // but wrong, and silently so.
-  Object.assign(env, workspacePinEnv(ctx.workspacePin, inheritable));
+  Object.assign(env, workspacePinEnv(ctx.workspacePin, inheritable), autoModeEnv(ctx.autoModeRef));
   // Composition-supplied per-child environment (the activity timeline's observation identity today).
   // Never process-global grant state: a key in the governance namespace is a programming error in the
   // caller, refused loudly rather than letting a product widen what the child inherits.

package/src/kernel/env-names.ts

@@ -20,6 +20,8 @@ export const ENV_MAX_DEPTH = "PI_DADDY_MAX_DEPTH";
 export const ENV_GATED = "PI_DADDY_GATED";
 export const ENV_LEDGER = "PI_DADDY_LEDGER";
 export const ENV_APPROVED = "PI_DADDY_APPROVED";
+export const ENV_AUTO_MODE = "PI_DADDY_AUTO_MODE";
+export const ENV_AUTO_MODE_REF = "PI_DADDY_AUTO_MODE_REF";
 export const ENV_FANOUT = "PI_DADDY_FANOUT";
 export const ENV_PARENT_ID = "PI_DADDY_PARENT_ID";
 export const ENV_EXECUTION_ID = "PI_DADDY_EXECUTION_ID";
@@ -86,6 +88,8 @@ export const GOVERNANCE_ENV_KEYS: readonly string[] = Object.freeze([
   ENV_GATED,
   ENV_LEDGER,
   ENV_APPROVED,
+  ENV_AUTO_MODE,
+  ENV_AUTO_MODE_REF,
   ENV_FANOUT,
   ENV_PARENT_ID,
   ENV_EXECUTION_ID,

package/src/kernel/propagation.ts

@@ -25,7 +25,8 @@
  * interceptor and pi handed the child more than the parent held, the intersection clamps it back.
  */
 
-import { ENV_PUBLIC_EVIDENCE_DIR } from "./env-names.ts";
+import { ENV_AUTO_MODE, ENV_AUTO_MODE_REF, ENV_PUBLIC_EVIDENCE_DIR } from "./env-names.ts";
+import type { AutoModeRef } from "./auto-mode.ts";
 import type { Capability } from "./resolve.ts";
 import { attenuateWorkspacePin, formatWorkspacePin, type WorkspacePins } from "./workspace-pin.ts";
 import { WILDCARD } from "./pi-tools.ts";
@@ -87,6 +88,8 @@ export {
  * to give it.
  */
 export const GRANT_ENV_KEYS = [
+  ENV_AUTO_MODE,
+  ENV_AUTO_MODE_REF,
   ENV_PUBLIC_EVIDENCE_DIR,
   // Not governance state, but the same rule applies for a stronger reason: neither a credential the parent holds
   // nor the switch that points it at a third party is something a child inherits by being spawned (ADR-0077).
@@ -265,6 +268,7 @@ export function gatedFromEnv(raw: string | undefined): Capability[] {
 }
 
 export interface ChildEnvInput {
+  autoModeRef?: AutoModeRef;
   /** This session's own grant — becomes the child's inherited parent grant. */
   ownGrant: Capability[];
   /**
@@ -362,7 +366,7 @@ export function childEnv(input: ChildEnvInput): Record<string, string> {
   // `ENV_APPROVED` is: an omitted key does not overwrite, so a child would inherit the PARENT's unnarrowed pin
   // through the process-global publication path. An empty value parses back as "a pin was established and you
   // got nothing from it", which refuses at routing with a different message from "no pin exists".
-  Object.assign(env, workspacePinEnv(input.workspacePin, inheritable));
+  Object.assign(env, workspacePinEnv(input.workspacePin, inheritable), autoModeEnv(input.autoModeRef));
   return env;
 }
 
@@ -427,3 +431,8 @@ export function observeToolNames(payload: unknown): string[] | null {
   }
   return null;
 }
+
+/** A root preference is never copied; every descendant receives the same live owner reference. */
+export function autoModeEnv(ref: AutoModeRef | undefined): Record<string, string> {
+  return { [ENV_AUTO_MODE]: "0", ...(ref ? { [ENV_AUTO_MODE_REF]: JSON.stringify(ref) } : {}) };
+}