@basou/core 0.9.0 → 0.10.0

package/dist/index.js

@@ -767,7 +767,7 @@ function isLazyExpired(approval, now) {
 
 // src/decisions/decisions-renderer.ts
 import { lstat } from "fs/promises";
-import { dirname, join as join4, resolve } from "path";
+import { dirname as dirname2, join as join6, resolve } from "path";
 
 // src/events/event-replay.ts
 import { createReadStream } from "fs";
@@ -1013,7 +1013,208 @@ async function readAllEvents(sessionDir, options = {}) {
 
 // src/storage/sessions.ts
 import { readdir as readdir2 } from "fs/promises";
-import { join as join3 } from "path";
+import { join as join5 } from "path";
+
+// src/events/chained-append.ts
+import { appendFile, readFile as readFile3 } from "fs/promises";
+import { join as join4 } from "path";
+
+// src/storage/lockfile.ts
+import { mkdir, readFile as readFile2, unlink as unlink2 } from "fs/promises";
+import { dirname, join as join3 } from "path";
+var STALE_LOCK_MAX_AGE_MS = 60 * 60 * 1e3;
+async function acquireLock(paths, scope, resourceId) {
+  const lockPath = lockfilePath(paths, scope, resourceId);
+  const body = {
+    pid: process.pid,
+    acquired_at: (/* @__PURE__ */ new Date()).toISOString()
+  };
+  const serialised = JSON.stringify(body);
+  try {
+    await atomicCreate(lockPath, serialised);
+  } catch (error) {
+    if (findErrorCode(error, "ENOENT")) {
+      try {
+        await mkdir(dirname(lockPath), { recursive: true });
+        await atomicCreate(lockPath, serialised);
+        return {
+          release: async () => {
+            await unlink2(lockPath).catch(() => void 0);
+          }
+        };
+      } catch (retryError) {
+        throw new Error("Failed to acquire lock", { cause: retryError });
+      }
+    }
+    if (!findErrorCode(error, "EEXIST")) {
+      throw error;
+    }
+    const stale = await isStaleLock(lockPath);
+    if (!stale) {
+      throw new Error("Lock is held by another process", { cause: error });
+    }
+    await unlink2(lockPath).catch(() => void 0);
+    try {
+      await atomicCreate(lockPath, serialised);
+    } catch (retryError) {
+      throw new Error("Lock is held by another process", { cause: retryError });
+    }
+  }
+  return {
+    release: async () => {
+      await unlink2(lockPath).catch(() => void 0);
+    }
+  };
+}
+async function isStaleLock(lockPath) {
+  let body;
+  try {
+    const raw = await readFile2(lockPath, "utf8");
+    const parsed = JSON.parse(raw);
+    if (typeof parsed !== "object" || parsed === null) return true;
+    const candidate = parsed;
+    if (typeof candidate.pid !== "number" || typeof candidate.acquired_at !== "string") {
+      return true;
+    }
+    body = { pid: candidate.pid, acquired_at: candidate.acquired_at };
+  } catch {
+    return true;
+  }
+  const ageMs = Date.now() - Date.parse(body.acquired_at);
+  if (!Number.isFinite(ageMs) || ageMs > STALE_LOCK_MAX_AGE_MS) {
+    return true;
+  }
+  try {
+    process.kill(body.pid, 0);
+    return false;
+  } catch (error) {
+    if (findErrorCode(error, "ESRCH")) return true;
+    return false;
+  }
+}
+function lockfilePath(paths, scope, resourceId) {
+  const sep = resourceId.indexOf("_");
+  const ulid2 = sep >= 0 ? resourceId.slice(sep + 1) : resourceId;
+  return join3(paths.locks, `${scope}_${ulid2}.lock`);
+}
+
+// src/events/chain.ts
+import { createHash } from "crypto";
+var GENESIS_PREFIX = "basou:event-chain:v1:";
+function genesisHash(sessionId) {
+  return createHash("sha256").update(`${GENESIS_PREFIX}${sessionId}`, "utf8").digest("hex");
+}
+function lineHash(rawLine) {
+  const hash = createHash("sha256");
+  if (typeof rawLine === "string") {
+    hash.update(rawLine, "utf8");
+  } else {
+    hash.update(rawLine);
+  }
+  return hash.digest("hex");
+}
+function serializeEventLine(event) {
+  return JSON.stringify(event);
+}
+function chainEvents(events, sessionId) {
+  let prev = genesisHash(sessionId);
+  const lines = [];
+  for (const event of events) {
+    const chained = { ...event, prev_hash: prev };
+    const line = serializeEventLine(chained);
+    lines.push(line);
+    prev = lineHash(line);
+  }
+  return { lines, headHash: prev, count: lines.length };
+}
+function chainRawJsonLines(rawLines, sessionId) {
+  let prev = genesisHash(sessionId);
+  const lines = [];
+  for (const rawLine of rawLines) {
+    const parsed = JSON.parse(rawLine);
+    const line = JSON.stringify({ ...parsed, prev_hash: prev });
+    lines.push(line);
+    prev = lineHash(line);
+  }
+  return { lines, headHash: prev, count: lines.length };
+}
+
+// src/events/chained-append.ts
+function splitLinesBytes(buf) {
+  const out = [];
+  let start = 0;
+  for (let i = 0; i < buf.length; i++) {
+    if (buf[i] === 10) {
+      out.push(buf.subarray(start, i));
+      start = i + 1;
+    }
+  }
+  if (start < buf.length) out.push(buf.subarray(start));
+  return out;
+}
+function carriesPrevHash(line) {
+  try {
+    const obj = JSON.parse(line.toString("utf8"));
+    return typeof obj === "object" && obj !== null && "prev_hash" in obj;
+  } catch {
+    return false;
+  }
+}
+async function inspectChainTail(paths, sessionId) {
+  const filePath = join4(paths.sessions, sessionId, "events.jsonl");
+  let raw;
+  try {
+    raw = await readFile3(filePath);
+  } catch (error) {
+    if (findErrorCode(error, "ENOENT")) {
+      return { chained: true, head: genesisHash(sessionId), count: 0 };
+    }
+    throw new Error("Failed to read events.jsonl", { cause: error });
+  }
+  if (raw.length === 0) {
+    return { chained: true, head: genesisHash(sessionId), count: 0 };
+  }
+  if (raw[raw.length - 1] !== 10) {
+    throw new Error("Unterminated final line in events.jsonl");
+  }
+  const lines = splitLinesBytes(raw);
+  const first = lines[0];
+  const last = lines[lines.length - 1];
+  const firstChained = carriesPrevHash(first);
+  if (firstChained !== carriesPrevHash(last)) {
+    throw new Error("events.jsonl is partially chained");
+  }
+  return {
+    chained: firstChained,
+    head: firstChained ? lineHash(last) : genesisHash(sessionId),
+    count: lines.length
+  };
+}
+async function appendChainedEventLocked(paths, sessionId, event) {
+  let validated;
+  try {
+    validated = EventSchema.parse(event);
+  } catch (error) {
+    throw new Error("Invalid Basou event payload", { cause: error });
+  }
+  const tail = await inspectChainTail(paths, sessionId);
+  const line = tail.chained ? serializeEventLine({ ...validated, prev_hash: tail.head }) : serializeEventLine(validated);
+  try {
+    await appendFile(join4(paths.sessions, sessionId, "events.jsonl"), `${line}
+`, "utf8");
+  } catch (error) {
+    throw new Error("Failed to append event to events.jsonl", { cause: error });
+  }
+  return { chained: tail.chained };
+}
+async function appendChainedEvent(paths, sessionId, event) {
+  const lock = await acquireLock(paths, "session", sessionId);
+  try {
+    return await appendChainedEventLocked(paths, sessionId, event);
+  } finally {
+    await lock.release();
+  }
+}
 
 // src/schemas/session.schema.ts
 import { z as z4 } from "zod";
@@ -1108,7 +1309,7 @@ async function enumerateSessionDirs(paths) {
   }
 }
 async function readSessionYaml(paths, sessionId) {
-  const filePath = join3(paths.sessions, sessionId, "session.yaml");
+  const filePath = join5(paths.sessions, sessionId, "session.yaml");
   let raw;
   try {
     raw = await readYamlFile(filePath);
@@ -1122,11 +1323,26 @@ async function readSessionYaml(paths, sessionId) {
   }
   return result.data;
 }
+async function finalizeSessionYaml(paths, sessionId, mutate) {
+  const lock = await acquireLock(paths, "session", sessionId);
+  try {
+    const session = await readSessionYaml(paths, sessionId);
+    mutate(session);
+    const tail = await inspectChainTail(paths, sessionId);
+    if (tail.chained && tail.count > 0) {
+      session.session.integrity = { head_hash: tail.head, event_count: tail.count };
+    }
+    const validated = SessionSchema.parse(session);
+    await overwriteYamlFile(join5(paths.sessions, sessionId, "session.yaml"), validated);
+  } finally {
+    await lock.release();
+  }
+}
 async function classifySuspect(paths, sessionId, session, now, onWarning) {
   if (session.session.status !== "running") {
     return { suspect: false, suspectReason: null };
   }
-  const sessionDir = join3(paths.sessions, sessionId);
+  const sessionDir = join5(paths.sessions, sessionId);
   let endedFound = false;
   let lastEventOccurredAt = null;
   const replayOpts = onWarning !== void 0 ? { onWarning } : {};
@@ -1194,7 +1410,7 @@ async function renderDecisions(input) {
   const decisions = [];
   const knownEventIds = /* @__PURE__ */ new Set();
   for (const entry of entries) {
-    const sessionDir = join4(input.paths.sessions, entry.sessionId);
+    const sessionDir = join6(input.paths.sessions, entry.sessionId);
     try {
       for await (const ev of replayEvents(sessionDir, {
         onWarning: (w) => input.onWarning?.(w, entry.sessionId)
@@ -1224,7 +1440,7 @@ async function renderDecisions(input) {
     const c = Date.parse(a.occurredAt) - Date.parse(b.occurredAt);
     return c !== 0 ? c : a.decisionId.localeCompare(b.decisionId);
   });
-  const repoRoot = dirname(input.paths.root);
+  const repoRoot = dirname2(input.paths.root);
   const fileExistenceCache = /* @__PURE__ */ new Map();
   async function fileExists(relPath) {
     const cached = fileExistenceCache.get(relPath);
@@ -1298,50 +1514,9 @@ function shortDecisionSessionId(sessionId) {
   return sessionId.slice(0, 10);
 }
 
-// src/events/chain.ts
-import { createHash } from "crypto";
-var GENESIS_PREFIX = "basou:event-chain:v1:";
-function genesisHash(sessionId) {
-  return createHash("sha256").update(`${GENESIS_PREFIX}${sessionId}`, "utf8").digest("hex");
-}
-function lineHash(rawLine) {
-  const hash = createHash("sha256");
-  if (typeof rawLine === "string") {
-    hash.update(rawLine, "utf8");
-  } else {
-    hash.update(rawLine);
-  }
-  return hash.digest("hex");
-}
-function serializeEventLine(event) {
-  return JSON.stringify(event);
-}
-function chainEvents(events, sessionId) {
-  let prev = genesisHash(sessionId);
-  const lines = [];
-  for (const event of events) {
-    const chained = { ...event, prev_hash: prev };
-    const line = serializeEventLine(chained);
-    lines.push(line);
-    prev = lineHash(line);
-  }
-  return { lines, headHash: prev, count: lines.length };
-}
-function chainRawJsonLines(rawLines, sessionId) {
-  let prev = genesisHash(sessionId);
-  const lines = [];
-  for (const rawLine of rawLines) {
-    const parsed = JSON.parse(rawLine);
-    const line = JSON.stringify({ ...parsed, prev_hash: prev });
-    lines.push(line);
-    prev = lineHash(line);
-  }
-  return { lines, headHash: prev, count: lines.length };
-}
-
 // src/events/event-writer.ts
-import { appendFile } from "fs/promises";
-import { basename, join as join5 } from "path";
+import { appendFile as appendFile2 } from "fs/promises";
+import { basename, join as join7 } from "path";
 async function appendEvent(sessionDir, event) {
   let validated;
   try {
@@ -1352,7 +1527,7 @@ async function appendEvent(sessionDir, event) {
   const line = `${serializeEventLine(validated)}
 `;
   try {
-    await appendFile(join5(sessionDir, "events.jsonl"), line, "utf8");
+    await appendFile2(join7(sessionDir, "events.jsonl"), line, "utf8");
   } catch (error) {
     throw new Error("Failed to append event to events.jsonl", { cause: error });
   }
@@ -1366,7 +1541,7 @@ async function writeEventsBulk(sessionDir, events, options = {}) {
   } catch (error) {
     throw new Error("Invalid Basou event payload", { cause: error });
   }
-  const filePath = join5(sessionDir, "events.jsonl");
+  const filePath = join7(sessionDir, "events.jsonl");
   let body;
   let result = null;
   if (options.chain === true) {
@@ -1387,13 +1562,30 @@ async function writeEventsBulk(sessionDir, events, options = {}) {
 }
 
 // src/events/verify.ts
-import { readFile as readFile2 } from "fs/promises";
-import { join as join6 } from "path";
+import { readFile as readFile4 } from "fs/promises";
+import { join as join8 } from "path";
+var STRICT_STATUSES = /* @__PURE__ */ new Set([
+  "completed",
+  "failed",
+  "interrupted",
+  "imported",
+  "archived"
+]);
+function isLiveStatus(status) {
+  return !STRICT_STATUSES.has(status);
+}
 async function verifyEventsChain(paths, sessionId) {
-  const sessionDir = join6(paths.sessions, sessionId);
+  const first = await verifyOnce(paths, sessionId);
+  if (first.status === "tampered" && first.reason === "anchor_mismatch") {
+    return await verifyOnce(paths, sessionId);
+  }
+  return first;
+}
+async function verifyOnce(paths, sessionId) {
+  const sessionDir = join8(paths.sessions, sessionId);
   let raw = null;
   try {
-    raw = await readFile2(join6(sessionDir, "events.jsonl"));
+    raw = await readFile4(join8(sessionDir, "events.jsonl"));
   } catch (error) {
     if (!findErrorCode(error, "ENOENT")) {
       throw new Error("Failed to read events.jsonl", { cause: error });
@@ -1402,7 +1594,11 @@ async function verifyEventsChain(paths, sessionId) {
   let anchor;
   try {
     const session = await readSessionYaml(paths, sessionId);
-    anchor = { kind: "present", integrity: session.session.integrity };
+    anchor = {
+      kind: "present",
+      integrity: session.session.integrity,
+      status: session.session.status
+    };
   } catch (error) {
     if (error instanceof Error && error.message === "YAML file not found") {
       anchor = { kind: "absent" };
@@ -1411,10 +1607,10 @@ async function verifyEventsChain(paths, sessionId) {
     }
   }
   const terminated = raw === null || raw.length === 0 || raw[raw.length - 1] === 10;
-  const segments = raw === null ? [] : splitLinesBytes(raw);
+  const segments = raw === null ? [] : splitLinesBytes2(raw);
   const tailFragment = !terminated && segments.length > 0 ? segments.pop() : null;
   const lines = segments;
-  const carriesPrevHash = (s) => {
+  const carriesPrevHash2 = (s) => {
     try {
       const obj = JSON.parse(s.toString("utf8"));
       return typeof obj === "object" && obj !== null && "prev_hash" in obj;
@@ -1422,7 +1618,7 @@ async function verifyEventsChain(paths, sessionId) {
       return false;
     }
   };
-  const chained = lines.some((l) => l.length > 0 && carriesPrevHash(l)) || tailFragment !== null && carriesPrevHash(tailFragment);
+  const chained = lines.some((l) => l.length > 0 && carriesPrevHash2(l)) || tailFragment !== null && carriesPrevHash2(tailFragment);
   if (!chained) {
     if (anchor.kind === "present" && anchor.integrity !== void 0) {
       return {
@@ -1481,7 +1677,11 @@ async function verifyEventsChain(paths, sessionId) {
     }
     expected = lineHash(line);
   }
+  const live = anchor.kind === "present" && isLiveStatus(anchor.status);
   if (tailFragment !== null || !terminated) {
+    if (live) {
+      return { status: "in_progress", eventCount: lines.length };
+    }
     return {
       status: "tampered",
       eventCount: lines.length,
@@ -1495,6 +1695,9 @@ async function verifyEventsChain(paths, sessionId) {
   if (anchor.kind === "unreadable") {
     return { status: "tampered", eventCount: lines.length, reason: "yaml_unreadable" };
   }
+  if (live) {
+    return { status: "in_progress", eventCount: lines.length };
+  }
   if (anchor.integrity === void 0) {
     return { status: "tampered", eventCount: lines.length, reason: "anchor_missing" };
   }
@@ -1503,7 +1706,7 @@ async function verifyEventsChain(paths, sessionId) {
   }
   return { status: "verified", eventCount: lines.length };
 }
-function splitLinesBytes(buf) {
+function splitLinesBytes2(buf) {
   const out = [];
   let start = 0;
   for (let i = 0; i < buf.length; i++) {
@@ -1810,12 +2013,12 @@ function parseDiffNameStatus(raw) {
 }
 
 // src/handoff/handoff-renderer.ts
-import { join as join11 } from "path";
+import { join as join12 } from "path";
 
 // src/storage/tasks.ts
 import { createHash as createHash2 } from "crypto";
-import { mkdir as mkdir3, readdir as readdir3, readFile as readFile6, rename as rename2, stat as stat2, unlink as unlink3 } from "fs/promises";
-import { join as join10 } from "path";
+import { mkdir as mkdir3, readdir as readdir3, readFile as readFile7, rename as rename2, stat as stat2, unlink as unlink3 } from "fs/promises";
+import { join as join11 } from "path";
 import { parse as parseYaml, stringify as stringifyYaml } from "yaml";
 import { z as z8 } from "zod";
 
@@ -1857,9 +2060,9 @@ var TaskSchema = z6.object({
 });
 
 // src/storage/ad-hoc-session.ts
-import { mkdir, rm } from "fs/promises";
+import { mkdir as mkdir2, rm } from "fs/promises";
 import { homedir } from "os";
-import { join as join7 } from "path";
+import { join as join9 } from "path";
 
 // src/lib/path-sanitizer.ts
 import { posix as path } from "path";
@@ -1939,87 +2142,94 @@ async function createAdHocSessionWithEvent(input) {
       taskId: input.taskId ?? null
     })
   );
-  const sessionDir = join7(input.paths.sessions, sessionId);
-  try {
-    await mkdir(sessionDir, { recursive: true });
-  } catch (error) {
-    throw new Error("Failed to create session directory", { cause: error });
-  }
-  const sessionYamlPath = join7(sessionDir, "session.yaml");
+  const sessionDir = join9(input.paths.sessions, sessionId);
+  const sessionYamlPath = join9(sessionDir, "session.yaml");
+  const lock = await acquireLock(input.paths, "session", sessionId);
+  let bulkResult = null;
   try {
-    await linkYamlFile(sessionYamlPath, initialSession);
-  } catch (error) {
-    await rm(sessionDir, { recursive: true, force: true }).catch(() => void 0);
-    if (findErrorCode(error, "EEXIST")) {
-      throw new Error("Session directory collision (retry the command)", {
-        cause: error
-      });
+    try {
+      await mkdir2(sessionDir, { recursive: true });
+    } catch (error) {
+      throw new Error("Failed to create session directory", { cause: error });
     }
-    throw error;
-  }
-  try {
-    const targetEvents = input.targetEventBuilders.map((build, index) => {
-      const targetEventId = targetEventIds[index];
-      return assertTargetEventIdentity(build(sessionId, targetEventId), sessionId, targetEventId);
-    });
-    const events = [
-      {
-        schema_version: "0.1.0",
-        id: startedEventId,
-        session_id: sessionId,
-        occurred_at: input.occurredAt,
-        source: "local-cli",
-        type: "session_started"
-      },
-      {
-        schema_version: "0.1.0",
-        id: statusToRunningEventId,
-        session_id: sessionId,
-        occurred_at: input.occurredAt,
-        source: "local-cli",
-        type: "session_status_changed",
-        from: "initialized",
-        to: "running"
-      },
-      ...targetEvents,
-      {
-        schema_version: "0.1.0",
-        id: statusToCompletedEventId,
-        session_id: sessionId,
-        occurred_at: input.occurredAt,
-        source: "local-cli",
-        type: "session_status_changed",
-        from: "running",
-        to: "completed"
-      },
-      {
-        schema_version: "0.1.0",
-        id: endedEventId,
-        session_id: sessionId,
-        occurred_at: input.occurredAt,
-        source: "local-cli",
-        type: "session_ended",
-        exit_code: 0
-      }
-    ];
-    await writeEventsBulk(sessionDir, events);
-  } catch (error) {
-    await rm(sessionDir, { recursive: true, force: true }).catch(() => void 0);
-    throw error;
-  }
-  try {
-    const finalSession = SessionSchema.parse({
-      ...initialSession,
-      session: {
-        ...initialSession.session,
-        status: "completed",
-        ended_at: input.occurredAt,
-        invocation: { ...initialSession.session.invocation, exit_code: 0 }
+    try {
+      await linkYamlFile(sessionYamlPath, initialSession);
+    } catch (error) {
+      await rm(sessionDir, { recursive: true, force: true }).catch(() => void 0);
+      if (findErrorCode(error, "EEXIST")) {
+        throw new Error("Session directory collision (retry the command)", {
+          cause: error
+        });
       }
-    });
-    await overwriteYamlFile(sessionYamlPath, finalSession);
-  } catch (error) {
-    throw new FailedToFinalizeError(sessionId, targetEventIds, error);
+      throw error;
+    }
+    try {
+      const targetEvents = input.targetEventBuilders.map((build, index) => {
+        const targetEventId = targetEventIds[index];
+        return assertTargetEventIdentity(build(sessionId, targetEventId), sessionId, targetEventId);
+      });
+      const events = [
+        {
+          schema_version: "0.1.0",
+          id: startedEventId,
+          session_id: sessionId,
+          occurred_at: input.occurredAt,
+          source: "local-cli",
+          type: "session_started"
+        },
+        {
+          schema_version: "0.1.0",
+          id: statusToRunningEventId,
+          session_id: sessionId,
+          occurred_at: input.occurredAt,
+          source: "local-cli",
+          type: "session_status_changed",
+          from: "initialized",
+          to: "running"
+        },
+        ...targetEvents,
+        {
+          schema_version: "0.1.0",
+          id: statusToCompletedEventId,
+          session_id: sessionId,
+          occurred_at: input.occurredAt,
+          source: "local-cli",
+          type: "session_status_changed",
+          from: "running",
+          to: "completed"
+        },
+        {
+          schema_version: "0.1.0",
+          id: endedEventId,
+          session_id: sessionId,
+          occurred_at: input.occurredAt,
+          source: "local-cli",
+          type: "session_ended",
+          exit_code: 0
+        }
+      ];
+      bulkResult = await writeEventsBulk(sessionDir, events, { chain: true });
+    } catch (error) {
+      await rm(sessionDir, { recursive: true, force: true }).catch(() => void 0);
+      throw error;
+    }
+    try {
+      const finalSession = SessionSchema.parse({
+        ...initialSession,
+        session: {
+          ...initialSession.session,
+          status: "completed",
+          ended_at: input.occurredAt,
+          invocation: { ...initialSession.session.invocation, exit_code: 0 },
+          ...bulkResult !== null ? { integrity: { head_hash: bulkResult.headHash, event_count: bulkResult.count } } : {}
+        }
+      });
+      await overwriteYamlFile(sessionYamlPath, finalSession);
+    } catch (error) {
+      throw new FailedToFinalizeError(sessionId, targetEventIds, error);
+    }
+  } finally {
+    await lock.release();
   }
   return {
     sessionId,
@@ -2068,8 +2278,7 @@ async function appendEventToExistingSession(input) {
   }
   const eventId = prefixedUlid("evt");
   const event = assertTargetEventIdentity(input.eventBuilder(eventId), input.sessionId, eventId);
-  const sessionDir = join7(input.paths.sessions, input.sessionId);
-  await appendEvent(sessionDir, event);
+  await appendChainedEventLocked(input.paths, input.sessionId, event);
   return { eventId, sessionStatus: status };
 }
 function assertTargetEventIdentity(event, expectedSessionId, expectedEventId) {
@@ -2082,88 +2291,9 @@ function assertTargetEventIdentity(event, expectedSessionId, expectedEventId) {
   return event;
 }
 
-// src/storage/lockfile.ts
-import { mkdir as mkdir2, readFile as readFile4, unlink as unlink2 } from "fs/promises";
-import { dirname as dirname2, join as join8 } from "path";
-var STALE_LOCK_MAX_AGE_MS = 60 * 60 * 1e3;
-async function acquireLock(paths, scope, resourceId) {
-  const lockPath = lockfilePath(paths, scope, resourceId);
-  const body = {
-    pid: process.pid,
-    acquired_at: (/* @__PURE__ */ new Date()).toISOString()
-  };
-  const serialised = JSON.stringify(body);
-  try {
-    await atomicCreate(lockPath, serialised);
-  } catch (error) {
-    if (findErrorCode(error, "ENOENT")) {
-      try {
-        await mkdir2(dirname2(lockPath), { recursive: true });
-        await atomicCreate(lockPath, serialised);
-        return {
-          release: async () => {
-            await unlink2(lockPath).catch(() => void 0);
-          }
-        };
-      } catch (retryError) {
-        throw new Error("Failed to acquire lock", { cause: retryError });
-      }
-    }
-    if (!findErrorCode(error, "EEXIST")) {
-      throw error;
-    }
-    const stale = await isStaleLock(lockPath);
-    if (!stale) {
-      throw new Error("Lock is held by another process", { cause: error });
-    }
-    await unlink2(lockPath).catch(() => void 0);
-    try {
-      await atomicCreate(lockPath, serialised);
-    } catch (retryError) {
-      throw new Error("Lock is held by another process", { cause: retryError });
-    }
-  }
-  return {
-    release: async () => {
-      await unlink2(lockPath).catch(() => void 0);
-    }
-  };
-}
-async function isStaleLock(lockPath) {
-  let body;
-  try {
-    const raw = await readFile4(lockPath, "utf8");
-    const parsed = JSON.parse(raw);
-    if (typeof parsed !== "object" || parsed === null) return true;
-    const candidate = parsed;
-    if (typeof candidate.pid !== "number" || typeof candidate.acquired_at !== "string") {
-      return true;
-    }
-    body = { pid: candidate.pid, acquired_at: candidate.acquired_at };
-  } catch {
-    return true;
-  }
-  const ageMs = Date.now() - Date.parse(body.acquired_at);
-  if (!Number.isFinite(ageMs) || ageMs > STALE_LOCK_MAX_AGE_MS) {
-    return true;
-  }
-  try {
-    process.kill(body.pid, 0);
-    return false;
-  } catch (error) {
-    if (findErrorCode(error, "ESRCH")) return true;
-    return false;
-  }
-}
-function lockfilePath(paths, scope, resourceId) {
-  const sep = resourceId.indexOf("_");
-  const ulid2 = sep >= 0 ? resourceId.slice(sep + 1) : resourceId;
-  return join8(paths.locks, `${scope}_${ulid2}.lock`);
-}
-
 // src/storage/task-index.ts
-import { readFile as readFile5 } from "fs/promises";
-import { join as join9 } from "path";
+import { readFile as readFile6 } from "fs/promises";
+import { join as join10 } from "path";
 
 // src/schemas/task-index.schema.ts
 import { z as z7 } from "zod";
@@ -2182,13 +2312,13 @@ var TASK_INDEX_SCHEMA_VERSION = "0.1.0";
 
 // src/storage/task-index.ts
 function taskIndexPath(paths) {
-  return join9(paths.tasks, "index.json");
+  return join10(paths.tasks, "index.json");
 }
 async function readTaskIndex(paths) {
   const filePath = taskIndexPath(paths);
   let raw;
   try {
-    raw = await readFile5(filePath, "utf8");
+    raw = await readFile6(filePath, "utf8");
   } catch (error) {
     if (findErrorCode(error, "ENOENT")) {
       throw new Error("Task index not found", { cause: error });
@@ -2296,10 +2426,10 @@ function splitFrontMatter(raw) {
   return { yamlText, body };
 }
 async function readTaskFile(paths, taskId) {
-  const filePath = join10(paths.tasks, `${taskId}.md`);
+  const filePath = join11(paths.tasks, `${taskId}.md`);
   let raw;
   try {
-    raw = await readFile6(filePath, "utf8");
+    raw = await readFile7(filePath, "utf8");
   } catch (error) {
     if (findErrorCode(error, "ENOENT")) {
       throw new Error("Task file not found", { cause: error });
@@ -2329,7 +2459,7 @@ async function readTaskFile(paths, taskId) {
 }
 async function writeTaskFile(paths, taskId, doc, options) {
   const validated = TaskSchema.parse(doc.task);
-  const filePath = join10(paths.tasks, `${taskId}.md`);
+  const filePath = join11(paths.tasks, `${taskId}.md`);
   const yamlText = stringifyYaml(validated);
   const trimmedBody = doc.body.length === 0 ? "" : `
 ${doc.body.endsWith("\n") ? doc.body : `${doc.body}
@@ -2414,7 +2544,7 @@ async function safeUpdateTaskIndex(paths, op) {
 }
 var ARCHIVE_DIR_NAME = "archive";
 function archiveTasksDir(paths) {
-  return join10(paths.tasks, ARCHIVE_DIR_NAME);
+  return join11(paths.tasks, ARCHIVE_DIR_NAME);
 }
 async function enumerateArchivedTaskIds(paths) {
   let entries;
@@ -2444,10 +2574,10 @@ async function readTaskFileWithArchiveFallback(paths, taskId) {
       throw error;
     }
   }
-  const archiveFilePath = join10(archiveTasksDir(paths), `${taskId}.md`);
+  const archiveFilePath = join11(archiveTasksDir(paths), `${taskId}.md`);
   let raw;
   try {
-    raw = await readFile6(archiveFilePath, "utf8");
+    raw = await readFile7(archiveFilePath, "utf8");
   } catch (error) {
     if (findErrorCode(error, "ENOENT")) {
       throw new Error("Task file not found", { cause: error });
@@ -2738,7 +2868,7 @@ async function createTaskAttachLocked(input) {
       ...sessionDoc,
       session: { ...sessionDoc.session, task_id: input.taskId }
     };
-    await overwriteYamlFile(join10(input.paths.sessions, input.sessionId, "session.yaml"), updated);
+    await overwriteYamlFile(join11(input.paths.sessions, input.sessionId, "session.yaml"), updated);
   } catch (error) {
     throw new TaskWriteAfterEventError({
       taskId: input.taskId,
@@ -2997,17 +3127,17 @@ function buildUpdatedDoc(input) {
   return { task: next, body: input.currentDoc.body };
 }
 async function computeTaskMdSnapshot(paths, taskId) {
-  const filePath = join10(paths.tasks, `${taskId}.md`);
-  const [stats, raw] = await Promise.all([stat2(filePath), readFile6(filePath)]);
+  const filePath = join11(paths.tasks, `${taskId}.md`);
+  const [stats, raw] = await Promise.all([stat2(filePath), readFile7(filePath)]);
   const hash = createHash2("sha256").update(raw).digest("hex");
   return { mtimeMs: stats.mtimeMs, hash };
 }
 async function readTaskFileWithSnapshot(paths, taskId) {
-  const filePath = join10(paths.tasks, `${taskId}.md`);
+  const filePath = join11(paths.tasks, `${taskId}.md`);
   let rawBuffer;
   let stats;
   try {
-    [rawBuffer, stats] = await Promise.all([readFile6(filePath), stat2(filePath)]);
+    [rawBuffer, stats] = await Promise.all([readFile7(filePath), stat2(filePath)]);
   } catch (error) {
     if (findErrorCode(error, "ENOENT")) {
       throw new Error("Task file not found", { cause: error });
@@ -3495,7 +3625,7 @@ async function deleteTaskLocked(input) {
   });
   const eventId = adHoc.targetEventIds[0];
   try {
-    await unlink3(join10(input.paths.tasks, `${input.taskId}.md`));
+    await unlink3(join11(input.paths.tasks, `${input.taskId}.md`));
   } catch (error) {
     throw new TaskWriteAfterEventError({
       taskId: input.taskId,
@@ -3567,8 +3697,8 @@ async function archiveTaskLocked(input) {
     );
     await mkdir3(archiveTasksDir(input.paths), { recursive: true });
     await rename2(
-      join10(input.paths.tasks, `${input.taskId}.md`),
-      join10(archiveTasksDir(input.paths), `${input.taskId}.md`)
+      join11(input.paths.tasks, `${input.taskId}.md`),
+      join11(archiveTasksDir(input.paths), `${input.taskId}.md`)
     );
   } catch (error) {
     throw new TaskWriteAfterEventError({
@@ -3604,7 +3734,7 @@ async function renderHandoff(input) {
   const tasksCreated = [];
   const tasksStatusChanged = [];
   for (const entry of entries) {
-    const sessionDir = join11(input.paths.sessions, entry.sessionId);
+    const sessionDir = join12(input.paths.sessions, entry.sessionId);
     try {
       for await (const ev of replayEvents(sessionDir, {
         onWarning: (w) => input.onWarning?.(w, entry.sessionId)
@@ -4245,7 +4375,7 @@ function serializeJsonSchema(schema) {
 }
 
 // src/stats/work-stats.ts
-import { join as join12 } from "path";
+import { join as join13 } from "path";
 function resolveTimeZone(timeZone) {
   if (timeZone !== void 0 && timeZone.length > 0) return timeZone;
   return Intl.DateTimeFormat().resolvedOptions().timeZone;
@@ -4276,7 +4406,7 @@ async function computeWorkStats(input) {
     const events = [];
     let eventsUnreadable = false;
     try {
-      for await (const ev of replayEvents(join12(input.paths.sessions, entry.sessionId), {
+      for await (const ev of replayEvents(join13(input.paths.sessions, entry.sessionId), {
         onWarning: (w) => input.onWarning?.(w, entry.sessionId)
       })) {
         events.push(ev);
@@ -4532,27 +4662,27 @@ function tzDate(ms, timeZone) {
 
 // src/storage/basou-dir.ts
 import { lstat as lstat3, mkdir as mkdir4 } from "fs/promises";
-import { join as join13 } from "path";
+import { join as join14 } from "path";
 function basouPaths(repositoryRoot) {
-  const root = join13(repositoryRoot, ".basou");
-  const approvalsBase = join13(root, "approvals");
+  const root = join14(repositoryRoot, ".basou");
+  const approvalsBase = join14(root, "approvals");
   return {
     root,
-    sessions: join13(root, "sessions"),
-    tasks: join13(root, "tasks"),
+    sessions: join14(root, "sessions"),
+    tasks: join14(root, "tasks"),
     approvals: {
-      pending: join13(approvalsBase, "pending"),
-      resolved: join13(approvalsBase, "resolved")
+      pending: join14(approvalsBase, "pending"),
+      resolved: join14(approvalsBase, "resolved")
     },
-    locks: join13(root, "locks"),
-    logs: join13(root, "logs"),
-    raw: join13(root, "raw"),
-    tmp: join13(root, "tmp"),
+    locks: join14(root, "locks"),
+    logs: join14(root, "logs"),
+    raw: join14(root, "raw"),
+    tmp: join14(root, "tmp"),
     files: {
-      manifest: join13(root, "manifest.yaml"),
-      status: join13(root, "status.json"),
-      handoff: join13(root, "handoff.md"),
-      decisions: join13(root, "decisions.md")
+      manifest: join14(root, "manifest.yaml"),
+      status: join14(root, "status.json"),
+      handoff: join14(root, "handoff.md"),
+      decisions: join14(root, "decisions.md")
     }
   };
 }
@@ -4608,16 +4738,16 @@ function hasErrorCode3(error) {
 }
 
 // src/storage/gitignore.ts
-import { readFile as readFile7, writeFile as writeFile2 } from "fs/promises";
-import { join as join14 } from "path";
+import { readFile as readFile8, writeFile as writeFile2 } from "fs/promises";
+import { join as join15 } from "path";
 var MARKER = "# Basou - default ignore";
 var BASOU_GITIGNORE_BLOCK = "# Basou - default ignore\n.basou/logs/\n.basou/raw/\n.basou/tmp/\n.basou/locks/\n.basou/status.json\n.basou/sessions/*/events.jsonl\n.basou/sessions/*/artifacts/\n.basou/approvals/pending/\n.basou/approvals/resolved/\n\n# Basou - default commit\n# .basou/manifest.yaml\n# .basou/handoff.md\n# .basou/decisions.md\n# .basou/tasks/\n# .basou/sessions/*/session.yaml\n# .basou/sessions/*/transcript.md\n# .basou/sessions/*/changed-files.json\n";
 async function appendBasouGitignore(repositoryRoot) {
-  const gitignorePath = join14(repositoryRoot, ".gitignore");
+  const gitignorePath = join15(repositoryRoot, ".gitignore");
   let body;
   let existed;
   try {
-    body = await readFile7(gitignorePath, "utf8");
+    body = await readFile8(gitignorePath, "utf8");
     existed = true;
   } catch (error) {
     if (hasErrorCode4(error) && error.code === "ENOENT") {
@@ -4723,12 +4853,12 @@ function hasErrorCode5(error) {
 }
 
 // src/storage/markdown-store.ts
-import { readFile as readFile8 } from "fs/promises";
+import { readFile as readFile9 } from "fs/promises";
 var GENERATED_START = "<!-- BASOU:GENERATED:START -->";
 var GENERATED_END = "<!-- BASOU:GENERATED:END -->";
 async function readMarkdownFile(filePath) {
   try {
-    return await readFile8(filePath, "utf8");
+    return await readFile9(filePath, "utf8");
   } catch (error) {
     if (hasErrorCode6(error) && error.code === "ENOENT") return null;
     throw new Error("Failed to read markdown file", { cause: error });
@@ -4826,9 +4956,9 @@ function hasErrorCode6(error) {
 }
 
 // src/storage/session-import.ts
-import { mkdir as mkdir5, readFile as readFile9, rm as rm2 } from "fs/promises";
+import { mkdir as mkdir5, readFile as readFile10, rm as rm2 } from "fs/promises";
 import { homedir as homedir2 } from "os";
-import { join as join15 } from "path";
+import { join as join16 } from "path";
 async function importSessionFromJson(paths, manifest, payload, options) {
   if (options.taskIdOverride !== void 0 && !TaskIdSchema.safeParse(options.taskIdOverride).success) {
     throw new Error(`Invalid task_id: ${options.taskIdOverride}`);
@@ -4853,7 +4983,7 @@ async function importSessionFromJson(paths, manifest, payload, options) {
       pathSanitizeReport
     };
   }
-  const sessionDir = join15(paths.sessions, newSessionId);
+  const sessionDir = join16(paths.sessions, newSessionId);
   try {
     await mkdir5(sessionDir, { recursive: true });
   } catch (error) {
@@ -4867,7 +4997,7 @@ async function importSessionFromJson(paths, manifest, payload, options) {
     throw error;
   }
   try {
-    const sessionYamlPath = join15(sessionDir, "session.yaml");
+    const sessionYamlPath = join16(sessionDir, "session.yaml");
     await linkYamlFile(sessionYamlPath, withIntegrity(sessionRecord, chainResult));
   } catch (error) {
     await rm2(sessionDir, { recursive: true, force: true }).catch(() => void 0);
@@ -5035,7 +5165,7 @@ function reuseDerivedIds(priorDerived, freshDerived, sessionId) {
 async function reimportPreservingId(paths, manifest, priorSessionId, freshPayload, options = {}) {
   const sessionId = priorSessionId;
   const importSource = freshPayload.session.source.kind;
-  const sessionDir = join15(paths.sessions, priorSessionId);
+  const sessionDir = join16(paths.sessions, priorSessionId);
   const lock = options.dryRun === true ? null : await acquireLock(paths, "session", priorSessionId);
   try {
     const priorVerdict = await verifyEventsChain(paths, priorSessionId);
@@ -5077,10 +5207,10 @@ async function reimportPreservingId(paths, manifest, priorSessionId, freshPayloa
     };
     const updatedRecord = { schema_version: "0.1.0", session: preservedInner };
     if (options.dryRun !== true) {
-      const eventsPath = join15(sessionDir, "events.jsonl");
+      const eventsPath = join16(sessionDir, "events.jsonl");
       let priorEventsRaw = null;
       try {
-        priorEventsRaw = await readFile9(eventsPath);
+        priorEventsRaw = await readFile10(eventsPath);
       } catch (error) {
         if (!findErrorCode(error, "ENOENT")) {
           throw new Error("Failed to read events.jsonl", { cause: error });
@@ -5089,7 +5219,7 @@ async function reimportPreservingId(paths, manifest, priorSessionId, freshPayloa
       const chainResult = await writeEventsBulk(sessionDir, mergedEvents, { chain: true });
       try {
         await overwriteYamlFile(
-          join15(sessionDir, "session.yaml"),
+          join16(sessionDir, "session.yaml"),
           withIntegrity(updatedRecord, chainResult)
         );
       } catch (error) {
@@ -5113,7 +5243,7 @@ async function reimportPreservingId(paths, manifest, priorSessionId, freshPayloa
   }
 }
 async function rechainSessionInPlace(paths, sessionId, options = {}) {
-  const sessionDir = join15(paths.sessions, sessionId);
+  const sessionDir = join16(paths.sessions, sessionId);
   let lock;
   try {
     lock = await acquireLock(paths, "session", sessionId);
@@ -5146,10 +5276,10 @@ async function rechainSessionInPlace(paths, sessionId, options = {}) {
     if (verdict.status !== "unchained") {
       return { status: "skipped", reason: "tampered" };
     }
-    const eventsPath = join15(sessionDir, "events.jsonl");
+    const eventsPath = join16(sessionDir, "events.jsonl");
     let priorRaw;
     try {
-      priorRaw = await readFile9(eventsPath);
+      priorRaw = await readFile10(eventsPath);
     } catch (error) {
       throw new Error("Failed to read events.jsonl", { cause: error });
     }
@@ -5194,7 +5324,7 @@ async function rechainSessionInPlace(paths, sessionId, options = {}) {
     }
     try {
       await overwriteYamlFile(
-        join15(sessionDir, "session.yaml"),
+        join16(sessionDir, "session.yaml"),
         withIntegrity(record, { headHash: chainResult.headHash, count: chainResult.count })
       );
     } catch (error) {
@@ -5248,6 +5378,8 @@ export {
   WorkspaceIdSchema,
   acquireLock,
   appendBasouGitignore,
+  appendChainedEvent,
+  appendChainedEventLocked,
   appendEvent,
   appendEventToExistingSession,
   archiveTask,
@@ -5272,11 +5404,13 @@ export {
   enumerateArchivedTaskIds,
   enumerateSessionDirs,
   enumerateTaskIds,
+  finalizeSessionYaml,
   findErrorCode,
   genesisHash,
   getDiff,
   getSnapshot,
   importSessionFromJson,
+  inspectChainTail,
   isImportDerivedSource,
   isLazyExpired,
   isValidPrefixedId,