pi-daddy 0.37.0 → 0.38.0

package/src/kernel/delegate-types.ts

@@ -10,6 +10,7 @@ import type { InheritableApproval } from "./approval.ts";
 import type { Catalog } from "./catalog.ts";
 import type { ApprovalBinding, CorrelationMetadata } from "./correlation.ts";
 import type { StructuredRefusal } from "./refusals.ts";
+import type { WorkspacePins } from "./workspace-pin.ts";
 
 /** The two ways a child can be started. Defined here, below the executors, so the ledger and the planner can name it without importing an executor (ADR-0076 layering). */
 export const EXECUTOR_KINDS = ["process", "herdr"] as const;
@@ -82,6 +83,14 @@ export interface DelegationContext {
    * (ADR-0076: the kernel imports no product; products contribute through this hook).
    */
   childEnv?: (child: { childExecutionId?: string }) => Readonly<Record<string, string>>;
+  /**
+   * This session's destination pins (ADR-0042), narrowed by `workspacePinEnv` to what the child holds.
+   *
+   * Supplied by the composition layer rather than read from the environment here, so the kernel keeps one
+   * source for it and a test can hand one in. Absent means this session established no pin: the child then
+   * inherits none and can route nowhere, which is the fail-closed direction.
+   */
+  workspacePin?: WorkspacePins;
   /**
    * Stage what crosses for a GRANTED handoff (ADR-0078), supplied by the composition layer for `childEnv`'s
    * reason: building it means reading files and the parent's session, and the kernel does no I/O.

package/src/kernel/delegate.ts

@@ -24,6 +24,7 @@ import {
   ENV_MAX_DEPTH,
   ENV_PARENT_ID,
   inheritableGrant,
+  workspacePinEnv,
 } from "./propagation.ts";
 import { inheritApprovals, type InheritableApproval } from "./approval.ts";
 import { explainDoubledNamespace, suggestForUnknown, unknownCapabilities, type Catalog } from "./catalog.ts";
@@ -399,6 +400,11 @@ export function planDelegation(request: DelegationRequest, ctx: DelegationContex
   // reason on the other path.
   env[ENV_APPROVED] = inheritApprovals(ctx.approved ?? [], inheritable).join(",");
   if (ctx.ledgerPath) env[ENV_LEDGER] = ctx.ledgerPath;
+  // ADR-0042, through the SAME builder `childEnv` uses. This is the fork the comment above is about: a rule
+  // 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));
   // 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

@@ -34,6 +34,8 @@ export const ENV_APPROVAL_TIMEOUT = "PI_DADDY_APPROVAL_TIMEOUT";
 export const ENV_ALLOW_UNRESOLVED_MODELS = "PI_DADDY_ALLOW_UNRESOLVED_MODELS";
 export const ENV_WORKSPACE_REGISTRY = "PI_DADDY_WORKSPACE_REGISTRY";
 export const ENV_WORKSPACE_LEASE_DIR = "PI_DADDY_WORKSPACE_LEASE_DIR";
+/** ADR-0042: what each authorised workspace id MEANT when the grant was established. Authority, not metadata. */
+export const ENV_WORKSPACE_PIN = "PI_DADDY_WORKSPACE_PIN";
 export const ENV_EXECUTION_ARCHIVE = "PI_DADDY_EXECUTION_ARCHIVE";
 export const ENV_NATIVE_SESSION_ROOT = "PI_DADDY_NATIVE_SESSION_ROOT";
 export const ENV_RETAIN_NATIVE_SESSIONS = "PI_DADDY_RETAIN_NATIVE_SESSIONS";
@@ -83,6 +85,7 @@ export const GOVERNANCE_ENV_KEYS: readonly string[] = Object.freeze([
   ENV_ALLOW_UNRESOLVED_MODELS,
   ENV_WORKSPACE_REGISTRY,
   ENV_WORKSPACE_LEASE_DIR,
+  ENV_WORKSPACE_PIN,
   ENV_EXECUTION_ARCHIVE,
   ENV_NATIVE_SESSION_ROOT,
   ENV_RETAIN_NATIVE_SESSIONS,

package/src/kernel/propagation.ts

@@ -26,6 +26,7 @@
  */
 
 import type { Capability } from "./resolve.ts";
+import { attenuateWorkspacePin, formatWorkspacePin, type WorkspacePins } from "./workspace-pin.ts";
 import { WILDCARD } from "./pi-tools.ts";
 import { WORKSPACE_WILDCARD } from "./resolve.ts";
 import { inheritApprovals, type InheritableApproval } from "./approval.ts";
@@ -43,6 +44,7 @@ import {
   ENV_GATED,
   ENV_LEDGER,
   ENV_APPROVED,
+  ENV_WORKSPACE_PIN,
 } from "./env-names.ts";
 export {
   ENV_GRANT,
@@ -95,6 +97,9 @@ export const GRANT_ENV_KEYS = [
   ENV_FANOUT,
   ENV_PARENT_ID,
   ENV_EXECUTION_ID,
+  // ADR-0042: a child must never keep its parent's unnarrowed pin, so it is stripped like every other
+  // governance value and re-supplied only by the spawn plan.
+  ENV_WORKSPACE_PIN,
 ] as const;
 
 export const parseList = (raw: string | undefined): Capability[] =>
@@ -233,6 +238,14 @@ export function gatedFromEnv(raw: string | undefined): Capability[] {
 export interface ChildEnvInput {
   /** This session's own grant — becomes the child's inherited parent grant. */
   ownGrant: Capability[];
+  /**
+   * This session's destination pins (ADR-0042), narrowed here to what the child's grant names.
+   *
+   * Passed in rather than read from the environment for the reason `inheritableGrant`'s comment records: a rule
+   * with two spellings gets the guard on the quieter one. Absent means this session established none, and the
+   * child then inherits no pin and can route nowhere — which is the fail-closed direction.
+   */
+  workspacePin?: WorkspacePins;
   /** This session's depth; children are one deeper. */
   depth: number;
   maxDepth: number;
@@ -313,9 +326,36 @@ export function childEnv(input: ChildEnvInput): Record<string, string> {
   env[ENV_APPROVED] = inheritApprovals(input.approved ?? [], inheritable).join(",");
   // Empty is an explicit one-run ledger opt-out and must overwrite a prior publication too.
   if (input.ledgerPath !== undefined) env[ENV_LEDGER] = input.ledgerPath;
+  // ADR-0042. ALWAYS written when this session has any pin at all, empty string included, for the same reason
+  // `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));
   return env;
 }
 
+/**
+ * The destination-pin half of a child's environment (ADR-0042), spelled ONCE for both spawn paths.
+ *
+ * **There are two places a child's environment is built**, and this file already carries the scar: the
+ * "held but never inherited" rule for `workspace:*` lived only in `childEnv`, so `delegate.ts` — the path a
+ * delegated child's grant actually travels — handed the wildcard straight down, and the test written beside
+ * that fix exercised the wrong path. The pin reached the same fork. The ADR is explicit that "the process and
+ * Herdr paths must share one propagation builder", so this is that builder and both callers use it.
+ *
+ * Written even when it narrows to nothing, and omitted only when this session has no pin at all: an omitted
+ * key does not overwrite, so the child would inherit the parent's UNNARROWED pin through the process-global
+ * publication path. Empty parses back as "a pin exists and you got none of it", which refuses at routing.
+ */
+export function workspacePinEnv(
+  pins: WorkspacePins | undefined,
+  inheritable: readonly Capability[],
+): Record<string, string> {
+  return pins === undefined
+    ? {}
+    : { [ENV_WORKSPACE_PIN]: formatWorkspacePin(attenuateWorkspacePin(pins, inheritable)) };
+}
+
 /**
  * The environment for a child this process spawns itself: the parent's environment with every governance
  * variable stripped, then the per-child plan applied.

package/src/kernel/workspace-pin.ts

@@ -0,0 +1,158 @@
+/**
+ * The inherited destination pin (ADR-0042): what a workspace id MEANT when the authority was granted.
+ *
+ * **The escalation this closes, measured in `g37-registry-tamper`.** `workspace:<id>` attenuates the NAME, not
+ * the mutable id-to-path meaning. A child holding `workspace:staging` and `tool:write` — no `bash` — can rewrite
+ * the operator's registry so `staging` points at the `prod` worktree, route a grandchild there, and take an
+ * exclusive write lease on it. Every capability check passes, because the id it was granted is the id it used.
+ * File ownership cannot help: a governed child runs as the parent's uid, so the registry is as writable to it as
+ * to the operator.
+ *
+ * **The mechanism is authority, not metadata.** A root resolves each registered id to its canonical destination
+ * and records a digest of it. Descendants inherit only the entries their effective grant authorises, cannot mint
+ * an entry, and routing requires an exact match against the inherited digest. A rewritten registry therefore
+ * changes where an id points and NOT what an inherited id is allowed to mean, which is the whole property.
+ *
+ * **Why a digest rather than the path.** The path is already visible to the child through the registry it can
+ * read; pinning the digest keeps the wire small for a realistic registry and makes an equality check the only
+ * operation, so there is no path-comparison subtlety to get wrong. `validateRegisteredWorkspace` still does the
+ * canonicalisation; this only asks whether the answer changed.
+ *
+ * **Every failure refuses.** Missing, empty, malformed and mismatched all refuse, because the alternative is a
+ * mechanism a child can disable by corrupting one byte. ADR-0042 records that an earlier attempt was reverted
+ * after four failures, and that it failed "specifically because it was treated as a small patch".
+ */
+import { createHash } from "node:crypto";
+import { isSafeWorkspaceId, workspaceCapability } from "./capabilities.ts";
+import type { Capability } from "./resolve.ts";
+
+export { ENV_WORKSPACE_PIN } from "./env-names.ts";
+
+/**
+ * Half a SHA-256, hex. The comparison is equality against a value the operator's own root computed, not a
+ * signature, so this is sized to make accidental collision impossible rather than to resist an adversary who
+ * can already choose both sides.
+ */
+const DIGEST_HEX = 32;
+
+/** A canonical destination, reduced to something an environment variable can carry. */
+export function destinationDigest(canonicalRoot: string): string {
+  return createHash("sha256").update(canonicalRoot, "utf8").digest("hex").slice(0, DIGEST_HEX);
+}
+
+export type WorkspacePins = ReadonlyMap<string, string>;
+
+/** `id:digest` pairs. Ids cannot contain `:` or `,` — `isSafeWorkspaceId` is the reason this is unambiguous. */
+export function formatWorkspacePin(pins: WorkspacePins): string {
+  return [...pins.entries()]
+    .sort(([a], [b]) => a.localeCompare(b))
+    .map(([id, digest]) => `${id}:${digest}`)
+    .join(",");
+}
+
+export type ParsedPin = { pins: WorkspacePins } | { refusal: string };
+
+/**
+ * Read a pin, refusing anything that is not exactly the shape this module writes.
+ *
+ * An absent variable is NOT the same as an empty one and both are distinguished by the caller: absent means no
+ * root ever established a pin, empty means a parent established one and this child inherited no entries. Both
+ * refuse at routing time; they need different messages to be diagnosable.
+ */
+export function parseWorkspacePin(raw: string | undefined): ParsedPin {
+  if (raw === undefined) return { refusal: "no destination pin was inherited" };
+  const trimmed = raw.trim();
+  if (trimmed === "") return { pins: new Map() };
+  const pins = new Map<string, string>();
+  for (const entry of trimmed.split(",")) {
+    const at = entry.lastIndexOf(":");
+    if (at <= 0) return { refusal: `destination pin entry ${JSON.stringify(entry)} is not id:digest` };
+    const id = entry.slice(0, at);
+    const digest = entry.slice(at + 1);
+    if (!isSafeWorkspaceId(id))
+      return { refusal: `destination pin names a malformed workspace id ${JSON.stringify(id)}` };
+    if (!/^[0-9a-f]{32}$/.test(digest))
+      return { refusal: `destination pin for ${id} is not a ${DIGEST_HEX}-character digest` };
+    // A duplicated id with two digests is ambiguous, and picking either would let a tamperer supply both.
+    if (pins.has(id) && pins.get(id) !== digest)
+      return { refusal: `destination pin names ${id} twice with different destinations` };
+    pins.set(id, digest);
+  }
+  return { pins };
+}
+
+/**
+ * The pin a child inherits: the parent's entries, narrowed to the workspaces the child's grant actually names.
+ *
+ * Narrowing here rather than passing the parent's whole map is the difference between a pin and a hint. A child
+ * that cannot see an entry cannot route to it even if it rewrites the registry to make the id resolve, because
+ * routing needs a pin entry and it has none to offer.
+ */
+export function attenuateWorkspacePin(pins: WorkspacePins, inheritable: readonly Capability[]): WorkspacePins {
+  const held = new Set<Capability>(inheritable);
+  return new Map([...pins.entries()].filter(([id]) => held.has(workspaceCapability(id))));
+}
+
+/**
+ * Does the registry still resolve this id to what the grant meant?
+ *
+ * Returns a refusal reason, or `undefined` when the destination matches. A string rather than a thrown error
+ * because the one caller already owns the refusal code and the `details` this belongs in.
+ */
+export function checkPinnedDestination(input: {
+  workspaceId: string;
+  canonicalRoot: string;
+  pin: ParsedPin;
+}): string | undefined {
+  if ("refusal" in input.pin) return input.pin.refusal;
+  const expected = input.pin.pins.get(input.workspaceId);
+  if (expected === undefined)
+    return (
+      `no destination pin was inherited for workspace ${input.workspaceId}` +
+      (input.pin.pins.size > 0 ? ` — pinned: ${[...input.pin.pins.keys()].sort().join(", ")}` : "")
+    );
+  const actual = destinationDigest(input.canonicalRoot);
+  if (actual !== expected)
+    return (
+      `workspace ${input.workspaceId} now resolves to ${input.canonicalRoot}, which is not the destination this ` +
+      `session was granted. The registry has been rewritten since the grant was established, so the id no longer ` +
+      `means what it meant when it was authorised (ADR-0042)`
+    );
+  return undefined;
+}
+
+/**
+ * Establish a root's pin by resolving every registered id to its canonical destination.
+ *
+ * **Only a session that inherited NO pin may call this**, and that rule is the mechanism. If a descendant could
+ * mint its own pin it would simply rewrite the registry and then re-establish, and the whole thing would be a
+ * comment. The caller enforces it because only the caller knows whether a pin was inherited; this function is
+ * the resolution, not the policy.
+ *
+ * An id whose destination cannot be canonicalised is LEFT OUT rather than pinned to a guess. Routing then
+ * refuses it for having no pin, which is the same direction as every other failure here.
+ */
+export async function establishWorkspacePin(
+  registry: { workspaces: Record<string, { path: string }> },
+  canonicalise: (path: string) => Promise<string>,
+  onSkipped?: (id: string, reason: string) => void,
+): Promise<WorkspacePins> {
+  const pins = new Map<string, string>();
+  for (const [id, entry] of Object.entries(registry.workspaces)) {
+    if (!isSafeWorkspaceId(id)) {
+      onSkipped?.(id, "its id is malformed");
+      continue;
+    }
+    try {
+      pins.set(id, destinationDigest(await canonicalise(entry.path)));
+    } catch (error) {
+      // Rule 8, and `registeredWorkspaceIds` one file over carries the long version of why: this was a bare
+      // `catch {}`, so an unmounted worktree or a directory not yet created dropped a workspace silently and
+      // the operator met it later as "no destination pin was inherited", a message that names neither the
+      // directory nor the reason. Unresolvable still means no pin — routing must not invent one — but the
+      // caller is told which id and why.
+      onSkipped?.(id, `its destination could not be canonicalised (${String(error)})`);
+    }
+  }
+  return pins;
+}

package/src/kernel/workspace.ts

@@ -9,6 +9,7 @@ import { promisify } from "node:util";
 import { GovernanceRefusal, refusal } from "./refusals.ts";
 import { isSafeWorkspaceId, workspaceCapability } from "./capabilities.ts";
 import { ENV_WORKSPACE_REGISTRY } from "./env-names.ts";
+import { checkPinnedDestination, type ParsedPin } from "./workspace-pin.ts";
 export { ENV_WORKSPACE_REGISTRY } from "./env-names.ts";
 
 const execFileAsync = promisify(execFile);
@@ -181,9 +182,20 @@ export async function registeredWorkspaceIds(
   }
 }
 
+/**
+ * Resolve an authorised id to a worktree, refusing if the id no longer means what the grant meant.
+ *
+ * **`pin` is REQUIRED, and it used to default to reading the environment.** That default was the last
+ * environment fallback in the routing path, and it was the wrong reassurance: after `publishChildEnv` the
+ * variable holds a session's CHILD's pin, so a two-argument call checked a session against its child's
+ * authority. It is dead in-tree — the one production caller always passes one — but this is a public export,
+ * so an embedder could reach it. Requiring the argument closes it permanently and makes "a session's own pin
+ * lives in memory" unbreakable rather than merely currently-true.
+ */
 export async function resolveWorkspace(
   registry: WorkspaceRegistryFile,
   workspaceId: string,
+  pin: ParsedPin,
 ): Promise<ValidatedWorkspace> {
   const registered = Object.hasOwn(registry.workspaces, workspaceId) ? registry.workspaces[workspaceId] : undefined;
   const known = Object.keys(registry.workspaces).sort();
@@ -198,13 +210,34 @@ export async function resolveWorkspace(
       ),
     );
   }
-  return validateRegisteredWorkspace({ workspaceId, registeredRoot: registered.path });
+  const validated = await validateRegisteredWorkspace({ workspaceId, registeredRoot: registered.path });
+  // **ADR-0042, and it is checked HERE on purpose.** The capability check upstream asks whether this session may
+  // route to this NAME. This asks whether the name still points where it pointed when the name was granted —
+  // the question `g37-registry-tamper` showed nobody was asking. It runs after canonicalisation because the
+  // digest is of the canonical root; comparing the registry's raw string would be defeated by a symlink.
+  const mismatch = checkPinnedDestination({ workspaceId, canonicalRoot: validated.root, pin });
+  if (mismatch)
+    throw new GovernanceRefusal(
+      refusal("WORKSPACE_NOT_AUTHORIZED", `workspace ${workspaceId} is not routable: ${mismatch}`, {
+        workspace_id: workspaceId,
+        resolved_root: validated.root,
+      }),
+    );
+  return validated;
 }
 
 /**
  * Canonicalize and validate the initial workspace against Git's registered worktree list.
  * This prevents accidental misrouting. It does not constrain any path a child accesses after spawn.
  */
+/**
+ * Canonicalise and verify a registered root as a git worktree.
+ *
+ * **This performs NO destination-pin check (ADR-0042), deliberately and dangerously.** It answers "is this
+ * path the worktree it claims to be", not "may this session route here" — `resolveWorkspace` is the one that
+ * asks the second question, and it is the only path production takes. It is a public export, so it is said
+ * here rather than left to be discovered: an embedder calling this directly routes unpinned.
+ */
 export async function validateRegisteredWorkspace(input: {
   workspaceId: string;
   registeredRoot: string;