pi-daddy 0.46.0 → 0.47.0

package/extensions/ecosystem-versions.ts

@@ -0,0 +1,166 @@
+/** Report loaded package generations separately from the manifests currently installed on disk. */
+import {
+  DefaultPackageManager,
+  SettingsManager,
+  VERSION,
+  getPackageDir,
+  type ExtensionAPI,
+  type ExtensionContext,
+} from "@earendil-works/pi-coding-agent";
+import { join, resolve } from "node:path";
+import { readBoundedTextSync } from "../src/kernel/bounded-read-sync.ts";
+import { agentDir } from "../src/kernel/project-paths.ts";
+import type { EcosystemPackageId, EcosystemVersionRow, EcosystemVersions } from "../src/products/ecosystem-versions.ts";
+
+const CHANNEL = "pi-daddy:ecosystem-versions:v1";
+const packages = [
+  { id: "pi", label: "Pi", names: ["@earendil-works/pi-coding-agent"] },
+  { id: "pi-daddy", label: "pi-daddy", names: ["pi-daddy"] },
+  { id: "principal-pi-skills", label: "Principal", names: ["principal-pi-skills"] },
+  { id: "skill-harness", label: "Harness", names: ["skill-harness", "skill-harness-monorepo"] },
+] as const;
+interface LoadedPackage {
+  id: EcosystemPackageId;
+  version: string | null;
+  root: string;
+}
+const versionPattern = /^\d+\.\d+\.\d+(?:[-+][0-9A-Za-z.-]+)?$/;
+function manifest(root: string, names: readonly string[]): string | null {
+  try {
+    const value = JSON.parse(readBoundedTextSync(join(root, "package.json"), { maxBytes: 128 * 1024 }).text);
+    return names.includes(value.name) && typeof value.version === "string" && versionPattern.test(value.version)
+      ? value.version
+      : null;
+  } catch {
+    return null;
+  }
+}
+export interface VersionInventoryPorts {
+  hostVersion: string;
+  hostRoot: string;
+  ownRoot: string;
+  readVersion(root: string, names: readonly string[]): string | null;
+  configured(ctx: ExtensionContext): Array<{ source: string; scope: "user" | "project"; installedPath?: string }>;
+}
+const defaultPorts = (ownRoot: string): VersionInventoryPorts => ({
+  hostVersion: VERSION,
+  hostRoot: getPackageDir(),
+  ownRoot,
+  readVersion: manifest,
+  configured: (ctx) =>
+    new DefaultPackageManager({
+      cwd: ctx.cwd,
+      agentDir: agentDir(),
+      settingsManager: SettingsManager.create(ctx.cwd, agentDir(), {
+        projectTrusted: ctx.isProjectTrusted?.() === true,
+      }),
+    }).listConfiguredPackages(),
+});
+/** Every package answers synchronously on Pi's native event bus; old packages stay explicitly unreported. */
+export function createEcosystemVersionInventory(
+  pi: Pick<ExtensionAPI, "events">,
+  ownRoot: string,
+  ports = defaultPorts(ownRoot),
+) {
+  const own: LoadedPackage = {
+    id: "pi-daddy",
+    root: ports.ownRoot,
+    version: ports.readVersion(ports.ownRoot, ["pi-daddy"]),
+  };
+  return (ctx: ExtensionContext): EcosystemVersions => {
+    const reports: LoadedPackage[] = [own, { id: "pi", root: ports.hostRoot, version: ports.hostVersion }];
+    pi.events?.emit(CHANNEL, {
+      report: (value: unknown) => {
+        if (!value || typeof value !== "object") return;
+        const item = value as LoadedPackage;
+        if (
+          !["principal-pi-skills", "skill-harness"].includes(item.id) ||
+          typeof item.root !== "string" ||
+          !item.root.startsWith("/")
+        )
+          return;
+        if (typeof item.version !== "string" || !versionPattern.test(item.version)) return;
+        reports.push({ id: item.id, root: item.root, version: item.version });
+      },
+    });
+    let configured: ReturnType<VersionInventoryPorts["configured"]> = [],
+      note: string | undefined;
+    try {
+      configured = ports.configured(ctx);
+    } catch {
+      note = "Configured package sources unavailable; loaded reports remain visible.";
+    }
+    const rows: EcosystemVersionRow[] = packages.map((pkg) => {
+      const loaded = reports.filter((item) => item.id === pkg.id);
+      const sources = configured.filter(
+        (item) =>
+          item.source === `npm:${pkg.id}` ||
+          item.source.startsWith(`npm:${pkg.id}@`) ||
+          (item.installedPath !== undefined && ports.readVersion(item.installedPath, pkg.names) !== null) ||
+          loaded.some((x) => item.installedPath && resolve(item.installedPath) === resolve(x.root)),
+      );
+      const source = sources.length === 1 ? sources[0] : undefined;
+      const root = loaded.length === 1 ? loaded[0].root : loaded.length === 0 ? source?.installedPath : undefined;
+      const installedVersion = root ? ports.readVersion(root, pkg.names) : null;
+      const loadedVersion = loaded.length === 1 ? loaded[0].version : null;
+      const observedRoots = new Set([
+        ...loaded.map((item) => resolve(item.root)),
+        ...sources.flatMap((item) => (item.installedPath ? [resolve(item.installedPath)] : [])),
+      ]);
+      const multiple =
+        loaded.length > 1 ||
+        sources.length > 1 ||
+        observedRoots.size > 1 ||
+        (loaded.length > 0 && sources.some((item) => !item.installedPath));
+      const commands =
+        pkg.id === "pi"
+          ? ["pi update"]
+          : source?.source.startsWith("npm:") && !multiple
+            ? [`pi install${source.scope === "project" ? " --local" : ""} npm:${pkg.id}@<version>`]
+            : ["pi list", "pi config"];
+      if (pkg.id === "principal-pi-skills" && root && !multiple) {
+        const installer = "'" + join(root, "scripts/install-agents.mjs").replaceAll("'", "'\\''") + "'";
+        commands.push(`node ${installer} install`, `node ${installer} check`);
+      }
+      return {
+        id: pkg.id,
+        label: pkg.label,
+        loadedVersion,
+        installedVersion,
+        source: multiple ? null : (source?.source ?? (pkg.id === "pi" ? "host runtime" : null)),
+        path: root ?? null,
+        state: multiple
+          ? "multiple"
+          : loadedVersion && installedVersion
+            ? loadedVersion === installedVersion
+              ? "current"
+              : "reload-required"
+            : !loadedVersion && installedVersion
+              ? "not-reported"
+              : "unavailable",
+        commands,
+        note: multiple
+          ? "Multiple loaded or configured sources; inspect with pi list before changing versions."
+          : !loadedVersion
+            ? "This package did not report its loaded generation. Installed bytes alone do not establish the running version."
+            : pkg.id === "pi"
+              ? "Restart Pi after changing its version."
+              : "Use an explicit npm version to replace a pin; pi update keeps pinned versions. Reload Pi after installation." +
+                (pkg.id === "principal-pi-skills"
+                  ? " Agent installer commands are optional, for legacy installed agent definitions."
+                  : ""),
+      };
+    });
+    return { rows, checkedAt: new Date().toISOString(), note };
+  };
+}
+export function bindEcosystemVersions(
+  pi: ExtensionAPI,
+  session: { ecosystemVersions?: () => EcosystemVersions },
+  ownRoot: string,
+): void {
+  const read = createEcosystemVersionInventory(pi, ownRoot);
+  pi.on("session_start", (_event, ctx) => {
+    session.ecosystemVersions = () => read(ctx);
+  });
+}

package/extensions/execution-controls.ts

@@ -0,0 +1,42 @@
+/** Operator-facing execution settings; display never changes admission, deadlines or retention. */
+import { timeoutFromEnv, idleTimeoutFromEnv } from "../src/kernel/run-child.ts";
+import { timeoutMsFromEnv } from "../src/governance/approval-prompt.ts";
+import {
+  ENV_APPROVAL_TIMEOUT,
+  ENV_CHILD_TIMEOUT,
+  ENV_CHILD_IDLE_TIMEOUT,
+  ENV_EXECUTION_ARCHIVE,
+} from "../src/kernel/env-names.ts";
+
+export function renderExecutionControls(
+  nativeSessionRoot: string | undefined,
+  env: NodeJS.ProcessEnv = process.env,
+): string[] {
+  let approval: string;
+  try {
+    const timeout = timeoutMsFromEnv(env[ENV_APPROVAL_TIMEOUT]);
+    approval = timeout === undefined ? "wait for human; no deadline" : `${timeout / 1000}s configured deadline`;
+  } catch {
+    approval = `${ENV_APPROVAL_TIMEOUT} invalid; a needed new prompt will refuse`;
+  }
+  const source = (key: string) => (env[key] === undefined ? "default" : `from ${key}; zero/invalid uses default`);
+  return [
+    `  child wall ${timeoutFromEnv(env[ENV_CHILD_TIMEOUT]) / 1000}s (${source(ENV_CHILD_TIMEOUT)})`,
+    `  child idle ${idleTimeoutFromEnv(env[ENV_CHILD_IDLE_TIMEOUT]) / 1000}s (${source(ENV_CHILD_IDLE_TIMEOUT)})`,
+    "             process safety controls; no time/token budget is added to the model prompt",
+    `  approval   ${approval}`,
+    `  transcripts ${
+      nativeSessionRoot === undefined
+        ? "off"
+        : nativeSessionRoot
+          ? `opted in at ${JSON.stringify(nativeSessionRoot)}; destination checked at dispatch`
+          : "opted in but native session root is missing"
+    }`,
+    `  diagnostics ${
+      env[ENV_EXECUTION_ARCHIVE]
+        ? `configured at ${JSON.stringify(env[ENV_EXECUTION_ARCHIVE])}; check each result's retention status`
+        : "off"
+    }`,
+    "             local diagnostic retention is separate from JEV/LoRA consent",
+  ];
+}

package/extensions/grants-command.ts

@@ -12,6 +12,7 @@
  * being whatever happened to be in scope.
  */
 
+import { renderExecutionControls } from "./execution-controls.ts";
 import type { Capability } from "../src/kernel/resolve.ts";
 import type { ExecutorChoice } from "../src/executors/executor.ts";
 import type { Catalog } from "../src/kernel/catalog.ts";
@@ -25,6 +26,11 @@ import type { ResolvedDefinitionRuntime } from "./definition-runtime.ts";
 export interface GrantsCommandContext {
   cwd: string;
   governed: boolean;
+  /** Host opt-in captured by this session, not a later environment reread. */
+  nativeSessionRoot?: string;
+  autoModeStatus?: string;
+  /** Explicit owner mutation; the command parser itself holds no permission authority. */
+  changeAutoMode?: (enabled: boolean) => Promise<string>;
   ownGrant: Capability[];
   /**
    * Which executor this session settled on, and why — ADR-0031.
@@ -100,12 +106,13 @@ const KNOWN_SUBCOMMANDS: readonly string[] = [
   "revoke",
   "workspaces",
   "models",
+  "auto",
 ];
 
 export const grantsCommand = {
   description:
     "Show this session's capability grant, delegation depth, and known agent-type ceilings; " +
-    "/grants init | /grants dashboard | /grants approvals | /grants revoke | /grants ledger",
+    "/grants init | /grants dashboard | /grants auto [on|off] | /grants approvals | /grants revoke | /grants ledger",
   handler: async (args: string, ctx: any) => {
     // Everything this command may see, named in one place. Previously these were whatever happened to be in
     // the enclosing closure — which is how a diagnostic came to disagree with the enforcer (R-28).
@@ -129,7 +136,32 @@ export const grantsCommand = {
       runtimeFor,
     } = ctx.grants as GrantsCommandContext;
 
-    const [sub, target] = args.trim().split(/\s+/).filter(Boolean);
+    const words = args.trim().split(/\s+/).filter(Boolean);
+    const [sub, target] = words;
+    if (sub === "auto") {
+      if (words.length > 2 || (target !== undefined && target !== "on" && target !== "off")) {
+        ctx.ui.notify("grants: use /grants auto [on|off]; no permission setting changed.", "warning");
+        return;
+      }
+      if (target === undefined) {
+        ctx.ui.notify(`grants: Daddy permission Auto ${ctx.grants.autoModeStatus ?? "unavailable"}`, "info");
+        return;
+      }
+      if (!ctx.grants.changeAutoMode) {
+        ctx.ui.notify("grants: Daddy Auto controls are unavailable for this session owner.", "warning");
+        return;
+      }
+      try {
+        const status = await ctx.grants.changeAutoMode(target === "on");
+        ctx.ui.notify(`grants: Daddy permission Auto ${status}; admitted work continues.`, "info");
+      } catch (error) {
+        ctx.ui.notify(
+          `grants: Auto change not confirmed: ${String(error)}. Read /grants auto for current state.`,
+          "error",
+        );
+      }
+      return;
+    }
 
     if (sub === "init") {
       await ctx.grants.runInit();
@@ -261,7 +293,7 @@ export const grantsCommand = {
       if (attributed > 0 || unattributed > 0) {
         lines.push(
           `  approvals  ${bySource.prompt} prompt · ${bySource.persisted} persisted · ${bySource.session} session · ` +
-            `${bySource.inherited} inherited`,
+            `${bySource.inherited} inherited · ${bySource.auto} auto`,
         );
         // **Two numbers, because one of them would lie.** Counting `persisted` RECORDS as prompts avoided
         // overstates the layer twentyfold in the obvious case: precedence is inherited → session →
@@ -407,6 +439,8 @@ export const grantsCommand = {
       // ADR-0031, and its probe is only defensible because this line exists. Placed next to `holding` so the
       // two facts about what a spawn will be sit together.
       `  executor   ${executor.disclosure}`,
+      ...renderExecutionControls(ctx.grants.nativeSessionRoot),
+      `  Auto       ${ctx.grants.autoModeStatus ?? "OFF (default)"}`,
       `  depth      ${depth} of max ${maxDepth}${maxDepth <= 0 ? " (spawning disabled)" : ""}`,
       `  ledger     ${ledgerPath || "(not recording — set PI_DADDY_LEDGER)"}`,
       `  approvals  ${sessionApprovals.size} this session, ${valid.size} persisted` +

package/extensions/grants.ts

@@ -1,3 +1,10 @@
+import { bindEcosystemVersions } from "./ecosystem-versions.ts";
+import {
+  initializeSessionAutoMode,
+  closeSessionAutoMode,
+  getDashboardControlState,
+  setAutoApproval,
+} from "./session-auto-mode.ts";
 /**
  * pi-daddy — the extension entry point pi loads.
  *
@@ -79,6 +86,7 @@ export default function (pi: ExtensionAPI, trustedSession?: GrantsSession) {
   })();
   const observerExtensionPath = fileURLToPath(new URL("./activity-timeline.ts", import.meta.url));
   const session = trustedSession ?? createGrantsSession(extensionPath, undefined, observerExtensionPath);
+  bindEcosystemVersions(pi, session, fileURLToPath(new URL("../", import.meta.url)));
   session.currentThinking = typeof pi.getThinkingLevel === "function" ? () => pi.getThinkingLevel() : undefined;
   registerActivityTimeline(pi, session);
   const runtimeSnapshot = registerRuntimeSnapshot(pi, session);
@@ -131,6 +139,13 @@ export default function (pi: ExtensionAPI, trustedSession?: GrantsSession) {
     // this absolute identity verbatim, and resolve(abs) remains abs at every deeper session start.
     if (session.ledgerPath) session.ledgerPath = resolve(ctx.cwd, session.ledgerPath);
     try {
+      try {
+        const nativeId = (owner as { getSessionId?: () => string }).getSessionId?.() ?? session.episodeId;
+        await initializeSessionAutoMode(session, reload.environment, nativeId);
+      } catch (error) {
+        session.autoModeFailure = `Daddy Auto mode unavailable: ${String(error)}`;
+        throw error;
+      }
       // ADR-0076 PR 3d: a pre-format project ledger is imported once into the record envelope, bodies verbatim, each
       // record marked with its source line; the old file is left untouched. Happens before any spawn can append.
       if (session.governed) {
@@ -319,6 +334,10 @@ export default function (pi: ExtensionAPI, trustedSession?: GrantsSession) {
     return undefined;
   });
 
+  pi.on("session_shutdown", async (event) => {
+    if (event.reason !== "reload") await closeSessionAutoMode(session);
+  });
+
   /**
    * Reap the herdr panes this agent run opened — ADR-0032.
    *
@@ -433,8 +452,8 @@ export default function (pi: ExtensionAPI, trustedSession?: GrantsSession) {
     // Built per invocation and spelled out field by field, rather than passing the session whole: what a
     // read-only diagnostic may see is a decision, and `GrantsCommandContext` is where it is recorded.
     handler: async (args, ctx) => {
-      // Named revocation validates the current definition. Emergency revoke-all needs no resource acquisition.
-      if (args.trim() !== "revoke --all") await session.ensureDefinitions?.();
+      // Auto controls and emergency revoke-all need no definition acquisition; OFF must remain reachable.
+      if (args.trim() !== "revoke --all" && args.trim().split(/\s+/)[0] !== "auto") await session.ensureDefinitions?.();
       return grantsCommand.handler(args, {
         ...ctx,
         grants: {
@@ -462,6 +481,14 @@ export default function (pi: ExtensionAPI, trustedSession?: GrantsSession) {
                 },
               }
             : {}),
+          nativeSessionRoot: session.nativeSessionRoot,
+          changeAutoMode: async (enabled: boolean) => {
+            const { auto } = await setAutoApproval(session, enabled, "command");
+            return `${auto.enabled ? "ON" : "OFF"} (${auto.source}; current session permissions)`;
+          },
+          autoModeStatus: await getDashboardControlState(session)
+            .then(({ auto }) => `${auto.enabled ? "ON" : "OFF"} (${auto.source}; current session permissions)`)
+            .catch((error) => `unavailable: ${String(error)}`),
           catalog: session.catalog,
           definitions: session.definitions,
           sessionApprovals: session.sessionApprovals,

package/extensions/reload-environment.ts

@@ -1,9 +1,11 @@
+import { ENV_AUTO_MODE, ENV_AUTO_MODE_REF } from "../src/kernel/env-names.ts";
 import type { OwnerCapacity } from "./session-capacity.ts";
 import { GRANT_ENV_KEYS } from "../src/kernel/propagation.ts";
 import type { BoundedReadCleanupError } from "../src/kernel/bounded-read.ts";
 
 /** The root baseline and latest child publication for one real Pi session owner. */
 export interface ReloadLifecycle {
+  autoMode?: import("./session-auto-mode.ts").SessionAutoLifecycle;
   runtimeSnapshotUnsubscribe?: () => void;
   runtimeSnapshotGeneration?: object;
   runtimeSettlements?: Map<string, import("../src/governance/runtime-settlement.ts").RuntimeSettlement>;
@@ -59,7 +61,19 @@ function withRoot(root: Record<string, string | undefined>): NodeJS.ProcessEnv {
 
 /** Factory-time state is provisional: ExtensionAPI is recreated before the stable session owner is known. */
 export function beginExtensionLifecycle(): { environment: NodeJS.ProcessEnv; lifecycle: ReloadLifecycle } {
-  return { environment: process.env, lifecycle: { root: snapshot() } };
+  const root = snapshot();
+  const publication = state().latestChildPublication;
+  if (
+    publication?.environment[ENV_AUTO_MODE_REF] &&
+    root[ENV_AUTO_MODE_REF] === publication.environment[ENV_AUTO_MODE_REF]
+  ) {
+    // Recognize our own published Auto reference independently of unrelated grant setting changes.
+    // A new SDK owner must not adopt another local owner; a real descendant has no local publication.
+    if (root[ENV_AUTO_MODE] === publication.environment[ENV_AUTO_MODE])
+      root[ENV_AUTO_MODE] = publication.lifecycle.root[ENV_AUTO_MODE];
+    root[ENV_AUTO_MODE_REF] = publication.lifecycle.root[ENV_AUTO_MODE_REF];
+  }
+  return { environment: withRoot(root), lifecycle: { root } };
 }
 
 /**
@@ -100,6 +114,7 @@ export function bindReloadLifecycle(
       // Pending old-root operations keep THEIR original owner; they cannot publish/fault this replacement.
       existing = {
         root: current,
+        autoMode: existing.autoMode,
         activityRootId: existing.activityRootId,
         episodeId: existing.episodeId,
         capacity: existing.capacity,

package/extensions/run-delegation.ts

@@ -79,6 +79,13 @@ export interface GatedPlan {
   approval?: ApprovalOutcome;
 }
 
+/** Discard provisional Auto facts when OFF or a policy error requires a fresh decision. */
+function forgetAutoApprovals(outcome: ApprovalOutcome, capabilities: string[]): void {
+  outcome.approved = outcome.approved.filter((capability) => !capabilities.includes(capability));
+  for (const field of ["sources", "scopes", "recordedScopes", "bindings", "expiresAt", "uses"] as const)
+    for (const capability of capabilities) delete outcome[field][capability];
+}
+
 /**
  * Plan a delegation and satisfy its gate as far as approvals allow.
  *
@@ -143,12 +150,13 @@ export async function planWithApprovals(
       plan.approvalBinding,
     );
     const outcome = approval;
-    if (outcome.approved.length > 0) {
-      plan = observedPlan({
+    while (outcome.approved.length > 0) {
+      const context = {
         // The scope is the REAL one: a `once` approval still authorises this spawn, and
         // `inheritApprovals` then keeps it from reaching the child. See ADR-0014. R-29 is what makes
         // this safe under fan-out: a `once` is consumed by exactly one concurrent caller.
         ...(await session.delegationContext([
+          ...(preApproved ?? []),
           ...republishable(session),
           ...outcome.approved.map((capability) => ({
             capability,
@@ -167,7 +175,35 @@ export async function planWithApprovals(
           })),
         ])),
         ...extra,
-      });
+      };
+      const automatic = outcome.approved.filter((capability) => outcome.sources[capability] === "auto");
+      // The owner serializes this check with OFF. Permission is admitted here, after context preparation;
+      // a later OFF does not cancel a delegation already admitted to its load-bearing ledger write.
+      if (automatic.length > 0 && !(await session.autoMode?.admit(signal))) {
+        const renewed = await obtainApprovals(
+          session,
+          automatic,
+          approvalSubject,
+          request.agent ? "definition" : "delegate",
+          ctx,
+          request.task,
+          signal,
+          plan.approvalBinding,
+        );
+        forgetAutoApprovals(outcome, automatic);
+        outcome.approved.push(...renewed.approved);
+        for (const field of ["sources", "scopes", "recordedScopes", "bindings", "expiresAt", "uses"] as const)
+          Object.assign(outcome[field], renewed[field]);
+        outcome.banked = [...(outcome.banked ?? []), ...(renewed.banked ?? [])];
+        outcome.humanDenied ||= renewed.humanDenied;
+        outcome.gateOutcome = renewed.gateOutcome;
+        outcome.refusalCode = renewed.refusalCode;
+        outcome.reason = renewed.reason;
+        if (automatic.some((capability) => !renewed.approved.includes(capability))) break;
+        continue;
+      }
+      plan = observedPlan(context);
+      break;
     }
     if (!plan.ok && approval.reason) {
       plan = {
@@ -178,6 +214,16 @@ export async function planWithApprovals(
     }
   } catch (error) {
     const message = `grants: approval flow failed, denying (${String(error)})`;
+    if (approval) {
+      const failed = approval;
+      forgetAutoApprovals(
+        failed,
+        failed.approved.filter((capability) => failed.sources[capability] === "auto"),
+      );
+      approval.gateOutcome = "error";
+      approval.refusalCode = "APPROVAL_FLOW_FAILED";
+      approval.reason = message;
+    }
     plan = { ...plan, reason: message, refusal: structuredRefusal("APPROVAL_FLOW_FAILED", message) };
   }
 

package/extensions/session-auto-mode.ts

@@ -0,0 +1,132 @@
+/** Session-owned Auto policy. Dashboard mutations never become banked or inherited approvals. */
+import type { AutoModeReader, AutoModeSource } from "../src/kernel/auto-mode.ts";
+import { parseAutoModeDefault, parseAutoModeRef } from "../src/kernel/auto-mode.ts";
+import { ENV_AUTO_MODE, ENV_AUTO_MODE_REF } from "../src/kernel/env-names.ts";
+import {
+  createAutoModeAuthority,
+  connectAutoMode,
+  type AutoModeAuthority,
+} from "../src/governance/auto-mode-policy.ts";
+import { appendLedgerEvent, buildAutoModeConfigEvent } from "../src/governance/ledger.ts";
+import type { GrantsSession } from "./session.ts";
+
+export interface SessionAutoLifecycle {
+  nativeSessionId: string;
+  reader: AutoModeReader;
+  authority?: AutoModeAuthority;
+  updates: Promise<unknown>;
+}
+const stale = () => new Error("Daddy Auto controls are unavailable for this session owner");
+function current(session: GrantsSession): SessionAutoLifecycle {
+  const state = session.reloadLifecycle.autoMode;
+  if (!session.ownerBound || !state || session.autoMode !== state.reader) throw stale();
+  return state;
+}
+async function record(
+  session: GrantsSession,
+  enabled: boolean,
+  source: AutoModeSource,
+  revision: number,
+): Promise<void> {
+  if (!session.ledgerPath) return;
+  await appendLedgerEvent(
+    { path: session.ledgerPath, strict: true },
+    buildAutoModeConfigEvent({
+      episodeId: session.episodeId,
+      enabled,
+      source,
+      revision,
+      now: new Date(),
+    }),
+  );
+}
+
+export async function initializeSessionAutoMode(
+  session: GrantsSession,
+  environment: NodeJS.ProcessEnv,
+  nativeSessionId: string,
+): Promise<void> {
+  const lifecycle = session.reloadLifecycle;
+  let state = lifecycle.autoMode;
+  if (session.autoMode && session.autoMode !== state?.reader) await session.autoMode.close();
+  if (state && state.nativeSessionId !== nativeSessionId) {
+    await state.reader.close();
+    delete lifecycle.autoMode;
+    state = undefined;
+  }
+  if (state) {
+    session.autoMode = state.reader;
+    return;
+  }
+  const rawRef = environment[ENV_AUTO_MODE_REF];
+  if (rawRef !== undefined) {
+    // A descendant always consults its actual owner. A dead/malformed owner must not mint a new root.
+    const reader = connectAutoMode(parseAutoModeRef(rawRef));
+    try {
+      await reader.read();
+    } catch (error) {
+      await reader.close();
+      throw error;
+    }
+    state = { nativeSessionId, reader, updates: Promise.resolve() };
+  } else {
+    const initial = parseAutoModeDefault(environment[ENV_AUTO_MODE]);
+    const authority = await createAutoModeAuthority({ enabled: false, source: initial.source });
+    try {
+      if (initial.enabled) {
+        await record(session, true, initial.source, 1);
+        authority.set(true, initial.source);
+      }
+    } catch (error) {
+      await authority.close();
+      throw error;
+    }
+    state = { nativeSessionId, reader: authority, authority, updates: Promise.resolve() };
+  }
+  if (session.reloadLifecycle !== lifecycle) {
+    await state.reader.close();
+    throw stale();
+  }
+  lifecycle.autoMode = state;
+  session.autoMode = state.reader;
+  delete session.autoModeFailure;
+}
+
+export async function getDashboardControlState(session: GrantsSession) {
+  const state = current(session);
+  const value = await state.reader.read();
+  if (current(session) !== state) throw stale();
+  return { auto: { enabled: value.enabled, source: value.source }, pendingApprovals: value.pendingApprovals };
+}
+
+export async function setAutoApproval(session: GrantsSession, enabled: boolean, source: "dashboard" | "command") {
+  if (typeof enabled !== "boolean" || (source !== "dashboard" && source !== "command"))
+    throw new Error("Invalid Daddy Auto mode edit");
+  const state = current(session);
+  if (!state.authority) throw new Error("Only the owning root session may change Daddy Auto mode");
+  // Serialize operator edits. OFF remains effective even if its audit write fails; failed ON never enables.
+  const update = state.updates
+    .catch(() => {})
+    .then(async () => {
+      if (current(session) !== state) throw stale();
+      const before = state.authority!.snapshot();
+      if (enabled) {
+        await record(session, true, "session", before.revision + 1);
+        if (current(session) !== state) throw stale();
+        state.authority!.set(true, "session");
+      } else {
+        const after = state.authority!.set(false, "session");
+        await record(session, false, "session", after.revision);
+      }
+      return getDashboardControlState(session);
+    });
+  state.updates = update;
+  return update;
+}
+
+export async function closeSessionAutoMode(session: GrantsSession): Promise<void> {
+  const reader = session.autoMode;
+  delete session.autoMode;
+  if (reader && session.reloadLifecycle.autoMode?.reader === reader) delete session.reloadLifecycle.autoMode;
+  await reader?.close();
+}