@oisin-ee/pi-todo 0.7.2 → 0.9.0

package/src/generated/todo_core.js

@@ -1,5 +1,33 @@
 /* @ts-self-types="./todo_core.d.ts" */
 
+/**
+ * Reads validated current-session activation.
+ *
+ * # Errors
+ * Rejects invalid persisted state.
+ * @param {TodoList} list
+ * @param {string} session_id
+ * @returns {ActiveUnit | undefined}
+ */
+export function active(list, session_id) {
+    try {
+        const retptr = wasm.__wbindgen_add_to_stack_pointer(-16);
+        const ptr0 = passStringToWasm0(session_id, wasm.__wbindgen_export, wasm.__wbindgen_export2);
+        const len0 = WASM_VECTOR_LEN;
+        wasm.active(retptr, addBorrowedObject(list), ptr0, len0);
+        var r0 = getDataViewMemory0().getInt32(retptr + 4 * 0, true);
+        var r1 = getDataViewMemory0().getInt32(retptr + 4 * 1, true);
+        var r2 = getDataViewMemory0().getInt32(retptr + 4 * 2, true);
+        if (r2) {
+            throw takeObject(r1);
+        }
+        return takeObject(r0);
+    } finally {
+        wasm.__wbindgen_add_to_stack_pointer(16);
+        heap[stack_pointer++] = undefined;
+    }
+}
+
 /**
  * Applies one validated operation.
  *
@@ -7,13 +35,14 @@
  *
  * Throws for malformed input or a rejected operation.
  * @param {TodoList} list
- * @param {Request} request
+ * @param {unknown} request
+ * @param {MutationContext} context
  * @returns {Change}
  */
-export function apply(list, request) {
+export function apply(list, request, context) {
     try {
         const retptr = wasm.__wbindgen_add_to_stack_pointer(-16);
-        wasm.apply(retptr, addBorrowedObject(list), addBorrowedObject(request));
+        wasm.apply(retptr, addBorrowedObject(list), addHeapObject(request), addBorrowedObject(context));
         var r0 = getDataViewMemory0().getInt32(retptr + 4 * 0, true);
         var r1 = getDataViewMemory0().getInt32(retptr + 4 * 1, true);
         var r2 = getDataViewMemory0().getInt32(retptr + 4 * 2, true);
@@ -28,6 +57,37 @@ export function apply(list, request) {
     }
 }
 
+/**
+ * Validates and atomically freezes a worker contract.
+ *
+ * # Errors
+ * Rejects malformed requests, stale origins and competing claims.
+ * @param {TodoList} list
+ * @param {string} input
+ * @param {string} session_id
+ * @returns {ClaimChange}
+ */
+export function claim(list, input, session_id) {
+    try {
+        const retptr = wasm.__wbindgen_add_to_stack_pointer(-16);
+        const ptr0 = passStringToWasm0(input, wasm.__wbindgen_export, wasm.__wbindgen_export2);
+        const len0 = WASM_VECTOR_LEN;
+        const ptr1 = passStringToWasm0(session_id, wasm.__wbindgen_export, wasm.__wbindgen_export2);
+        const len1 = WASM_VECTOR_LEN;
+        wasm.claim(retptr, addBorrowedObject(list), ptr0, len0, ptr1, len1);
+        var r0 = getDataViewMemory0().getInt32(retptr + 4 * 0, true);
+        var r1 = getDataViewMemory0().getInt32(retptr + 4 * 1, true);
+        var r2 = getDataViewMemory0().getInt32(retptr + 4 * 2, true);
+        if (r2) {
+            throw takeObject(r1);
+        }
+        return takeObject(r0);
+    } finally {
+        wasm.__wbindgen_add_to_stack_pointer(16);
+        heap[stack_pointer++] = undefined;
+    }
+}
+
 /**
  * Computes completion policy from branch facts.
  *
@@ -60,6 +120,68 @@ export function completion_reminder(facts) {
     }
 }
 
+/**
+ * Imports one validated seed into a fresh worker session.
+ *
+ * # Errors
+ * Rejects invalid seed, repository identity or existing work.
+ * @param {TodoList} list
+ * @param {string} input
+ * @param {string} session_id
+ * @param {string} repository_id
+ * @returns {Change}
+ */
+export function import_unit(list, input, session_id, repository_id) {
+    try {
+        const retptr = wasm.__wbindgen_add_to_stack_pointer(-16);
+        const ptr0 = passStringToWasm0(input, wasm.__wbindgen_export, wasm.__wbindgen_export2);
+        const len0 = WASM_VECTOR_LEN;
+        const ptr1 = passStringToWasm0(session_id, wasm.__wbindgen_export, wasm.__wbindgen_export2);
+        const len1 = WASM_VECTOR_LEN;
+        const ptr2 = passStringToWasm0(repository_id, wasm.__wbindgen_export, wasm.__wbindgen_export2);
+        const len2 = WASM_VECTOR_LEN;
+        wasm.import_unit(retptr, addBorrowedObject(list), ptr0, len0, ptr1, len1, ptr2, len2);
+        var r0 = getDataViewMemory0().getInt32(retptr + 4 * 0, true);
+        var r1 = getDataViewMemory0().getInt32(retptr + 4 * 1, true);
+        var r2 = getDataViewMemory0().getInt32(retptr + 4 * 2, true);
+        if (r2) {
+            throw takeObject(r1);
+        }
+        return takeObject(r0);
+    } finally {
+        wasm.__wbindgen_add_to_stack_pointer(16);
+        heap[stack_pointer++] = undefined;
+    }
+}
+
+/**
+ * Reads immutable import acknowledgement and closure evidence.
+ *
+ * # Errors
+ * Rejects invalid persisted state.
+ * @param {TodoList} list
+ * @param {string} session_id
+ * @returns {ImportReceipt | undefined}
+ */
+export function imported(list, session_id) {
+    try {
+        const retptr = wasm.__wbindgen_add_to_stack_pointer(-16);
+        const ptr0 = passStringToWasm0(session_id, wasm.__wbindgen_export, wasm.__wbindgen_export2);
+        const len0 = WASM_VECTOR_LEN;
+        wasm.imported(retptr, addBorrowedObject(list), ptr0, len0);
+        var r0 = getDataViewMemory0().getInt32(retptr + 4 * 0, true);
+        var r1 = getDataViewMemory0().getInt32(retptr + 4 * 1, true);
+        var r2 = getDataViewMemory0().getInt32(retptr + 4 * 2, true);
+        if (r2) {
+            throw takeObject(r1);
+        }
+        return takeObject(r0);
+    } finally {
+        wasm.__wbindgen_add_to_stack_pointer(16);
+        heap[stack_pointer++] = undefined;
+    }
+}
+
 /**
  * Replaces the whole list with `items`.
  *
@@ -87,6 +209,34 @@ export function init(items) {
     }
 }
 
+/**
+ * Reads a complete task contract.
+ *
+ * # Errors
+ * Rejects unknown IDs or incomplete contracts.
+ * @param {TodoList} list
+ * @param {string} id
+ * @returns {UnitContract}
+ */
+export function inspect(list, id) {
+    try {
+        const retptr = wasm.__wbindgen_add_to_stack_pointer(-16);
+        const ptr0 = passStringToWasm0(id, wasm.__wbindgen_export, wasm.__wbindgen_export2);
+        const len0 = WASM_VECTOR_LEN;
+        wasm.inspect(retptr, addBorrowedObject(list), ptr0, len0);
+        var r0 = getDataViewMemory0().getInt32(retptr + 4 * 0, true);
+        var r1 = getDataViewMemory0().getInt32(retptr + 4 * 1, true);
+        var r2 = getDataViewMemory0().getInt32(retptr + 4 * 2, true);
+        if (r2) {
+            throw takeObject(r1);
+        }
+        return takeObject(r0);
+    } finally {
+        wasm.__wbindgen_add_to_stack_pointer(16);
+        heap[stack_pointer++] = undefined;
+    }
+}
+
 /**
  * Validates a stored snapshot. It comes from the session file, so it is typed
  * `unknown` and checked here, by the type that owns its shape.
@@ -113,6 +263,64 @@ export function parse(snapshot) {
     }
 }
 
+/**
+ * Prevents mutations of revisions with an in-flight tool call.
+ *
+ * # Errors
+ * Rejects closure, replacement or alteration of any leased revision.
+ * @param {TodoList} before
+ * @param {TodoList} after
+ * @param {UnitRef[]} leases
+ */
+export function protect(before, after, leases) {
+    try {
+        const retptr = wasm.__wbindgen_add_to_stack_pointer(-16);
+        const ptr0 = passArrayJsValueToWasm0(leases, wasm.__wbindgen_export);
+        const len0 = WASM_VECTOR_LEN;
+        wasm.protect(retptr, addBorrowedObject(before), addBorrowedObject(after), ptr0, len0);
+        var r0 = getDataViewMemory0().getInt32(retptr + 4 * 0, true);
+        var r1 = getDataViewMemory0().getInt32(retptr + 4 * 1, true);
+        if (r1) {
+            throw takeObject(r0);
+        }
+    } finally {
+        wasm.__wbindgen_add_to_stack_pointer(16);
+        heap[stack_pointer++] = undefined;
+        heap[stack_pointer++] = undefined;
+    }
+}
+
+/**
+ * Records an executor's exact release evidence, never acceptance.
+ *
+ * # Errors
+ * Rejects malformed or mismatched settlements.
+ * @param {TodoList} list
+ * @param {string} input
+ * @param {string} session_id
+ * @returns {SettlementChange}
+ */
+export function settle(list, input, session_id) {
+    try {
+        const retptr = wasm.__wbindgen_add_to_stack_pointer(-16);
+        const ptr0 = passStringToWasm0(input, wasm.__wbindgen_export, wasm.__wbindgen_export2);
+        const len0 = WASM_VECTOR_LEN;
+        const ptr1 = passStringToWasm0(session_id, wasm.__wbindgen_export, wasm.__wbindgen_export2);
+        const len1 = WASM_VECTOR_LEN;
+        wasm.settle(retptr, addBorrowedObject(list), ptr0, len0, ptr1, len1);
+        var r0 = getDataViewMemory0().getInt32(retptr + 4 * 0, true);
+        var r1 = getDataViewMemory0().getInt32(retptr + 4 * 1, true);
+        var r2 = getDataViewMemory0().getInt32(retptr + 4 * 2, true);
+        if (r2) {
+            throw takeObject(r1);
+        }
+        return takeObject(r0);
+    } finally {
+        wasm.__wbindgen_add_to_stack_pointer(16);
+        heap[stack_pointer++] = undefined;
+    }
+}
+
 /**
  * The model-facing summary of `list`.
  *
@@ -187,6 +395,10 @@ function __wbg_get_imports() {
             const ret = Error(getStringFromWasm0(arg0, arg1));
             return addHeapObject(ret);
         },
+        __wbg_Number_14af1003b8dd5ead: function(arg0) {
+            const ret = Number(getObject(arg0));
+            return ret;
+        },
         __wbg_String_8564e559799eccda: function(arg0, arg1) {
             const ret = String(getObject(arg1));
             const ptr1 = passStringToWasm0(ret, wasm.__wbindgen_export, wasm.__wbindgen_export2);
@@ -374,16 +586,21 @@ function __wbg_get_imports() {
             return addHeapObject(ret);
         },
         __wbindgen_generic_0000000000000001: function(arg0) {
+            // Cast intrinsic for `F64 -> Externref`.
+            const ret = arg0;
+            return addHeapObject(ret);
+        },
+        __wbindgen_generic_0000000000000002: function(arg0) {
             // Cast intrinsic for `I64 -> Externref`.
             const ret = arg0;
             return addHeapObject(ret);
         },
-        __wbindgen_generic_0000000000000002: function(arg0, arg1) {
+        __wbindgen_generic_0000000000000003: function(arg0, arg1) {
             // Cast intrinsic for `Ref(String) -> Externref`.
             const ret = getStringFromWasm0(arg0, arg1);
             return addHeapObject(ret);
         },
-        __wbindgen_generic_0000000000000003: function(arg0) {
+        __wbindgen_generic_0000000000000004: function(arg0) {
             // Cast intrinsic for `U64 -> Externref`.
             const ret = BigInt.asUintN(64, arg0);
             return addHeapObject(ret);

package/src/generated/todo_core_bg.wasm.d.ts

@@ -1,10 +1,17 @@
 /* tslint:disable */
 /* eslint-disable */
 export const memory: WebAssembly.Memory;
-export const apply: (a: number, b: number, c: number) => void;
+export const active: (a: number, b: number, c: number, d: number) => void;
+export const apply: (a: number, b: number, c: number, d: number) => void;
+export const claim: (a: number, b: number, c: number, d: number, e: number, f: number) => void;
 export const completion_reminder: (a: number, b: number) => void;
+export const import_unit: (a: number, b: number, c: number, d: number, e: number, f: number, g: number, h: number) => void;
+export const imported: (a: number, b: number, c: number, d: number) => void;
 export const init: (a: number, b: number, c: number) => void;
+export const inspect: (a: number, b: number, c: number, d: number) => void;
 export const parse: (a: number, b: number) => void;
+export const protect: (a: number, b: number, c: number, d: number, e: number) => void;
+export const settle: (a: number, b: number, c: number, d: number, e: number, f: number) => void;
 export const view: (a: number, b: number) => void;
 export const widget: (a: number, b: number, c: number) => void;
 export const __wbindgen_export: (a: number, b: number) => number;

package/src/guidance.ts

@@ -3,6 +3,10 @@ const workUnitGuidance =
   "Size each executable unit for one agent session, with one deliverable, clear scope, and an acceptance condition. " +
   "Split independent outcomes or work that needs another session. Combine trivial steps with their deliverable and tests. " +
   "Delegate independent units separately; the lead can execute one unit. Keep dependent units ordered. " +
-  "Do not delegate an oversized parent as one assignment. Close children before explicit parent integration review.";
+  "Do not delegate an oversized parent as one assignment. Close children before explicit parent integration review. " +
+  "Supply deliverable, repository-relative scope, acceptance, prerequisite IDs, and self or worker/profile assignment. " +
+  "Use local keys for new prerequisites and the optional start selector for atomic creation and activation. " +
+  "Use returned IDs after creation. Update drafts before start; only one complete self leaf executes locally. " +
+  "Done requires concrete acceptance evidence; worker exit alone is not acceptance.";
 
 export { workUnitGuidance };

package/src/handoff.ts

@@ -0,0 +1,84 @@
+import type {
+  ExtensionAPI,
+  ExtensionContext,
+  SessionStartEvent,
+} from "@earendil-works/pi-coding-agent";
+import type { TaskProvider } from "./provider.ts";
+import { ownsTodo } from "./lifecycle.ts";
+import { seedPath } from "./seed-transport.ts";
+import { seedSource } from "./source.ts";
+
+type ImportHost = Readonly<Pick<ExtensionAPI, "exec" | "getAllTools">> & {
+  readonly events: Readonly<ExtensionAPI["events"]>;
+};
+
+/** Startup transport is read once; branch progress always wins on resume. */
+class WorkerImport {
+  readonly #pi: ImportHost;
+  readonly #provider: Readonly<TaskProvider>;
+
+  public constructor(pi: ImportHost, provider: Readonly<TaskProvider>) {
+    this.#pi = pi;
+    this.#provider = provider;
+  }
+
+  /**
+   * Activates a seed before the worker's initial request, without an LLM call.
+   * @param {SessionStartEvent} event Runtime startup reason.
+   * @param {ExtensionContext} ctx Current session authority.
+   */
+  public async start(event: SessionStartEvent, ctx: ExtensionContext): Promise<void> {
+    if (!ownsTodo(this.#pi)) {
+      return;
+    }
+    try {
+      const file = seedPath(this.#pi.events);
+      if (file !== undefined && this.#requiresImport(event, ctx)) {
+        await this.#load(file, ctx);
+      }
+    } catch (error: unknown) {
+      ctx.abort();
+      ctx.ui.notify(
+        `IMPORT_FAILED: ${error instanceof Error ? error.message : String(error)}`,
+        "error",
+      );
+    }
+  }
+
+  #requiresImport(event: SessionStartEvent, ctx: ExtensionContext): boolean {
+    const receipt = this.#provider.capability().imported();
+    if (!receipt.ok) {
+      throw new Error(receipt.error.message);
+    }
+    if (receipt.value !== null) {
+      return false;
+    }
+    if (
+      event.reason !== "startup" ||
+      ctx.sessionManager.getEntries().some((entry) => entry.type === "message")
+    ) {
+      throw new Error("IMPORT_FAILED: cannot seed an existing session");
+    }
+    return true;
+  }
+
+  async #load(file: string, ctx: ExtensionContext): Promise<void> {
+    const sessionId = ctx.sessionManager.getSessionId(),
+      leaf = ctx.sessionManager.getLeafId(),
+      source = seedSource(file),
+      origin = await this.#pi.exec("git", ["remote", "get-url", "origin"], { cwd: ctx.cwd }),
+      success = 0;
+    if (origin.code !== success) {
+      throw new Error("IMPORT_FAILED: checkout has no origin");
+    }
+    if (
+      ctx.sessionManager.getSessionId() !== sessionId ||
+      ctx.sessionManager.getLeafId() !== leaf
+    ) {
+      throw new Error("STALE_ORIGIN: session changed while reading repository identity");
+    }
+    this.#provider.import(source, origin.stdout, ctx);
+  }
+}
+
+export { WorkerImport };

package/src/import-fixture.ts

@@ -0,0 +1,63 @@
+import { mkdtemp, rm, writeFile } from "node:fs/promises";
+import { createBashTool } from "@earendil-works/pi-coding-agent";
+import { tmpdir } from "node:os";
+import { worker } from "./provider-fixture.ts";
+
+/**
+ * Runs Git with argument boundaries and explicit exit failure.
+ * @param {string} cwd Temporary owned checkout.
+ * @returns {Promise<void>} Command completion.
+ */
+const repository = async (cwd: string): Promise<void> => {
+    await createBashTool(cwd).execute("repository", {
+      command: "git init && git remote add origin git@github.com:oisin-ee/oisinpi.git",
+    });
+  },
+  /**
+   * Makes an owned repository and a seed from the real provider, without network I/O.
+   * @param {string} repositoryId Logical identity authored by the lead.
+   * @returns {Promise<object>} Temporary checkout and exact claim.
+   */
+  importFixture = async (
+    repositoryId = "github.com/oisin-ee/oisinpi",
+  ): Promise<{
+    cwd: string;
+    seedPath: string;
+    origin: Awaited<ReturnType<typeof worker>>;
+    removeSeed: () => Promise<void>;
+    close: () => Promise<void>;
+  }> => {
+    const cwd = await mkdtemp(`${tmpdir()}/todo-import-`),
+      seedPath = `${cwd}/seed.json`,
+      origin = await worker(repositoryId);
+    try {
+      await repository(cwd);
+      await writeFile(
+        seedPath,
+        JSON.stringify({
+          binding: origin.claimed.binding,
+          execution: origin.claimed.binding.execution,
+          exported: origin.claimed.exported,
+          version: 1,
+        }),
+      );
+      return {
+        close: async (): Promise<void> => {
+          origin.test.session.dispose();
+          await rm(cwd, { force: true, recursive: true });
+        },
+        cwd,
+        origin,
+        removeSeed: async (): Promise<void> => {
+          await rm(seedPath);
+        },
+        seedPath,
+      };
+    } catch (error: unknown) {
+      origin.test.session.dispose();
+      await rm(cwd, { force: true, recursive: true });
+      throw error;
+    }
+  };
+
+export { importFixture };

package/src/index.ts

@@ -1,12 +1,13 @@
 import { ownsTodo, settle } from "./lifecycle.ts";
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { PlannotatorHandoff } from "./plannotator.ts";
-import { StringEnum } from "@earendil-works/pi-ai";
+import { TaskProvider } from "./provider.ts";
 import { TodoPresentation } from "./presentation.ts";
 import { TodoWork } from "./work.ts";
-import { Type } from "typebox";
 import type { WorkHost } from "./work.ts";
-import { runTodo } from "./tool.ts";
+import { WorkerImport } from "./handoff.ts";
+import { parameters } from "./schema.ts";
+import { registerGate } from "./gate.ts";
 import { workUnitGuidance } from "./guidance.ts";
 
 type TodoAPI = WorkHost &
@@ -15,6 +16,7 @@ type TodoAPI = WorkHost &
       ExtensionAPI,
       | "appendEntry"
       | "getAllTools"
+      | "exec"
       | "on"
       | "registerCommand"
       | "registerShortcut"
@@ -23,37 +25,6 @@ type TodoAPI = WorkHost &
     >
   >;
 
-const subtasks = Type.Immutable(Type.Array(Type.String())),
-  outcome = Type.Immutable(
-    Type.Object({ content: Type.String(), subtasks }, { additionalProperties: false }),
-  ),
-  item = Type.Union([Type.String(), outcome]),
-  items = Type.Immutable(
-    Type.Array(item, {
-      description:
-        "Pending outcomes for init/append. With parent, append accepts string work units only. Two levels only.",
-    }),
-  ),
-  parameters = Type.Object({
-    items: Type.Optional(items),
-    op: StringEnum(["init", "start", "done", "drop", "append", "view"] as const, {
-      description:
-        "init replaces; start explicitly activates without demoting others; done completes; drop abandons open work; append adds pending work; view reads.",
-    }),
-    parent: Type.Optional(
-      Type.String({
-        description:
-          "Exact root content to target a child. Child start/done/drop also require task.",
-      }),
-    ),
-    task: Type.Optional(
-      Type.String({
-        description:
-          "Exact task content within parent, or at root. Omit for done/drop to close open roots. Complete children before parents.",
-      }),
-    ),
-  });
-
 /**
  * Registers the branch-backed `todo` tool and its completion reminder.
  * @param {TodoAPI} pi The extension API methods used here.
@@ -61,17 +32,16 @@ const subtasks = Type.Immutable(Type.Array(Type.String())),
 export default function piTodo(pi: TodoAPI): void {
   const handoff = new PlannotatorHandoff(pi),
     presentation = new TodoPresentation(),
-    work = new TodoWork(pi, presentation);
+    work = new TodoWork(pi, presentation),
+    provider = new TaskProvider(pi),
+    workerImport = new WorkerImport(pi, provider);
   work.register(pi);
+  provider.register();
+  registerGate(pi, provider);
   pi.registerTool({
-    description: `Keep branch-local outcomes and optional bounded subtasks. Address exact content plus optional parent. Creation is pending. Start explicitly; parallel starts preserve other active work. Parents require explicit integration review after children close. ${workUnitGuidance}`,
+    description: `Keep branch-local outcomes and executable contracts. Use returned IDs, not labels. Draft creation is pending. Start one complete self-assigned leaf; workers require their assigned profile through the executor. Update replaces pending contract fields. Done requires acceptance evidence. Parents require explicit integration review after children close. ${workUnitGuidance}`,
     async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
-      const result = runTodo(params, {
-        append: (customType, list) => {
-          pi.appendEntry(customType, list);
-        },
-        branch: () => ctx.sessionManager.getBranch(),
-      });
+      const result = provider.run(params, ctx);
       work.publish(ctx);
       presentation.refresh(ctx);
       return result;
@@ -81,16 +51,20 @@ export default function piTodo(pi: TodoAPI): void {
     name: "todo",
     parameters,
   });
-  pi.on("session_start", (_event, ctx) => {
+  pi.on("session_start", async (event, ctx) => {
+    provider.context(ctx);
+    await workerImport.start(event, ctx);
     presentation.start(pi, ctx);
     work.start(ctx);
     handoff.start(ctx);
   });
   pi.on("session_shutdown", () => {
+    provider.stop();
     handoff.stop();
     work.stop();
   });
   pi.on("session_tree", (_event, ctx) => {
+    provider.context(ctx);
     if (ownsTodo(pi)) {
       work.publish(ctx);
       presentation.reset(ctx);

package/src/lease-fixture.ts

@@ -0,0 +1,95 @@
+import { contract, firstId } from "./contract-fixture.ts";
+import { emptyParameters, emptyResult, runtimeFixture } from "./runtime-fixture.ts";
+import { branchSnapshot } from "./state.ts";
+
+/**
+ * Completes an unrelated unit on a fresh branch.
+ * @param {Readonly<object>} test Runtime task and branch operations.
+ */
+const unrelated = async (test: {
+  readonly manager: {
+    readonly resetLeaf: () => void;
+    readonly getBranch: () => ReturnType<
+      Awaited<ReturnType<typeof runtimeFixture>>["manager"]["getBranch"]
+    >;
+  };
+  readonly todo: Awaited<ReturnType<typeof runtimeFixture>>["todo"];
+}): Promise<void> => {
+  test.manager.resetLeaf();
+  await test.todo({
+    items: [{ content: "Other branch", contract: contract(), key: "other" }],
+    op: "init",
+    start: "other",
+  });
+  const list = branchSnapshot(test.manager.getBranch());
+  await test.todo({ evidence: "Reviewed unrelated work", op: "done", task: firstId(list) });
+};
+
+interface Leased {
+  readonly test: Awaited<ReturnType<typeof runtimeFixture>>;
+  readonly id: string;
+  readonly calls: readonly string[];
+  readonly revisit: () => void;
+  readonly unrelated: () => Promise<void>;
+  readonly finish: () => Promise<void>;
+  readonly close: () => void;
+}
+
+/**
+ * Owns the controlled execution boundary used by lease regressions.
+ * @param {boolean} nested Runs through real codemode when true.
+ * @param {boolean} fail Throws at the actual execute boundary when true.
+ * @returns {Promise<object>} Running tool and deterministic completion controls.
+ */
+const leased = async (nested: boolean, fail: boolean): Promise<Leased> => {
+  const entered = Promise.withResolvers<boolean>(),
+    finished = Promise.withResolvers<boolean>(),
+    calls: string[] = [],
+    test = await runtimeFixture((pi) => {
+      pi.registerTool({
+        description: "Controlled mutation",
+        execute: async (id) => {
+          calls.push(id);
+          entered.resolve(true);
+          await finished.promise;
+          if (fail) {
+            throw new Error("Mutation failed");
+          }
+          return emptyResult();
+        },
+        label: "Mutation",
+        name: "mutation",
+        parameters: emptyParameters,
+      });
+    });
+  await test.create();
+  const id = firstId(branchSnapshot(test.manager.getBranch())),
+    running = nested
+      ? test.call("codemode", { code: "return await tools.mutation({})" })
+      : test.call("mutation", {});
+  await entered.promise;
+  const origin = test.manager.getLeafId();
+  if (origin === null) {
+    throw new Error("Expected leased origin branch leaf");
+  }
+  return {
+    calls,
+    close: (): void => {
+      finished.resolve(true);
+      test.session.dispose();
+    },
+    finish: async (): Promise<void> => {
+      finished.resolve(true);
+      await running;
+    },
+    id,
+    revisit: (): void => {
+      test.manager.resetLeaf();
+      test.manager.branch(origin);
+    },
+    test,
+    unrelated: async (): Promise<void> => unrelated(test),
+  };
+};
+
+export { leased };