pi-daddy 0.26.1 → 0.27.1

package/src/learning-connection.ts

@@ -0,0 +1,70 @@
+import { join, resolve } from "node:path";
+import { intentKey } from "./intent-control.ts";
+import { loadDeclaredWork, type DeclaredWorkState } from "./work-command.ts";
+import { readProductJson, writeProductJson } from "./product-files.ts";
+import { loadedDashboardHarnessDigest } from "./dashboard-harness.ts";
+import type { DashboardHarness } from "./dashboard-host-contract.ts";
+import { buildAdoptionBinding, type AdoptionAuthority, type AdoptionBinding, type AdoptionFacts, type AdoptionReceipt, type RollbackRequest, type ProductionObservation } from "./vendor/adoption.ts";
+
+export interface LearningConfiguration { archiveRoot: string; scopeDigest: string; population: string; author: string }
+export interface LearningUI { select(title: string, choices: string[]): Promise<string | undefined>; input(title: string, initial?: string): Promise<string | undefined>; editor(title: string, text: string): Promise<string | undefined>; confirm(title: string, detail: string): Promise<boolean>; notify(text: string, level?: "info" | "warning" | "error"): void }
+export interface LearningComparisonContext { caseReference: unknown | null; hypothesisManifestId: string | null; adoptionBinding: AdoptionBinding | null }
+export interface LearningWorkspace {
+  configuration(): LearningConfiguration;
+  inspect(now: number): { version: string; configuration: LearningConfiguration; cases: { name: string; title: string; state?: string; reason?: string }[]; comparisons: { name: string; title: string; state?: string; reason?: string }[]; trust: Record<string, unknown>; [key: string]: unknown };
+  dashboardBinding(): { trustDirectory: string | null; trustPolicyId: string | null };
+  bindCases(input: { name: string; title: string; version: 2 | 3; batchId: string }): unknown;
+  comparisonContext(name: string): LearningComparisonContext;
+  linkComparisonContext(name:string, context:LearningComparisonContext):unknown;
+  hypotheses(): {name:string;manifestId:string;hypothesis:{id:string}}[];
+  decisionStatus(name:string):{current:{disposition:string}|null};
+  reveal(name:string):{manifestId:string;choice:{kind:string;labels:readonly string[]};arms:readonly {label:string;configuration:{configuration:string}}[]};
+  preparedAdoption(name: string): AdoptionReceipt | null;
+  previewObservation(name: string, input: ProductionObservation): { observation: ProductionObservation; classification: unknown; digest: string };
+  observe(name: string, input: ProductionObservation, authorized: readonly string[]): { manifestId: string };
+  prepareAdoption(name: string, authority: AdoptionAuthority | null, facts: AdoptionFacts, now: number): AdoptionReceipt;
+  linkActivation(name: string, manifest: string, independentlyAuthorized: readonly string[]): unknown;
+  previewRollback(name: string, reason: "operator-request" | "confirmed-escape", evidence: string[], expiresAt?: number): RollbackRequest;
+  prepareRollback(name: string, request: RollbackRequest, authority: AdoptionAuthority | null, now: number, current: { adoptionId: string; candidateDigest: string; scopeDigest: string }): unknown;
+  linkRollback(name: string, manifest: string, independentlyAuthorized: readonly string[]): unknown;
+}
+export interface LearningHarness extends DashboardHarness {
+  createLearningWorkspace(directory: string, input: LearningConfiguration): LearningWorkspace;
+  openLearningWorkspace(directory: string): LearningWorkspace;
+  runLearningWizard(input: { directory: string; cwd: string; ui: LearningUI }): Promise<unknown>;
+}
+export function learningHarness(harness: DashboardHarness): LearningHarness {
+  if (!loadedDashboardHarnessDigest(harness) || ["createLearningWorkspace", "openLearningWorkspace", "runLearningWizard"].some(key => typeof (harness as unknown as Record<string, unknown>)[key] !== "function")) throw Error("Learning services are unavailable in the loaded skill-harness. Load the compatible learning-workspace-v1 release and start a fresh Pi session (the existing immutable bridge survives /reload); no private adapter is needed.");
+  return harness as LearningHarness;
+}
+/** Author only the missing binding from validated public readback after a durable choice. No authority is generated. */
+export function bindLearningAdoption(workspace:LearningWorkspace,name:string,input:{candidateDigest:string;rollbackCandidateDigest:string;assessmentPolicyDigest:string;expiresAt:number}):AdoptionBinding {
+  const context=workspace.comparisonContext(name);
+  if(context.adoptionBinding)throw Error("Adoption proposal is already bound; it cannot be replaced");
+  if(!context.caseReference||!context.hypothesisManifestId)throw Error("Link the comparison's original confirmed case and hypothesis in Learning first");
+  const original=workspace.hypotheses().find(h=>h.manifestId===context.hypothesisManifestId);
+  if(!original||workspace.decisionStatus(name).current?.disposition!=="adopt")throw Error("Retained original hypothesis and explicit adopt intent required");
+  const reveal=workspace.reveal(name);
+  if(!["one","tie"].includes(reveal.choice.kind)||!reveal.arms.some(a=>reveal.choice.labels.includes(a.label)&&a.configuration.configuration===input.candidateDigest))throw Error("Candidate is not the exact configuration selected by the full-artifact quality choice");
+  const binding=buildAdoptionBinding({...input,hypothesisDigest:original.hypothesis.id,experimentDigest:reveal.manifestId,scopeDigest:workspace.configuration().scopeDigest,activationBoundary:"next-orders"});
+  workspace.linkComparisonContext(name,{...context,adoptionBinding:binding});return binding;
+}
+export interface LearningConnection { version: "producer-learning-connection-v1"; directory: string; configuration: LearningConfiguration; selection: DeclaredWorkState["selectedSnapshot"] }
+export const learningScopeDigest = (state: DeclaredWorkState) => state.selectedSnapshot.snapshot.digest;
+export async function bindLearningConnection(cwd: string, state: DeclaredWorkState, directory: string, harness: LearningHarness, author: string): Promise<LearningConnection> {
+  if (resolve(directory) !== directory) throw Error("absolute learning workspace directory required");
+  const current=await loadDeclaredWork(state.statePath);
+  if(intentKey(current?.selectedSnapshot??null)!==intentKey(state.selectedSnapshot))throw Error("selected work changed before learning connection; reopen Learning");
+  const configuration = harness.openLearningWorkspace(directory).configuration();
+  if (configuration.scopeDigest !== learningScopeDigest(state) || configuration.author !== author) throw Error("learning workspace belongs to another work scope or author; not rebound");
+  const connection: LearningConnection = { version: "producer-learning-connection-v1", directory, configuration, selection: state.selectedSnapshot };
+  await writeProductJson(join(resolve(cwd), ".pi", "learning-workspace.json"), connection, true); return connection;
+}
+export async function loadLearningConnection(cwd: string, state: DeclaredWorkState, harness: LearningHarness, author: string): Promise<{ connection: LearningConnection; workspace: LearningWorkspace } | null> {
+  const c = await readProductJson(join(resolve(cwd), ".pi", "learning-workspace.json")) as LearningConnection | null;
+  if (!c) return null;
+  if (Object.keys(c).sort().join() !== "configuration,directory,selection,version" || c.version !== "producer-learning-connection-v1" || typeof c.directory !== "string" || resolve(c.directory) !== c.directory || intentKey(c.selection) !== intentKey(state.selectedSnapshot)) throw Error("Learning connection is stale for selected work. Reconnect deliberately with /grants learning; no evidence was carried forward.");
+  const workspace = harness.openLearningWorkspace(c.directory), actual = workspace.configuration();
+  if (intentKey(actual) !== intentKey(c.configuration) || actual.scopeDigest !== learningScopeDigest(state) || actual.author !== author) throw Error("learning archive/population/scope/author mismatch");
+  return { connection: c, workspace };
+}

package/src/model-preflight.ts

@@ -2,6 +2,15 @@ import { refusal, type StructuredRefusal } from "./refusals.ts";
 
 export const ENV_ALLOW_UNRESOLVED_MODELS = "PI_GRANTS_ALLOW_UNRESOLVED_MODELS";
 
+/** Pi's resolved catalogue carries provider support in thinkingLevelMap. Never silently clamp a user's choice. */
+export function supportedModelEfforts(model: { reasoning: boolean; thinkingLevelMap?: Partial<Record<string, string | null>> }): ("off"|"minimal"|"low"|"medium"|"high"|"xhigh"|"max")[] {
+  if (!model.reasoning) return ["off"];
+  return (["off","minimal","low","medium","high","xhigh","max"] as const).filter(level => {
+    const mapped=model.thinkingLevelMap?.[level];
+    return mapped!==null && ((level!=="xhigh"&&level!=="max") || mapped!==undefined);
+  });
+}
+
 export interface ModelCatalogue {
   find(provider: string, modelId: string): unknown;
 }

package/src/product-files.ts

@@ -0,0 +1,34 @@
+import { lstat, mkdir, realpath, rename, rm, writeFile } from "node:fs/promises";
+import { basename, dirname, resolve } from "node:path";
+import { randomUUID } from "node:crypto";
+import { readDailySnapshot } from "./daily-view-input.ts";
+import { parseRetentionJson } from "./retention-json.ts";
+import { runWithFinalizers } from "./finalization.ts";
+
+export const privateDirectory = (path:string) => directory(path,true);
+/** Pi's shared resource directory may be searchable; retained text files/subdirectories remain owner-only. */
+export const projectProductDirectory = (path:string) => directory(path,false);
+async function directory(path: string, ownerOnly:boolean): Promise<void> {
+  if (resolve(path) !== path) throw Error("absolute canonical product directory required");
+  try { await mkdir(path, { mode: 0o700 }); }
+  catch (error) { if ((error as NodeJS.ErrnoException).code !== "EEXIST") throw error; }
+  const state = await lstat(path);
+  if (!state.isDirectory() || state.isSymbolicLink() || state.mode & (ownerOnly?0o077:0o022) || state.uid !== process.getuid?.() || await realpath(path) !== path) throw Error(`owned non-writable${ownerOnly?" private":""} directory required: ${path}; existing permissions were not changed`);
+}
+export async function readProductJson(path: string, limit = 128 * 1024): Promise<unknown | null> {
+  try { const state = await lstat(path); if (!state.isFile() || state.isSymbolicLink() || state.mode & 0o077 || state.uid !== process.getuid?.() || state.nlink !== 1 || await realpath(path) !== path) throw Error(`private regular product file required: ${path}`); }
+  catch (error) { if ((error as NodeJS.ErrnoException).code === "ENOENT") return null; throw error; }
+  const snapshot = await readDailySnapshot(path, limit);
+  if (snapshot.status !== "read") throw Error(`product file unavailable: ${path}`);
+  const state = await lstat(path);
+  if (state.mode & 0o077 || state.uid !== process.getuid?.() || state.nlink !== 1 || await realpath(path) !== path) throw Error(`private regular product file required: ${path}`);
+  return parseRetentionJson(new TextDecoder("utf-8", { fatal: true }).decode(snapshot.bytes), limit);
+}
+export async function writeProductJson(path: string, value: unknown, replace = false): Promise<void> {
+  await (basename(dirname(path))===".pi"?projectProductDirectory:privateDirectory)(dirname(path));
+  const text = JSON.stringify(value, null, 2) + "\n";
+  if (Buffer.byteLength(text) > 128 * 1024) throw Error("product file bound exceeded");
+  if (!replace) { await writeFile(path, text, { mode: 0o600, flag: "wx" }); return; }
+  const temporary = `${path}.${randomUUID()}.tmp`;
+  await runWithFinalizers(async()=>{await writeFile(temporary, text, { mode: 0o600, flag: "wx" }); await rename(temporary, path);},[{label:"product temporary cleanup",run:async()=>{await rm(temporary,{force:true});}}]);
+}

package/src/skill-packages.ts

@@ -1,34 +1,15 @@
 /**
- * Which installed npm packages ship `SKILL.md` definitions — read from their own manifests.
- *
- * `pi-daddy init` scaffolds a governed project from whatever skill packages are already installed, and
- * this is how it finds them: **a package declares its skills in `package.json`'s `pi.skills` array**, which
- * is pi's own convention and how pi itself loads them. Measured against `principal-pi-skills@2.3.1`:
- *
- * ```json
- * "pi": { "skills": ["./decide", "./architect", "./plan", "./build", "./review", "./debug", "./git-ops"] }
- * ```
- *
- * **A declaration, never a heuristic.** Walking `node_modules` looking for files called `SKILL.md` would
- * find a package's test fixtures, its examples, and its vendored copies of someone else's skills — and
- * would then offer to install them as spawnable sub-agents. A package that says which of its files are
- * skills has said so on purpose, and that is the only list this reads.
- *
- * What it deliberately does NOT do: scan `~/.pi/agent/skills/`. Definitions already in a skill root are
- * discovered by `loadDefinitions` and governed as they stand; copying them into a project would duplicate
- * them under a name that shadows the original (project wins on collision), which is a change nobody asked
- * for.
- *
- * **Everything read here comes from a third party**, so this module is also where the refusals live: a
- * name, a declared capability id, or a path that cannot safely be written into a generated file is refused
- * with a reason rather than passed on (R-77, R-78, R-80). `init` generates a shell file an operator
- * `source`s; the only strings that may reach it are ones that survived a whitelist here.
+ * Setup discovers enabled Pi resources in place through its package resolver. Configured packages
+ * are never copied into another autoload root. For legacy npm installs unregistered with Pi only,
+ * the explicit package.json pi.skills declaration remains a scaffold source (ADR-0074).
+ * Names, ceilings and bytes are checked before they can enter the generated shell grant.
  */
 
 import { readdir, readFile, realpath } from "node:fs/promises";
 import { homedir } from "node:os";
 import { join, resolve, sep } from "node:path";
 import { ceilingForDefinition, parseSkillDefinition, type SkillDefinition } from "./definitions.ts";
+import { resolveSkillResources, skillResourceName } from "./skill-resources.ts";
 import { WILDCARD } from "./pi-tools.ts";
 import { AGENT_WILDCARD, WORKSPACE_WILDCARD, type Capability } from "./resolve.ts";
 import { isSafeCapability } from "./capabilities.ts";
@@ -38,6 +19,8 @@ export interface DiscoveredSkill {
   /** The file verbatim. `init` copies it rather than regenerating it, so nothing is lost in a round trip. */
   text: string;
   path: string;
+  /** Already enabled by Pi; setup must reference it rather than making a competing copy. */
+  referenced?: boolean;
 }
 
 /** Why a declared skill was refused before it could be planned. Each has a different fix. */
@@ -248,21 +231,63 @@ export function skillPackageRoots(cwd: string): string[] {
 }
 
 export async function discoverSkillPackages(cwd: string): Promise<SkillPackage[]> {
+  const resolved = await resolveSkillResources(cwd);
+  const packages: SkillPackage[] = [];
+  const seenSkills = new Set<string>();
+  const runtimeNames = new Set(resolved.skills.map(s => skillResourceName(s.path)));
+  const configuredRoots = new Set(resolved.configured.flatMap(p => p.installedPath ? [resolve(p.installedPath)] : []));
+  const configuredNames = new Set<string>(resolved.configured.flatMap(p => {
+    if (!p.source.startsWith("npm:")) return [];
+    const spec = p.source.slice(4);
+    const versionAt = spec.indexOf("@", 1);
+    return [versionAt < 0 ? spec : spec.slice(0, versionAt)];
+  }));
+  for (const root of configuredRoots) {
+    try { configuredNames.add(JSON.parse(await readFile(join(root, "package.json"), "utf8")).name); } catch { /* absent */ }
+  }
+  for (const resource of resolved.skills) {
+    const bytes = await readFile(resource.path).catch(() => null);
+    if (bytes === null) continue;
+    const text = bytes.toString("utf8");
+    const resourceName = skillResourceName(resource.path);
+    if (seenSkills.has(resourceName)) continue;
+    seenSkills.add(resourceName);
+    let name = resource.metadata.source;
+    let version = "local";
+    if (resource.metadata.origin === "package" && resource.metadata.baseDir) {
+      try {
+        const manifest = JSON.parse(await readFile(join(resource.metadata.baseDir, "package.json"), "utf8"));
+        name = manifest.name ?? name; version = manifest.version ?? version;
+      } catch { /* the resource can be used without optional display metadata */ }
+    } else name = `${resource.metadata.scope} skills`;
+    let pkg = packages.find(p => p.name === name && p.version === version);
+    if (!pkg) { pkg = { name, version, skills: [], refused: [], unreadable: [] }; packages.push(pkg); }
+    if (!Buffer.from(text, "utf8").equals(bytes)) {
+      pkg.refused.push({ subject: resourceName, reason: "not-utf8", detail: [] });
+      continue;
+    }
+    const definition = parseSkillDefinition(resource.path, text);
+    if (!definition) continue;
+    const skill = { definition, text, path: resource.path, referenced: true };
+    const refusal = refusalFor(skill);
+    if (refusal) pkg.refused.push(refusal); else pkg.skills.push(skill);
+  }
+
+  // Compatibility for npm installs that were never registered with Pi. Runtime discovery never scans
+  // node_modules. A configured package (including one disabled by a filter) must not re-enter here.
   const dirs: string[] = [];
-  const seenNames = new Set<string>();
   for (const root of skillPackageRoots(cwd)) await collectFrom(root, dirs);
-
-  const packages: SkillPackage[] = [];
+  const seenNames = new Set(packages.map(p => p.name));
   for (const dir of dirs) {
+    if (configuredRoots.has(resolve(dir))) continue;
     const found = await readSkillPackage(dir);
-    // First root wins on a name collision: the project's pinned copy outranks the machine-wide one, and
-    // silently preferring the other would make a committed lockfile stop meaning anything.
-    if (found && !seenNames.has(found.name)) {
-      seenNames.add(found.name);
-      packages.push(found);
-    }
+    if (!found || configuredNames.has(found.name) || seenNames.has(found.name)) continue;
+    seenNames.add(found.name);
+    found.skills = found.skills.filter(skill => !runtimeNames.has(skill.definition.name));
+    packages.push(found);
   }
-  return packages.sort((a, b) => a.name.localeCompare(b.name));
+  return packages;
+
 }
 
 /** Append every package directory under one `node_modules`, scoped packages included. */

package/src/skill-resources.ts

@@ -0,0 +1,48 @@
+/** Read Pi's configured resource surface without locks, installs, extension execution or model calls. */
+import { readFileSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { DefaultPackageManager, getAgentDir, SettingsManager } from "@earendil-works/pi-coding-agent";
+
+interface SkillResources {
+  skills: { path: string; enabled: boolean; metadata: { source: string; scope: string; origin: string; baseDir?: string } }[];
+  configured: { source: string; scope: string; installedPath?: string }[];
+}
+
+export function skillResourceName(path: string): string {
+  const parts = path.split(/[\\/]/);
+  const file = parts.at(-1) ?? "";
+  return file.toLowerCase() === "skill.md" ? parts.at(-2) ?? "" : file.replace(/\.md$/i, "");
+}
+
+export async function resolveSkillResources(cwd: string): Promise<SkillResources> {
+  const agentDir = getAgentDir();
+  const settingsManager = SettingsManager.fromStorage({
+    withLock(scope, read) {
+      const path = scope === "global" ? join(agentDir, "settings.json") : join(cwd, ".pi", "settings.json");
+      let text: string | undefined;
+      try { text = readFileSync(path, "utf8"); }
+      catch (error) { if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error; }
+      // This storage is intentionally read-only: no lock files or migrated settings are persisted.
+      read(text);
+    },
+  });
+  const errors = settingsManager.drainErrors();
+  if (errors.length) throw new Error(`Cannot discover skills: ${errors.map(e => `${e.scope} settings: ${e.error.message}`).join("; ")}`);
+  const manager = new DefaultPackageManager({ cwd, agentDir, settingsManager });
+  const resolved = await manager.resolve(async () => "skip");
+  // Pi has already applied package identity, scope, manifest and settings filters and precedence.
+  const seen = new Set<string>();
+  const skills = resolved.skills.filter(resource => resource.enabled).flatMap(resource => {
+    try {
+      const path = statSync(resource.path).isDirectory() ? join(resource.path, "SKILL.md") : resource.path;
+      return statSync(path).isFile() ? [{ ...resource, path }] : [];
+    } catch { return []; }
+  }).filter(resource => {
+    // Reserve identity before parsing: a malformed local override cannot reveal a wider package ceiling.
+    const name = skillResourceName(resource.path);
+    if (seen.has(name)) return false;
+    seen.add(name);
+    return true;
+  });
+  return { skills, configured: manager.listConfiguredPackages() };
+}

package/src/work-command.ts

@@ -17,6 +17,8 @@ import {
 } from "./work-ledger.ts";
 import { withFileLock } from "./file-lock.ts";
 import { resolveWorkSnapshotText } from "./work-ledger-snapshot.ts";
+import { readProductJson, writeProductJson } from "./product-files.ts";
+import { intentKey } from "./intent-control.ts";
 
 const ID = /^[A-Za-z0-9][A-Za-z0-9._:/@+\-]{0,127}$/;
 const DIGEST = /^[a-f0-9]{64}$/;
@@ -88,7 +90,8 @@ export async function loadDeclaredWork(statePath: string): Promise<WorkFrozen<De
     const ingestion = parseWorkLedgerText(ledger);
     const projection = projectWorkLedger(ledger, { selectedSnapshot: value.selectedSnapshot, authority: null });
     const obligation = projection.obligations.find(item => item.binding.obligation.digest === value.obligation.digest);
-    if (!ingestion.complete || projection.scopeState !== "valid" || !obligation || projection.selectedSnapshot?.digest !== value.selectedSnapshot.snapshot.digest) throw new Error("unbound");
+    const selected = resolveWorkSnapshotText(ledger, value.selectedSnapshot);
+    if (!ingestion.complete || projection.scopeState !== "valid" || !obligation || projection.selectedSnapshot?.digest !== value.selectedSnapshot.snapshot.digest || intentKey(obligation.binding.intent) !== intentKey(value.intent) || intentKey(obligation.binding.policy) !== intentKey(value.policy) || !selected.scope || selected.scope.digest !== value.scope.digest || selected.scope.id !== value.scope.id || selected.scope.revision !== value.scope.revision) throw new Error("unbound");
     return Object.freeze({ ...value, statePath: resolve(statePath) });
   } catch {
     throw new Error("invalid declared work state; no task was selected");
@@ -112,10 +115,12 @@ export async function declareWork(input: DeclareWorkInput): Promise<WorkFrozen<D
   }
   return withFileLock(resolved.statePath, "declared work", async () => {
     const existing = await loadDeclaredWork(resolved.statePath);
-    if (existing) {
-      if (existing.id === input.id && existing.outcomeDigest === outcomeDigest) return existing;
-      throw new Error(`declared work id ${input.id} already names a different outcome`);
-    }
+    if (existing && (existing.id !== input.id || existing.outcomeDigest !== outcomeDigest)) throw new Error(`declared work id ${input.id} already names a different outcome`);
+    const outcomePath = join(projectPi, "work-outcomes", `${outcomeDigest}.json`);
+    const retained = await readProductJson(outcomePath);
+    if (retained && JSON.stringify(retained) !== JSON.stringify({ outcome: input.outcome.trim() })) throw Error("declared outcome identity conflict");
+    if (!retained) await writeProductJson(outcomePath, { outcome: input.outcome.trim() });
+    if (existing) return existing;
     const pendingPath = `${resolved.statePath}.pending`;
     let prepared: { version: "pi-daddy-work-preparation-v1"; id: string; outcomeDigest: string; createdAt: string };
     try {
@@ -158,7 +163,7 @@ export async function declareWork(input: DeclareWorkInput): Promise<WorkFrozen<D
 
 /** Persist an already-applied exact selection so the next governed dispatch cannot keep using the old cached declaration. */
 export async function rebindDeclaredWork(state:WorkFrozen<DeclaredWorkState>,selectedSnapshot:NonNullable<WorkProjectionContext["selectedSnapshot"]>):Promise<WorkFrozen<DeclaredWorkState>>{
- return withFileLock(state.statePath,"declared work rebind",async()=>{const current=await loadDeclaredWork(state.statePath);if(!current||JSON.stringify(current.selectedSnapshot)!==JSON.stringify(state.selectedSnapshot))throw Error("declared work rebind is stale; new dispatch remains unsupported");const text=await readFile(state.ledgerPath,"utf8"),resolved=resolveWorkSnapshotText(text,selectedSnapshot),binding=resolved.snapshot?.bindings[0];if(resolved.scopeState!=="valid"||!resolved.scope||!resolved.snapshot||!binding)throw Error("applied declared selection cannot bind future dispatch");const stored:StoredDeclaredWorkState={version:"pi-daddy-declared-work-v1",id:state.id,outcomeDigest:state.outcomeDigest,ledgerPath:state.ledgerPath,grantLedgerPath:state.grantLedgerPath,selectedSnapshot,scope:{kind:resolved.scope.kind,id:resolved.scope.id,revision:resolved.scope.revision,digest:resolved.scope.digest},intent:binding.intent,obligation:binding.obligation,policy:binding.policy};const temporary=`${state.statePath}.${process.pid}.${randomUUID()}.tmp`;try{await writeFile(temporary,`${JSON.stringify(stored,null,2)}\n`,{encoding:"utf8",mode:0o600,flag:"wx"});await rename(temporary,state.statePath);}finally{await rm(temporary,{force:true});}return Object.freeze({...stored,statePath:state.statePath});});
+ return withFileLock(state.statePath,"declared work rebind",async()=>{const current=await loadDeclaredWork(state.statePath);if(!current||intentKey(current.selectedSnapshot)!==intentKey(state.selectedSnapshot))throw Error("declared work rebind is stale; new dispatch remains unsupported");const text=await readFile(state.ledgerPath,"utf8"),resolved=resolveWorkSnapshotText(text,selectedSnapshot),binding=resolved.snapshot?.bindings[0];if(resolved.scopeState!=="valid"||!resolved.scope||!resolved.snapshot||!binding)throw Error("applied declared selection cannot bind future dispatch");const stored:StoredDeclaredWorkState={version:"pi-daddy-declared-work-v1",id:state.id,outcomeDigest:state.outcomeDigest,ledgerPath:state.ledgerPath,grantLedgerPath:state.grantLedgerPath,selectedSnapshot,scope:{kind:resolved.scope.kind,id:resolved.scope.id,revision:resolved.scope.revision,digest:resolved.scope.digest},intent:binding.intent,obligation:binding.obligation,policy:binding.policy};const temporary=`${state.statePath}.${process.pid}.${randomUUID()}.tmp`;try{await writeFile(temporary,`${JSON.stringify(stored,null,2)}\n`,{encoding:"utf8",mode:0o600,flag:"wx"});await rename(temporary,state.statePath);}finally{await rm(temporary,{force:true});}return Object.freeze({...stored,statePath:state.statePath});});
 }
 
 export type DeclaredOccurrenceIdentity = Pick<WorkOccurrencePayload["labels"], "toolCallId" | "taskId" | "workspaceId" | "definitionDigest" | "configurationDigest" | "modelId" | "effortId"> & {

package/src/work-policy-registry.ts

@@ -0,0 +1,81 @@
+import { createControlJournal, controlJournal, type ControlBinding } from "./control-journal.ts";
+import { experimentHash, closed, cloneExperiment } from "./experiment-contract.ts";
+import { buildAdoptionBinding, buildRollbackRequest, validateAdoptionReceipt, authorizeRollback, type AdoptionBinding, type AdoptionReceipt, type RollbackRequest } from "./vendor/adoption.ts";
+import { factoryAuthority, requireFactoryAuthority, type FactoryAuthority } from "./factory-contract.ts";
+import { WORK_EFFORTS, type WorkSetup } from "./work-setup.ts";
+
+/** Additive profile: ONLY model/effort may change. Task IDs and definition names stay fixed. Normal definition-digest/grant checks still run; this is not a filesystem pin. */
+export interface WorkPolicy { version: "ordinary-work-policy-v1"; scopeDigest: string; assessmentPolicyDigest: string; profiles: { taskId: string; agent: string | null; model: string; thinking: typeof WORK_EFFORTS[number] }[] }
+export interface WorkPolicyInitial { version: "ordinary-work-registry-v1"; authorityId: string; scopeDigest: string; baseline: WorkPolicy }
+export type WorkPolicyRegistry = ControlBinding<WorkPolicyInitial>;
+export interface WorkPolicyActivation { version: "ordinary-work-activation-v1"; requestId: string; expectedRevision: number; expectedCandidateDigest: string; candidate: WorkPolicy; binding: AdoptionBinding; receipt: AdoptionReceipt }
+const sha = (x: unknown) => typeof x === "string" && /^[a-f0-9]{64}$/.test(x);
+export function workPolicy(input: WorkPolicy): WorkPolicy {
+  const p = cloneExperiment(input); closed(p, ["version", "scopeDigest", "assessmentPolicyDigest", "profiles"]);
+  if (p.version !== "ordinary-work-policy-v1" || !sha(p.scopeDigest) || !sha(p.assessmentPolicyDigest) || !Array.isArray(p.profiles) || !p.profiles.length || p.profiles.length > 8) throw Error("unsupported ordinary policy profile");
+  for (const t of p.profiles) { closed(t, ["taskId", "agent", "model", "thinking"]); if (!/^[A-Za-z0-9][A-Za-z0-9_-]{0,31}$/.test(t.taskId) || !(t.agent === null || typeof t.agent === "string" && /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/.test(t.agent)) || !/^[A-Za-z0-9._-]+\/[A-Za-z0-9._:/@+-]+$/.test(t.model) || t.model.length > 128 || !WORK_EFFORTS.includes(t.thinking)) throw Error("invalid model/effort profile; no fallback"); }
+  if (new Set(p.profiles.map(t => t.taskId)).size !== p.profiles.length) throw Error("duplicate profile task");
+  return p;
+}
+export const workPolicyDigest = (p: WorkPolicy) => experimentHash(workPolicy(p));
+export const workPolicyActivationDigest = (r: WorkPolicyActivation) => experimentHash(r);
+export function policyForSetup(setup: WorkSetup, scopeDigest: string, assessmentPolicyDigest: string): WorkPolicy { return workPolicy({ version: "ordinary-work-policy-v1", scopeDigest, assessmentPolicyDigest, profiles: setup.tasks.map(({ id: taskId, agent, model, thinking }) => ({ taskId, agent, model, thinking })) }); }
+function compatible(baseline: WorkPolicy, candidate: WorkPolicy) {
+  const shape = (p: WorkPolicy) => p.profiles.map(t => ({ taskId: t.taskId, agent: t.agent })).sort((a, b) => a.taskId.localeCompare(b.taskId));
+  if (baseline.scopeDigest !== candidate.scopeDigest || baseline.assessmentPolicyDigest !== candidate.assessmentPolicyDigest || experimentHash(shape(baseline)) !== experimentHash(shape(candidate))) throw Error("policy changes may only select models/effort for the same scoped definitions; no instruction, capability, topology or assessment expansion");
+}
+function replay(binding: WorkPolicyRegistry, events: Record<string, unknown>[]) {
+  const initial = binding.initial; closed(initial, ["version", "authorityId", "scopeDigest", "baseline"]);
+  if (initial.version !== "ordinary-work-registry-v1" || !/^[a-zA-Z0-9:_-]{1,128}$/.test(initial.authorityId) || initial.scopeDigest !== workPolicy(initial.baseline).scopeDigest) throw Error("invalid policy registry binding");
+  let candidate = initial.baseline, revision = 0, active: WorkPolicyActivation | null = null;
+  let lastChange: {operation:"activate"|"rollback";requestId:string;adoptionId:string}|null=null;
+  const lineage: (WorkPolicyActivation | null)[] = [], policies = new Map([[workPolicyDigest(candidate), candidate]]), requests = new Map<string, string>(), orders = new Map<string, { candidateDigest: string; adoptionId: string | null; revision: number }>();
+  for (const e of events) {
+    if (e.type === "activate") {
+      closed(e, ["type", "request"]); const r = e.request as unknown as WorkPolicyActivation; closed(r, ["version", "requestId", "expectedRevision", "expectedCandidateDigest", "candidate", "binding", "receipt"]);
+      const { version, id, ...draft } = r.binding;
+      if (r.version !== "ordinary-work-activation-v1" || !/^[a-zA-Z0-9:_-]{1,128}$/.test(r.requestId) || requests.has(r.requestId) || r.expectedRevision !== revision || r.expectedCandidateDigest !== workPolicyDigest(candidate) || version !== "adoption-binding-v1" || buildAdoptionBinding(draft).id !== id || r.binding.scopeDigest !== initial.scopeDigest || r.binding.candidateDigest !== workPolicyDigest(r.candidate) || r.binding.rollbackCandidateDigest !== workPolicyDigest(candidate) || r.binding.assessmentPolicyDigest !== r.candidate.assessmentPolicyDigest || r.receipt.bindingId !== id || r.receipt.authorityId !== initial.authorityId) throw Error("invalid activation sequence");
+      validateAdoptionReceipt(r.receipt, r.binding, { id: r.receipt.authorityId, adoptions: [r.binding.id], rollbacks: [] }, { experimentDigest: r.binding.experimentDigest, candidateDigest: r.binding.candidateDigest, scopeDigest: r.binding.scopeDigest, assessmentPolicyDigest: r.binding.assessmentPolicyDigest, eligible: true }, 0); // Structural replay only; activate/pin independently authorize again at use.
+      compatible(initial.baseline, workPolicy(r.candidate)); requests.set(r.requestId, workPolicyActivationDigest(r)); lineage.push(active); active = r; candidate = r.candidate; policies.set(workPolicyDigest(candidate), candidate); revision++; lastChange={operation:"activate",requestId:r.requestId,adoptionId:r.receipt.id};
+    } else if (e.type === "rollback") {
+      closed(e, ["type", "request", "fromRevision"]); const r = e.request as unknown as RollbackRequest;
+      if (!active || experimentHash(buildRollbackRequest(active.receipt,r.reason,[...r.evidence],r.expiresAt)) !== experimentHash(r) || e.fromRevision !== revision || requests.has(r.id) || r.adoptionId !== active.receipt.id || r.scopeDigest !== initial.scopeDigest || r.restoreCandidateDigest !== active.binding.rollbackCandidateDigest || !policies.has(r.restoreCandidateDigest)) throw Error("invalid rollback sequence");
+      candidate = policies.get(r.restoreCandidateDigest)!; if(!lineage.length)throw Error("missing rollback lineage"); active = lineage.pop() ?? null; if((active?.binding.candidateDigest??workPolicyDigest(initial.baseline))!==workPolicyDigest(candidate))throw Error("rollback lineage mismatch"); requests.set(r.id, experimentHash(r)); revision++; lastChange={operation:"rollback",requestId:r.id,adoptionId:r.adoptionId};
+    } else if (e.type === "order-pin") {
+      closed(e, ["type", "orderId", "candidateDigest", "adoptionId", "revision"]);
+      if (typeof e.orderId !== "string" || !/^[a-zA-Z0-9:_-]{1,128}$/.test(e.orderId) || orders.has(e.orderId) || e.candidateDigest !== workPolicyDigest(candidate) || e.adoptionId !== (active?.receipt.id ?? null) || e.revision !== revision) throw Error("invalid future-order pin");
+      orders.set(e.orderId, { candidateDigest: String(e.candidateDigest), adoptionId: e.adoptionId as string | null, revision });
+    } else throw Error("unknown work policy registry event");
+  }
+  return { candidate, revision, active, requests, orders, lastChange };
+}
+export async function createWorkPolicyRegistry(input: { directory: string; authorityId: string; baseline: WorkPolicy }): Promise<WorkPolicyRegistry> {
+  const baseline = workPolicy(input.baseline);
+  return createControlJournal(input.directory, { version: "ordinary-work-registry-v1", authorityId: input.authorityId, scopeDigest: baseline.scopeDigest, baseline });
+}
+export function openWorkPolicyRegistry(binding: WorkPolicyRegistry) {
+  const store = controlJournal(binding);
+  const inspect = async () => { const s = replay(binding, (await store.read()).events); return { version: "factory-registry-view-v1" as const, profile: "ordinary-model-effort-v1", scopeDigest: binding.initial.scopeDigest, candidateDigest: workPolicyDigest(s.candidate), candidate: s.candidate, revision: s.revision, activation: s.active, lastChange:s.lastChange, application:s.lastChange?"applied":"not-performed", requestId:s.lastChange?.requestId??null, orders: [...s.orders].map(([orderId, pin]) => ({ orderId, ...pin })), acceptance: "not-assessed" }; };
+  const authority = (host: FactoryAuthority | null) => requireFactoryAuthority(factoryAuthority(host), binding.initial.authorityId);
+  const eligible = (r: WorkPolicyActivation, host: FactoryAuthority) => { const facts = host.facts.find(f => f.bindingId === r.binding.id)?.facts; if (!facts) throw Error("current independent eligibility facts required"); validateAdoptionReceipt(r.receipt, r.binding, host.adoption, facts, Date.now()); };
+  return { inspect,
+    /** Pure validated replay of the proposed rollback; resolves original retained bytes, never a mutable named file. */
+    async previewRollback(request: RollbackRequest) {
+      const r=cloneExperiment(request),events=(await store.read()).events,s=replay(binding,events);
+      const restored=replay(binding,[...events,{type:"rollback",request:r,fromRevision:s.revision}]);
+      return {requestId:r.id,adoptionId:r.adoptionId,expectedRevision:s.revision,restoreCandidateDigest:workPolicyDigest(restored.candidate),candidate:cloneExperiment(restored.candidate)};
+    },
+    async activate(request: WorkPolicyActivation, host: FactoryAuthority | null) {
+      const r = cloneExperiment(request), a = authority(host); if (!a.activationDigests.includes(workPolicyActivationDigest(r))) throw Error("exact independent activation approval required");
+      await store.transaction(async (events, append) => { eligible(r,a); const s = replay(binding, events), old = s.requests.get(r.requestId); if (old) { if (old !== workPolicyActivationDigest(r)) throw Error("immutable activation ID"); return; } const event = { type: "activate", request: r }; replay(binding, [...events, event]); await append(event); }); return inspect();
+    },
+    async rollback(request: RollbackRequest, host: FactoryAuthority | null) {
+      const r = cloneExperiment(request), a = authority(host);
+      await store.transaction(async (events, append) => { const s = replay(binding, events), old = s.requests.get(r.id); if (old) { if (old !== experimentHash(r) || !a.adoption?.rollbacks.includes(r.id)) throw Error("rollback identity/authority mismatch"); return; } if (!s.active) throw Error("no active adoption to roll back"); authorizeRollback(s.active.receipt, r, a.adoption, Date.now(), { adoptionId: s.active.receipt.id, candidateDigest: workPolicyDigest(s.candidate), scopeDigest: binding.initial.scopeDigest }); const event = { type: "rollback", request: r, fromRevision: s.revision }; replay(binding, [...events, event]); await append(event); }); return { ...await inspect(), application: "applied" as const, requestId: r.id, grantExpansion: false };
+    },
+    async pin(orderId: string, host: FactoryAuthority | null, expected: { revision: number; candidateDigest: string }) {
+      const a = authority(host);
+      return store.transaction(async (events, append) => { const s = replay(binding, events); if(s.revision!==expected.revision||workPolicyDigest(s.candidate)!==expected.candidateDigest)throw Error("registry changed before order pin"); if (s.orders.has(orderId)) throw Error("order already pinned; never relaunch on readback"); if (s.active) eligible(s.active, a); const event = { type: "order-pin", orderId, candidateDigest: workPolicyDigest(s.candidate), adoptionId: s.active?.receipt.id ?? null, revision: s.revision }; replay(binding, [...events, event]); await append(event); return { ...event, candidate: s.candidate }; });
+    },
+  };
+}

package/src/work-run.ts

@@ -0,0 +1,79 @@
+import { randomUUID, createHash } from "node:crypto";
+import { writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { setTimeout as wait } from "node:timers/promises";
+import { createControlJournal, controlJournal, type ControlBinding } from "./control-journal.ts";
+import { composeStepTask, HANDOFF_MAX_BYTES } from "./chain.ts";
+import { splitBudget } from "./fanout.ts";
+import { workSetup, type WorkSetup, type WorkTaskSetup } from "./work-setup.ts";
+
+export interface WorkRunOutcome { ok: boolean; text: string; reason?: string; control?: "failed"; exitCode: number | null; truncated?: boolean; aborted?: boolean; timedOut?: boolean }
+export interface WorkRunTask { id: string; state: "waiting" | "running" | "finished" | "failed" | "blocked"; executionId: string | null; resultPath: string | null; resultDigest: string | null; reason: string | null }
+export interface WorkPolicyPin { orderId: string; candidateDigest: string; adoptionId: string | null; revision: number; scopeDigest: string }
+export interface WorkRunInitial { version: "work-run-v1"; runId: string; selectionDigest: string; setup: WorkSetup; policyPin: WorkPolicyPin | null }
+export interface WorkRunResult { binding: ControlBinding<WorkRunInitial>; tasks: WorkRunTask[]; acceptance: "not-assessed" }
+/** Finite DAG scheduler only. Execution, grants, cancellation, deadlines and observation remain original-owner operations. */
+export async function runWorkSetup(input: {
+  directory: string; selectionDigest: string; setup: WorkSetup; budget: number; signal?: AbortSignal; orderId?: string; policyPin?: WorkPolicyPin | null;
+  execute(task: WorkTaskSetup, prompt: string, perChildBudget: number, started: (executionId: string) => Promise<void>): Promise<WorkRunOutcome>;
+  onUpdate?: (tasks: readonly WorkRunTask[]) => void;
+  priorities?: string[];
+  /** Read the existing owner hold; waiting here never grants or performs a control action. */
+  admissionOpen?: () => boolean;
+}): Promise<WorkRunResult> {
+  const setup = workSetup(input.setup), split = splitBudget(input.budget, setup.tasks.length);
+  if (!split.ok) throw Error(split.reason);
+  if (!/^[a-f0-9]{64}$/.test(input.selectionDigest)) throw Error("exact selected work digest required");
+  const order = input.priorities ?? setup.tasks.map(t => t.id);
+  if (order.length !== setup.tasks.length || new Set(order).size !== order.length || order.some(id => !setup.tasks.some(t => t.id === id))) throw Error("priority must name each task exactly once");
+  const binding = await createControlJournal(input.directory, { version: "work-run-v1" as const, runId: input.orderId ?? randomUUID(), selectionDigest: input.selectionDigest, setup, policyPin: input.policyPin ?? null });
+  const journal = controlJournal(binding), outcomes = new Map<string, WorkRunOutcome>();
+  const tasks: WorkRunTask[] = order.map(id => ({ id, state: "waiting", executionId: null, resultPath: null, resultDigest: null, reason: null }));
+  const running = new Map<string, Promise<void>>();
+  let persistenceFailure: unknown;
+  const publish = () => { try { input.onUpdate?.(tasks.map(t => ({ ...t }))); } catch { /* display is not execution */ } };
+  const record = (task: WorkRunTask) => journal.transaction(async (_events, append) => append({ type: "task", ...task }));
+  while (tasks.some(t => t.state === "waiting") || running.size) {
+    for (const row of tasks.filter(t => t.state === "waiting")) {
+      const spec = setup.tasks.find(t => t.id === row.id)!;
+      if (input.signal?.aborted || persistenceFailure || spec.dependencies.some(d => ["failed", "blocked"].includes(tasks.find(t => t.id === d)!.state))) {
+        row.state = "blocked"; row.reason = input.signal?.aborted ? "Cancelled before admission" : persistenceFailure ? "Result/control persistence failed; no further admission" : "A dependency did not finish successfully";
+        try { await record(row); } catch (error) { persistenceFailure ??= error; }
+        continue;
+      }
+      if (input.admissionOpen?.() === false || running.size >= setup.maxParallel || !spec.dependencies.every(d => tasks.find(t => t.id === d)!.state === "finished")) continue;
+      row.state = "running";
+      const pending = (async () => {
+        try {
+          const previous = spec.dependencies.map(d => `${d}\n${outcomes.get(d)!.text}`).join("\n\n");
+          if (Buffer.byteLength(previous) > HANDOFF_MAX_BYTES) throw Error("Complete predecessor output exceeds the 32 KiB handoff bound; dependent work was not launched");
+          await record(row);
+          const outcome = await input.execute(spec, composeStepTask(spec.outcome, spec.dependencies.length ? previous : undefined), split.perChild, async executionId => { row.executionId = executionId; await record(row); publish(); });
+          outcomes.set(spec.id, outcome);
+          if (Buffer.byteLength(outcome.text) > 1024 * 1024) throw Error("original child result exceeds retention bound");
+          const bytes = Buffer.from(outcome.text), file = `${spec.id}.txt`;
+          await writeFile(join(binding.directory, file), bytes, { mode: 0o600, flag: "wx" });
+          row.resultPath = join(binding.directory, file); row.resultDigest = createHash("sha256").update(bytes).digest("hex");
+          row.state = outcome.ok && !outcome.control && !outcome.truncated ? "finished" : "failed";
+          row.reason = row.state === "finished" ? null : outcome.reason ?? (outcome.control ? "Observation/control failed" : outcome.truncated ? "Output truncated" : "Attempt failed");
+        } catch (error) { row.state = "failed"; row.reason = String(error); }
+        try { await record(row); } catch (error) { persistenceFailure ??= error; row.state = "failed"; row.reason = `Control acknowledgement unknown: ${String(error)}`; }
+        publish();
+      })().finally(() => running.delete(row.id));
+      running.set(row.id, pending); publish();
+    }
+    publish();
+    if (running.size) await Promise.race(running.values());
+    else if(tasks.some(t=>t.state==="waiting"))await wait(100,undefined,{signal:input.signal}).catch(error=>{if(!input.signal?.aborted)throw error;});
+  }
+  // No detached promises, restart relaunch, refund or retry. Original children have all settled here.
+  if (persistenceFailure) throw Error(`Work results may exist but control persistence failed: ${String(persistenceFailure)}`);
+  return { binding, tasks, acceptance: "not-assessed" };
+}
+export async function inspectWorkRun(binding: ControlBinding<WorkRunInitial>): Promise<WorkRunResult> {
+  workSetup(binding.initial.setup);
+  if (binding.initial.version !== "work-run-v1") throw Error("unsupported work run");
+  const rows = new Map<string, WorkRunTask>();
+  for (const event of (await controlJournal(binding).read()).events) if (event.type === "task") rows.set(String(event.id), event as unknown as WorkRunTask);
+  return { binding, tasks: binding.initial.setup.tasks.map(t => rows.get(t.id) ?? { id: t.id, state: "waiting", executionId: null, resultPath: null, resultDigest: null, reason: "No launch acknowledgement; do not infer or retry" }), acceptance: "not-assessed" };
+}