fix(leases): make knotsLeaseId required throughout lease lifecycle

Harden the Knots lease contract: ensureKnotsLease now throws on failure
instead of returning undefined, all downstream signatures require a
non-optional knotsLeaseId, and prompt_delivered audit events are emitted
after take/poll prompt construction. Passes lease ID to poll --claim.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: acartine

src/lib/__tests__/execution-backend-rollback.test.ts

@@ -311,18 +311,14 @@ describe("rollbackIteration: metadata and edge cases", () => {
     expect(mockTerminateLease).toHaveBeenCalledWith("lease-k1", "/repo");
   });
 
-  it("warn-and-continues when createLease fails during prepareTake", async () => {
+  it("returns failure when createLease fails during prepareTake", async () => {
     mockResolveMemoryManagerType.mockReturnValue("knots");
     mockCreateLease.mockResolvedValue({ ok: false, error: "lease create failed" });
-    mockClaimKnot.mockResolvedValue({
-      ok: true,
-      data: { id: "beat-1", title: "Test", state: "in_progress", profile_id: "default", prompt: "do work" },
-    });
 
     const result = await seb.prepareTake({ beatId: "beat-1", repoPath: "/repo", mode: "take" });
 
-    expect(result.ok).toBe(true);
-    expect(result.data?.knotsLeaseId).toBeUndefined();
+    expect(result.ok).toBe(false);
+    expect(result.error?.message).toContain("lease create failed");
   });
 
   it("releases the knots lease when preparePoll fails after lease creation", async () => {

src/lib/__tests__/knots-backend-contract.test.ts

@@ -349,13 +349,18 @@ describe("KnotsBackend: buildTakePrompt", () => {
     expect(created.ok).toBe(true);
     const id = created.data!.id;
 
-    const result = await backend.buildTakePrompt(id);
+    const result = await backend.buildTakePrompt(id, {
+      knotsLeaseId: "test-lease",
+    });
     expect(result.ok).toBe(true);
     expect(result.data?.prompt).toContain(id);
     expect(result.data?.prompt).toContain(
       "KNOTS CLAIM MODE",
     );
     expect(result.data?.prompt).toContain("kno claim");
+    expect(result.data?.prompt).toContain(
+      '--lease "test-lease"',
+    );
     expect(result.data?.prompt).toContain(
       "single-step authorization",
     );

src/lib/__tests__/knots-backend-coverage-deps.test.ts

@@ -234,6 +234,7 @@ describe("KnotsBackend coverage: buildTakePrompt single-beat mode", () => {
     const result = await backend.buildTakePrompt("SOLO-1", {
       isParent: true,
       childBeatIds: [],
+      knotsLeaseId: "test-lease",
     });
 
     expect(result.ok).toBe(true);
@@ -253,6 +254,7 @@ describe("KnotsBackend coverage: buildTakePrompt single-beat mode", () => {
     const result = await backend.buildTakePrompt("SOLO-2", {
       isParent: false,
       childBeatIds: ["unused"],
+      knotsLeaseId: "test-lease",
     });
 
     expect(result.ok).toBe(true);
@@ -263,7 +265,9 @@ describe("KnotsBackend coverage: buildTakePrompt single-beat mode", () => {
 
   it("returns error when showKnot fails for single-beat mode", async () => {
     const backend = new KnotsBackend("/repo");
-    const result = await backend.buildTakePrompt("MISSING-SINGLE");
+    const result = await backend.buildTakePrompt("MISSING-SINGLE", {
+      knotsLeaseId: "test-lease",
+    });
 
     expect(result.ok).toBe(false);
     expect(mockClaimKnot).not.toHaveBeenCalled();
@@ -277,7 +281,9 @@ describe("KnotsBackend coverage: buildTakePrompt single-beat mode", () => {
       description: "Do the thing",
     });
 
-    const result = await backend.buildTakePrompt("DETAIL-1");
+    const result = await backend.buildTakePrompt("DETAIL-1", {
+      knotsLeaseId: "test-lease",
+    });
 
     expect(result.ok).toBe(true);
     expect(result.data?.prompt).toContain("Beat ID: DETAIL-1");
@@ -303,7 +309,9 @@ describe("KnotsBackend coverage: buildTakePrompt single-beat mode", () => {
       body: "Body text here",
     });
 
-    const result = await backend.buildTakePrompt("BODY-1");
+    const result = await backend.buildTakePrompt("BODY-1", {
+      knotsLeaseId: "test-lease",
+    });
 
     expect(result.ok).toBe(true);
     expect(result.data?.prompt).toContain(

src/lib/__tests__/terminal-manager-abort.test.ts

@@ -82,7 +82,7 @@ vi.mock("@/lib/knots", () => ({
 
 vi.mock("@/lib/lease-audit", () => ({
   appendLeaseAuditEvent: vi.fn(async () => undefined),
-  logLeaseAudit: vi.fn(),
+  logLeaseAudit: vi.fn(async () => undefined),
 }));
 
 vi.mock("@/lib/beads-state-machine", () => ({

src/lib/__tests__/terminal-manager-error-retry-retry.test.ts

@@ -68,6 +68,7 @@ vi.mock("@/lib/backend-instance", () => ({
 }));
 
 vi.mock("@/lib/interaction-logger", () => ({
+  resolveInteractionLogRoot: vi.fn(() => "/tmp/foolery-logs"),
   startInteractionLog: vi.fn(async () => interactionLog),
   noopInteractionLog: vi.fn(() => interactionLog),
 }));
@@ -81,7 +82,7 @@ vi.mock("@/lib/knots", () => ({
 
 vi.mock("@/lib/lease-audit", () => ({
   appendLeaseAuditEvent: vi.fn(async () => undefined),
-  logLeaseAudit: vi.fn(),
+  logLeaseAudit: vi.fn(async () => undefined),
 }));
 
 vi.mock("@/lib/beads-state-machine", () => ({

src/lib/__tests__/terminal-manager-knots-next-guard-take-loop.test.ts

@@ -89,7 +89,7 @@ vi.mock("@/lib/knots", () => ({
 
 vi.mock("@/lib/lease-audit", () => ({
   appendLeaseAuditEvent: vi.fn(async () => undefined),
-  logLeaseAudit: vi.fn(),
+  logLeaseAudit: vi.fn(async () => undefined),
 }));
 
 vi.mock("@/lib/beads-state-machine", () => ({

src/lib/__tests__/terminal-manager-queue-claims.test.ts

@@ -134,7 +134,7 @@ vi.mock("@/lib/agent-outcome-stats", () => ({
 
 vi.mock("@/lib/lease-audit", () => ({
   appendLeaseAuditEvent: vi.fn(async () => undefined),
-  logLeaseAudit: vi.fn(),
+  logLeaseAudit: vi.fn(async () => undefined),
 }));
 
 import { createSession } from "@/lib/terminal-manager";

src/lib/__tests__/terminal-manager-step-failure-rollback.test.ts

@@ -82,7 +82,7 @@ vi.mock("@/lib/knots", () => ({
 
 vi.mock("@/lib/lease-audit", () => ({
   appendLeaseAuditEvent: vi.fn(async () => undefined),
-  logLeaseAudit: vi.fn(),
+  logLeaseAudit: vi.fn(async () => undefined),
 }));
 
 vi.mock("@/lib/beads-state-machine", () => ({

src/lib/backends/knots-backend-prompts.ts

@@ -300,10 +300,26 @@ export async function buildSingleTakePrompt(
   }
   const knot = showResult.data!;
 
-  const claimCmd = options?.knotsLeaseId
-    ? `kno claim "${beatId}" --json ` +
-      `--lease "${options.knotsLeaseId}"`
-    : `kno claim "${beatId}" --json`;
+  if (!options?.knotsLeaseId) {
+    return {
+      ok: false,
+      error: {
+        code: "INTERNAL",
+        message: `knotsLeaseId is required to build ` +
+          `a take prompt for ${beatId}`,
+        retryable: false,
+      },
+    };
+  }
+  const claimCmd =
+    `kno claim "${beatId}" --json ` +
+    `--lease "${options.knotsLeaseId}"`;
+  console.log(
+    `[knots-backend-prompts] buildSingleTakePrompt: ` +
+    `beatId=${beatId} ` +
+    `leaseId=${options.knotsLeaseId} ` +
+    `claimCmd=${claimCmd}`,
+  );
 
   const prompt = [
     `Beat ID: ${beatId}`,

src/lib/execution-backend-helpers.ts

@@ -23,6 +23,7 @@ import {
   logAttachedKnotsLease,
   terminateKnotsRuntimeLease,
 } from "@/lib/knots-lease-runtime";
+import { logLeaseAudit } from "@/lib/lease-audit";
 import {
   forwardTransitionTarget,
   resolveStep,
@@ -69,14 +70,23 @@ export async function prepareTakeKnots(
   leaseId: string,
   loadSnapshot: LoadSnapshotFn,
 ): Promise<BackendResult<ExecutionLease>> {
-  const knotsLeaseId = await ensureKnotsLease({
-    repoPath: input.repoPath,
-    source: "structured_prepare_take",
-    executionLeaseId: leaseId,
-    beatId: input.beatId,
-    interactionType: input.mode,
-    agentInfo: input.agentInfo,
-  });
+  let knotsLeaseId: string;
+  try {
+    knotsLeaseId = await ensureKnotsLease({
+      repoPath: input.repoPath,
+      source: "structured_prepare_take",
+      executionLeaseId: leaseId,
+      beatId: input.beatId,
+      interactionType: input.mode,
+      agentInfo: input.agentInfo,
+    });
+  } catch (err) {
+    return fail(
+      err instanceof Error
+        ? err.message
+        : "Failed to create Knots lease",
+    );
+  }
   const claimResult = await claimKnot(
     input.beatId, input.repoPath, {
       agentName: input.agentInfo?.agentName,
@@ -115,7 +125,7 @@ async function finalizeTakeKnots(
   backend: BackendPort,
   input: PrepareTakeInput,
   leaseId: string,
-  knotsLeaseId: string | undefined,
+  knotsLeaseId: string,
   claimData: { prompt: string; state: string },
   loadSnapshot: LoadSnapshotFn,
 ): Promise<BackendResult<ExecutionLease>> {
@@ -172,6 +182,27 @@ async function finalizeTakeKnots(
     agentInfo: input.agentInfo,
     knotsLeaseId,
   });
+  void logLeaseAudit({
+    event: "prompt_delivered",
+    repoPath: input.repoPath,
+    executionLeaseId: leaseId,
+    knotsLeaseId,
+    beatId: input.beatId,
+    interactionType: input.mode,
+    agentName: input.agentInfo?.agentName,
+    agentModel: input.agentInfo?.agentModel,
+    agentVersion: input.agentInfo?.agentVersion,
+    outcome: "success",
+    message:
+      `Execution prompt includes lease ` +
+      `${knotsLeaseId} for ${input.beatId}.`,
+    data: {
+      source: "structured_prepare_take",
+      promptLength: claimData.prompt.length,
+      hasLeaseInPrompt:
+        claimData.prompt.includes("--lease"),
+    },
+  });
   return ok(lease);
 }
 
@@ -297,15 +328,27 @@ export async function preparePollKnots(
   loadSnapshot: LoadSnapshotFn,
 ): Promise<BackendResult<PollLeaseResult>> {
   const executionLeaseId = generateLeaseId();
-  const knotsLeaseId = await ensureKnotsLease({
-    repoPath: input.repoPath,
-    source: "structured_prepare_poll",
-    executionLeaseId,
-    interactionType: "poll",
-    agentInfo: input.agentInfo,
-  });
+  let knotsLeaseId: string;
+  try {
+    knotsLeaseId = await ensureKnotsLease({
+      repoPath: input.repoPath,
+      source: "structured_prepare_poll",
+      executionLeaseId,
+      interactionType: "poll",
+      agentInfo: input.agentInfo,
+    });
+  } catch (err) {
+    return fail(
+      err instanceof Error
+        ? err.message
+        : "Failed to create Knots lease",
+    );
+  }
   const pollResult = await pollKnot(
-    input.repoPath, input.agentInfo,
+    input.repoPath, {
+      ...input.agentInfo,
+      leaseId: knotsLeaseId,
+    },
   );
   if (!pollResult.ok || !pollResult.data) {
     await terminateKnotsRuntimeLease({
@@ -333,7 +376,7 @@ async function finalizePollKnots(
   backend: BackendPort,
   input: PreparePollInput,
   executionLeaseId: string,
-  knotsLeaseId: string | undefined,
+  knotsLeaseId: string,
   pollData: { id: string; prompt: string; state: string },
   loadSnapshot: LoadSnapshotFn,
 ): Promise<BackendResult<PollLeaseResult>> {
@@ -391,6 +434,28 @@ async function finalizePollKnots(
     agentInfo: input.agentInfo,
     knotsLeaseId,
   });
+  void logLeaseAudit({
+    event: "prompt_delivered",
+    repoPath: input.repoPath,
+    executionLeaseId,
+    knotsLeaseId,
+    beatId: pollData.id,
+    claimedId: pollData.id,
+    interactionType: "poll",
+    agentName: input.agentInfo?.agentName,
+    agentModel: input.agentInfo?.agentModel,
+    agentVersion: input.agentInfo?.agentVersion,
+    outcome: "success",
+    message:
+      `Poll prompt includes lease ` +
+      `${knotsLeaseId} for ${pollData.id}.`,
+    data: {
+      source: "structured_prepare_poll",
+      promptLength: pollData.prompt.length,
+      hasLeaseInPrompt:
+        pollData.prompt.includes("--lease"),
+    },
+  });
   return ok({ lease, claimedId: pollData.id });
 }