pi-daddy 0.32.1 → 0.35.0

package/extensions/session.ts

@@ -48,6 +48,11 @@ import type { GrantStoreRefusalReason } from "../src/governance/grant-store.ts";
 import { republishable } from "./approvals.ts";
 import { storedGrantSessionState } from "./stored-grant-session.ts";
 import { nativeSessionRootFromEnv, type NativeSessionHost } from "../src/executors/native-session-target.ts";
+import { createHandoffStager, type ParentSession } from "./context-staging.ts";
+import { createAdvisorSession, type AdvisorSession } from "./advisor-session.ts";
+import { join } from "node:path";
+import { readFileSync, statSync } from "node:fs";
+import { agentDir, projectSettingsPath } from "../src/kernel/project-paths.ts";
 import { ENV_ALLOW_UNRESOLVED_MODELS } from "../src/kernel/model-preflight.ts";
 import { beginExtensionLifecycle, rememberChildPublication, type ReloadLifecycle } from "./reload-environment.ts";
 import { reconcileSessionEnvironment } from "./session-environment.ts";
@@ -84,7 +89,7 @@ import {
   ENV_ACTIVITY_ROOT,
   ENV_ACTIVITY_TASK,
 } from "../src/products/activity-timeline.ts";
-import { ENV_HERDR_KEEP_PANE, ENV_GOVERNANCE } from "../src/kernel/env-names.ts";
+import { ENV_HERDR_KEEP_PANE, ENV_GOVERNANCE, ENV_ADVISOR } from "../src/kernel/env-names.ts";
 export { ENV_HERDR_KEEP_PANE, ENV_GOVERNANCE } from "../src/kernel/env-names.ts";
 import { adoptLegacyEnvironment } from "../src/kernel/env-names.ts";
 
@@ -149,6 +154,13 @@ export interface GrantsSession extends NativeSessionHost {
   /** Stable root identity plus current turn, used only to join local activity facts. */
   activityRootId: string;
   activity?: { rootId: string; path: string; taskId?: string };
+  /**
+   * The parent's own session, once `session_start` supplies it. Read-only and used only to stage a granted
+   * context handoff (ADR-0078): its file path for `fork`, its message turns for `pruned`.
+   */
+  parentSession?: ParentSession;
+  /** ADR-0077: the session's advisor, off unless the environment enables one. Never consulted for authority. */
+  advisorSession: AdvisorSession;
   /** Root identity keyed to ctx.sessionManager once session_start supplies it. */
   reloadLifecycle: ReloadLifecycle;
   /** Approval keys approved for this session. In memory only — this dies with the process. */
@@ -288,7 +300,18 @@ export function createGrantsSession(
   const bounds = depthConfig(environment[ENV_DEPTH], environment[ENV_MAX_DEPTH]);
   const { depth, maxDepth } = bounds;
   const emptyCatalog = makeCatalog([]);
+  // ADR-0077. The environment decides whether there is an advisor at all; the project's settings block may only
+  // narrow it. The block IS read — the first version passed `undefined` and every narrowing the release advertised
+  // was dead code reachable only from tests, which review measured: `enabled: false` turned nothing off.
+  //
+  // Read from `storeCwd` for `loadStoredGrantStateSync`'s reason: this factory runs before any hook, so `ctx.cwd`
+  // does not exist yet. Reading a workspace-writable file here is safe precisely because it can only narrow.
+  const advisorSession = createAdvisorSession({
+    block: projectAdvisorBlock(storeCwd),
+    ...(storedLedger ? { ledgerPath: storedLedger } : {}),
+  });
   const session: GrantsSession = {
+    advisorSession,
     adoptedLegacyEnv,
     governed,
     inherited,
@@ -352,6 +375,17 @@ export function createGrantsSession(
       extensionPath: session.extensionPath,
       observerExtensionPath: session.observerExtensionPath,
       childEnv: activityChildEnv(session.activity),
+      // ADR-0078: composition reads, the kernel decides. Called only for a mode that survived the gate.
+      // `options` is forwarded, and its absence is why the second decision point was dead in production: a
+      // one-parameter arrow is assignable to a two-parameter type, so the ids reached here and were discarded while
+      // the advisor had already been asked. Review measured it. `test/pruning-advice.test.ts` now goes through this
+      // function rather than calling the stager directly.
+      stageHandoff: (granted, options) =>
+        createHandoffStager({
+          cwd: session.cwd,
+          forkRoot: join(agentDir(), "context-forks"),
+          ...(session.parentSession ? { parentSession: session.parentSession } : {}),
+        })(granted, options),
       catalog: await session.catalogReady,
       // R-32: where each granted skill lives, so `planSpawn` can pass `--skill` for those and only those.
       // Derived from the catalog's own `source`, so it cannot drift from what was discovered.
@@ -405,3 +439,27 @@ export function createGrantsSession(
   };
   return session;
 }
+
+/**
+ * The `advisor` block of `.pi/pi-daddy/settings.json`, or undefined.
+ *
+ * Unreadable, absent or malformed all yield undefined: this file is the reviewable record, not authority, and the
+ * only thing it can do to an advisor is turn one off. A parse failure therefore costs nothing worth reporting.
+ */
+function projectAdvisorBlock(cwd: string): unknown {
+  // Only when an advisor could exist at all. This runs in every session including every child, before any hook, and
+  // a child can never use the result because `PI_DADDY_ADVISOR` is stripped from it.
+  if (!process.env[ENV_ADVISOR]?.trim()) return undefined;
+  try {
+    const path = projectSettingsPath(cwd);
+    // Bounded and type-checked first: this is the third unbounded session-start read AGENTS.md warns about, and the
+    // only one whose path a governed child holding `tool:write` can replace with a FIFO — which would hang pi
+    // before any hook exists to report it.
+    const stats = statSync(path);
+    if (!stats.isFile() || stats.size > 1024 * 1024) return undefined;
+    const parsed: unknown = JSON.parse(readFileSync(path, "utf8"));
+    return typeof parsed === "object" && parsed !== null ? (parsed as Record<string, unknown>).advisor : undefined;
+  } catch {
+    return undefined;
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-daddy",
-  "version": "0.32.1",
+  "version": "0.35.0",
   "description": "Capability governance for pi sub-agents: spawn Agent Skills (SKILL.md) definitions whose allowed-tools becomes a grant that can only narrow going down a delegation tree, enforced by pi's own --tools allowlist, with an append-only ledger.",
   "keywords": [
     "pi-package",

package/src/advisors/advisor.ts

@@ -0,0 +1,123 @@
+/**
+ * The wrapper that makes "every use is recorded" structural rather than a rule (ADR-0077).
+ *
+ * A caller cannot reach a `Decider` directly through this layer's public surface: it asks an `Advisor`, and asking
+ * always produces an `advice` record — including when the answer was "no advice", which is the case a reviewer most
+ * needs to see, because an advisor that silently stops answering would otherwise look exactly like one nobody used.
+ *
+ * **What is recorded, and what is not.** The record names the purpose, the decider, the question keys, the answers
+ * and how long it took. It does NOT contain the state. A caller composes that state from its own context, which can
+ * include task text, file contents and a repository's private material; the ledger has never stored a task
+ * (ADR-0021) and an advisor must not become the way it starts. The question keys are the caller's own constants,
+ * so they name the decision without describing the situation.
+ */
+import type { Advice, AdviceRequest, Decider } from "./decider.ts";
+
+/** Two seconds. An advisor is on the path of a decision a human is waiting for; it is not worth more than that. */
+export const DEFAULT_ADVICE_TIMEOUT_MS = 2000;
+
+export interface AdviceRecord {
+  /** Which decision this advice was for, from the caller's own closed list. */
+  purpose: string;
+  decider: string;
+  /** Question keys only — never the state, and never a question's free text. */
+  questions: string[];
+  answered: boolean;
+  durationMs: number;
+  /** Present only when advice came back. */
+  answers?: Readonly<Record<string, { value: string | number | boolean; confidence?: number }>>;
+  model?: string;
+  /**
+   * Why there is no advice. `declined` means the advisor answered with nothing; `error` means it could not be
+   * reached or its response was unrecognised; `cancelled` means the CALLER went away, which is not the advisor's
+   * failure and must not read as one.
+   */
+  outcome: "answered" | "disabled" | "timeout" | "error" | "declined" | "cancelled";
+}
+
+export interface Advisor {
+  ask(purpose: string, request: AdviceRequest, signal?: AbortSignal): Promise<Advice | null>;
+}
+
+export function createAdvisor(input: {
+  decider: Decider;
+  /** Where the record goes. Injected so this layer does no I/O and governance does not import it. */
+  record: (entry: AdviceRecord) => void | Promise<void>;
+  timeoutMs?: number;
+  /** Absent or false means the null decider is used whatever `decider` says. */
+  enabled?: boolean;
+}): Advisor {
+  const timeoutMs = input.timeoutMs ?? DEFAULT_ADVICE_TIMEOUT_MS;
+  return {
+    async ask(purpose, request, signal) {
+      const started = Date.now();
+      const base = { purpose, decider: input.decider.name, questions: Object.keys(request.questions) };
+      const write = async (entry: AdviceRecord) => {
+        try {
+          await input.record(entry);
+        } catch {
+          // Recording is an observation of a decision that has already been taken. Failing to write it must not
+          // change what the caller does, for `execute-child`'s reason: an audit failure that discards the work is
+          // worse than one that is merely missing.
+        }
+      };
+      if (input.enabled !== true) {
+        await write({ ...base, decider: "none", answered: false, durationMs: 0, outcome: "disabled" });
+        return null;
+      }
+      const timer = new AbortController();
+      const cancel = setTimeout(() => timer.abort(), timeoutMs);
+      const linked = signal ? AbortSignal.any([signal, timer.signal]) : timer.signal;
+      try {
+        // RACED, not merely signalled. A decider that ignores its signal would otherwise run as long as it liked
+        // and then be recorded as a timeout — measured at fifty times the configured bound. The `Decider` contract
+        // cannot make an implementation honour an abort, so the bound is enforced on this side of it.
+        const advice = await Promise.race([
+          input.decider.decide(request, linked),
+          new Promise<null>((settle) => linked.addEventListener("abort", () => settle(null), { once: true })),
+        ]);
+        const durationMs = Date.now() - started;
+        if (!advice) {
+          await write({ ...base, answered: false, durationMs, outcome: outcomeFor(timer.signal, signal, "declined") });
+          return null;
+        }
+        await write({
+          ...base,
+          answered: true,
+          durationMs,
+          outcome: "answered",
+          answers: Object.fromEntries(
+            Object.entries(advice.answers).map(([key, answer]) => [
+              key,
+              { value: answer.value, ...(answer.confidence === undefined ? {} : { confidence: answer.confidence }) },
+            ]),
+          ),
+          ...(advice.model ? { model: advice.model } : {}),
+        });
+        return advice;
+      } catch {
+        // Including an abort. A caller asked for advice and is getting none; it proceeds exactly as it would have.
+        await write({
+          ...base,
+          answered: false,
+          durationMs: Date.now() - started,
+          outcome: outcomeFor(timer.signal, signal, "error"),
+        });
+        return null;
+      } finally {
+        clearTimeout(cancel);
+      }
+    },
+  };
+}
+
+/** The bound fired, the caller went away, or neither — three different facts a reviewer needs to tell apart. */
+function outcomeFor(
+  timer: AbortSignal,
+  caller: AbortSignal | undefined,
+  otherwise: "declined" | "error",
+): AdviceRecord["outcome"] {
+  if (timer.aborted && !caller?.aborted) return "timeout";
+  if (caller?.aborted) return "cancelled";
+  return otherwise;
+}

package/src/advisors/decider.ts

@@ -0,0 +1,68 @@
+/**
+ * An advisor is a thing that answers a typed question. It is never a thing that decides (ADR-0077).
+ *
+ * The boundary is the whole design, and it is structural rather than remembered: **no type in this layer names a
+ * `Capability` or a refusal code**, and no function in `kernel/` or `governance/` accepts an advisor's result. An
+ * advisor may select among options the caller already had, rank them, annotate them, or propose one. It can never
+ * widen an `effective` set, satisfy a gate, or stand in for a human's answer — not because it is asked not to, but
+ * because nothing on those paths can receive what it returns. `test/advisors.test.ts` forces that.
+ *
+ * Non-generative on purpose. The first advisor is a classifier that returns a typed answer with a probability, not
+ * prose, which is what makes an advisor auditable: "it chose `b` at 0.91" is a fact a reviewer can disagree with,
+ * where a paragraph of reasoning is not.
+ *
+ * Degradation is "no advice", never a guess. Every path that cannot produce an answer — disabled, missing key,
+ * timeout, transport error, a response shape we do not recognise — returns `null`, and the caller does what it
+ * would have done without an advisor at all. That is why a caller must be written to work with `nullDecider`
+ * first, and why `nullDecider` is the default.
+ */
+
+/** A question, in the three shapes the first advisor understands. */
+export type Question =
+  | { kind: "noul"; instructions: string; whenTrue: string; whenFalse: string }
+  | { kind: "choice"; instructions: string; options: Readonly<Record<string, string>> }
+  | { kind: "score"; instructions: string; levels: readonly string[] };
+
+/** One typed answer. `confidence` is absent when the transport did not report one; it is never invented. */
+export type Answer =
+  | { kind: "noul"; value: boolean; confidence?: number }
+  | { kind: "choice"; value: string; confidence?: number }
+  // `level` is the string the value indexes, so a caller never has to know which end the scale starts at.
+  | { kind: "score"; value: number; level: string; confidence?: number };
+
+export interface AdviceRequest {
+  /**
+   * What the advisor is told about the situation, composed by the caller.
+   *
+   * **Sent, never recorded.** The task is never STORED (ADR-0021) and that still holds — `createAdvisor` writes the
+   * question keys and the answers and never this object. But an advisor cannot judge a task it cannot see, so a
+   * caller that needs one judged does send it, and the operator's consent for that is the advisor being off by
+   * default. An earlier draft of this paragraph said the raw task "must not be shipped to a third party either",
+   * which the first decision point then did; the rule that survived review is the narrower and true one.
+   */
+  state: Readonly<Record<string, unknown>>;
+  questions: Readonly<Record<string, Question>>;
+}
+
+export interface Advice {
+  answers: Readonly<Record<string, Answer>>;
+  /** What actually answered, as the transport reported it — a dated model id, not the one we asked for. */
+  model?: string;
+}
+
+export interface Decider {
+  /** Recorded in the ledger so a reviewer can tell which advisor a decision was taken beside. */
+  readonly name: string;
+  decide(request: AdviceRequest, signal?: AbortSignal): Promise<Advice | null>;
+}
+
+/**
+ * The default, and the one every caller must work correctly with.
+ *
+ * Not a placeholder: it is how advisors stay optional. A caller that behaves differently under `nullDecider` than
+ * under no advisor at all has made advice load-bearing, which is the one thing ADR-0077 forbids.
+ */
+export const nullDecider: Decider = {
+  name: "none",
+  decide: async () => null,
+};

package/src/advisors/jev.ts

@@ -0,0 +1,130 @@
+/**
+ * Jev, through OpenRouter's Decisions endpoint — the first advisor adapter (ADR-0077).
+ *
+ * **What is verified and what is not.** The REQUEST shape below is taken from OpenRouter's own SDK reference for
+ * `POST /api/alpha/decisions`: `{model, state, questions}`, where each question is `noul` with `criteria.true` and
+ * `criteria.false`, `choice` with a `criteria` map of option to description, or `score` with a `criteria` array of
+ * level descriptions. That much is documented. The RESPONSE is described there only as an `answers` object beside
+ * `id`, `model`, `provider` and `usage`, with probabilities and confidence mentioned but never shown, and the one
+ * public guide to this endpoint says plainly that it has not run paid calls either. **So no shape below has been
+ * confirmed against a live response.** The parser therefore accepts what the documentation describes, tolerates the
+ * obvious variants, and returns `null` for anything else rather than guessing — which is the same thing it does when
+ * the endpoint is down. A live check is the `PI_DADDY_IT_JEV=1` tier, and until somebody runs it this adapter's
+ * response handling is a reading of documentation, not a measurement.
+ *
+ * Nothing here can widen anything: it returns `Advice`, and no kernel or governance function accepts one.
+ */
+import type { Advice, AdviceRequest, Answer, Decider, Question } from "./decider.ts";
+
+export const JEV_ENDPOINT = "https://openrouter.ai/api/alpha/decisions";
+export const JEV_MODEL = "typesafe/jev-1.13";
+
+/** The wire form of one question, exactly as OpenRouter's reference documents it. */
+export function wireQuestion(question: Question): Record<string, unknown> {
+  if (question.kind === "noul")
+    return {
+      type: "noul",
+      instructions: question.instructions,
+      criteria: { true: question.whenTrue, false: question.whenFalse },
+    };
+  if (question.kind === "choice")
+    return { type: "choice", instructions: question.instructions, criteria: { ...question.options } };
+  return { type: "score", instructions: question.instructions, criteria: [...question.levels] };
+}
+
+export function wireRequest(request: AdviceRequest, model: string): Record<string, unknown> {
+  return {
+    model,
+    state: request.state,
+    questions: Object.fromEntries(Object.entries(request.questions).map(([key, q]) => [key, wireQuestion(q)])),
+  };
+}
+
+/**
+ * Read one answer out of a response, or nothing.
+ *
+ * Deliberately generous about WHERE the value and the probability sit, because the documentation names the fields
+ * without showing them, and strict about WHAT they are: a `choice` answer must be one of the options that were
+ * asked about, and a `score` must be an index into the levels. An answer outside the question's own vocabulary is
+ * not a low-confidence answer, it is a response we did not understand, and the honest reading of that is no advice.
+ */
+export function parseAnswer(question: Question, raw: unknown): Answer | undefined {
+  if (raw === null || raw === undefined) return undefined;
+  const object = typeof raw === "object" && !Array.isArray(raw) ? (raw as Record<string, unknown>) : undefined;
+  const value = object ? (object.value ?? object.answer ?? object.choice ?? object.result) : raw;
+  const confidenceRaw = object ? (object.confidence ?? object.probability ?? object.p) : undefined;
+  const confidence = typeof confidenceRaw === "number" && Number.isFinite(confidenceRaw) ? confidenceRaw : undefined;
+  const withConfidence = <T extends Answer>(answer: T): T =>
+    (confidence === undefined ? answer : { ...answer, confidence }) as T;
+
+  if (question.kind === "noul") {
+    if (typeof value !== "boolean") return undefined;
+    return withConfidence({ kind: "noul", value });
+  }
+  if (question.kind === "choice") {
+    if (typeof value !== "string" || !Object.hasOwn(question.options, value)) return undefined;
+    return withConfidence({ kind: "choice", value });
+  }
+  // ONE reading: a score is a 0-based index into the `criteria` array that was asked about, and `level` carries the
+  // string so a caller never indexes the number itself.
+  //
+  // The first draft accepted both a 0-based and a 1-based reading "because the documentation shows neither", which
+  // pushed the ambiguity onto the caller and into the ledger: with three levels, 1 and 2 were valid under both, so
+  // `levels[value]` could read "high" where the model meant "mid". An advisor exists to remove that guess, not to
+  // relocate it. **The 0-based reading is an assumption** — it indexes the documented array form — and it is
+  // unverified for the same reason everything else about the response is: no live call has been made. If Jev is
+  // 1-based, its top level falls outside the array and the whole answer is refused as unrecognised, which is the
+  // loud failure rather than a silently shifted one, and the `PI_DADDY_IT_JEV=1` tier is what would show it.
+  if (typeof value !== "number" || !Number.isInteger(value)) return undefined;
+  if (value < 0 || value >= question.levels.length) return undefined;
+  return withConfidence({ kind: "score", value, level: question.levels[value] });
+}
+
+export function parseAdvice(request: AdviceRequest, body: unknown): Advice | null {
+  if (typeof body !== "object" || body === null) return null;
+  const envelope = body as Record<string, unknown>;
+  const raw = envelope.answers;
+  if (typeof raw !== "object" || raw === null) return null;
+  const answers: Record<string, Answer> = {};
+  for (const [key, question] of Object.entries(request.questions)) {
+    const parsed = parseAnswer(question, (raw as Record<string, unknown>)[key]);
+    // Every question or none: a caller that asked two questions and silently received one would have to guess which
+    // of its branches the missing answer belonged to, and guessing is what an advisor exists to remove.
+    if (!parsed) return null;
+    answers[key] = parsed;
+  }
+  return { answers, ...(typeof envelope.model === "string" ? { model: envelope.model } : {}) };
+}
+
+export interface JevConfig {
+  apiKey: string;
+  model?: string;
+  endpoint?: string;
+  /** Injected so the adapter is testable without a network, and so nothing here reaches for a global. */
+  fetch?: typeof globalThis.fetch;
+}
+
+export function jevDecider(config: JevConfig): Decider {
+  return {
+    name: "jev",
+    async decide(request, signal) {
+      const send = config.fetch ?? globalThis.fetch;
+      const response = await send(config.endpoint ?? JEV_ENDPOINT, {
+        method: "POST",
+        headers: { "content-type": "application/json", authorization: `Bearer ${config.apiKey}` },
+        body: JSON.stringify(wireRequest(request, config.model ?? JEV_MODEL)),
+        ...(signal ? { signal } : {}),
+      });
+      // A dead endpoint and an advisor with nothing to say must not read alike in the ledger: the whole reason for
+      // recording the nothing-cases is that an advisor which quietly stopped answering should not look like one
+      // nobody called. Thrown, so `createAdvisor` records `error` rather than `declined`; it catches, so nothing
+      // reaches the caller but `null` either way.
+      if (!response.ok) throw new Error(`advisor endpoint returned ${response.status}`);
+      try {
+        return parseAdvice(request, await response.json());
+      } catch {
+        return null;
+      }
+    },
+  };
+}

package/src/advisors/settings.ts

@@ -0,0 +1,113 @@
+/**
+ * Whether an advisor is on, and which one (ADR-0077).
+ *
+ * **Default off, and only the environment can turn it on.** An advisor sends a description of the caller's
+ * situation to a third party, so enabling one is `PI_DADDY_ADVISOR=jev` plus a key — both outside the workspace,
+ * both stripped from every child.
+ *
+ * 0.34.0 read the enable from `.pi/pi-daddy/settings.json` and that was wrong for the reason `grant-store.ts`
+ * states about the same file: it is writable by any child holding `tool:write`, so it is "the reviewable record of
+ * the decision, not the thing the enforcer reads". A grant lives outside the workspace precisely so a child cannot
+ * widen the next session's ceiling; an advisor switch a child could flip would make the operator's next session
+ * ship its own description to a third party, which is the same self-defeating shape. The settings block may still
+ * NARROW — a shorter timeout, or `enabled: false` to turn an advisor off for one project — and can never turn one
+ * on, choose its model, or lengthen its bound. A model is a destination rather than a narrowing, so `model` in the
+ * block is refused with a message naming `PI_DADDY_ADVISOR_MODEL`, and a timeout is clamped to the default rather
+ * than trusted. Malformed configuration disables the advisor and says so: a typo must not be a way to enable anything.
+ *
+ * **Not a dashboard toggle**, which is what the programme originally sketched. The dashboard is a read-only
+ * renderer in a separate process that "never affects enforcement" (ADR-0036), and a control there that wrote to
+ * settings would be the first thing it ever wrote. Turning an advisor on is an operator decision that belongs in
+ * the reviewable file; `/grants` reports what is in force. That is a deliberate departure from the roadmap line.
+ *
+ * The key is never in the settings file either, because that file is committed and an API key must not be.
+ */
+
+// Spelled once, in the kernel's table, so this layer cannot drift from the list `childEnv` refuses to write.
+export { ENV_ADVISOR_KEY as ADVISOR_KEY_ENV } from "../kernel/env-names.ts";
+import { ENV_ADVISOR, ENV_ADVISOR_KEY, ENV_ADVISOR_MODEL } from "../kernel/env-names.ts";
+import { DEFAULT_ADVICE_TIMEOUT_MS } from "./advisor.ts";
+export { ENV_ADVISOR_MODEL } from "../kernel/env-names.ts";
+export { ENV_ADVISOR } from "../kernel/env-names.ts";
+
+export interface AdvisorSettings {
+  enabled: boolean;
+  /** The only decider this release knows besides the null one. */
+  decider: "none" | "jev";
+  /** Overrides the adapter's pinned model id; absent means the adapter's own default. */
+  model?: string;
+  timeoutMs?: number;
+  /** Why an advisor is off when the settings asked for one on — reported, never silently applied. */
+  refusal?: string;
+}
+
+export const ADVISOR_OFF: AdvisorSettings = Object.freeze({ enabled: false, decider: "none" });
+
+/**
+ * Read the `advisor` block of a project settings file. Absent is off; malformed is off WITH a reason.
+ *
+ * The reason matters more than it looks: an operator who wrote `"enabeld": true` and got silence would conclude the
+ * feature does not work, and an operator who wrote it and got an advisor anyway would have a third party reading
+ * their session without having successfully asked for it. Both are worse than a sentence naming the field.
+ */
+export function advisorSettingsFrom(raw: unknown, env: NodeJS.ProcessEnv = process.env): AdvisorSettings {
+  // The environment decides WHETHER, before the workspace is consulted at all. A settings file that asks for an
+  // advisor nobody enabled is not a configuration error; it is simply a project that would use one if the operator
+  // turned it on, so it is reported rather than refused.
+  const requested = env[ENV_ADVISOR]?.trim();
+  if (!requested) return ADVISOR_OFF;
+  if (requested !== "jev")
+    return { ...ADVISOR_OFF, refusal: `${ENV_ADVISOR}=${requested} names no advisor this release knows` };
+
+  const block = raw === undefined || raw === null ? {} : raw;
+  if (typeof block !== "object" || Array.isArray(block))
+    return { ...ADVISOR_OFF, refusal: "settings.advisor must be an object; no advisor is enabled" };
+  const fields = block as Record<string, unknown>;
+  // `model` stays KNOWN so the refusal below can say why it is refused, rather than reporting it as a typo.
+  const unknownKeys = Object.keys(fields).filter((key) => !["enabled", "decider", "model", "timeoutMs"].includes(key));
+  // Key names are echoed back, and this file is workspace-writable: a key containing an escape sequence or a
+  // newline would otherwise forge lines in the `/grants` panel, which is a trust surface. Review measured a forged
+  // `grant tool:*` line. Sanitised and truncated before it reaches any renderer.
+  if (unknownKeys.length > 0)
+    return {
+      ...ADVISOR_OFF,
+      refusal: `settings.advisor has unknown field(s) ${unknownKeys
+        .map((key) => key.replace(/[^\w.-]/g, "?").slice(0, 40))
+        .join(", ")}`,
+    };
+  // A project may switch it OFF; it may never switch it on, which is why `true` is not read. Anything that is not
+  // exactly `true` disables: `"false"`, `0` and `null` used to leave the advisor ON with no word said, which is
+  // rule 8 inverted — the one control this file retains failing open.
+  if (fields.enabled !== undefined && fields.enabled !== true)
+    return { ...ADVISOR_OFF, refusal: "settings.advisor.enabled is not true for this project" };
+  if (fields.decider !== undefined && fields.decider !== "jev")
+    return { ...ADVISOR_OFF, refusal: `settings.advisor.decider must be "jev"; no advisor is enabled` };
+  // **A model is a DESTINATION, not a narrowing.** Letting this workspace-writable file choose it would let a child
+  // holding `tool:write` point the operator's next session at a generative model of its choosing, billed to the
+  // operator's key — the same self-defeating shape this release moved the enable switch to close, one step
+  // sideways. Review measured it. The model comes from the environment or not at all.
+  if ((fields as Record<string, unknown>).model !== undefined)
+    return { ...ADVISOR_OFF, refusal: `settings.advisor.model is not a narrowing; set ${ENV_ADVISOR_MODEL} instead` };
+  if (
+    fields.timeoutMs !== undefined &&
+    (!Number.isInteger(fields.timeoutMs) || (fields.timeoutMs as number) < 1 || (fields.timeoutMs as number) > 30_000)
+  )
+    return { ...ADVISOR_OFF, refusal: "settings.advisor.timeoutMs must be an integer between 1 and 30000" };
+  const model = env[ENV_ADVISOR_MODEL]?.trim();
+  const key = env[ENV_ADVISOR_KEY]?.trim();
+  if (!key)
+    return {
+      ...ADVISOR_OFF,
+      refusal: `settings.advisor is enabled but ${ENV_ADVISOR_KEY} is not set; no advisor is enabled`,
+    };
+  return {
+    enabled: true,
+    decider: "jev",
+    ...(model ? { model } : {}),
+    // Clamped, never raised: a longer bound is not a narrowing either, and a child-writable 30s would be a stall on
+    // every delegation.
+    ...(fields.timeoutMs !== undefined
+      ? { timeoutMs: Math.min(fields.timeoutMs as number, DEFAULT_ADVICE_TIMEOUT_MS) }
+      : {}),
+  };
+}

package/src/executors/activity-session.ts

@@ -23,7 +23,35 @@ export interface ActivitySession {
   dispose(): Promise<void>;
 }
 
+/** The newest session file pi wrote into a directory we own, as a size:mtime marker. */
+function probeDirectory(directory: string) {
+  return async (): Promise<string | undefined> => {
+    try {
+      const { readdir, stat } = await import("node:fs/promises");
+      const names = (await readdir(directory)).filter((name) => name.endsWith(".jsonl"));
+      if (names.length === 0) return undefined;
+      const marks = await Promise.all(
+        names.map(async (name) => {
+          const s = await stat(join(directory, name));
+          return `${name}:${s.size}:${s.mtimeMs}`;
+        }),
+      );
+      return marks.sort().join("|");
+    } catch {
+      return undefined;
+    }
+  };
+}
+
 export async function activitySessionFor(planArgs: string[], executionId: string): Promise<ActivitySession> {
+  // A forked child (ADR-0078) has no `--session`, and adding one would make pi refuse the spawn outright: it
+  // rejects `--fork` beside `--session` or `--no-session`. The fork writes exactly one session into a directory
+  // that is ours, so the probe watches the directory and the argv is left exactly as planned.
+  const fork = planArgs.indexOf("--fork");
+  if (fork >= 0) {
+    const dir = planArgs[planArgs.indexOf("--session-dir") + 1];
+    return { args: planArgs, path: dir, probe: probeDirectory(dir), dispose: async () => undefined };
+  }
   const flag = planArgs.indexOf("--session");
   const probeFor = (path: string) => async () => {
     try {

package/src/executors/herdr-stage.ts

@@ -26,10 +26,22 @@ import { join } from "node:path";
  * direct executor passes the same text inline with no trouble, and a plan builder that pre-emptively wrote
  * temp files for everybody would be paying one executor's tax on both paths.
  */
-export function splitSystemPrompt(args: string[]): { args: string[]; systemPrompt?: string } {
-  const at = args.indexOf("--append-system-prompt");
-  if (at === -1 || at + 1 >= args.length) return { args };
-  return { args: [...args.slice(0, at), ...args.slice(at + 2)], systemPrompt: args[at + 1] };
+export function splitSystemPrompt(args: string[]): { args: string[]; systemPrompts: string[] } {
+  // EVERY occurrence, not the first. pi accumulates `--append-system-prompt`, and ADR-0078 added a second one for a
+  // granted context handoff — whose fence always contains newlines. Taking only the first left that fence inline,
+  // and `herdr agent start` refuses a multi-line argument, so every non-fork handoff failed on the Herdr executor
+  // AFTER the gate, the ledger record and the fan-out spend. Measured during review.
+  const kept: string[] = [];
+  const systemPrompts: string[] = [];
+  for (let index = 0; index < args.length; index += 1) {
+    if (args[index] === "--append-system-prompt" && index + 1 < args.length) {
+      systemPrompts.push(args[index + 1]);
+      index += 1;
+      continue;
+    }
+    kept.push(args[index]);
+  }
+  return { args: kept, systemPrompts };
 }
 
 /**
@@ -43,12 +55,18 @@ export async function stageSystemPrompt(
   args: string[],
 ): Promise<{ args: string[]; promptDir?: string; error?: string }> {
   const split = splitSystemPrompt(args);
-  if (split.systemPrompt === undefined) return { args: split.args };
+  if (split.systemPrompts.length === 0) return { args: split.args };
   try {
     const promptDir = await mkdtemp(join(tmpdir(), "grants-herdr-"));
-    const file = join(promptDir, "system-prompt.md");
-    await writeFile(file, split.systemPrompt, "utf8");
-    return { args: [...split.args, "--append-system-prompt", file], promptDir };
+    const staged: string[] = [];
+    // One file per prompt, in order: pi appends them in argv order and the definition body must still precede the
+    // context a parent chose to add to it.
+    for (const [index, prompt] of split.systemPrompts.entries()) {
+      const file = join(promptDir, `system-prompt-${index}.md`);
+      await writeFile(file, prompt, "utf8");
+      staged.push("--append-system-prompt", file);
+    }
+    return { args: [...split.args, ...staged], promptDir };
   } catch (error) {
     return { args: split.args, error: `could not stage the system prompt for herdr: ${String(error)}` };
   }

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

@@ -101,6 +101,7 @@ const FIELDS = {
     "humanDenied",
     "gateOutcome",
     "definitionDigest",
+    "handoff",
     "executor",
     "taskFrom",
     "taskFromExecutionId",