pi-daddy 0.22.0 → 0.23.0

package/dist/work-ledger.js

@@ -0,0 +1,225 @@
+/** Opt-in work-v4 evidence. No default emission or built-in acceptance authority. */
+import { isDate } from "node:util/types";
+import { open, stat } from "node:fs/promises";
+import { constants } from "node:fs";
+import { appendLedgerLine, readWorkBytes, closeWorkHandle } from "./ledger-append.js";
+import { workDestination, workFsError, validWorkPath } from "./work-ledger-destination.js";
+import { LockTimeoutError } from "./file-lock.js";
+import { canonicalWorkJson, copyWorkJson, freezeWork, ownWorkFields, parseWorkJson, WORK_EVENT_BYTES, WORK_TEXT_BYTES, WORK_RECORDS, mergeWorkConflicts, } from "./work-ledger-json.js";
+import { validateWorkEvent, validateWorkContext } from "./work-ledger-validation.js";
+import { indexWorkLedgerText, indexWorkReceipts, projectWorkAcceptance } from "./work-ledger-projection.js";
+import { resolveWorkSnapshotText } from "./work-ledger-snapshot.js";
+import { foldWorkOccurrences } from "./work-ledger-occurrences.js";
+import { WorkInputError, WorkLedgerWriteError, } from "./work-ledger-types.js";
+export * from "./work-ledger-types.js";
+function build(args, kind, field) {
+    const fields = ownWorkFields(args);
+    const required = ["eventId", "now", field];
+    if (Object.keys(fields).length !== required.length || required.some(key => !Object.hasOwn(fields, key))) {
+        throw new WorkInputError("WORK_SCHEMA_INVALID");
+    }
+    const now = fields.now.value;
+    if (!isDate(now) || Object.getPrototypeOf(now) !== Date.prototype || Reflect.ownKeys(now).length !== 0 ||
+        !Number.isFinite(Date.prototype.getTime.call(now)))
+        throw new WorkInputError("WORK_SCHEMA_INVALID");
+    const content = copyWorkJson(fields[field].value);
+    const candidate = copyWorkJson({ ledgerVersion: 4, event: kind, eventId: fields.eventId.value,
+        ts: Date.prototype.toISOString.call(now), payload: field === "payload" ? content : { [field]: content } });
+    const event = validateWorkEvent(candidate, true);
+    if (Buffer.byteLength(canonicalWorkJson(event), "utf8") > WORK_EVENT_BYTES)
+        throw new WorkInputError("WORK_LIMIT_EXCEEDED");
+    return freezeWork(event);
+}
+export function buildWorkRevisionEvent(args) {
+    return build(args, "work_revision", "revision");
+}
+export function buildWorkSnapshotEvent(args) {
+    return build(args, "work_snapshot", "snapshot");
+}
+export function buildWorkOccurrenceEvent(args) {
+    return build(args, "work_occurrence", "payload");
+}
+export function buildWorkAcceptanceEvent(args) {
+    return build(args, "work_acceptance", "payload");
+}
+function* lines(text) {
+    let start = 0, line = 1;
+    while (start < text.length) {
+        const end = text.indexOf("\n", start);
+        yield { text: text.slice(start, end === -1 ? text.length : end), line: line++ };
+        if (end === -1)
+            return;
+        start = end + 1;
+    }
+}
+const blank = (text) => /^[ \t\r]*$/.test(text);
+/** Diagnostic boundary: retain physical valid deliveries, never rewrite, deduplicate or elect a winner. */
+export function parseWorkLedgerText(text) {
+    const wholeError = (code) => freezeWork({ events: [], errors: [{ line: null, code }], complete: false });
+    if (typeof text !== "string")
+        return wholeError("WORK_SCHEMA_INVALID");
+    if (Buffer.byteLength(text, "utf8") > WORK_TEXT_BYTES)
+        return wholeError("WORK_LIMIT_EXCEEDED");
+    let records = 0;
+    for (const row of lines(text))
+        if (!blank(row.text) && ++records > WORK_RECORDS)
+            return wholeError("WORK_LIMIT_EXCEEDED");
+    const events = [], errors = [];
+    for (const row of lines(text)) {
+        if (blank(row.text))
+            continue;
+        try {
+            events.push(validateWorkEvent(parseWorkJson(row.text)));
+        }
+        catch (error) {
+            if (!(error instanceof WorkInputError))
+                throw error;
+            errors.push({ line: row.line, code: error.code });
+        }
+    }
+    return freezeWork({ events, errors, complete: errors.length === 0 });
+}
+/** Public opt-in projection: strict text, detached host context, exact selection, actual runtime,
+ * then conditional authority binding. No I/O, authenticator, ambient trust or acceptance callback. */
+export function projectWorkLedger(text, context = { selectedSnapshot: null, authority: null }) {
+    const index = indexWorkLedgerText(text);
+    const errors = [...index.ingestion.errors];
+    let copied = null;
+    try {
+        const value = copyWorkJson(context);
+        validateWorkContext(value);
+        copied = JSON.parse(canonicalWorkJson(value));
+    }
+    catch (error) {
+        if (!(error instanceof WorkInputError))
+            throw error;
+        errors.push({ line: null, code: "WORK_CONTEXT_INVALID" });
+    }
+    errors.sort((a, b) => (a.line ?? Infinity) - (b.line ?? Infinity) || (a.code < b.code ? -1 : a.code > b.code ? 1 : 0));
+    const conflicts = mergeWorkConflicts([
+        ...index.conflictingEvents.map(ref => ({ kind: "event", id: ref.eventId, digests: [ref.digest], affectedObligations: [] })),
+        ...indexWorkReceipts(copied?.authority ?? null).conflicts,
+    ]);
+    const identities = { selectedSnapshot: copied?.selectedSnapshot?.snapshot ?? null, authoritySnapshot: copied?.authority?.snapshot ?? null };
+    function empty(scopeState, problems, retained = conflicts) {
+        return freezeWork({ ...identities, scopeState, progress: null, obligations: [], claims: [], supersededClaims: 0,
+            conflicts: mergeWorkConflicts([...retained, ...conflicts]), problems, errors, runtime: null });
+    }
+    if (errors.length)
+        return empty("unresolved", [{ code: "INPUT_INCOMPLETE", reference: null, affectedObligations: [] }]);
+    const structure = resolveWorkSnapshotText(text, copied.selectedSnapshot);
+    if (structure.scopeState !== "valid")
+        return empty(structure.scopeState, structure.problems, structure.conflicts);
+    const runtime = foldWorkOccurrences(index, structure.snapshot);
+    const acceptance = projectWorkAcceptance(index, structure, copied.authority, runtime);
+    return freezeWork({ ...identities, scopeState: "valid", ...acceptance, errors, runtime: runtime.runtime });
+}
+/** Always opt-in, strict, and detached before the first filesystem await. No environment defaults. */
+export function appendWorkLedgerEvent(options, event) {
+    return appendWorkEvent(options, event, false);
+}
+/** Explicit controller application seam: exact ID/digest redelivery does not append a second event. */
+export function appendWorkLedgerEventOnce(options, event) {
+    return appendWorkEvent(options, event, true);
+}
+async function appendWorkEvent(options, event, once) {
+    const fields = ownWorkFields(options);
+    if (Object.keys(fields).length !== 2 || !Object.hasOwn(fields, "path") || !Object.hasOwn(fields, "grantLedgerPath") || typeof fields.path.value !== "string" ||
+        (fields.grantLedgerPath.value !== null && typeof fields.grantLedgerPath.value !== "string"))
+        throw new WorkInputError("WORK_SCHEMA_INVALID");
+    const path = fields.path.value, grant = fields.grantLedgerPath.value;
+    const candidate = validateWorkEvent(copyWorkJson(event));
+    const canonical = canonicalWorkJson(candidate);
+    if (Buffer.byteLength(canonical, "utf8") > WORK_EVENT_BYTES)
+        throw new WorkInputError("WORK_LIMIT_EXCEEDED");
+    try {
+        const destination = await workDestination(path, grant);
+        await appendLedgerLine({ path: destination.path }, canonical + "\n", destination, once ? { eventId: candidate.eventId, digest: candidate.digest } : undefined);
+    }
+    catch (error) {
+        if (error instanceof LockTimeoutError || workFsError(error))
+            throw new WorkLedgerWriteError("WORK_LEDGER_WRITE_FAILED");
+        throw error;
+    }
+}
+/** Read-only regular-file inspection; a successful read is not a content-validity or acceptance claim. */
+export async function inspectWorkLedger(options, context = { selectedSnapshot: null, authority: null }) {
+    let exists = null;
+    const failure = (code) => freezeWork({
+        version: 4, status: "error", exists, ingestion: null, projection: null, errors: [{ line: null, code }],
+    });
+    const missing = () => freezeWork({ version: 4, status: "missing", exists: false,
+        ingestion: null, projection: null, errors: [] });
+    let path, copied;
+    try {
+        const fields = ownWorkFields(options);
+        if (Object.keys(fields).length !== 2 || !Object.hasOwn(fields, "path") || !Object.hasOwn(fields, "version") || typeof fields.path.value !== "string")
+            throw new WorkInputError("WORK_SCHEMA_INVALID");
+        if (fields.version.value !== 4)
+            throw new WorkInputError("WORK_VERSION_UNSUPPORTED");
+        path = fields.path.value;
+        try {
+            const value = copyWorkJson(context);
+            validateWorkContext(value);
+            copied = value;
+        }
+        catch (error) {
+            if (error instanceof WorkInputError)
+                throw new WorkInputError("WORK_CONTEXT_INVALID");
+            throw error;
+        }
+    }
+    catch (error) {
+        if (error instanceof WorkInputError)
+            return failure(error.code);
+        throw error;
+    }
+    if (!validWorkPath(path))
+        return failure("WORK_INSPECTION_PATH_INVALID");
+    try {
+        let info;
+        try {
+            info = await stat(path);
+        }
+        catch (error) {
+            if (workFsError(error) && error.code === "ENOENT")
+                return missing();
+            throw error;
+        }
+        exists = true;
+        if (!info.isFile())
+            return failure("WORK_INSPECTION_NOT_REGULAR");
+        let handle;
+        try {
+            handle = await open(path, constants.O_RDONLY | constants.O_NONBLOCK);
+        }
+        catch (error) {
+            if (workFsError(error) && error.code === "ENOENT")
+                return missing();
+            throw error;
+        }
+        let failed = false, bytes;
+        try {
+            if (!(await handle.stat()).isFile())
+                return failure("WORK_INSPECTION_NOT_REGULAR");
+            bytes = await readWorkBytes(handle);
+        }
+        catch (error) {
+            failed = true;
+            throw error;
+        }
+        finally {
+            await closeWorkHandle(handle, failed);
+        }
+        const text = bytes.toString("utf8");
+        return freezeWork({ version: 4, status: "read", exists: true, ingestion: parseWorkLedgerText(text), projection: projectWorkLedger(text, copied), errors: [] });
+    }
+    catch (error) {
+        if (error instanceof WorkInputError)
+            return failure(error.code);
+        if (workFsError(error))
+            return failure("WORK_INSPECTION_READ_FAILED");
+        throw error;
+    }
+}
+//# sourceMappingURL=work-ledger.js.map

package/dist/work-ledger.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"work-ledger.js","sourceRoot":"","sources":["../src/work-ledger.ts"],"names":[],"mappings":"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"}

package/extensions/delegate-chain.ts

@@ -251,6 +251,7 @@ export function registerChainTool(pi: ExtensionAPI, session: GrantsSession): voi
           signal,
           {
             preApproved: availableForStep,
+            toolCallId: _toolCallId,
             // Only approvals actually offered to this step are attributed or consumed here.
             approvalFacts: chainApprovalFacts(approvalAudit, availableForStep, step.agent ?? DELEGATE_SUBJECT),
             onProgress: (update) => {

package/extensions/delegation-native.ts

@@ -0,0 +1,12 @@
+import { allocateNativeSessionTarget } from "../src/native-session-target.ts";
+import type { GrantsSession } from "./session.ts";
+import type { ExecutionOccurrenceIds } from "./execution-occurrence.ts";
+/** Shared delegate/all/chain host setup, before planning/audit; no tool-schema destination parameter. */
+export async function nativeDelegationContext(session:GrantsSession,ids:ExecutionOccurrenceIds,budget:number|undefined,refused:boolean){
+  let sessionFile:string|undefined,refusal:string|undefined;
+  if(!refused&&session.nativeSessionRoot!==undefined){
+    try{sessionFile=await allocateNativeSessionTarget(session.nativeSessionRoot,ids.executionId);}
+    catch(error){refusal=`native retention target refused (${String(error)})`;}
+  }
+  return {extra:{fanoutBudget:budget,spawnId:ids.parentId,childSpawnId:ids.childId,childExecutionId:ids.executionId,sessionFile},refusal};
+}

package/extensions/delegation.ts

@@ -241,7 +241,7 @@ export function registerDelegationTools(pi: ExtensionAPI, session: GrantsSession
         session.fanoutBudget,
         ctx,
         signal,
-        { onProgress: progress.sink(0) },
+        { onProgress: progress.sink(0), toolCallId: _toolCallId },
       );
       progress.settle([outcome]);
 
@@ -259,7 +259,7 @@ export function registerDelegationTools(pi: ExtensionAPI, session: GrantsSession
 
       return {
         content: [{ type: "text", text: outcome.text || "(no output)" }],
-        details: { granted: outcome.granted, depth: outcome.depth, exitCode: outcome.exitCode },
+        details: { granted: outcome.granted, depth: outcome.depth, exitCode: outcome.exitCode, retention: outcome.retention },
       };
     },
   });
@@ -317,7 +317,7 @@ export function registerDelegationTools(pi: ExtensionAPI, session: GrantsSession
             return await runOneDelegation(
               session, child,
               newDelegationOccurrence(session, index),
-              split.perChild, ctx, signal, { onProgress: progress.sink(index) },
+              split.perChild, ctx, signal, { onProgress: progress.sink(index), toolCallId: _toolCallId },
             );
           } catch (error) {
             infrastructureErrors.push(error);
@@ -353,6 +353,7 @@ export function registerDelegationTools(pi: ExtensionAPI, session: GrantsSession
           budgetPerChild: split.perChild,
           granted: outcomes.map((o) => o.granted),
           refusals: outcomes.map((o) => o.refusal ?? null),
+          retention: outcomes.map((o) => o.retention ?? null),
         },
       };
     },

package/extensions/execute-child.ts

@@ -1,4 +1,6 @@
+import { withOrdinaryChild } from "./ordinary-runtime.ts";
 import type { Delegation } from "../src/delegate.ts";
+import { beginExecutionRetention, retentionConfigurationDigest, type RetentionStatus } from "../src/execution-retention.ts";
 import { appendLedgerEvent, buildChildLifecycleEvent } from "../src/ledger.ts";
 import { hasFinalizerError } from "../src/finalization.ts";
 import { mergeChildEnv } from "../src/propagation.ts";
@@ -23,6 +25,9 @@ export interface DelegationOutcome {
   aborted?: boolean;
   truncated?: boolean;
   spawnFailed?: boolean;
+  retention?: RetentionStatus;
+  /** A loud best-effort post-execution observation failure; execution ownership is still settled. */
+  control?: "failed";
 }
 
 /**
@@ -78,13 +83,17 @@ export interface ChildProgressUpdate {
  * has already run, so failing closed there prevents nothing and used to discard completed work while
  * blaming "ledger" (R-99). The failure is reported alongside the outcome instead of replacing it.
  */
-export async function executePlannedChild(input: {
+export function executePlannedChild(input: Parameters<typeof executeChildBody>[0]): Promise<DelegationOutcome> {
+  return withOrdinaryChild(input, signal => executeChildBody({ ...input, signal }));
+}
+async function executeChildBody(input: {
   session: GrantsSession;
   plan: Delegation;
   agent?: string;
   childId: string;
   executionId: string;
   parentExecutionId: string | null;
+  toolCallId?: string;
   cwd: string;
   preparedWorkspace?: PreparedWorkspace;
   signal?: AbortSignal;
@@ -134,6 +143,13 @@ export async function executePlannedChild(input: {
   const executionSignal = signal
     ? AbortSignal.any([signal, leaseAbort.signal])
     : writerLease ? leaseAbort.signal : undefined;
+  const retention = beginExecutionRetention({ executionId, parentExecutionId, childId,
+    toolCallId: input.toolCallId ?? null, executor: session.executor.kind, taskDigest: plan.taskDigest,
+    definitionDigest: plan.definitionDigest?.sha256 ?? null,
+    configurationDigest: retentionConfigurationDigest({ args: plan.args, effective: plan.effective, timeoutMs: configuredTimeoutMs }),
+    workspaceId: preparedWorkspace?.workspace.workspaceId ?? null });
+  const sessionFlag = plan.args.indexOf("--session");
+  if (sessionFlag >= 0) retention.observeSession({ source: "pi-session-file", value: plan.args[sessionFlag + 1] });
   let releaseReason = "failed";
   let retainWriterLease = false;
   let terminalAttempted = false;
@@ -171,7 +187,12 @@ export async function executePlannedChild(input: {
           timeoutMs: remainingTimeoutMs,
           keepPane: writerLease ? false : process.env[ENV_HERDR_KEEP_PANE] === "1",
           closeOnSettle: Boolean(writerLease),
-          onPane: (paneId, agentName) => onProgress?.({ paneId, agentName, state: "starting" }),
+          onPane: (paneId, agentName) => {
+            retention.native({ paneId, agentName });
+            onProgress?.({ paneId, agentName, state: "starting" });
+          },
+          onObservation: (bytes) => retention.capture("paneSnapshot", bytes, true),
+          onSessionReference: (reference) => retention.observeSession(reference),
           onRunning: (paneId, agentName) => {
             // Record first: runHerdrPane isolates this display callback, so a renderer exception after the
             // observation cannot suppress the authoritative running event.
@@ -179,6 +200,7 @@ export async function executePlannedChild(input: {
             onProgress?.({ paneId, agentName, state: "running" });
           },
           onTab: preparedWorkspace ? (tabId) => preparedWorkspace.lease.attachHerdrTab(tabId) : undefined,
+          onNativeTab: (tabId) => retention.native({ tabId }),
           onSnapshot: onProgress ? (snapshot) => onProgress({ snapshot }) : undefined,
         })
       : await runChild({
@@ -192,17 +214,23 @@ export async function executePlannedChild(input: {
           timeoutMs: Math.max(1, remainingTimeoutMs - terminationGraceMs),
           hardDeadlineAt: Date.parse(deadlineAt),
           onOutput: onProgress ? (chunk) => onProgress({ chunk }) : undefined,
+          onObservation: (stream, bytes) => retention.capture(stream, bytes),
           onSpawn: (pid) => {
             // Lease attachment is a security hook and may fail the spawn. The shared reporters isolate
             // display exceptions before they reach this callback; runChild deliberately kills on any error
             // here, so presentation must never be added directly without that reporter boundary.
             preparedWorkspace?.lease.attachProcess(pid);
+            retention.native({ pid });
             recordRunning("process");
             onProgress?.({ state: "running" });
           },
         });
 
+    if (sessionFlag >= 0) retention.observeSession({ source: "pi-session-file", value: plan.args[sessionFlag + 1] });
+    retention.capture("result", Buffer.from(output.text), true);
     const childFailed = Boolean(output.spawnError || output.aborted || output.timedOut || output.code !== 0);
+    retention.finish({ code: output.code, signal: output.signal ?? null, timedOut: output.timedOut,
+      aborted: output.aborted, truncated: output.truncated, failed: childFailed });
     releaseReason = output.timedOut ? "timeout" : output.aborted ? "cancelled" : childFailed ? "failed" : "completed";
     if (ledgerPath) {
       terminalAttempted = true;
@@ -286,6 +314,7 @@ export async function executePlannedChild(input: {
     await teardown();
     return withTeardownNotes(succeeded);
   } catch (error) {
+    retention.finish({ code: null, signal: null, timedOut: false, aborted: Boolean(signal?.aborted), truncated: false, failed: true });
     retainWriterLease = Boolean(writerLease && isHerdrWriterCloseFailure(error));
     if (ledgerPath && !terminalAttempted) {
       // Best-effort: this records the failure, so it must not REPLACE the failure. A strict append that
@@ -338,8 +367,9 @@ function errorWithTeardownNotes(error: unknown, notes: readonly string[]): unkno
 }
 
   function withTeardownNotes(outcome: DelegationOutcome): DelegationOutcome {
-    if (teardownFailures.length === 0) return outcome;
-    return { ...outcome, reason: [outcome.reason, ...teardownFailures].filter(Boolean).join("; ") };
+    const observed = { ...outcome, retention: retention.status() };
+    if (teardownFailures.length === 0) return observed;
+    return { ...observed, control: "failed", reason: [outcome.reason, ...teardownFailures].filter(Boolean).join("; ") };
   }
 
   async function teardown(): Promise<void> {

package/extensions/grants.ts

@@ -47,6 +47,7 @@ import {
   openDashboardCommand,
 } from "../src/dashboard-handshake.ts";
 
+import { associateOrdinaryHost } from "../src/ordinary-children.ts";
 export default function (pi: ExtensionAPI) {
   // The path pi loads as the extension, so a child granted `tool:delegate` can be started with `-e <this>`.
   // Only this file can say so about itself, which is why the session takes it rather than deriving it.
@@ -59,6 +60,7 @@ export default function (pi: ExtensionAPI) {
   })();
 
   const session = createGrantsSession(extensionPath);
+  associateOrdinaryHost(pi,session);
   const dashboardPluginRoot = fileURLToPath(new URL("../herdr-plugin/", import.meta.url));
   const dashboardPaths = defaultDashboardPaths(
     process.env.PI_CODING_AGENT_DIR?.trim() || join(homedir(), ".pi", "agent"),

package/extensions/ordinary-runtime.ts

@@ -0,0 +1,14 @@
+import { retainSessionChild } from "../src/ordinary-children.ts";
+import { dataDigest } from "../src/debrief-contract.ts";
+import { runWithFinalizers } from "../src/finalization.ts";
+import { releaseDelegationWorkspace,type PreparedWorkspace } from "./workspace-runtime.ts";
+import type { GrantsSession } from "./session.ts";
+import type { DelegationOutcome } from "./execute-child.ts";
+/** One wrapper around the original executor. It neither consumes nor replaces the caller's promise. */
+export async function withOrdinaryChild(input:{session:GrantsSession;executionId:string;parentExecutionId:string|null;childId:string;toolCallId?:string;signal?:AbortSignal;preparedWorkspace?:PreparedWorkspace},operation:(signal?:AbortSignal)=>Promise<DelegationOutcome>){
+ let retained:ReturnType<typeof retainSessionChild>;
+ try{retained=retainSessionChild(input.session,{executionId:input.executionId,parentExecutionId:input.parentExecutionId,toolCallId:input.toolCallId??null},input.signal);}
+ catch(error){return runWithFinalizers(async()=>{throw error;},[{label:"ordinary admission workspace release",run:async()=>{await releaseDelegationWorkspace({prepared:input.preparedWorkspace,childId:input.childId,executionId:input.executionId,parentExecutionId:input.parentExecutionId,ledgerPath:input.session.ledgerPath,reason:"refused"});}}]);}
+ try{const outcome=await operation(retained?.signal??input.signal);retained?.settle({ok:outcome.ok,exitCode:outcome.exitCode,aborted:outcome.aborted??false,outputDigest:dataDigest(outcome.text)},outcome.control??"not-assessed",outcome.control==="failed"?"not-assessed":outcome.control??"not-assessed");return outcome;}
+ catch(error){retained?.settle({failure:"original executor threw; inspect original caller"},"unknown");throw error;}
+}

package/extensions/run-delegation.ts

@@ -11,6 +11,7 @@
  * tool surface is observed.
  */
 
+import { nativeDelegationContext } from "./delegation-native.ts";
 import { DELEGATE_SUBJECT, shouldSeekApproval } from "../src/approval.ts";
 import { planDelegation } from "../src/delegate.ts";
 import {
@@ -201,6 +202,8 @@ export async function runOneDelegation(
    * mistake unspellable.
    */
   options: {
+    /** Actual public execute argument, never read from model-authored correlation or output. */
+    toolCallId?: string;
     /** Progress for the parent's status block (ADR-0032). Display only. */
     onProgress?: (update: {
       /** Appended (process executor: a genuine byte stream). */
@@ -254,12 +257,6 @@ export async function runOneDelegation(
     boundWorkspaceId: spec.workspace?.workspace_id,
     boundContextId: spec.correlation?.context_id,
   };
-  const extra = {
-    fanoutBudget: budget,
-    spawnId: ids.parentId,
-    childSpawnId: ids.childId,
-    childExecutionId: ids.executionId,
-  };
 
   // ADR-0031: herdr was DEMANDED (`PI_GRANTS_HERDR=1`) and is not answering. Refused rather than relocated —
   // the operator chose that over falling back, so the ledger can never name a child that ran somewhere nobody
@@ -275,13 +272,15 @@ export async function runOneDelegation(
   // `ctx: null` rather than skipping the plan entirely: the ledger still gets a full, honest record of what was
   // requested and refused, and stored approvals still count toward it — nothing is *hidden*, only nobody is
   // *asked*. It is the same argument `/grants` uses for its preview.
-  const executorRefusal = session.executor.refusal;
+  let executorRefusal = session.executor.refusal;
   const modelRefusal = preflightModel(
     request.model,
     ctx.modelRegistry,
     session.modelResolutionCache,
     session.allowUnresolvedModels,
   );
+  const {extra,refusal:nativeRefusal}=await nativeDelegationContext(session,ids,budget,Boolean(executorRefusal||modelRefusal));
+  executorRefusal ||= nativeRefusal;
   let preparedWorkspace: PreparedWorkspace | undefined;
   let approvalOutcome: ApprovalOutcome | undefined;
   let plan: ReturnType<typeof planDelegation>;
@@ -388,6 +387,7 @@ export async function runOneDelegation(
     childId: ids.childId,
     executionId: ids.executionId,
     parentExecutionId: ids.parentExecutionId,
+    toolCallId: options.toolCallId,
     cwd: ctx.cwd,
     preparedWorkspace,
     signal,

package/extensions/session.ts

@@ -47,6 +47,7 @@ import { ENV_WORKSPACE_REGISTRY } from "../src/workspace.ts";
 import type { GrantStoreRefusalReason } from "../src/grant-store.ts";
 import { republishable } from "./approvals.ts";
 import { storedGrantSessionState } from "./stored-grant-session.ts";
+import { nativeSessionRootFromEnv, type NativeSessionHost } from "../src/native-session-target.ts";
 import { ENV_ALLOW_UNRESOLVED_MODELS } from "../src/model-preflight.ts";
 
 /**
@@ -79,7 +80,7 @@ export { ENV_HERDR_WORKSPACE } from "../src/herdr-cli.ts";
 /** Keep each child's pane after it finishes, for inspection. Off by default: fan-out would flood it. */
 export const ENV_HERDR_KEEP_PANE = "PI_GRANTS_HERDR_KEEP_PANE";
 
-export interface GrantsSession {
+export interface GrantsSession extends NativeSessionHost {
   /**
    * False when neither `PI_GRANTS_GRANT` nor a stored grant applies: the session holds the wildcard and
    * nothing is governed.
@@ -318,6 +319,7 @@ export function createGrantsSession(extensionPath: string | undefined): GrantsSe
      */
     mayDelegate: !governed || inherited.includes(DELEGATE_CAPABILITY) || inherited.includes(WILDCARD),
     allowUnresolvedModels: process.env[ENV_ALLOW_UNRESOLVED_MODELS] === "1",
+    nativeSessionRoot: nativeSessionRootFromEnv(process.env),
     modelResolutionCache: new Map<string, boolean>(),
     extensionPath,
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-daddy",
-  "version": "0.22.0",
+  "version": "0.23.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",
@@ -37,6 +37,67 @@
       "types": "./dist/ledger.d.ts",
       "default": "./dist/ledger.js"
     },
+    "./work-ledger": {
+      "types": "./dist/work-ledger.d.ts",
+      "default": "./dist/work-ledger.js"
+    },
+    "./factory-order": {
+      "types": "./dist/factory-order.d.ts",
+      "default": "./dist/factory-order.js"
+    },
+    "./experiment": {
+      "types": "./dist/experiment.d.ts",
+      "default": "./dist/experiment.js"
+    },
+    "./dashboard-harness": {
+      "types": "./dist/dashboard-harness.d.ts",
+      "default": "./dist/dashboard-harness.js"
+    },
+    "./dashboard-host": {
+      "types": "./dist/dashboard-host.d.ts",
+      "default": "./dist/dashboard-host.js"
+    },
+    "./dashboard-host-transport": {
+      "types": "./dist/dashboard-host-transport.d.ts",
+      "default": "./dist/dashboard-host-transport.js"
+    },
+    "./debrief-host": {
+      "types": "./dist/debrief-host.d.ts",
+      "default": "./dist/debrief-host.js"
+    },
+    "./contracts/debrief/v2/*": "./contracts/debrief/v2/*",
+    "./debrief": {
+      "types": "./dist/debrief.d.ts",
+      "default": "./dist/debrief.js"
+    },
+    "./daily-view": {
+      "types": "./dist/daily-view.d.ts",
+      "default": "./dist/daily-view.js"
+    },
+    "./intent-control": {
+      "types": "./dist/intent-control.d.ts",
+      "default": "./dist/intent-control.js"
+    },
+    "./dispatch-control": {
+      "types": "./dist/dispatch-control.d.ts",
+      "default": "./dist/dispatch-control.js"
+    },
+    "./resource-budget": {
+      "types": "./dist/resource-budget.d.ts",
+      "default": "./dist/resource-budget.js"
+    },
+    "./producer-ipc": {
+      "types": "./dist/producer-ipc.d.ts",
+      "default": "./dist/producer-ipc.js"
+    },
+    "./effect-profile": {
+      "types": "./dist/effect-profile.d.ts",
+      "default": "./dist/effect-profile.js"
+    },
+    "./execution-retention": {
+      "types": "./dist/execution-retention.d.ts",
+      "default": "./dist/execution-retention.js"
+    },
     "./spawn": {
       "types": "./dist/spawn.d.ts",
       "default": "./dist/spawn.js"
@@ -137,6 +198,19 @@
       "types": "./dist/dashboard-render.d.ts",
       "default": "./dist/dashboard-render.js"
     },
+    "./contracts/factory-order/v1/*": "./contracts/factory-order/v1/*",
+    "./contracts/experiment/v1/*": "./contracts/experiment/v1/*",
+    "./contracts/producer-ipc/v1/*": "./contracts/producer-ipc/v1/*",
+    "./contracts/debrief/v1/*": "./contracts/debrief/v1/*",
+    "./contracts/intent-control/v2/request.schema.json": "./contracts/intent-control/v2/request.schema.json",
+    "./contracts/intent-control/v1/request.schema.json": "./contracts/intent-control/v1/request.schema.json",
+    "./contracts/dispatch-control/v1/request.schema.json": "./contracts/dispatch-control/v1/request.schema.json",
+    "./contracts/daily-view/v1/fixtures/*": "./contracts/daily-view/v1/fixtures/*",
+    "./contracts/daily-view/v1/p03/projection.schema.json": "./contracts/daily-view/v1/p03/projection.schema.json",
+    "./contracts/execution-retention/v2/manifest.schema.json": "./contracts/execution-retention/v2/manifest.schema.json",
+    "./contracts/execution-retention/v2/fixtures/*": "./contracts/execution-retention/v2/fixtures/*",
+    "./contracts/ledger/v4/ledger-event.schema.json": "./contracts/ledger/v4/ledger-event.schema.json",
+    "./contracts/ledger/v4/fixtures/*.json": "./contracts/ledger/v4/fixtures/*.json",
     "./contracts/ledger/v3/ledger-event.schema.json": "./contracts/ledger/v3/ledger-event.schema.json",
     "./contracts/ledger/v3/fixtures/*.json": "./contracts/ledger/v3/fixtures/*.json",
     "./contracts/ledger/v2/ledger-event.schema.json": "./contracts/ledger/v2/ledger-event.schema.json",
@@ -159,13 +233,13 @@
   "scripts": {
     "build": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\" && tsc -p tsconfig.json",
     "typecheck": "tsc -p tsconfig.check.json",
-    "test": "node --test test/*.test.ts",
+    "test": "node scripts/unit-tests.ts",
     "test:integration": "node --test test-integration/*.it.ts",
     "test:integration:ci": "node --test test-integration/approval.it.ts test-integration/governance.it.ts",
     "contracts:generate": "node scripts/generate-ledger-v3-contract.ts",
+    "contracts:generate:v4": "node scripts/generate-ledger-v4-contract.ts contracts/ledger/v4",
     "prepack": "npm run build",
-    "test:smoke": "node scripts/smoke-installed.mjs",
-    "test:mutation": "node scripts/mutation-audit.mjs"
+    "test:smoke": "node scripts/smoke-installed.mjs"
   },
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",