pi-daddy 0.22.0 → 0.24.0

package/src/herdr-poll.ts

@@ -12,6 +12,7 @@
  */
 
 import { parseReply, type HerdrExec } from "./herdr-cli.ts";
+import { herdrSessionReference } from "./native-session.ts";
 
 /**
  * What `waitForSettled` needs from a run request.
@@ -22,6 +23,8 @@ import { parseReply, type HerdrExec } from "./herdr-cli.ts";
 export interface PollTarget {
   /** herdr agent name. */
   name: string;
+  nativePaneId?: string;
+  onSessionReference?: (reference: NonNullable<ReturnType<typeof herdrSessionReference>>) => void;
   signal?: AbortSignal;
   /**
    * The pane's last few lines, re-reported on every poll — a SNAPSHOT, not a stream (ADR-0032).
@@ -31,6 +34,8 @@ export interface PollTarget {
    * `tailLines`.
    */
   onSnapshot?: (lines: string[]) => void;
+  /** Reuses already-requested pane bytes; never adds an observation-only RPC. */
+  onObservation?: (bytes: Uint8Array) => void;
   /** How many lines the display wants. Bounds the per-poll cost regardless of how big the pane is. */
   snapshotLines?: number;
   /** Poll cadence override. Exists so tests do not wait `POLL_INTERVAL_MS` per state transition. */
@@ -40,6 +45,17 @@ export interface PollTarget {
 /** Statuses herdr reports for a settled agent. `blocked` counts: it is waiting for a human, not working. */
 const TERMINAL = new Set(["idle", "done", "blocked"]);
 
+/** The pre-prompt sequence from the native start reply; absent is unknown, never zero. */
+export function observeHerdrSession(agent: unknown, pane: string | undefined, sink: PollTarget["onSessionReference"]): void {
+  if (!pane || !sink) return;
+  try { const reference = herdrSessionReference(agent, pane); if (reference) sink(reference); } catch { /* optional observation */ }
+}
+
+export function seqOf(result: Record<string, unknown> | undefined): number {
+  const agent = (result?.agent ?? {}) as { state_change_seq?: number };
+  return typeof agent.state_change_seq === "number" ? agent.state_change_seq : -1;
+}
+
 /** How often to poll `agent get` while waiting for the child to settle. */
 export const POLL_INTERVAL_MS = 750;
 /** Lines of pane tail reported per poll. Matches the status block's own tail, so nothing is fetched unused. */
@@ -81,6 +97,7 @@ export async function waitForSettled(
     if (reply.error) return { spawnError: `herdr agent get failed: ${reply.error}` };
 
     const agent = (reply.result?.agent ?? reply.result ?? {}) as { agent_status?: string; state_change_seq?: number };
+    observeHerdrSession(agent, request.nativePaneId, request.onSessionReference);
     const status = agent.agent_status;
     const seq = typeof agent.state_change_seq === "number" ? agent.state_change_seq : -1;
 
@@ -89,6 +106,7 @@ export async function waitForSettled(
       // output shown. `readFailed` is passed so a failed read renders as such instead of silently freezing the
       // block on the previous frame — and, crucially, is never mistaken for the child's output.
       const read = await readPane(exec, request.name, maxOutputBytes);
+      if (!read.readFailed) { try { request.onObservation?.(Buffer.from(read.text)); } catch { /* observation only */ } }
       try {
         request.onSnapshot(read.readFailed ? ["[pane could not be read]"] : tailLines(read.text, keep));
       } catch {

package/src/index.ts

@@ -34,7 +34,39 @@ export {
   type WorkflowFactState,
 } from "./ledger.ts";
 
+export { createDebriefPresenter, type DebriefPresenter, type DebriefHost, type DebriefFrame, type DebriefCheckpoint, type DebriefPersistence } from "./debrief.ts";
+export { ordinaryChildrenFor, ordinaryCancellation, ordinaryCancellationDigest, isOrdinaryChildren, type OrdinaryChildren, type OrdinaryCancellation, type OrdinaryAuthority, type OrdinaryTarget } from "./ordinary-children.ts";
+export { loadDashboardHarness, loadedDashboardHarnessDigest, type DashboardHarnessArtifact } from "./dashboard-harness.ts";
+export { createDashboardHost, openDashboardHost, dashboardHostDigest, dashboardHostRequestDigest, dashboardSelectionDigest, type DashboardHost, type DashboardHostConfig, type DashboardHostRequest, type DashboardHostAuthority, type DashboardHarness, type DashboardHostOptions } from "./dashboard-host.ts";
+export { serveDashboardHost, connectDashboardHost, ENV_DASHBOARD_HOST_SOCKET, type DashboardConnection } from "./dashboard-host-transport.ts";
+export { createRetainedDebrief, retainDebriefBlind, openDebriefBlindPreview, type DebriefHarness, type CaseSelection, type DurableBlindBinding } from "./debrief-host.ts";
+export { renderDebrief, debriefAction as dashboardDebriefAction } from "./debrief-render.ts";
+export { type ReviewPort, type ReviewRequest, type BlindPort, type BlindChoice } from "./debrief-contract.ts";
+export { readDailyView, createDailyViewReader, DAILY_VIEW_VERSION, type DailyView, type DailyViewOptions,
+  type DailyAttempt, type DailyObligation } from "./daily-view.ts";
+export { renderDailyView } from "./daily-view-render.ts";
+export { parseArchiveProjection, ARCHIVE_PROJECTION_VERSION } from "./daily-view-input.ts";
+export { bindWorkIntent } from "./intent-application.ts";
+export { intentRequestDigest, parseIntentRequest, type IntentRequest, type IntentSelection, type IntentPriority,
+  type IntentAdmission, type IntentSnapshot, type IntentReceipt, type WorkIntentBinding } from "./intent-control.ts";
+export { dispatchRequestDigest, parseDispatchRequest, type DispatchRequest, type DispatchAuthority, type DispatchRecord, type DispatchSnapshot } from "./dispatch-control.ts";
+export { createFactoryRegistry, openFactoryRegistry, createFactoryOrder, openFactoryOrder, migrateFactoryOrder,
+  factoryOrderDigest, parseFactoryOrder, fixedPolicyDigest, factoryDecisionDigest, activationRequestDigest, factoryMigrationDigest,
+  type FactoryRegistryBinding, type FactoryOrderCharter, type FactoryAuthority, type FactoryOrderView, type FixedPolicy, type ActivationRequest, type FactoryMigration } from "./factory-order.ts";
+export { createExperiment, openExperiment, experimentCharterDigest, experimentBindingDigest, experimentCancellationDigest, parseExperimentCharter,
+  type ExperimentBinding, type ExperimentCharter, type ExperimentAuthority, type ExperimentCancellation, type ExperimentRun, type ExperimentView } from "./experiment.ts";
+export { createResourceBudget, createDispatchBudget, createIntentBudget, createExperimentBudget, openResourceBudget, resourceBindingDigest, ResourceAdmissionError,
+  type BudgetBinding, type DispatchBudgetBinding, type IntentBudgetBinding, type ExperimentBudgetBinding, type GovernedBudgetBinding, type ResourceLimits, type AttemptDemand, type ResourcePermit, type BudgetSnapshot } from "./resource-budget.ts";
+export { createProducerIpcHost, startProducerIpc, producerIpcBinding, producerIpcBindingDigest, producerIpcDemand, PRODUCER_IPC_LIMITS,
+  type ProducerIpcBinding, type ProducerIpcReferences, type ProducerIpcContext, type ProducerIpcHost, type ProducerIpcSnapshot, type ProducerIpcRun } from "./producer-ipc.ts";
+export { prepareDigestProfile, runDigestProfile, DIGEST_PROFILE, EffectProfileUnavailableError,
+  type DigestProfile, type DigestAttempt } from "./effect-profile.ts";
 export { planSpawn, type SpawnPlan, type SpawnPlanInput } from "./spawn.ts";
+export { beginExecutionRetention, drainExecutionRetention, ENV_EXECUTION_ARCHIVE, RETENTION_VERSION, retentionConfigurationDigest, verifyRetainedBytes,
+  type ExecutionRetentionManifest, type RetainedContent, type RetentionIdentity, type RetentionStatus,
+  type ExecutionRetention, buildExecutionRetentionManifest, parseExecutionRetentionManifest, RETENTION_SCHEMA,
+  ENV_NATIVE_SESSION_ROOT, readNativeSession, parseNativeSessionBytes,
+  type NativeSessionObservation, type NativeSessionManager } from "./execution-retention.ts";
 
 export {
   APPROVAL_TTL_DAYS,

package/src/intent-application.ts

@@ -0,0 +1,90 @@
+import { lstat, realpath } from "node:fs/promises";
+import { dirname, isAbsolute, resolve } from "node:path";
+import { readDailySnapshot } from "./daily-view-input.ts";
+import { workDestination } from "./work-ledger-destination.ts";
+import { appendWorkLedgerEventOnce, buildWorkRevisionEvent, buildWorkSnapshotEvent, parseWorkLedgerText, type WorkFrozen, type WorkRevision } from "./work-ledger.ts";
+import { resolveWorkSnapshotText } from "./work-ledger-snapshot.ts";
+import { controlShape } from "./dispatch-control.ts";
+import { freezeWork } from "./work-ledger-json.ts";
+import { intentKey, intentSelection, intentPriorities, type WorkIntentBinding, type IntentRequest, type IntentState, type IntentSelection, type IntentPriority } from "./intent-control.ts";
+const ref = (r: WorkFrozen<WorkRevision>) => ({ kind: r.kind, id: r.id, revision: r.revision, digest: r.digest });
+const entity = (r: { kind: string; id: string } | null) => r ? `${r.kind}:${r.id}` : null;
+export function workIntentBinding(input: WorkIntentBinding): WorkIntentBinding {
+  controlShape(input, ["version", "path", "device", "inode", "grantLedgerPath", "selection", "priorities"]);
+  if (input.version !== "1.0" || typeof input.path !== "string" || input.path.length > 1024 || !isAbsolute(input.path) || resolve(input.path) !== input.path || input.path.split("/").includes(".pi") ||
+    ![input.device, input.inode].every(x => typeof x === "string" && /^\d+$/.test(x)) || !(input.grantLedgerPath === null || typeof input.grantLedgerPath === "string" && input.grantLedgerPath.length <= 1024 && isAbsolute(input.grantLedgerPath))) throw new TypeError("invalid pinned work binding");
+  return JSON.parse(intentKey({ ...input, selection: intentSelection(input.selection), priorities: intentPriorities(input.priorities) }));
+}
+export async function readIntentWork(input: WorkFrozen<WorkIntentBinding>): Promise<string> {
+  const check = async () => {
+    const st = await lstat(input.path, { bigint: true });
+    if (!st.isFile() || st.nlink !== 1n || st.uid !== BigInt(process.getuid!()) || (st.mode & 0o077n) || String(st.dev) !== input.device || String(st.ino) !== input.inode || await realpath(input.path) !== input.path) throw new Error("work binding changed");
+  };
+  await check(); const bytes = await readDailySnapshot(input.path, 16 * 1024 * 1024); await check();
+  if (bytes.status !== "read") throw new Error("required work snapshot unavailable");
+  const text = new TextDecoder("utf-8", { fatal: true }).decode(bytes.bytes);
+  if (!text.endsWith("\n") || !parseWorkLedgerText(text).complete) throw new Error("incomplete work ledger; no repair");
+  return text;
+}
+export function resolveIntent(text: string, selection: WorkFrozen<IntentSelection>, priorities: WorkFrozen<IntentPriority[]>): ReturnType<typeof resolveWorkSnapshotText> {
+  const result = resolveWorkSnapshotText(text, selection);
+  if (result.scopeState !== "valid" || !result.scope || !result.snapshot || result.revisions.length > 64) throw new Error("unresolved authoritative work selection");
+  const wanted = result.snapshot.bindings.map(b => intentKey(b.obligation)).sort();
+  if (intentKey(wanted) !== intentKey(priorities.map(p => intentKey(p.obligation)).sort())) throw new Error("priority policy must name exactly the selected obligations");
+  return result;
+}
+/** Actual owned bytes establish the physical binding; caller supplies the exact initial selection. */
+export async function bindWorkIntent(input: { path: string; grantLedgerPath: string | null; selection: IntentSelection; priorities: IntentPriority[] }): Promise<WorkFrozen<WorkIntentBinding>> {
+  controlShape(input, ["path", "grantLedgerPath", "selection", "priorities"]);
+  const selection = intentSelection(input.selection), priorities = intentPriorities(input.priorities), path = input.path, grantLedgerPath = input.grantLedgerPath;
+  if (typeof path !== "string" || !isAbsolute(path) || path.split("/").includes(".pi")) throw new TypeError("explicit work path required");
+  await workDestination(path, grantLedgerPath);
+  const parent = await lstat(dirname(path), { bigint: true });
+  if (!parent.isDirectory() || (parent.mode & 0o077n) || parent.uid !== BigInt(process.getuid!())) throw new Error("owner-private work parent required");
+  const st = await lstat(path, { bigint: true });
+  const binding = workIntentBinding({ version: "1.0", path, grantLedgerPath, device: String(st.dev), inode: String(st.ino), selection, priorities });
+  resolveIntent(await readIntentWork(binding), selection, priorities); return freezeWork(binding);
+}
+/** No authority callback: validate concrete P01 effects and prevent permission/owner/policy expansion. */
+export async function validateIntentApplication(binding: WorkFrozen<WorkIntentBinding>, state: IntentState, request: WorkFrozen<IntentRequest>): Promise<void> {
+  const text = await readIntentWork(binding), current = resolveIntent(text, state.selection, state.priorities);
+  const existing = parseWorkLedgerText(text).events;
+  const missing = request.events.filter(e => {
+    const sameId = existing.filter(old => old.eventId === e.eventId);
+    if (sameId.some(old => old.digest !== e.digest)) throw new Error("proposed event identity conflicts with retained work");
+    return sameId.length === 0;
+  });
+  const candidate = text + missing.map(e => intentKey(e) + "\n").join("");
+  const next = resolveIntent(candidate, request.selection, request.priorities);
+  if (request.action === "reprioritize" && intentKey(request.selection) !== intentKey(state.selection)) throw new Error("priority is not scope selection");
+  if (request.action !== "reprioritize" && intentKey(request.selection) === intentKey(state.selection)) throw new Error("a different exact recorded selection is required");
+  const old = [current.scope!, ...current.revisions], after = [next.scope!, ...next.revisions];
+  if (intentKey(old.map(entity).sort()) !== intentKey(after.map(entity).sort())) throw new Error("entity expansion/removal is outside this bounded adapter");
+  for (const r of after) {
+    const prior = old.find(p => entity(p) === entity(r))!;
+    if (r.ownerId !== prior.ownerId || r.scopeId !== prior.scopeId || r.permittedEffects.some(e => !prior.permittedEffects.includes(e)) || intentKey(r.policy) !== intentKey(prior.policy) ||
+      entity(r.parent) !== entity(prior.parent) || intentKey(r.dependencies.map(entity).sort()) !== intentKey(prior.dependencies.map(entity).sort()) ||
+      r.kind === "policy" && r.digest !== prior.digest) throw new Error("owner, policy, topology or permission expansion refused");
+    if (["revise-scope", "revise-selection"].includes(request.action) && r.digest !== prior.digest && (r.revision !== prior.revision + 1 || intentKey(r.predecessor) !== intentKey(ref(prior)))) throw new Error("exact successor required");
+  }
+  if (request.action === "revise-selection" && !after.some(r => r.digest !== old.find(p => entity(p) === entity(r))!.digest)) throw new Error("at least one exact successor revision required");
+  if (request.action === "revise-scope" && (next.scope!.revision !== current.scope!.revision + 1 || intentKey(next.scope!.predecessor) !== intentKey(ref(current.scope!)))) throw new Error("scope revision is not dispatch revision");
+  for (const e of request.events) {
+    // Rebuild through the actual P01 builders, not an alternate event/hash encoder.
+    if (e.event === "work_revision") {
+      const { digest: _digest, ...revision } = e.payload.revision;
+      if (!after.some(r => intentKey(ref(r)) === intentKey(ref(e.payload.revision))) || intentKey(buildWorkRevisionEvent({ eventId: e.eventId, now: new Date(e.ts), revision: JSON.parse(intentKey(revision)) })) !== intentKey(e)) throw new Error("unselected or noncanonical revision proposal");
+    } else if (e.event === "work_snapshot") {
+      const { digest: _digest, ...snapshot } = e.payload.snapshot;
+      if (e.eventId !== request.selection.event.eventId || e.digest !== request.selection.event.digest || intentKey(buildWorkSnapshotEvent({ eventId: e.eventId, now: new Date(e.ts), snapshot: JSON.parse(intentKey(snapshot)) })) !== intentKey(e)) throw new Error("unselected snapshot proposal");
+    }
+  }
+}
+export async function applyIntentApplication(binding: WorkFrozen<WorkIntentBinding>, state: IntentState, request: WorkFrozen<IntentRequest>): Promise<void> {
+  await validateIntentApplication(binding, state, request);
+  for (const event of request.events) {
+    await readIntentWork(binding);
+    await appendWorkLedgerEventOnce({ path: binding.path, grantLedgerPath: binding.grantLedgerPath }, event);
+  }
+  resolveIntent(await readIntentWork(binding), request.selection, request.priorities);
+}

package/src/intent-control.ts

@@ -0,0 +1,107 @@
+import { createHash } from "node:crypto";
+import { canonicalWorkJson, copyWorkJson, freezeWork, parseWorkJson } from "./work-ledger-json.ts";
+import { parseWorkLedgerText, type WorkFrozen, type WorkProjectionContext, type RevisionRef, type WorkRevisionEvent, type WorkSnapshotEvent } from "./work-ledger.ts";
+import { validateWorkSelection } from "./work-ledger-validation.ts";
+import { controlShape } from "./dispatch-control.ts";
+export type IntentSelection = NonNullable<WorkProjectionContext["selectedSnapshot"]>;
+export interface IntentPriority { obligation: RevisionRef; rank: number }
+export interface WorkIntentBinding {
+  version: "1.0"; path: string; device: string; inode: string; grantLedgerPath: string | null;
+  selection: IntentSelection; priorities: IntentPriority[];
+}
+export interface IntentRequest {
+  version: "intent-request-v1" | "intent-request-v2"; requestId: string; bindingDigest: string; expectedRevision: number;
+  expectedSelection: IntentSelection; action: "revise-scope" | "reprioritize" | "select-alternative" | "revise-selection";
+  events: (WorkRevisionEvent | WorkSnapshotEvent)[]; selection: IntentSelection; priorities: IntentPriority[];
+}
+export interface IntentReceipt {
+  requestId: string; digest: string; expectedRevision: number; expectedSelection: IntentSelection;
+  action: IntentRequest["action"]; selection: IntentSelection; priorities: IntentPriority[];
+  events: { eventId: string; digest: string }[];
+  decision: "approved" | "authority-unavailable" | "stale" | "busy";
+  application: "pending-or-unknown" | "applied" | "not-applied";
+  outcome: "pending-or-unknown" | "selection-applied" | "priority-applied" | "refused";
+  resultSelection: IntentSelection | null;
+}
+export interface IntentState { revision: number; selection: IntentSelection; priorities: IntentPriority[]; records: IntentReceipt[] }
+export interface IntentAdmission { selection: IntentSelection; revision: number; obligation: RevisionRef }
+export type IntentSnapshot = WorkFrozen<IntentState & { version: "intent-controller-snapshot-v1"; bindingDigest: string;
+  admission: "blocked-pending" | "intent-ready"; acceptance: "not-assessed"; freshness: "snapshot-unknown" }>;
+export const intentKey = (value: unknown) => canonicalWorkJson(copyWorkJson(value));
+const hash = (value: unknown) => createHash("sha256").update(intentKey(value)).digest("hex");
+const id = (x: unknown) => typeof x === "string" && /^[a-zA-Z0-9:_-]{1,128}$/.test(x);
+const hex = (x: unknown) => typeof x === "string" && /^[a-f0-9]{64}$/.test(x);
+export function intentPriorities(input: unknown): IntentPriority[] {
+  const result = copyWorkJson(input) as unknown as IntentPriority[];
+  if (!Array.isArray(result) || result.length > 32) throw new TypeError("bounded explicit priorities required");
+  for (const p of result) {
+    controlShape(p, ["obligation", "rank"]); controlShape(p.obligation, ["kind", "id", "revision", "digest"]);
+    if (p.obligation.kind !== "obligation" || !id(p.obligation.id) || !hex(p.obligation.digest) || !Number.isSafeInteger(p.obligation.revision) || p.obligation.revision < 1 ||
+      !Number.isSafeInteger(p.rank) || p.rank < 0 || p.rank > 127) throw new TypeError("invalid priority");
+  }
+  if (new Set(result.map(p => intentKey(p.obligation))).size !== result.length) throw new TypeError("duplicate priority obligation");
+  return result.sort((a, b) => a.rank - b.rank || (intentKey(a.obligation) < intentKey(b.obligation) ? -1 : 1));
+}
+export function intentSelection(value: unknown): IntentSelection {
+  const copied = copyWorkJson(value); validateWorkSelection(copied);
+  if (copied === null) throw new TypeError("exact intent selection required");
+  return copied as unknown as IntentSelection;
+}
+export function intentRequest(input: IntentRequest): WorkFrozen<IntentRequest> {
+  const r = copyWorkJson(input) as unknown as IntentRequest;
+  controlShape(r, ["version", "requestId", "bindingDigest", "expectedRevision", "expectedSelection", "action", "events", "selection", "priorities"]);
+  if ((r.action === "revise-selection" ? r.version !== "intent-request-v2" : r.version !== "intent-request-v1") || !id(r.requestId) || !hex(r.bindingDigest) || !Number.isSafeInteger(r.expectedRevision) || r.expectedRevision < 0 || r.expectedRevision > 32 ||
+    !["revise-scope", "reprioritize", "select-alternative", "revise-selection"].includes(r.action) || !Array.isArray(r.events) || r.events.length > 16 || Buffer.byteLength(intentKey(r)) > 48 * 1024) throw new TypeError("invalid bounded intent request");
+  const parsed = parseWorkLedgerText(r.events.map(e => intentKey(e)).join("\n"));
+  if (!parsed.complete || parsed.events.some(e => !id(e.eventId) || !["work_revision", "work_snapshot"].includes(e.event)) || new Set(parsed.events.map(e => e.eventId)).size !== parsed.events.length ||
+    (!["revise-scope", "revise-selection"].includes(r.action) && r.events.length)) throw new TypeError("only strict revision/snapshot proposals may be appended");
+  return freezeWork({ ...r, expectedSelection: intentSelection(r.expectedSelection), selection: intentSelection(r.selection), priorities: intentPriorities(r.priorities) });
+}
+export const parseIntentRequest = (text: string) => intentRequest(parseWorkJson(text) as unknown as IntentRequest);
+export const intentRequestDigest = (input: WorkFrozen<IntentRequest>) => hash(intentRequest(input as IntentRequest));
+export function intentReceipt(input: WorkFrozen<IntentRequest>, decision: IntentReceipt["decision"]): IntentReceipt {
+  return JSON.parse(intentKey({ requestId: input.requestId, digest: intentRequestDigest(input), expectedRevision: input.expectedRevision,
+    expectedSelection: input.expectedSelection, action: input.action, selection: input.selection, priorities: input.priorities,
+    events: input.events.map(e => ({ eventId: e.eventId, digest: e.digest })), decision,
+    application: decision === "approved" ? "pending-or-unknown" : "not-applied",
+    outcome: decision === "approved" ? "pending-or-unknown" : "refused", resultSelection: null }));
+}
+export function matchesIntentReceipt(receipt: IntentReceipt, request: WorkFrozen<IntentRequest>): boolean {
+  const expected = intentReceipt(request, receipt.decision);
+  if (receipt.application === "applied") {
+    expected.application = "applied"; expected.resultSelection = JSON.parse(intentKey(request.selection));
+    expected.outcome = request.action === "reprioritize" ? "priority-applied" : "selection-applied";
+  }
+  return intentKey(receipt) === intentKey(expected);
+}
+export function intentDecision(state: IntentState, request: Pick<IntentRequest, "expectedRevision" | "expectedSelection">, authorized: boolean, dispatchBusy: boolean): IntentReceipt["decision"] {
+  if (!authorized) return "authority-unavailable";
+  if (request.expectedRevision !== state.revision || intentKey(request.expectedSelection) !== intentKey(state.selection)) return "stale";
+  if (dispatchBusy || state.records.some(r => r.application === "pending-or-unknown")) return "busy";
+  return "approved";
+}
+export function replayIntent(state: IntentState, event: Record<string, unknown>, active: number, dispatchBusy: boolean): void {
+  if (event.type === "intent-request") {
+    controlShape(event, ["type", "receipt"]);
+    const r = event.receipt as IntentReceipt;
+    controlShape(r, ["requestId", "digest", "expectedRevision", "expectedSelection", "action", "selection", "priorities", "events", "decision", "application", "outcome", "resultSelection"]);
+    intentSelection(r.expectedSelection); intentSelection(r.selection); intentPriorities(r.priorities);
+    if (!id(r.requestId) || !hex(r.digest) || !Number.isSafeInteger(r.expectedRevision) || r.expectedRevision < 0 || !["revise-scope", "reprioritize", "select-alternative", "revise-selection"].includes(r.action) ||
+      !Array.isArray(r.events) || r.events.length > 16 || state.records.length >= 32 || state.records.some(p => p.requestId === r.requestId) ||
+      intentDecision(state, r, r.decision !== "authority-unavailable", dispatchBusy) !== r.decision || r.application !== (r.decision === "approved" ? "pending-or-unknown" : "not-applied") ||
+      r.outcome !== (r.decision === "approved" ? "pending-or-unknown" : "refused") || r.resultSelection !== null) throw new Error("invalid intent decision sequence");
+    for (const ref of r.events) { controlShape(ref, ["eventId", "digest"]); if (!id(ref.eventId) || !hex(ref.digest)) throw new Error("invalid event reference"); }
+    state.records.push(r); if (r.decision === "approved") state.revision++;
+  } else {
+    controlShape(event, ["type", "requestId"]);
+    const r = state.records.find(r => r.requestId === event.requestId);
+    if (event.type !== "intent-apply" || !r || r.application !== "pending-or-unknown" || active || dispatchBusy) throw new Error("invalid intent application boundary");
+    state.selection = r.selection; state.priorities = r.priorities; r.application = "applied";
+    r.outcome = r.action === "reprioritize" ? "priority-applied" : "selection-applied"; r.resultSelection = r.selection;
+  }
+}
+export function intentSnapshot(state: IntentState, bindingDigest: string): IntentSnapshot {
+  return freezeWork({ version: "intent-controller-snapshot-v1", bindingDigest, ...state,
+    admission: state.records.some(r => r.application === "pending-or-unknown") ? "blocked-pending" : "intent-ready",
+    acceptance: "not-assessed", freshness: "snapshot-unknown" });
+}

package/src/intent-scheduling.ts

@@ -0,0 +1,14 @@
+import { intentKey, intentSelection, intentPriorities, type IntentState, type IntentAdmission } from "./intent-control.ts";
+import { controlShape } from "./dispatch-control.ts";
+interface Charged { intent?: IntentAdmission }
+export function nextIntent(state: IntentState, records: readonly Charged[]) {
+  return intentPriorities(state.priorities).find(p => !records.some(r => r.intent &&
+    intentKey(r.intent.selection) === intentKey(state.selection) && intentKey(r.intent.obligation) === intentKey(p.obligation)))?.obligation ?? null;
+}
+/** Explicit once-per-selection primary dispatch policy. This is not completion/acceptance accounting. */
+export function intentAdmission(state: IntentState, records: readonly Charged[], input: IntentAdmission): IntentAdmission {
+  controlShape(input, ["selection", "revision", "obligation"]);
+  const selection = intentSelection(input.selection), obligation = intentPriorities([{ obligation: input.obligation, rank: 0 }])[0].obligation;
+  if (input.revision !== state.revision || intentKey(selection) !== intentKey(state.selection) || intentKey(obligation) !== intentKey(nextIntent(state, records))) throw new Error("stale selection/revision or out-of-priority dispatch");
+  return { selection, revision: input.revision, obligation };
+}

package/src/ledger-append.ts

@@ -0,0 +1,72 @@
+import { appendFile, mkdir, open, type FileHandle } from "node:fs/promises";
+import { constants } from "node:fs";
+import { dirname } from "node:path";
+import { withFileLock } from "./file-lock.ts";
+import { recheckWorkDestination, workFsError, type WorkDestination } from "./work-ledger-destination.ts";
+import { WORK_TEXT_BYTES, WORK_RECORDS } from "./work-ledger-json.ts";
+import { WorkInputError } from "./work-ledger-types.ts";
+import { parseWorkLedgerText } from "./work-ledger.ts";
+
+/** Bounded descriptor read, including one detection byte; never trust a pre-read size alone. */
+export async function readWorkBytes(handle: FileHandle): Promise<Buffer> {
+  const chunks: Buffer[] = []; let total = 0;
+  for (;;) {
+    const chunk = Buffer.alloc(Math.min(64 * 1024, WORK_TEXT_BYTES + 1 - total));
+    const { bytesRead } = await handle.read(chunk, 0, chunk.length, total);
+    if (bytesRead === 0) return Buffer.concat(chunks, total);
+    total += bytesRead;
+    if (total > WORK_TEXT_BYTES) throw new WorkInputError("WORK_LIMIT_EXCEEDED");
+    chunks.push(chunk.subarray(0, bytesRead));
+  }
+}
+/** A secondary filesystem close failure must not replace a primary content/capacity refusal. */
+export async function closeWorkHandle(handle: FileHandle, failed: boolean): Promise<void> {
+  try { await handle.close(); }
+  catch (error) { if (!failed || !workFsError(error)) throw error; }
+}
+
+/** Shared existing-producer persistence. Serialization and each caller's exception policy remain
+ * outside this function. The private destination facts select v4 protection, never ambient defaults. */
+export async function appendLedgerLine(options: { readonly path: string }, line: string, destination?: WorkDestination, once?: { eventId: string; digest: string }): Promise<void> {
+  await mkdir(dirname(options.path), { recursive: true });
+  if (!destination) {
+    // Retain even legacy path-property evaluation timing across waits; only v4 owns detached inputs.
+    await withFileLock(options.path, "grant ledger", () => appendFile(options.path, line, { encoding: "utf8", flag: "a" }));
+    return;
+  }
+  const path = destination.path;
+  await recheckWorkDestination(destination);
+  await withFileLock(path, "work ledger", async () => {
+    await recheckWorkDestination(destination);
+    let handle: FileHandle;
+    try {
+      handle = await open(path, constants.O_RDWR | constants.O_APPEND | constants.O_CREAT | constants.O_NOFOLLOW | constants.O_NONBLOCK, 0o600);
+    } catch (error) {
+      // A newly proven alias/unsafe kind retains its classification rather than becoming generic I/O.
+      if (workFsError(error)) await recheckWorkDestination(destination);
+      throw error;
+    }
+    let failed = false;
+    try {
+      await recheckWorkDestination(destination, handle);
+      const bytes = await readWorkBytes(handle);
+      const ingestion = parseWorkLedgerText(bytes.toString("utf8"));
+      if (!ingestion.complete) throw new WorkInputError(ingestion.errors[0].code);
+      if (bytes.length && bytes[bytes.length - 1] !== 10) throw new WorkInputError("WORK_JSON_INVALID");
+      if (once) {
+        const sameId = ingestion.events.filter(e => e.eventId === once.eventId);
+        if (sameId.some(e => e.digest !== once.digest)) throw new WorkInputError("WORK_DIGEST_MISMATCH");
+        if (sameId.length) { await handle.sync(); return; } // Reconcile an earlier complete but unacknowledged append.
+      }
+      if (bytes.length + Buffer.byteLength(line, "utf8") > WORK_TEXT_BYTES || ingestion.events.length + 1 > WORK_RECORDS) {
+        throw new WorkInputError("WORK_LIMIT_EXCEEDED");
+      }
+      await recheckWorkDestination(destination, handle);
+      // Same descriptor, same non-expiring lock, O_APPEND. A failed write may leave partial bytes;
+      // preserve them and fail closed. Never truncate, repair or reserialize existing deliveries.
+      await handle.writeFile(line, "utf8");
+      if (once) await handle.sync(); // New application seam requires durable append before controller receipt.
+    } catch (error) { failed = true; throw error; }
+    finally { await closeWorkHandle(handle, failed); }
+  }, { staleRecovery: "disabled" });
+}

package/src/ledger.ts

@@ -19,9 +19,8 @@
  * "what was this child told to do?" is out of the ledger by decision, not by omission.
  */
 
-import { appendFile, mkdir, readFile } from "node:fs/promises";
-import { withFileLock } from "./file-lock.ts";
-import { dirname } from "node:path";
+import { readFile } from "node:fs/promises";
+import { appendLedgerLine } from "./ledger-append.ts";
 import type { Capability, ResolveResult } from "./resolve.ts";
 import type { ExecutorKind } from "./executor.ts";
 import type { DefinitionDigest } from "./definitions.ts";
@@ -314,15 +313,10 @@ export { verifyLedger, type LedgerReport } from "./ledger-report.ts";
  * — because a child running with granted capabilities and no audit line is what the ledger exists to
  * prevent. That is the opposite of what the approvals store does with the same lock, and deliberately so.
  */
-const withLedgerLock = <T>(path: string, write: () => Promise<T>): Promise<T> =>
-  withFileLock(path, "grant ledger", write);
-
 export async function appendLedgerEvent(options: LedgerOptions, event: RuntimeLedgerEvent | GrantRecord): Promise<void> {
   const line = `${JSON.stringify(event)}\n`;
   try {
-    await mkdir(dirname(options.path), { recursive: true });
-    // O_APPEND alone is not enough once several processes write to one ledger — see `withLedgerLock`.
-    await withLedgerLock(options.path, () => appendFile(options.path, line, { encoding: "utf8", flag: "a" }));
+    await appendLedgerLine(options, line);
   } catch (error) {
     if (options.strict ?? true) {
       throw new Error(`grant ledger write failed (failing closed): ${String(error)}`);

package/src/native-session-target.ts

@@ -0,0 +1,23 @@
+import { lstat, realpath, mkdir } from "node:fs/promises";
+import { dirname, isAbsolute, join, parse, resolve } from "node:path";
+import { createHash } from "node:crypto";
+import { ENV_NATIVE_SESSION_ROOT } from "./native-session.ts";
+export interface NativeSessionHost { /** Explicit host opt-in captured once, not model-supplied. */ readonly nativeSessionRoot?: string }
+export const nativeSessionRootFromEnv=(env:NodeJS.ProcessEnv)=>env[ENV_RETAIN_NATIVE_SESSIONS]==="1"?env[ENV_NATIVE_SESSION_ROOT]??"":undefined;
+export const ENV_RETAIN_NATIVE_SESSIONS = "PI_GRANTS_RETAIN_NATIVE_SESSIONS";
+/** Explicit ordinary-host opt-in only. Never read a destination from tool/model parameters.
+ * Allocate a fresh per-occurrence directory; no scan, existing-session takeover or transcript creation. */
+export async function allocateNativeSessionTarget(root: string, executionId: string): Promise<string> {
+  if (!isAbsolute(root) || resolve(root) !== root || !/^[a-zA-Z0-9:_-]{1,128}$/.test(executionId)) throw new Error("explicit native root/execution identity required");
+  for (let p = root;; p = dirname(p)) {
+    const s = await lstat(p); if (!s.isDirectory() || s.isSymbolicLink()) throw new Error("native target ancestor changed");
+    if (p === parse(p).root) break;
+  }
+  const before = await lstat(root);
+  if (await realpath(root) !== root || before.mode & 0o077 || before.uid !== process.getuid?.()) throw new Error("private owned native target root required");
+  const directory = join(root, "execution-" + createHash("sha256").update(executionId).digest("hex"));
+  await mkdir(directory, { mode: 0o700 }); // EEXIST is a refusal, never permission to append an old occurrence.
+  const after = await lstat(root);
+  if (before.dev !== after.dev || before.ino !== after.ino || await realpath(directory) !== directory) throw new Error("native target root replaced");
+  return join(directory, "session.jsonl");
+}

package/src/native-session.ts

@@ -0,0 +1,139 @@
+import { constants } from "node:fs";
+import { open, lstat, realpath } from "node:fs/promises";
+import { isAbsolute, relative, sep } from "node:path";
+import { createHash } from "node:crypto";
+import { parseRetentionJson } from "./retention-json.ts";
+
+export const ENV_NATIVE_SESSION_ROOT = "PI_GRANTS_NATIVE_SESSION_ROOT";
+export const MAX_NATIVE_SESSION_BYTES = 1024 * 1024;
+export type NativeSessionSource = "herdr-id" | "herdr-path" | "pi-session-file" | "pi-session-manager";
+export interface NativeSessionObservation {
+  source: NativeSessionSource | null;
+  status: "missing" | "verified" | "invalid" | "changed" | "truncated" | "unsupported";
+  sessionId: string | null;
+  sessionPath: string | null;
+  parentSessionPath: string | null;
+  branchLeafId: string | null;
+  branchState: "unknown" | "observed";
+  lastPersistedEntryId: string | null;
+  sha256: string | null;
+  reason: string | null;
+}
+export interface NativeSessionCapture { observation: NativeSessionObservation; bytes?: Buffer; fileIdentity?: { device: string; inode: string } }
+/** Read-only methods of pi 0.84.2's public SessionManager; no runtime/session creation or model work. */
+export interface NativeSessionManager {
+  getSessionFile(): string | undefined;
+  getSessionId(): string;
+  getLeafId(): string | null;
+}
+export const missingNativeSession = (): NativeSessionObservation => ({ source: null, status: "missing", sessionId: null,
+  sessionPath: null, parentSessionPath: null, branchLeafId: null, branchState: "unknown", lastPersistedEntryId: null,
+  sha256: null, reason: "native-session-unavailable" });
+const id = (x: unknown): x is string => typeof x === "string" && /^[a-zA-Z0-9_-]{1,128}$/.test(x);
+const uuid = (x: unknown): x is string => typeof x === "string" && /^[a-f0-9]{8}(?:-[a-f0-9]{4}){3}-[a-f0-9]{12}$/i.test(x);
+const obj = (x: unknown): x is Record<string, unknown> => x !== null && typeof x === "object" && !Array.isArray(x);
+const filePath = (x: unknown): x is string => typeof x === "string" && x.length <= 4096 && isAbsolute(x) && !x.includes("\0");
+
+/** Parse the retained native v3 bytes, never load/migrate/rewrite a session via SessionManager.open(). */
+export function parseNativeSessionBytes(bytes: Uint8Array, input: {
+  source: NativeSessionSource; path: string; expectedSessionId?: string; truncated?: boolean;
+  liveLeaf?: { sessionId: string; leafId: string | null };
+}): NativeSessionCapture {
+  const observation = { ...missingNativeSession(), source: input.source, sessionPath: input.path };
+  const result: NativeSessionCapture = { observation };
+  const fail = (status: NativeSessionObservation["status"], reason: string) => {
+    observation.status = status; observation.reason = reason; observation.branchLeafId = null; observation.branchState = "unknown";
+    return result;
+  };
+  if (bytes.length > MAX_NATIVE_SESSION_BYTES) return fail("truncated", "native-session-size-limit");
+  const raw = Buffer.from(bytes), newline = raw.indexOf(10);
+  let header: unknown;
+  try { header = parseRetentionJson(new TextDecoder("utf-8", { fatal: true }).decode(raw.subarray(0, newline < 0 ? raw.length : newline)), MAX_NATIVE_SESSION_BYTES); }
+  catch { return fail("invalid", "native-session-header-invalid"); }
+  if (!obj(header) || header.type !== "session" || header.version !== 3 || !uuid(header.id) ||
+    !filePath(header.cwd) || typeof header.timestamp !== "string" || !Number.isFinite(Date.parse(header.timestamp)) ||
+    (header.parentSession !== undefined && !filePath(header.parentSession))) return fail("invalid", "native-session-header-invalid");
+  if (input.expectedSessionId !== undefined && header.id !== input.expectedSessionId) return fail("changed", "native-session-id-changed");
+  // Only validated session headers admit transcript bytes; arbitrary files are never archived here.
+  result.bytes = Buffer.from(bytes);
+  observation.sessionId = header.id;
+  observation.parentSessionPath = header.parentSession as string | undefined ?? null;
+  observation.sha256 = createHash("sha256").update(bytes).digest("hex");
+  if (input.truncated || raw.at(-1) !== 10) return fail("truncated", "native-session-incomplete-bytes");
+  let text: string;
+  try { text = new TextDecoder("utf-8", { fatal: true }).decode(raw); }
+  catch { return fail("invalid", "native-session-utf8-invalid"); }
+  const lines = text.split("\n");
+  const ids = new Set<string>();
+  if (lines.length > 10002) return fail("invalid", "native-session-entry-limit");
+  for (const line of lines.slice(1, -1)) {
+    let entry: unknown;
+    try { entry = parseRetentionJson(line, MAX_NATIVE_SESSION_BYTES); } catch { return fail("invalid", "native-session-entry-invalid"); }
+    if (!obj(entry) || typeof entry.type !== "string" || entry.type === "session" || !id(entry.id) || ids.has(entry.id) ||
+      !(entry.parentId === null || (id(entry.parentId) && ids.has(entry.parentId))) || typeof entry.timestamp !== "string" ||
+      !Number.isFinite(Date.parse(entry.timestamp))) return fail("invalid", "native-session-parent-link-invalid");
+    ids.add(entry.id); observation.lastPersistedEntryId = entry.id;
+  }
+  if (input.liveLeaf) {
+    if (input.liveLeaf.sessionId !== header.id || (input.liveLeaf.leafId !== null && !ids.has(input.liveLeaf.leafId))) {
+      return fail("changed", "native-session-live-leaf-mismatch");
+    }
+    observation.branchLeafId = input.liveLeaf.leafId; observation.branchState = "observed";
+  }
+  observation.status = "verified"; observation.reason = observation.branchState === "unknown" ? "active-branch-unknown" : null;
+  return result;
+}
+
+/** Private allowlisted files only, bounded non-following descriptor reads, no scan of session/auth dirs. */
+export async function readNativeSession(input: {
+  path: string; source: NativeSessionSource; expectedSessionId?: string; allowedRoot?: string;
+  manager?: NativeSessionManager;
+  expectedFile?: { device: string; inode: string };
+}): Promise<NativeSessionCapture> {
+  const gap = (status: NativeSessionObservation["status"], reason: string): NativeSessionCapture => ({ observation: {
+    ...missingNativeSession(), source: input.source, status, reason, sessionPath: filePath(input.path) ? input.path : null,
+  } });
+  const root = input.allowedRoot ?? process.env[ENV_NATIVE_SESSION_ROOT];
+  if (!filePath(input.path) || !input.path.endsWith(".jsonl") || !root || !filePath(root)) return gap("unsupported", "native-session-private-root-required");
+  const within = (base: string, candidate: string) => { const p = relative(base, candidate); return p !== "" && p !== ".." && !p.startsWith(`..${sep}`) && !isAbsolute(p); };
+  if (!within(root, input.path)) return gap("unsupported", "native-session-outside-private-root");
+  let handle: Awaited<ReturnType<typeof open>> | undefined;
+  try {
+    const canonicalRoot = await realpath(root), canonicalFile = await realpath(input.path);
+    const rootStat = await lstat(canonicalRoot);
+    if (!rootStat.isDirectory() || (rootStat.mode & 0o077) !== 0 || (typeof process.getuid === "function" && rootStat.uid !== process.getuid())) return gap("unsupported", "native-session-root-not-private");
+    if (!within(canonicalRoot, canonicalFile) || (await lstat(input.path)).isSymbolicLink()) return gap("unsupported", "native-session-path-alias");
+    handle = await open(input.path, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+    const before = await handle.stat();
+    if (!before.isFile() || before.nlink !== 1 || (typeof process.getuid === "function" && before.uid !== process.getuid())) {
+      return gap("unsupported", "native-session-not-private-regular-file");
+    }
+    const fileIdentity = { device: String(before.dev), inode: String(before.ino) };
+    if (input.expectedFile && (input.expectedFile.device !== fileIdentity.device || input.expectedFile.inode !== fileIdentity.inode)) return gap("changed", "native-session-file-replaced");
+    const live = input.manager ? { sessionId: input.manager.getSessionId(), leafId: input.manager.getLeafId(), path: input.manager.getSessionFile() } : undefined;
+    if (live && live.path !== input.path) return gap("changed", "native-session-manager-path-changed");
+    const bytes = Buffer.alloc(Math.min(before.size, MAX_NATIVE_SESSION_BYTES));
+    let offset = 0;
+    while (offset < bytes.length) { const read = await handle.read(bytes, offset, bytes.length - offset, offset); if (!read.bytesRead) break; offset += read.bytesRead; }
+    const after = await handle.stat(), location = await lstat(input.path);
+    if (before.dev !== location.dev || before.ino !== location.ino || before.size !== after.size || before.mtimeMs !== after.mtimeMs ||
+      before.ctimeMs !== after.ctimeMs || location.isSymbolicLink() || after.size !== location.size) return gap("changed", "native-session-file-changed");
+    if (live && (input.manager!.getSessionId() !== live.sessionId || input.manager!.getLeafId() !== live.leafId || input.manager!.getSessionFile() !== live.path)) {
+      return gap("changed", "native-session-live-state-changed");
+    }
+    return { ...parseNativeSessionBytes(bytes.subarray(0, offset), { ...input, liveLeaf: live,
+      truncated: before.size > MAX_NATIVE_SESSION_BYTES || offset !== before.size }), fileIdentity };
+  } catch (error) {
+    return gap((error as NodeJS.ErrnoException).code === "ENOENT" ? "missing" : "invalid", "native-session-read-failed");
+  } finally { await handle?.close().catch(() => undefined); }
+}
+
+/** Herdr 0.8.2 protocol 20 AgentInfo.agent_session; never scrape terminal text, PID or names. */
+export function herdrSessionReference(value: unknown, expectedPane: string): { source: "herdr-id" | "herdr-path"; value: string } | null {
+  if (!obj(value) || value.pane_id !== expectedPane || value.agent !== "pi" || !obj(value.agent_session)) return null;
+  const s = value.agent_session;
+  if (s.agent !== "pi" || typeof s.source !== "string" || s.source.length > 128) return null;
+  if (s.kind === "id" && uuid(s.value)) return { source: "herdr-id", value: s.value };
+  if (s.kind === "path" && filePath(s.value)) return { source: "herdr-path", value: s.value };
+  return null;
+}