pi-daddy 0.26.1 → 0.27.0

package/extensions/ordinary-runtime.ts

@@ -5,9 +5,9 @@ import { releaseDelegationWorkspace,type PreparedWorkspace } from "./workspace-r
 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>){
+export async function withOrdinaryChild(input:{session:GrantsSession;executionId:string;parentExecutionId:string|null;childId:string;toolCallId?:string;signal?:AbortSignal;preparedWorkspace?:PreparedWorkspace;declaredWork?:GrantsSession["declaredWork"]},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);}
+ try{if(input.declaredWork&&dataDigest(input.declaredWork.selectedSnapshot)!==dataDigest(input.session.declaredWork?.selectedSnapshot??null))throw Error("declared work changed before original child admission");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

@@ -204,7 +204,7 @@ export async function runOneDelegation(
    */
   options: {
     /** Actual public execute argument, never read from model-authored correlation or output. */
-    toolCallId?: string;
+    toolCallId?: string; declaredWork?: GrantsSession["declaredWork"];
     /** Progress for the parent's status block (ADR-0032). Display only. */
     onProgress?: (update: {
       /** Appended (process executor: a genuine byte stream). */
@@ -389,7 +389,7 @@ export async function runOneDelegation(
     childId: ids.childId,
     executionId: ids.executionId,
     parentExecutionId: ids.parentExecutionId,
-    toolCallId: options.toolCallId,
+    toolCallId: options.toolCallId, declaredWork: options.declaredWork,
     cwd: ctx.cwd,
     preparedWorkspace,
     signal,

package/extensions/work-policy-session.ts

@@ -0,0 +1,139 @@
+import { randomUUID } from "node:crypto";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { mkdir, readdir } from "node:fs/promises";
+import type { ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
+import { supportedModelEfforts as getSupportedThinkingLevels } from "../src/model-preflight.ts";
+import { createWorkPolicyRegistry, openWorkPolicyRegistry, policyForSetup, workPolicy, workPolicyDigest, workPolicyActivationDigest, type WorkPolicy, type WorkPolicyRegistry, type WorkPolicyActivation } from "../src/work-policy-registry.ts";
+import { loadWorkSetup, type WorkSetup } from "../src/work-setup.ts";
+import { bindLearningAdoption, learningScopeDigest, type LearningHarness, type LearningWorkspace } from "../src/learning-connection.ts";
+import type { DeclaredWorkState } from "../src/work-command.ts";
+import { privateDirectory, readProductJson, writeProductJson } from "../src/product-files.ts";
+import type { AdoptionBinding, AdoptionFacts } from "../src/vendor/adoption.ts";
+import type { FactoryAuthority } from "../src/factory-contract.ts";
+import { experimentHash } from "../src/experiment-contract.ts";
+
+const descriptor = (cwd: string) => join(cwd, ".pi", "work-policy-registry.json");
+const policyPath = (cwd: string, digest: string) => join(cwd, ".pi", "work-policies", `${digest}.json`);
+const registryHistoryPath=(cwd:string,scope:string)=>join(cwd,".pi","work-registry-bindings",`${scope}.json`);
+async function retainRegistryBinding(cwd:string,binding:WorkPolicyRegistry){const path=registryHistoryPath(cwd,binding.initial.scopeDigest),old=await readProductJson(path);if(old&&experimentHash(old)!==experimentHash(binding))throw Error("scoped registry binding history conflict");if(!old)await writeProductJson(path,binding);}
+function authority(id: string, binding?: AdoptionBinding, facts?: AdoptionFacts): FactoryAuthority { return { id, orderDigests: [], decisionDigests: [], activationDigests: [], migrationDigests: [], adoption: { id, adoptions: binding ? [binding.id] : [], rollbacks: [] }, facts: binding && facts ? [{ bindingId: binding.id, facts }] : [] }; }
+async function independentFacts(ctx: ExtensionCommandContext, b: AdoptionBinding): Promise<AdoptionFacts | null> {
+  if (!await ctx.ui.confirm("Independent eligibility attestation — not a quality preference", `Have you independently verified that this exact comparison/candidate meets the scoped assessment policy, and is still eligible?\nExperiment: ${b.experimentDigest}\nCandidate: ${b.candidateDigest}\nScope: ${b.scopeDigest}\nAssessment: ${b.assessmentPolicyDigest}\n\nConfirm only with real independent evidence. Missing/uncertain evidence means No. This does not fabricate calibration or accept any result.`)) return null;
+  return { experimentDigest: b.experimentDigest, candidateDigest: b.candidateDigest, scopeDigest: b.scopeDigest, assessmentPolicyDigest: b.assessmentPolicyDigest, eligible: true };
+}
+export async function loadWorkPolicyRegistry(cwd: string, state: DeclaredWorkState): Promise<WorkPolicyRegistry | null> {
+  const binding = await readProductJson(descriptor(cwd)) as WorkPolicyRegistry | null;
+  if (binding && binding.initial.scopeDigest !== learningScopeDigest(state)) throw Error("Configured adoption registry belongs to different work. Use /grants learning → Adoption / rollback to reconnect or create scoped settings; no adopted setting was carried forward.");
+  if (binding) await openWorkPolicyRegistry(binding).inspect(); return binding;
+}
+async function savePolicy(cwd: string, name: string, policy: WorkPolicy) {
+  if(typeof name!=="string"||!name.trim()||Buffer.byteLength(name)>128||/[\p{Cc}\p{Cf}]/u.test(name))throw Error("bounded plain candidate name required");
+  const path = policyPath(cwd, workPolicyDigest(policy)), old = await readProductJson(path);
+  if(old){await readPolicy(cwd,workPolicyDigest(policy));return;}
+  await writeProductJson(path, { version: "named-work-policy-v1", name, policy });
+}
+async function readPolicy(cwd: string, digest: string) {
+  const saved = await readProductJson(policyPath(cwd, digest)) as { version: string; name: string; policy: WorkPolicy } | null;
+  if (!saved || Object.keys(saved).sort().join()!=="name,policy,version" || typeof saved.name!=="string" || !saved.name.trim() || Buffer.byteLength(saved.name)>128 || /[\p{Cc}\p{Cf}]/u.test(saved.name) || saved.version !== "named-work-policy-v1" || workPolicyDigest(saved.policy) !== digest) throw Error("Exact candidate policy bytes are missing; prepare the candidate profile first");
+  return workPolicy(saved.policy);
+}
+function retain(h: LearningHarness, root: string, parser: string, value: unknown) {
+  return h.retainArchiveSource(root, { sourceId: `${parser}-${experimentHash(value).slice(0, 24)}`, parser: { id: parser, version: "1" }, retention: "exact", bytes: Buffer.from(JSON.stringify(value)) }).manifestId;
+}
+export async function workPolicyMenu(ctx: ExtensionCommandContext, state: DeclaredWorkState, workspace: LearningWorkspace, harness: LearningHarness): Promise<void> {
+  const setup = await loadWorkSetup(state); if (!setup) throw Error("Declare a multi-task work setup before configuring ordinary model/effort adoption");
+  let binding = await readProductJson(descriptor(ctx.cwd)) as WorkPolicyRegistry|null;
+  if(binding)await openWorkPolicyRegistry(binding).inspect();
+  if(binding&&binding.initial.scopeDigest!==learningScopeDigest(state)){
+    if(!await ctx.ui.confirm("Settings belong to different selected work","Connect settings for this exact work scope? Previous registry and active/history-bearing orders remain untouched. No adopted setting carries across scopes."))return;
+    await retainRegistryBinding(ctx.cwd,binding);binding=null;
+  }
+  if(!binding){
+    const saved=await readProductJson(registryHistoryPath(ctx.cwd,learningScopeDigest(state))) as WorkPolicyRegistry|null;
+    if(saved){const view=await openWorkPolicyRegistry(saved).inspect();if(view.scopeDigest!==learningScopeDigest(state))throw Error("saved registry scope mismatch");if(!await ctx.ui.confirm("Reconnect saved settings for this work?",`${view.candidate.profiles.map(p=>`${p.model} / ${p.thinking}`).join(", ")}\nFuture runs still require current eligibility; existing runs do not migrate.`))return;binding=saved;await writeProductJson(descriptor(ctx.cwd),binding,true);}
+  }
+  if (!binding) {
+    const baseline = policyForSetup(setup.setup, learningScopeDigest(state), state.policy.digest);
+    if (!await ctx.ui.confirm("Create a scoped next-order registry?", "Baseline is the selected task models/effort. Future adoption can only change model/effort for these same definitions. No existing or active run changes.")) return;
+    const root = join(homedir(), ".local", "state", "pi-daddy", "work-registries"); await mkdir(root, { recursive: true, mode: 0o700 }); await privateDirectory(root);
+    binding = await createWorkPolicyRegistry({ directory: join(root, randomUUID()), authorityId: "local-operator", baseline });
+    await savePolicy(ctx.cwd, "Baseline", baseline); await retainRegistryBinding(ctx.cwd,binding); await writeProductJson(descriptor(ctx.cwd), binding, true);
+  }
+  const registry = openWorkPolicyRegistry(binding), current = await registry.inspect();
+  const menu = ["Prepare candidate model/effort profile", "Activate adopted comparison for next orders", "Roll back active adoption", "Inspect registry", "Recover learning link (no registry change)"];
+  const choice = await ctx.ui.select("Scoped settings — existing runs stay pinned", menu);
+  if (!choice) return;
+  if (choice === menu[3]) { await ctx.ui.editor("Registry details (read-only; editor changes are discarded)", JSON.stringify(current, null, 2)); return; }
+  if (choice === menu[0]) {
+    const candidate = structuredClone(current.candidate);
+    for (const profile of candidate.profiles) {
+      const models = ctx.scopedModels?.length ? ctx.scopedModels.map(entry => entry.model) : ctx.modelRegistry.getAvailable();
+      if(!models.length)throw Error("No available Pi models. Configure a model in Pi, then reopen settings; no fallback is chosen.");
+      const labels = models.map(m => `${m.provider}/${m.id}`), selected = await ctx.ui.select(`Model for ${setup.setup.tasks.find(t => t.id === profile.taskId)!.outcome}`, labels), model = models[labels.indexOf(selected ?? "")]; if (!model) return;
+      const thinking = await ctx.ui.select("Requested effort", getSupportedThinkingLevels(model)); if (!thinking) return;
+      profile.model = `${model.provider}/${model.id}`; profile.thinking = thinking as typeof profile.thinking;
+    }
+    const name = await ctx.ui.input("Candidate name", "Alternative profile"); if (!name?.trim()) return;
+    await savePolicy(ctx.cwd, name, candidate);
+    ctx.ui.notify(`Candidate retained, not adopted. Comparison must bind configuration digest ${workPolicyDigest(candidate)} to actual outputs. Use Learning to review full artifacts, record quality and choose adopt/reject/defer.`, "info"); return;
+  }
+  const view = workspace.inspect(Date.now()), comparisons = view.comparisons.filter(c => c.state !== "deferred");
+  if(!comparisons.length)throw Error("Adoption deferred: no ready retained comparison. Open Learning to connect/review actual evidence and inspect defer reasons. No setting was activated.");
+  const labels = comparisons.map((c, i) => `${i + 1}. ${c.title}`), picked = await ctx.ui.select("Retained comparison", labels), comparison = comparisons[labels.indexOf(picked ?? "")]; if (!comparison) return;
+  if (choice === menu[1]) {
+    let adoptionBinding = workspace.comparisonContext(comparison.name).adoptionBinding;
+    if (!adoptionBinding) {
+      const files=await readdir(join(ctx.cwd,".pi","work-policies")); if(files.length>128)throw Error("candidate profile bound exceeded");
+      const candidates: {name:string;policy:WorkPolicy}[]=[];
+      for(const file of files.filter(f=>/^[a-f0-9]{64}\.json$/.test(f))){const saved=await readProductJson(join(ctx.cwd,".pi","work-policies",file)) as {name:string;policy:WorkPolicy};const policy=await readPolicy(ctx.cwd,file.slice(0,-5));if(policy.scopeDigest===current.scopeDigest)candidates.push({name:saved.name,policy});}
+      const names=candidates.map((c,i)=>`${i+1}. ${c.name}: ${c.policy.profiles.map(p=>`${p.model}/${p.thinking}`).join(", ")}`),picked=await ctx.ui.select("Candidate already compared in this retained evidence",names),selected=candidates[names.indexOf(picked??"")];if(!selected)return;
+      if(!await ctx.ui.confirm("Bind this scoped adoption proposal?","This requires linked confirmed cases, hypothesis and a durable full-artifact choice of this exact candidate. It does not create eligibility or activate anything."))return;
+      adoptionBinding=bindLearningAdoption(workspace,comparison.name,{candidateDigest:workPolicyDigest(selected.policy),rollbackCandidateDigest:current.candidateDigest,assessmentPolicyDigest:selected.policy.assessmentPolicyDigest,expiresAt:Date.now()+7*86400000});
+    }
+    const candidate = await readPolicy(ctx.cwd, adoptionBinding.candidateDigest), facts = await independentFacts(ctx, adoptionBinding); if (!facts) return;
+    const a = authority(binding.initial.authorityId, adoptionBinding, facts), receipt = workspace.prepareAdoption(comparison.name, a.adoption, facts, Date.now());
+    const request: WorkPolicyActivation = { version: "ordinary-work-activation-v1", requestId: `activate-${randomUUID()}`, expectedRevision: current.revision, expectedCandidateDigest: current.candidateDigest, candidate, binding: adoptionBinding, receipt };
+    if (!await ctx.ui.confirm("Activate for NEXT orders only?", `${comparison.title}\n${candidate.profiles.map(p => `${p.taskId}: ${p.model} / ${p.thinking}`).join("\n")}\nNo active work changes. This is separate from your quality choice.`)) return;
+    a.activationDigests = [workPolicyActivationDigest(request)];
+    const applied = await registry.activate(request, a), archiveRoot = workspace.configuration().archiveRoot;
+    const registryManifestId = retain(harness, archiveRoot, "producer-registry", applied);
+    const wrapper = retain(harness, archiveRoot, "learning-registry-receipt", { version: "learning-registry-receipt-v1", operation: "activate", requestId: request.requestId, adoptionId: receipt.id, scopeDigest: applied.scopeDigest, candidateDigest: applied.candidateDigest, revision: applied.revision, registryManifestId });
+    try { workspace.linkActivation(comparison.name, wrapper, [wrapper]); }
+    catch (error) { throw Error(`Registry activated but learning link failed (${String(error)}). Do not activate again; use Recover learning link. Retained receipt ${wrapper}.`); }
+    ctx.ui.notify("Activated for subsequent bounded work runs. Existing runs remain pinned; later outcomes are still unobserved.", "info"); return;
+  }
+  if(choice===menu[4]){
+    const change=current.lastChange,receipt=workspace.preparedAdoption(comparison.name);
+    if(!change||!receipt||change.adoptionId!==receipt.id)throw Error("Last original registry change does not belong to this comparison");
+    if(!await ctx.ui.confirm("Reconnect actual registry observation?",`The last ${change.operation} is already applied at revision ${current.revision}. This only retains and links that exact original registry observation; no effect is replayed.`))return;
+    const root=workspace.configuration().archiveRoot,registryManifestId=retain(harness,root,"producer-registry",current),wrapper=retain(harness,root,"learning-registry-receipt",{version:"learning-registry-receipt-v1",operation:change.operation,requestId:change.requestId,adoptionId:receipt.id,scopeDigest:current.scopeDigest,candidateDigest:current.candidateDigest,revision:current.revision,registryManifestId});
+    if(change.operation==="activate")workspace.linkActivation(comparison.name,wrapper,[wrapper]);else workspace.linkRollback(comparison.name,wrapper,[wrapper]);
+    ctx.ui.notify("Original registry observation linked. No activation or rollback replayed.","info");return;
+  }
+  if (!current.activation) throw Error("No current adoption to roll back");
+  const receipt = workspace.preparedAdoption(comparison.name);
+  if (!receipt || receipt.id !== current.activation.receipt.id) throw Error("Selected comparison is not the active adoption");
+  const root = workspace.configuration().archiveRoot;
+  const evidence = retain(harness, root, "producer-rollback-request", { reason: "operator-request", adoptionId: receipt.id, observedRevision: current.revision });
+  const request = workspace.previewRollback(comparison.name, "operator-request", [evidence], Date.now() + 120_000);
+  const restore = await registry.previewRollback(request);
+  if (!await ctx.ui.confirm("Roll back NEXT orders?", `Restore candidate: ${restore.restoreCandidateDigest}\n${restore.candidate.profiles.map(p => `${p.taskId}: ${p.model} / ${p.thinking}`).join("\n")}\nNo active run changes; no defect or improvement is inferred.`)) return;
+  const a = authority(binding.initial.authorityId); a.adoption = { id: a.id, adoptions: [], rollbacks: [request.id] };
+  workspace.prepareRollback(comparison.name, request, a.adoption, Date.now(), { adoptionId: receipt.id, candidateDigest: current.candidateDigest, scopeDigest: current.scopeDigest });
+  const applied = await registry.rollback(request, a), registryManifestId = retain(harness, root, "producer-registry", applied);
+  const wrapper = retain(harness, root, "learning-registry-receipt", { version: "learning-registry-receipt-v1", operation: "rollback", requestId: request.id, adoptionId: receipt.id, scopeDigest: applied.scopeDigest, candidateDigest: applied.candidateDigest, revision: applied.revision, registryManifestId });
+  try { workspace.linkRollback(comparison.name, wrapper, [wrapper]); }
+  catch (error) { throw Error(`Rollback applied but learning link failed (${String(error)}). Use Recover learning link; do not repeat the effect. Retained receipt ${wrapper}.`); }
+  ctx.ui.notify("Rollback applied for next orders. Active/history-bearing runs were not changed.", "info");
+}
+/** Fresh human facts at use; a stored lifecycle/receipt is never treated as independent live authority. */
+export async function prepareNextWorkPolicy(ctx: ExtensionCommandContext, state: DeclaredWorkState, setup: WorkSetup) {
+  const binding = await loadWorkPolicyRegistry(ctx.cwd, state); if (!binding) return { setup, pin: async (_id: string) => null };
+  const registry = openWorkPolicyRegistry(binding), current = await registry.inspect();
+  const facts = current.activation ? await independentFacts(ctx, current.activation.binding) : undefined;
+  if (facts === null) throw Error("Next-order adoption deferred; no fallback profile or child launched");
+  const a = authority(binding.initial.authorityId, current.activation?.binding, facts);
+  const configured = { ...setup, tasks: setup.tasks.map(t => { const profile = current.candidate.profiles.find(p => p.taskId === t.id); if (!profile || profile.agent !== t.agent) throw Error("adopted profile no longer matches task definition"); return { ...t, model: profile.model, thinking: profile.thinking }; }) };
+  return { setup: configured, async pin(orderId: string) { const pinned = await registry.pin(orderId, a, { revision: current.revision, candidateDigest: current.candidateDigest }); if (pinned.candidateDigest !== current.candidateDigest || pinned.revision !== current.revision) throw Error("registry changed before order pin; no child launched"); return { orderId, candidateDigest: pinned.candidateDigest, adoptionId: pinned.adoptionId, revision: pinned.revision, scopeDigest: binding.initial.scopeDigest }; } };
+}

package/extensions/work-run-session.ts

@@ -0,0 +1,75 @@
+import { randomUUID } from "node:crypto";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { mkdir } from "node:fs/promises";
+import { BorderedLoader, type ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
+import { supportedModelEfforts as getSupportedThinkingLevels } from "../src/model-preflight.ts";
+import { splitBudget } from "../src/fanout.ts";
+import { runWorkSetup, type WorkRunResult } from "../src/work-run.ts";
+import { loadWorkSetup, type RecordedWorkSetup } from "../src/work-setup.ts";
+import { privateDirectory, writeProductJson } from "../src/product-files.ts";
+import { loadDeclaredWork } from "../src/work-command.ts";
+import { readDailySnapshot } from "../src/daily-view-input.ts";
+import { ordinaryChildrenFor } from "../src/ordinary-children.ts";
+import { runOneDelegation } from "./run-delegation.ts";
+import { newDelegationOccurrence } from "./execution-occurrence.ts";
+import { assertDelegationAuthority } from "./delegation-authority.ts";
+import type { GrantsSession } from "./session.ts";
+import { prepareNextWorkPolicy } from "./work-policy-session.ts";
+
+export async function runSelectedWork(session: GrantsSession, ctx: ExtensionCommandContext, setup: RecordedWorkSetup, priorities?: string[], lifetime?: { signal: AbortSignal; started: (promise: Promise<WorkRunResult>) => void }): Promise<WorkRunResult | null> {
+  assertDelegationAuthority(session);
+  if (!ctx.isIdle() || !ordinaryChildrenFor(session).quiescent()) throw Error("Wait for original work to settle before starting a bounded run");
+  const loaded = await loadWorkSetup(setup.state);
+  if (!loaded || session.declaredWork?.selectedSnapshot.snapshot.digest !== setup.state.selectedSnapshot.snapshot.digest) throw Error("selected work changed");
+  const available=splitBudget(session.fanoutBudget,setup.setup.tasks.length);if(!available.ok)throw Error(available.reason);
+  const policy = await prepareNextWorkPolicy(ctx, setup.state, setup.setup), configured = policy.setup;
+  // Resolve every profile before any ledger, result store or child. No provider/model/effort fallback.
+  for (const task of configured.tasks) {
+    const slash = task.model.indexOf("/"), model = ctx.modelRegistry.find(task.model.slice(0, slash), task.model.slice(slash + 1));
+    if (!model || !getSupportedThinkingLevels(model).includes(task.thinking)) throw Error(`Unsupported profile for ${task.outcome}: ${task.model} / ${task.thinking}; choose a listed model and effort`);
+  }
+  if (!await ctx.ui.confirm("Run this work?", `${setup.setup.tasks.length} attempts; at most ${setup.setup.maxParallel} parallel. Each child's existing timeout/output/grant bounds apply. Dependencies receive complete bounded predecessor output. No automatic retries; no universal token/cost cap on ordinary children.\n\n${configured.tasks.map(t => `${t.outcome} — ${t.agent ?? "no tools"}, ${t.model}, ${t.thinking}`).join("\n")}`)) return null;
+  const selectedNow=await loadDeclaredWork(setup.state.statePath);
+  if(selectedNow?.selectedSnapshot.snapshot.digest!==setup.state.selectedSnapshot.snapshot.digest||session.declaredWork?.selectedSnapshot.snapshot.digest!==setup.state.selectedSnapshot.snapshot.digest)throw Error("work selection changed during confirmation; no order started");
+  const root = join(homedir(), ".local", "state", "pi-daddy", "work-runs");
+  await mkdir(root, { recursive: true, mode: 0o700 }); await privateDirectory(root);
+  const abort = new AbortController(), signal = lifetime ? AbortSignal.any([abort.signal, lifetime.signal]) : abort.signal;
+  signal.throwIfAborted(); const orderId = randomUUID(), policyPin = await policy.pin(orderId);
+  const run = (update: (text: string) => void) => { const pending = runWorkSetup({ directory: join(root, orderId), orderId, policyPin, selectionDigest: setup.state.selectedSnapshot.snapshot.digest, setup: configured, budget: session.fanoutBudget, priorities, signal, admissionOpen:()=>(ordinaryChildrenFor(session).inspect() as {admission:string}).admission==="open",
+    onUpdate: rows => update(rows.map(row => `${row.state}: ${setup.setup.tasks.find(t => t.id === row.id)!.outcome}`).join("\n")),
+    execute: async (task, prompt, budget, started) => {
+      assertDelegationAuthority(session);
+      if(session.declaredWork?.selectedSnapshot.snapshot.digest!==setup.state.selectedSnapshot.snapshot.digest)throw Error("selected work changed; remaining order attempts were not launched");
+      const ids = newDelegationOccurrence(session, setup.setup.tasks.findIndex(t => t.id === task.id));
+      await started(ids.executionId);
+      const state = { ...setup.state, obligation: setup.tasks.find(t => t.id === task.id)!.obligation };
+      return runOneDelegation(session, { task: prompt, ...(task.agent ? { agent: task.agent } : { tools: [] }), model: task.model, thinking: task.thinking, correlation: { schema_version: "1.0", task_id: task.id, context_id: `work-${setup.setup.id}` } }, ids, budget, ctx, signal, { declaredWork: state, toolCallId: `work-run:${ids.executionId}` });
+    },
+  }); lifetime?.started(pending); return pending; };
+  let result: WorkRunResult;
+  if (ctx.mode === "tui") {
+    result = await ctx.ui.custom<WorkRunResult>((tui, theme, _keys, done) => {
+      const loader = new BorderedLoader(tui, theme, "Running declared work — Esc requests cancellation; awaiting all original children");
+      loader.onAbort = () => abort.abort();
+      void run(text => ctx.ui.setWidget("pi-daddy-work", text.split("\n"))).then(done).catch(error => done({ error } as unknown as WorkRunResult));
+      return loader;
+    });
+    ctx.ui.setWidget("pi-daddy-work", undefined);
+    if ("error" in result) throw (result as unknown as { error: unknown }).error;
+  } else result = await run(text => ctx.ui.notify(text, "info"));
+  // Navigation index only; the original occurrence ledger/control journal remains the result authority.
+  await writeProductJson(join(session.cwd, ".pi", "work-last-run.json"), result.binding, true);
+  return result;
+}
+export async function showWorkResults(ctx: ExtensionCommandContext, result: WorkRunResult): Promise<void> {
+  const choices = result.tasks.map((row, i) => `${i + 1}. ${row.state} — ${result.binding.initial.setup.tasks.find(t => t.id === row.id)?.outcome ?? row.id}`);
+  const choice = await ctx.ui.select("Results — execution is not acceptance", choices);
+  const row = result.tasks[choices.indexOf(choice ?? "")]; if (!row) return;
+  if (!row.resultPath || !row.resultDigest) { ctx.ui.notify(row.reason ?? "No retained output; original acknowledgement unavailable", "warning"); return; }
+  if (row.resultPath !== join(result.binding.directory, `${row.id}.txt`)) throw Error("result path mismatch");
+  const source = await readDailySnapshot(row.resultPath, 1024 * 1024);
+  if (source.status !== "read" || source.sha256 !== row.resultDigest) throw Error("retained output missing or changed");
+  const output = new TextDecoder("utf8", { fatal: true }).decode(source.bytes);
+  await ctx.ui.editor("Retained full output (controls escaped; edits do not alter the artifact)", output.replace(/[\p{Cc}\p{Cf}]/gu, c => c === "\n" || c === "\t" ? c : `\\u${c.charCodeAt(0).toString(16).padStart(4,"0")}`));
+}

package/extensions/work-runtime.ts

@@ -11,12 +11,12 @@ export async function beginDeclaredWorkAttempt(input: {
   childId: string;
   executionId: string;
   parentExecutionId: string | null;
-  toolCallId?: string;
+  toolCallId?: string; declaredWork?: GrantsSession["declaredWork"];
   preparedWorkspace?: PreparedWorkspace;
   configuredTimeoutMs: number;
   startedAt: Date;
 }): Promise<null | { finish(state: Extract<WorkOccurrencePayload["state"], "completed" | "failed">): Promise<void> }> {
-  const state = input.session.declaredWork;
+  const state = input.declaredWork ?? input.session.declaredWork;
   if (!state) return null;
   const argument = (flag: string): string | null => {
     const index = input.plan.args.indexOf(flag);

package/extensions/work-session.ts

@@ -0,0 +1,132 @@
+import { randomUUID, createHash } from "node:crypto";
+import { join } from "node:path";
+import type { ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
+import { supportedModelEfforts as getSupportedThinkingLevels } from "../src/model-preflight.ts";
+import { workSetup, recordWorkSetup, selectRecordedWork, loadWorkSetup, listWorkSetups, type WorkSetup, type WorkTaskSetup } from "../src/work-setup.ts";
+import { loadDeclaredWork } from "../src/work-command.ts";
+import { intentKey } from "../src/intent-control.ts";
+import { ordinaryChildrenFor } from "../src/ordinary-children.ts";
+import { inspectWorkRun, type WorkRunInitial, type WorkRunResult } from "../src/work-run.ts";
+import type { ControlBinding } from "../src/control-journal.ts";
+import { readProductJson } from "../src/product-files.ts";
+import { dashboardActionFeedback } from "../src/dashboard-cli.ts";
+import { runSelectedWork, showWorkResults } from "./work-run-session.ts";
+import type { GrantsSession } from "./session.ts";
+import type { createDailyDashboardSession } from "./daily-dashboard-session.ts";
+
+const cancelled = () => Error("Work setup cancelled; nothing selected or launched");
+async function ask(ctx: ExtensionCommandContext, title: string, initial = ""): Promise<string> {
+  const value = await ctx.ui.editor(title, initial); if (!value?.trim()) throw cancelled(); return value.trim();
+}
+async function profile(ctx: ExtensionCommandContext, session: GrantsSession, previous?: WorkTaskSetup) {
+  const agents = ["No tools (text-only)", ...session.definitions.keys()];
+  const agent = await ctx.ui.select("Agent definition — existing grants still apply", agents);
+  if (!agent) throw cancelled();
+  const available = ctx.scopedModels?.length ? ctx.scopedModels.map(entry => entry.model) : ctx.modelRegistry.getAvailable();
+  if(!available.length)throw Error("No available Pi models. Configure a model in Pi, then reopen work setup; no fallback is chosen.");
+  const labels = available.map(model => `${model.provider}/${model.id}`);
+  const selected = await ctx.ui.select("Model — no silent fallback", labels);
+  const model = available[labels.indexOf(selected ?? "")]; if (!model) throw cancelled();
+  const thinking = await ctx.ui.select("Requested effort (not proof of provider-internal reasoning)", getSupportedThinkingLevels(model));
+  if (!thinking) throw cancelled();
+  return { agent: agent === agents[0] ? null : agent, model: `${model.provider}/${model.id}`, thinking: thinking as WorkTaskSetup["thinking"] };
+}
+async function author(ctx: ExtensionCommandContext, session: GrantsSession): Promise<WorkSetup> {
+  const outcome = await ask(ctx, "What outcome should this work produce?");
+  const tasks: WorkTaskSetup[] = [];
+  do {
+    const outcome = await ask(ctx, `Task ${tasks.length + 1}: outcome / instructions`);
+    const selected = await profile(ctx, session);
+    const dependencies: string[] = [];
+    while (tasks.length) {
+      const candidates = tasks.filter(t => !dependencies.includes(t.id));
+      const labels = ["Dependencies complete", ...candidates.map((t, i) => `${i + 1}. ${t.outcome}`)];
+      const choice = await ctx.ui.select("Wait for which prior tasks? Failed dependencies block only their branch", labels);
+      if (!choice) throw cancelled(); if (choice === labels[0]) break;
+      dependencies.push(candidates[labels.indexOf(choice) - 1].id);
+    }
+    tasks.push({ id: `task${tasks.length + 1}`, outcome, ...selected, dependencies });
+  } while (tasks.length < 8 && await ctx.ui.confirm("Add another task?", "Independent tasks can run in parallel; dependent tasks receive predecessor results."));
+  const width = await ctx.ui.select("Maximum parallel agents", Array.from({ length: tasks.length }, (_, i) => String(i + 1)));
+  if (!width) throw cancelled();
+  return workSetup({ version: "work-setup-v1", id: `work-${randomUUID().slice(0, 8)}`, outcome, tasks, maxParallel: Number(width) });
+}
+async function revise(ctx: ExtensionCommandContext, session: GrantsSession, previous: WorkSetup): Promise<WorkSetup> {
+  const setup = structuredClone(previous);
+  while (true) {
+    const labels = ["Save revision", "Overall outcome", "Parallel limit", ...setup.tasks.map((t,i) => `${i+1}. ${t.outcome}`)];
+    const choice = await ctx.ui.select("Revise scope/configuration (topology and permissions stay fixed)", labels);
+    if (!choice) throw cancelled();
+    const index = labels.indexOf(choice);
+    if (index === 0) return workSetup(setup);
+    if (index === 1) setup.outcome = await ask(ctx, "Revised outcome", setup.outcome);
+    else if (index === 2) { const width = await ctx.ui.select("Parallel limit", Array.from({ length: setup.tasks.length }, (_, i) => String(i + 1))); if (!width) throw cancelled(); setup.maxParallel = Number(width); }
+    else { const task = setup.tasks[index - 3]; task.outcome = await ask(ctx, "Task outcome", task.outcome); Object.assign(task, await profile(ctx, session, task)); }
+  }
+}
+
+export function createWorkSession(session: GrantsSession, host: ReturnType<typeof createDailyDashboardSession>, rebind: () => void) {
+  let pending: Promise<void> | null = null, owned: Promise<WorkRunResult> | null = null;
+  const shutdown = new AbortController();
+  const run = async (verb: string, ctx: ExtensionCommandContext) => {
+    if (!ctx.hasUI) throw Error("Use /grants work in interactive Pi for setup and explicit run confirmation");
+    const current = await loadDeclaredWork(join(ctx.cwd, ".pi", "work-current.json"));
+    if (current) { session.declaredWork = current; rebind(); }
+    const selected = current ? await loadWorkSetup(current) : null;
+    const menu = ["Run selected work", "Declare new work", "Revise scope / configuration", "Record alternative", "Select saved work", "Select task for ordinary delegation", "Change priority", "Inspect results"];
+    const choice = verb ? ({ run: menu[0], new: menu[1], results: menu[7] } as Record<string, string>)[verb] : await ctx.ui.select(current ? selected?.setup.outcome ?? `Declared work: ${current.id}` : "No work selected", menu);
+    if (!choice) { if (verb) throw Error("Use /grants work, work new, work run or work results"); return; }
+    const guard = () => { if (!ctx.isIdle() || !ordinaryChildrenFor(session).quiescent()) throw Error("Wait for the original active work to settle before changing setup"); };
+    if (choice === menu[0]) {
+      if (!selected) throw Error("Declare multi-task work first; existing ordinary delegation remains available");
+      let priorities: string[] | undefined;
+      if (host.running) {
+        const frame = await host.frame(), controls = frame.controls as { intent?: { priorities: { obligation: { digest: string } }[] } };
+        priorities = controls.intent?.priorities.map(p => selected.tasks.find(t => t.obligation.digest === p.obligation.digest)?.id ?? "");
+      }
+      const result = await runSelectedWork(session, ctx, selected, priorities, { signal: shutdown.signal, started: promise => { owned = promise; } });
+      if (shutdown.signal.aborted) return;
+      if (result) { ctx.ui.notify(`${result.tasks.filter(t => t.state === "finished").length} finished; ${result.tasks.filter(t => t.state !== "finished").length} failed/blocked. No acceptance inferred.`, "info"); await showWorkResults(ctx, result); }
+      return;
+    }
+    if (choice === menu[7]) {
+      const binding = await readProductJson(join(ctx.cwd, ".pi", "work-last-run.json")) as ControlBinding<WorkRunInitial> | null;
+      if (!binding) throw Error("No bounded run result is retained for this project yet");
+      await showWorkResults(ctx, await inspectWorkRun(binding)); return;
+    }
+    if (choice === menu[6]) {
+      if (!host.running) throw Error("Start /grants host to change priority through the current dispatch owner");
+      const frame = await host.frame(), actions = frame.actions.filter(a => a.key.startsWith("priority-"));
+      const labels = actions.map((a, i) => `${i + 1}. ${a.label}`), picked = await ctx.ui.select("Next-work priority (does not rearrange active children)", labels);
+      const action = actions[labels.indexOf(picked ?? "")]; if (action) ctx.ui.notify(dashboardActionFeedback(action.label, await host.choose(action.key,{tip:frame.tip,requestDigest:action.requestDigest})), "info"); return;
+    }
+    guard();
+    if (choice === menu[5]) {
+      if (!selected || !current) throw Error("No multi-task setup selected");
+      const labels = selected.setup.tasks.map((t, i) => `${i + 1}. ${t.outcome}`), picked = await ctx.ui.select("Ordinary delegate binds which task?", labels), task = selected.tasks[labels.indexOf(picked ?? "")];
+      if (!task) return;
+      guard(); session.declaredWork = await selectRecordedWork({ ...selected, state: { ...selected.state, obligation: task.obligation } }, current.selectedSnapshot); rebind();
+      ctx.ui.notify("Task selected for subsequent ordinary delegation. Existing attempts were not rebound.", "info"); return;
+    }
+    if (choice === menu[4]) {
+      const setups = await listWorkSetups(ctx.cwd), labels = setups.map((s, i) => `${i + 1}. ${s.setup.outcome}`), picked = await ctx.ui.select("Select saved setup (existing work stays pinned)", labels), target = setups[labels.indexOf(picked ?? "")];
+      if (!target) return;
+      guard();
+      if (host.running) { if (!await ctx.ui.confirm("Stop the current host and select saved work?", "The old host's evidence remains intact. Start /grants host again for the selected setup.")) return; await host.run("stop"); }
+      session.declaredWork = await selectRecordedWork(target, current?.selectedSnapshot ?? null); rebind(); return;
+    }
+    const mode = choice === menu[1] ? "new" : choice === menu[2] ? "revise" : "alternative";
+    if (mode !== "new" && !selected) throw Error("Existing single-task work remains supported; declare a new multi-task setup to use revisions");
+    const draft = mode === "new" ? await author(ctx, session) : await revise(ctx, session, selected!.setup);
+    if (!await ctx.ui.confirm("Save this work setup?", `${draft.outcome}\n${draft.tasks.length} obligations; up to ${draft.maxParallel} parallel. Outcome/instruction text is retained in private project files, not governance ledgers. Nothing runs now.`)) return;
+    guard();
+    if (mode === "new" && host.running) { if (!await ctx.ui.confirm("Stop current host?", "A new topology needs a new host binding. Old evidence is preserved; no running work changes.")) return; await host.run("stop"); }
+    const recorded = await recordWorkSetup(ctx.cwd, draft, mode, current);
+    if (host.running) {
+      const prefix = mode === "revise" ? "scope" : "alternative", digest = createHash("sha256").update(intentKey(recorded.state.selectedSnapshot)).digest("hex").slice(0, 12);
+      ctx.ui.notify(dashboardActionFeedback("Select recorded work", await host.choose(`${prefix}-${digest}`)), "info");
+    } else { session.declaredWork = await selectRecordedWork(recorded, current?.selectedSnapshot ?? null); rebind(); }
+    ctx.ui.notify("Work saved. /grants work run starts it explicitly; /grants host connects the panel.", "info");
+  };
+  return { async close() { shutdown.abort(); if (owned) await owned.catch(() => undefined); }, async run(verb: string, ctx: ExtensionCommandContext) { shutdown.signal.throwIfAborted(); if (pending) throw Error("A work setup/run command is already active"); pending = run(verb, ctx); try { await pending; } finally { pending = null; owned = null; } } };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-daddy",
-  "version": "0.26.1",
+  "version": "0.27.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,12 @@
       "types": "./dist/ledger.d.ts",
       "default": "./dist/ledger.js"
     },
+    "./work-setup": { "types": "./dist/work-setup.d.ts", "default": "./dist/work-setup.js" },
+    "./work-command": { "types": "./dist/work-command.d.ts", "default": "./dist/work-command.js" },
+    "./work-run": { "types": "./dist/work-run.d.ts", "default": "./dist/work-run.js" },
+    "./work-policy-registry": { "types": "./dist/work-policy-registry.d.ts", "default": "./dist/work-policy-registry.js" },
+    "./factory-registry": { "types": "./dist/factory-registry.d.ts", "default": "./dist/factory-registry.js" },
+    "./learning-connection": { "types": "./dist/learning-connection.d.ts", "default": "./dist/learning-connection.js" },
     "./work-ledger": {
       "types": "./dist/work-ledger.d.ts",
       "default": "./dist/work-ledger.js"
@@ -241,6 +247,8 @@
     "THIRD_PARTY_LICENSES",
     "THIRD_PARTY_NOTICES.md",
     "README.md",
+    "PRODUCT-GUIDE.md",
+    "REQUIREMENTS.md",
     "CHANGELOG.md",
     "LICENSE"
   ],

package/src/cli.ts

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 /**
- * `pi-daddy` — the command line, which today has exactly one subcommand.
+ * `pi-daddy` — scaffolding, read-only work inspection and the installed product guide.
  *
  * Thin on purpose: argv in, `discoverSkillPackages` + `planInit` + `applyInit`, report out. Every decision
  * lives in `./init.ts`, `./grant-env.ts` and `./skill-packages.ts` as functions that touch no argv and print
@@ -21,7 +21,9 @@ import { UnsafeGrantError } from "./grant-env.ts";
 import { applyInit, countDeclaring, planInit, type InitPlan } from "./init.ts";
 import { registeredWorkspaceIds } from "./workspace.ts";
 import { discoverSkillPackages, skillPackageRoots, type RefusedSkill, type SkillPackage } from "./skill-packages.ts";
-import { declareWork } from "./work-command.ts";
+import { declareWork, loadDeclaredWork } from "./work-command.ts";
+import { listWorkSetups, workPresentation } from "./work-setup.ts";
+import { panelText } from "./daily-panel.ts";
 
 const USAGE = `pi-daddy — capability governance for pi sub-agents
 
@@ -30,6 +32,11 @@ Usage:
                                            packages that declare skills (package.json "pi": {"skills": …})
   pi-daddy work add --id <id> --outcome <text> [--dir <path>]
                                            declare one current obligation for ordinary delegation
+  pi-daddy work list | work show [--dir <path>]
+                                           inspect saved setups or selected outcome (no model calls)
+  In Pi: /grants work                     guided multi-task/model/effort/dependency setup and run
+         /grants learning                 retained review, trust, adoption and later outcomes
+  pi-daddy guide | current               installed product guide / current requirement register
   pi-daddy --help | --version
 
 init copies each declared SKILL.md into .pi/skills/ and writes a grant naming exactly what those files
@@ -41,7 +48,7 @@ placeholder and stays unspawnable until you fill it in. Capabilities that can ch
             It never rewrites .pi/grants.env — delete that file if you want it regenerated.`;
 
 export interface ParsedArgs {
-  command: "init" | "work-add" | "help" | "version";
+  command: "init" | "work-add" | "work-list" | "work-show" | "guide" | "current" | "help" | "version";
   dir?: string;
   force: boolean;
   id?: string;
@@ -64,10 +71,12 @@ export function parseArgs(argv: string[]): ParsedArgs {
   if (args.includes("--version") || args.includes("-v")) return { command: "version", force: false, errors: [] };
 
   const [command, ...tail] = args;
+  if(command==="guide"||command==="current")return{command,force:false,errors:tail.length?[`${command} takes no arguments`]:[]};
   if (command !== "init" && command !== "work") return { command: "help", force: false, errors: [`unknown command "${command}"`] };
   const work = command === "work";
-  const rest = work && tail[0] === "add" ? tail.slice(1) : tail;
-  if (work && tail[0] !== "add") return { command: "work-add", force: false, errors: ["work needs subcommand add"] };
+  const workVerb = tail[0];
+  const rest = work ? tail.slice(1) : tail;
+  if (work && !["add", "list", "show"].includes(workVerb)) return { command: "work-add", force: false, errors: ["work needs add, list or show; /grants work opens guided setup in Pi"] };
 
   const errors: string[] = [];
   let dir: string | undefined;
@@ -77,11 +86,11 @@ export function parseArgs(argv: string[]): ParsedArgs {
     const arg = rest[i];
     if (arg === "--force" && !work) {
       force = true;
-    } else if (arg === "--id" && work) {
+    } else if (arg === "--id" && work && workVerb === "add") {
       const value = rest[i + 1];
       if (value === undefined || value.startsWith("-")) errors.push("--id needs a value");
       else { id = value; i += 1; }
-    } else if (arg === "--outcome" && work) {
+    } else if (arg === "--outcome" && work && workVerb === "add") {
       const value = rest[i + 1];
       if (value === undefined || value.startsWith("-")) errors.push("--outcome needs text");
       else { outcome = value; i += 1; }
@@ -104,6 +113,7 @@ export function parseArgs(argv: string[]): ParsedArgs {
     }
   }
 
+  if (work && workVerb !== "add") return { command: workVerb === "list" ? "work-list" : "work-show", force: false, errors, ...(dir ? { dir } : {}) };
   if (work) {
     if (!id && !errors.some(error => error.startsWith("--id"))) errors.push("--id needs a value");
     if (!outcome && !errors.some(error => error.startsWith("--outcome"))) errors.push("--outcome needs text");
@@ -282,6 +292,15 @@ export async function main(argv: string[]): Promise<number> {
     console.log(USAGE);
     return 0;
   }
+  if(parsed.command==="guide"||parsed.command==="current"){
+    console.log(await readFile(new URL(parsed.command==="guide"?"../PRODUCT-GUIDE.md":"../REQUIREMENTS.md",import.meta.url),"utf8"));return 0;
+  }
+  if (parsed.command === "work-list" || parsed.command === "work-show") {
+    const cwd=resolvePath(parsed.dir??process.cwd());
+    if(parsed.command==="work-list") {const setups=await listWorkSetups(cwd);console.log(setups.map((s,i)=>`${i+1}. ${panelText(s.setup.outcome)} — ${s.setup.tasks.length} tasks; up to ${s.setup.maxParallel} parallel`).join("\n")||"No saved multi-task setups. In Pi: /grants work");}
+    else {const state=await loadDeclaredWork(resolvePath(cwd,".pi/work-current.json")),view=state?await workPresentation(state):null;console.log(view?[panelText(view.outcome),...view.obligations.map(o=>`- ${panelText(o.outcome)}`)].join("\n"):state?"Selected legacy work; outcome text unavailable":"No work selected. In Pi: /grants work");}
+    return 0;
+  }
   if (parsed.command === "work-add") {
     const declared = await declareWork({
       cwd: resolvePath(parsed.dir ?? process.cwd()),