@visual-z/xeno 0.7.2 → 0.8.0

package/src/store/log.ts

@@ -26,7 +26,7 @@
  * fine and, unlike a single rollout file, nothing grows without bound.
  */
 
-import { mkdir, readdir, readFile, open } from "node:fs/promises";
+import { access, mkdir, readdir, readFile, open } from "node:fs/promises";
 import { createHash } from "node:crypto";
 import { join } from "node:path";
 import type { LogEvent, NodeRef, IsoTime, EventId } from "../core/events.ts";
@@ -37,6 +37,7 @@ import { emitHandoff } from "../core/handoff.ts";
 import { atomicWrite, durableAppend } from "./atomic.ts";
 import { serialized } from "./serial.ts";
 import { stateAtPosition } from "../core/session-position.ts";
+import { SESSION_FORMAT, SessionFormatError } from "../core/session-format.ts";
 
 /** Allocation number. Not an ordering over the tree. */
 export type NodeId = number;
@@ -502,17 +503,8 @@ export async function writeHandoff(
   return text;
 }
 
-async function readLegacyManifest(dir: string): Promise<Manifest> {
-  try {
-    return JSON.parse(await readFile(manifestPath(dir), "utf8")) as Manifest;
-  } catch (err) {
-    if ((err as { code?: string }).code === "ENOENT") return { version: 1, nodes: [] };
-    throw err;
-  }
-}
-
 type MetadataRecord =
-  | { kind: "seed"; manifest: Manifest }
+  | { kind: "format"; version: number }
   | { kind: "relocate"; workspace: string }
   | { kind: "cursor"; cursor: Cursor }
   | { kind: "parent_session"; path: string }
@@ -521,31 +513,40 @@ type MetadataRecord =
 
 function metadataPath(dir: string): string { return join(dir, "metadata.jsonl"); }
 
+/**
+ * S.3: the journal's first record declares the session format. A directory in
+ * any other format -- a journal opening with something else, or a manifest
+ * with no journal at all -- is refused before anything reads or writes it.
+ * Null means a directory no session has written yet.
+ */
 async function readMetadata(dir: string): Promise<MetadataRecord[] | null> {
   let text: string;
   try { text = await readFile(metadataPath(dir), "utf8"); }
   catch (error) {
-    if ((error as { code?: string }).code === "ENOENT") return null;
-    throw error;
+    if ((error as { code?: string }).code !== "ENOENT") throw error;
+    if (await access(manifestPath(dir)).then(() => true, () => false)) throw new SessionFormatError(dir, "undeclared");
+    return null;
   }
   if (text.length > 0 && !text.endsWith("\n")) throw new Error("INTEGRITY: incomplete metadata journal tail; no cursor is guessed");
-  return text.split("\n").filter(Boolean).map((line) => {
+  const records = text.split("\n").filter(Boolean).map((line) => {
     const envelope = JSON.parse(line) as { record: MetadataRecord; sha256: string };
     const digest = createHash("sha256").update(JSON.stringify(envelope.record)).digest("hex");
     if (envelope.sha256 !== digest) throw new Error("INTEGRITY: metadata journal digest mismatch");
     return envelope.record;
   });
+  const first = records[0];
+  if (first?.kind !== "format") throw new SessionFormatError(dir, "undeclared");
+  if (first.version !== SESSION_FORMAT) throw new SessionFormatError(dir, first.version);
+  return records;
 }
 
 /** The metadata journal already owns configuration history; no second state log is needed. */
 export async function readCursorAt(dir: string, node: number, atEvent?: string): Promise<Cursor | null> {
   const records = await readMetadata(dir);
-  const legacy = records === null ? await readLegacyManifest(dir) : undefined;
-  const states: Cursor[] = legacy?.cursor ? [legacy.cursor] : [];
-  let relocated = legacy?.relocated === true;
+  const states: Cursor[] = [];
+  let relocated = false;
   for (const record of records ?? []) {
     if (record.kind === "cursor") states.push({ ...record.cursor });
-    else if (record.kind === "seed") { if (record.manifest.cursor) states.push({ ...record.manifest.cursor }); relocated ||= record.manifest.relocated === true; }
     else if (record.kind === "relocate") { relocated = true; for (const state of states) state.workspace = record.workspace; }
   }
   if (relocated) for (const state of states) state.blob_dir = join(dir, "blobs");
@@ -560,11 +561,10 @@ export async function readManifest(dir: string): Promise<Manifest> {
 
 async function readManifestUnlocked(dir: string): Promise<Manifest> {
   const records = await readMetadata(dir);
-  if (records === null) return readLegacyManifest(dir);
-  let manifest: Manifest = { version: 1, nodes: [] };
-  for (const event of records) {
+  const manifest: Manifest = { version: 1, nodes: [] };
+  for (const event of records ?? []) {
     switch (event.kind) {
-      case "seed": manifest = structuredClone(event.manifest); break;
+      case "format": break;
       case "cursor": manifest.cursor = event.cursor; break;
       case "relocate":
         manifest.relocated = true;
@@ -603,11 +603,9 @@ async function appendMetadata(dir: string, event: MetadataRecord): Promise<void>
   const encode = (record: MetadataRecord) => JSON.stringify({
     record, sha256: createHash("sha256").update(JSON.stringify(record)).digest("hex"),
   }) + "\n";
-  if (await readMetadata(dir) === null) {
-    // Preserve old manifests once, then make every subsequent move append-only.
-    const seed: MetadataRecord = { kind: "seed", manifest: await readLegacyManifest(dir) };
-    await durableAppend(metadataPath(dir), encode(seed));
-  }
+  // The first write declares the format; readMetadata has already refused a
+  // directory in any other format, so nothing here appends to an old log.
+  if (await readMetadata(dir) === null) await durableAppend(metadataPath(dir), encode({ kind: "format", version: SESSION_FORMAT }));
   await durableAppend(metadataPath(dir), encode(event));
 }
 

package/src/store/recovery.ts

@@ -33,10 +33,8 @@ export async function recoverCut(dir: string, cursor: Cursor): Promise<Cursor> {
     next_node: Math.max(cursor.next_node, cut.next_node + 1, ...nodes.map((n) => n + 1)),
     model: cut.next_model ?? cursor.model, updated_at: cut.at,
   };
-  // Old cut records did not identify providers. Do not carry the source's
-  // provider onto a different legacy model and manufacture an identity.
+  // Cuts of this session format always record the successor's provider (S.3).
   if (cut.next_provider !== undefined) next.provider = cut.next_provider;
-  else if (next.model !== cursor.model) delete next.provider;
   if (cut.next_thinking !== undefined) next.thinking = cut.next_thinking;
   if (cut.next_context_ref !== undefined) next.context_ref = cut.next_context_ref;
   delete next.at_event;

package/src/store/replay.ts

@@ -7,7 +7,7 @@
 import { deriveHandoff } from "../core/derive.ts";
 import type { Handoff } from "../core/handoff.ts";
 import type { CutEvent, LogEvent } from "../core/events.ts";
-import { boundHandoff, boundWorkingHandoff, boundRecoveryHandoff } from "../core/history.ts";
+import { boundHandoff, boundRecoveryHandoff } from "../core/history.ts";
 import { retainedContext } from "../core/context-window.ts";
 import { digestNode, nodePath, readAncestry, readManifest, type Manifest } from "./log.ts";
 import { readNodeHistory } from "./restore.ts";
@@ -32,7 +32,7 @@ export async function carriedHandoff(dir: string, node: number, full: Handoff,
     if (!history.ok) throw new Error(history.error);
     return boundRecoveryHandoff(full, history.nodes, policy.handoff_tokens, policy.guidance_tools);
   }
-  return (policy.working_set_version === 1 ? boundWorkingHandoff : boundHandoff)(full, policy.handoff_tokens);
+  return boundHandoff(full, policy.handoff_tokens);
 }
 
 export async function replayContext(

package/src/store/restore.ts

@@ -1,46 +1,24 @@
 /**
- * Restoring the workspace to a node.
- *
- * This is where appendix H's argument becomes executable: reverting is not
- * overwriting the present with the past, it is moving a cursor to another
- * node. The nodes are untouched, so the cursor can move again -- which is
- * why a restore here cannot produce the failure that made Zed's checkpoint
- * restore an unanswered S1, where reverting destroyed both the files and the
- * thread with no way back.
+ * Walking a node's ancestry for history: every ancestor's events, bounded by
+ * the fork point below each one.
  *
  * WHY THIS DOES NOT REUSE readAncestry. That walk stops at a cut, because a
  * handoff basis means the parent's events do not replay -- correct for
- * context, catastrophic for files. A node whose ancestry crosses a cut would
- * see only the snapshots after it, and applyRestore deletes whatever is not
- * in its target, so restoring past a boundary would silently remove every
- * file written before it. File history therefore always walks to the root,
- * whatever each node declared about context.
+ * context, wrong for files and turns. File history (checkpoint-history.ts)
+ * therefore walks to the root whatever each node declared about context; the
+ * "context" scope stops at an explicit new root instead.
  */
 
 import { readNode, readManifest, digestNode, MAX_ANCESTRY_DEPTH, type Manifest } from "./log.ts";
 import type { LogEvent } from "../core/events.ts";
-import {
-  planRestore, applyRestore, scanWorkspace, DEFAULT_IGNORE,
-  type ScanDelta, type FileSet, type RestoreResult,
-} from "./workspace.ts";
 
 /**
- * Where to move the workspace to.
- *
- * A bare node means the end of that node. `atEvent` names a snapshot inside
- * it, which is what makes an ordinary undo possible: a node accumulates many
- * turns, so without it the earliest reachable state is the end of the node
- * and nothing in the node being worked in can be taken back.
+ * Where to move the workspace to. A bare node means the end of that node;
+ * `atEvent` names a point inside it, which is what makes an ordinary undo
+ * possible within the node being worked in.
  */
 export type RestoreTarget = number | { node: number; atEvent?: string };
 
-/** One snapshot, kept separate from its neighbours so a turn can be addressed. */
-export type FileDelta = ScanDelta & { node: number; event: string };
-
-export type FileHistoryResult =
-  | { ok: true; deltas: FileDelta[] }
-  | { ok: false; error: string };
-
 /** One ancestor's contribution: its events, bounded by any fork point below it. */
 export interface NodeEvents {
   node: number;
@@ -51,28 +29,6 @@ export type NodeHistoryResult =
   | { ok: true; nodes: NodeEvents[] }
   | { ok: false; error: string };
 
-export type PlanResult =
-  | { ok: true; files: FileSet; willWrite: string[]; willDelete: string[] }
-  | { ok: false; error: string };
-
-export type RestoreToNodeResult =
-  | ({ ok: true } & RestoreResult)
-  | { ok: false; error: string };
-
-/**
- * Every snapshot delta from the root to `node`, in replay order.
- *
- * Two fields on the way up, treated oppositely, because they answer different
- * questions:
- *
- *   `basis` says what the MODEL should see, and is ignored here. A cut
- *   truncates the context walk; the files it wrote are still on disk.
- *
- *   `at_event` says where this node's history BEGINS in its parent, which is
- *   a question about history, so it is obeyed. Ignoring it makes a rewind
- *   restore the very file it was asked to undo -- the parent's later turns
- *   would flow into a node that forked before them.
- */
 /**
  * Every ancestor's events, root-to-leaf, bounded by the fork points below.
  *
@@ -125,9 +81,8 @@ export async function readNodeHistory(
       };
     }
 
-    // The fork point is an event id in the node's whole stream, not a
-    // snapshot index: a turn that changed nothing writes no snapshot, so
-    // counting snapshots would land on the wrong turn.
+    // The fork point is an event id in the node's whole stream, never a
+    // count of checkpoints: a turn that changed nothing writes none.
     let contributed = events;
     if (cutoff !== undefined) {
       const at = events.findIndex((e) => e.id === cutoff);
@@ -153,150 +108,3 @@ export async function readNodeHistory(
   chain.reverse();
   return { ok: true, nodes: chain };
 }
-
-/**
- * Every snapshot delta from the root to `node`, in replay order.
- *
- * Two fields on the way up, treated oppositely, because they answer different
- * questions:
- *
- *   `basis` says what the MODEL should see, and is ignored here. A cut
- *   truncates the context walk; the files it wrote are still on disk.
- *
- *   `at_event` says where this node's history BEGINS in its parent, which is
- *   a question about history, so it is obeyed. Ignoring it makes a rewind
- *   restore the very file it was asked to undo -- the parent's later turns
- *   would flow into a node that forked before them.
- *
- * Kept one entry per snapshot rather than merged per node: merging is lossy
- * in exactly the direction that matters, since the turns inside a node are
- * the ones a person is most likely to want back.
- */
-export async function readFileHistory(
-  dir: string,
-  node: number,
-  manifest?: Manifest,
-): Promise<FileHistoryResult> {
-  const history = await readNodeHistory(dir, node, manifest);
-  if (!history.ok) return { ok: false, error: history.error };
-
-  const deltas: FileDelta[] = [];
-  for (const n of history.nodes) {
-    for (const e of n.events) {
-      if (e.t !== "snapshot") continue;
-      deltas.push({
-        node: n.node, event: e.id,
-        added: { ...e.added }, changed: { ...e.changed }, removed: [...e.removed],
-      });
-    }
-  }
-  return { ok: true, deltas };
-}
-
-/**
- * What a restore would do, without doing it.
- *
- * Separate from the restore because applyRestore deletes whatever is not in
- * the target -- necessary, or the workspace would end up a mixture of two
- * states, but destructive enough that a caller has to be able to look first.
- */
-export async function planRestoreToNode(
-  dir: string,
-  target: RestoreTarget,
-  manifest?: Manifest,
-  root?: string,
-  ignore: readonly string[] = DEFAULT_IGNORE,
-): Promise<PlanResult> {
-  const { node, atEvent } = typeof target === "number" ? { node: target, atEvent: undefined } : target;
-  const history = await readNodeHistory(dir, node, manifest);
-  if (!history.ok) return { ok: false, error: history.error };
-
-  const deltas: FileDelta[] = [];
-  for (const n of history.nodes) {
-    // The cutoff is an id in the EVENT stream, not in the snapshot stream: a
-    // fork point is where a conversation was whole, which is the end of an
-    // exchange and usually not a snapshot at all. Cutting the events first
-    // and collecting snapshots after is what keeps the files and the
-    // conversation landing on the same point.
-    let events = n.events;
-    if (atEvent !== undefined && n.node === node) {
-      const at = events.findIndex((e) => e.id === atEvent);
-      if (at === -1) {
-        return { ok: false, error: `NO_SUCH_EVENT: node ${node} has no event ${atEvent}` };
-      }
-      events = events.slice(0, at + 1);
-    }
-    for (const e of events) {
-      if (e.t !== "snapshot") continue;
-      deltas.push({
-        node: n.node, event: e.id,
-        added: { ...e.added }, changed: { ...e.changed }, removed: [...e.removed],
-      });
-    }
-  }
-
-  const files = planRestore(deltas, node);
-  const willWrite = Object.keys(files).sort();
-  if (!root) return { ok: true, files, willWrite, willDelete: [] };
-
-  const current = await scanWorkspace(root, ignore);
-  if (!current.ok) return { ok: false, error: current.error };
-  const willDelete = Object.keys(current.files).filter((p) => !(p in files)).sort();
-  return { ok: true, files, willWrite, willDelete };
-}
-
-/**
- * Moves the workspace to the state it had at `node`.
- *
- * Writes nothing to the log. The log is the truth and the workspace is a
- * projection of it, so there is nothing to record: the nodes did not change,
- * only which one is being projected. That is also what keeps this safe
- * despite being irreversible in itself -- the previous cursor position is
- * still a node, so the move can be made again in the other direction.
- */
-export async function restoreToNode(
-  dir: string,
-  blobDir: string,
-  root: string,
-  target: RestoreTarget,
-  manifest?: Manifest,
-  ignore: readonly string[] = DEFAULT_IGNORE,
-): Promise<RestoreToNodeResult> {
-  const plan = await planRestoreToNode(dir, target, manifest ?? (await readManifest(dir)), root, ignore);
-  if (!plan.ok) return { ok: false, error: plan.error };
-  return { ok: true, ...(await applyRestorePlan(root, blobDir, plan.files, ignore, describeTarget(target))) };
-}
-
-/**
- * Applies a plan that has already been computed.
- *
- * Split out so a caller holding a plan does not have to compute it twice.
- * That is not only wasted work: a caller that re-planned inside the apply
- * could never see the apply fail on its own, which turns its own "did the
- * files move?" guard into unreachable code.
- */
-export async function applyRestorePlan(
-  root: string,
-  blobDir: string,
-  files: FileSet,
-  ignore: readonly string[],
-  label: string,
-): Promise<RestoreResult> {
-  const result = await applyRestore(root, blobDir, files, ignore);
-  if (result.unrecoverable.length > 0) return result;
-  return {
-    ...result,
-    note:
-      `Workspace moved to ${label}. ` +
-      result.note +
-      " Other logged snapshots remain available. File versions never " +
-      "snapshotted cannot be reconstructed from the log.",
-  };
-}
-
-function describeTarget(target: RestoreTarget): string {
-  if (typeof target === "number") return `node ${target}`;
-  return target.atEvent === undefined
-    ? `node ${target.node}`
-    : `node ${target.node} as of snapshot ${target.atEvent}`;
-}

package/src/store/search.ts

@@ -1,8 +1,10 @@
 /**
  * Workspace search: grep, find, ls.
  *
- * The walk reuses buildFileIndex so ignore rules, the 20000 cap, and the
- * no-symlink rule stay one implementation. Ripgrep / fd are used only when
+ * The walk reuses buildFileIndex so ignore rules (.gitignore inside a Git
+ * work tree, S.6 item 4), the walk cap, and the no-symlink rule stay one
+ * implementation. Ripgrep / fd follow the same .gitignore rule, and search an
+ * ignored target named explicitly, like the walk. They are used only when
  * they are already on PATH -- never downloaded -- because fetching a binary
  * at runtime is a supply-chain path the Isolation section of README.md
  * told the user they would not be taking.
@@ -16,7 +18,7 @@ import { lstat, readdir, readFile } from "node:fs/promises";
 import { isAbsolute, join, relative, sep } from "node:path";
 import { Worker } from "node:worker_threads";
 import { assertNever } from "../core/exhaustive.ts";
-import { buildFileIndex } from "./file-index.ts";
+import { buildFileIndex, gitIgnored } from "./file-index.ts";
 import { DEFAULT_IGNORE } from "./workspace.ts";
 import { blobAddress } from "./blobs.ts";
 import { previewSearchObservation, type SearchObservation } from "../core/search-observation.ts";
@@ -464,7 +466,7 @@ async function grepRipgrep(opts: GrepOpts, abs: string, limit: number): Promise<
     "--color=never",
     "--hidden",
     "--no-follow",
-    "--no-ignore",
+    ...(await gitIgnored(abs, opts.signal) ? ["--no-ignore"] : []),
     "--max-filesize",
     String(MAX_FILE_BYTES),
     ...rgIgnoreArgs(),
@@ -606,7 +608,7 @@ async function findFd(opts: FindOpts, abs: string, limit: number): Promise<Searc
     "--glob",
     "--color=never",
     "--hidden",
-    "--no-ignore",
+    ...(await gitIgnored(abs, opts.signal) ? ["--no-ignore"] : []),
     "--absolute-path",
     "--print0",
     ...fdExcludeArgs(),

package/src/store/session-archive.ts

@@ -39,7 +39,6 @@ async function referencedBlobs(dir: string, fallback?: string): Promise<Map<stri
     const roots = [...new Set([historical?.blob_dir, cursor?.blob_dir, fallback, join(dir, "blobs")].filter((p): p is string => !!p))];
     const add = (sha: string) => { refs.set(sha, [...new Set([...(refs.get(sha) ?? []), ...roots])]); };
     for (const event of read.events) {
-      if (event.t === "snapshot") for (const sha of [...Object.values(event.added), ...Object.values(event.changed)]) add(sha);
       if (event.t === "checkpoint") for (const change of Object.values(event.changes)) {
         if (change.before) add(change.before.sha256);
         if (change.after) add(change.after.sha256);

package/src/store/sessions.ts

@@ -22,7 +22,7 @@
  * and silently truncate a log.
  */
 
-import { cp, lstat, mkdir, mkdtemp, open, readdir, rename, rm, stat } from "node:fs/promises";
+import { cp, lstat, mkdir, mkdtemp, open, readdir, rename, rm, stat, writeFile } from "node:fs/promises";
 import type { Dirent } from "node:fs";
 import { tmpdir } from "node:os";
 import { basename, dirname, isAbsolute, join, relative, resolve } from "node:path";
@@ -112,10 +112,6 @@ export function sessionsDir(workspace: string, override?: string): string {
   return join(workspace, ".xeno", "sessions");
 }
 
-export function legacyLogDir(workspace: string): string {
-  return join(workspace, ".xeno", "log");
-}
-
 /**
  * `<base36 ms>-<4 digit base36 random>`.
  *
@@ -141,6 +137,8 @@ export async function createSession(
 ): Promise<{ id: string; path: string }> {
   const dir = sessionsDir(workspace, sessionDir);
   await mkdir(dir, { recursive: true });
+  // The first session makes the state directory exist; keep it out of git from that moment.
+  await ignoreStateDir(dirname(dir));
   for (let attempt = 0; attempt < MAX_ID_ATTEMPTS; attempt++) {
     const id = formatSessionId(clock.nowMs(), clock.random());
     const path = join(dir, id);
@@ -193,21 +191,6 @@ export async function listSessions(workspace: string, sessionDir?: string, limit
   return { sessions, truncated };
 }
 
-/**
- * A leftover `.xeno/log` is not migrated. Moving someone else's data cannot
- * be a startup side effect; the person keeps using it by pointing `--log`
- * at it. Once `.xeno/sessions/` exists they are already in the new layout
- * and the leftover is just leftover, so the notice stays quiet.
- */
-export async function legacyLogNotice(workspace: string): Promise<string | null> {
-  if (!(await isDirectory(legacyLogDir(workspace)))) return null;
-  if (await isDirectory(sessionsDir(workspace))) return null;
-  return (
-    "This workspace still has a log at .xeno/log from before named sessions existed. " +
-    "It has not been moved. Continue it with --log .xeno/log"
-  );
-}
-
 export type SessionPrefixMatch =
   | { ok: true; session: Extract<ListedSession, { ok: true }> }
   | { ok: false; reason: string; candidates: string[] };
@@ -352,46 +335,44 @@ export interface ResolveLogOpts extends SessionEntryFlags {
 export async function resolveLogDir(
   workspace: string,
   opts: ResolveLogOpts = {},
-): Promise<{ logDir: string; created: boolean; legacyNotice: string | null }> {
+): Promise<{ logDir: string; created: boolean }> {
   const entry = planSessionEntry(opts);
-  // Computed first: createSession will mkdir `.xeno/sessions/`, after which
-  // the leftover-log condition is no longer true.
-  const legacyNotice = await legacyLogNotice(workspace);
   switch (entry.kind) {
     case "named": {
       const root = sessionsDir(workspace, opts.sessionDir), logDir = join(root, entry.id);
       await mkdir(root, { recursive: true });
-      try { await mkdir(logDir); return { logDir, created: true, legacyNotice }; }
+      await ignoreStateDir(dirname(root));
+      try { await mkdir(logDir); return { logDir, created: true }; }
       catch (error) {
         if ((error as { code?: string }).code !== "EEXIST" || !(await lstat(logDir)).isDirectory()) throw error;
-        return { logDir, created: false, legacyNotice };
+        return { logDir, created: false };
       }
     }
     case "ephemeral": {
       const logDir = await mkdtemp(join(tmpdir(), "xeno-nosession-"));
-      return { logDir, created: true, legacyNotice };
+      return { logDir, created: true };
     }
     case "open": {
-      if (entry.explicit) return { logDir: entry.target, created: false, legacyNotice };
+      if (entry.explicit) return { logDir: entry.target, created: false };
       const archive = resolve(workspace, entry.target);
       if (await stat(archive).then(info => info.isFile(), () => false)) {
-        return { logDir: await importSessionArchive(archive, sessionsDir(workspace, opts.sessionDir), workspace), created: true, legacyNotice };
+        return { logDir: await importSessionArchive(archive, sessionsDir(workspace, opts.sessionDir), workspace), created: true };
       }
       const found = await findSessionByPrefix(workspace, entry.target, opts.sessionDir);
       if (!found.ok) throw new Error(found.reason);
-      return { logDir: found.session.path, created: false, legacyNotice };
+      return { logDir: found.session.path, created: false };
     }
     case "fork": {
       const found = await findSessionByPrefix(workspace, entry.target, opts.sessionDir);
       if (!found.ok) throw new Error(found.reason);
       const created = await createSession(workspace, systemIdClock, opts.sessionDir);
       await copyAncestryTo(found.session.path, created.path, new Date().toISOString());
-      return { logDir: created.path, created: true, legacyNotice };
+      return { logDir: created.path, created: true };
     }
     case "continue": {
       const { sessions } = await listSessions(workspace, opts.sessionDir, Infinity);
       const newest = sessions.find((s) => s.ok);
-      if (newest !== undefined) return { logDir: newest.path, created: false, legacyNotice };
+      if (newest !== undefined) return { logDir: newest.path, created: false };
       break;
     }
     case "select":
@@ -400,7 +381,7 @@ export async function resolveLogDir(
     default: return assertNever(entry, "resolveLogDir");
   }
   const created = await createSession(workspace, systemIdClock, opts.sessionDir);
-  return { logDir: created.path, created: true, legacyNotice };
+  return { logDir: created.path, created: true };
 }
 
 async function existingDir(workspace: string, prefix: string): Promise<string | null> {
@@ -482,3 +463,20 @@ async function isDirectory(path: string): Promise<boolean> {
     throw err;
   }
 }
+
+/**
+ * Keeps a state directory out of `git status` the way pytest, ruff and mypy
+ * keep their caches out: a `.gitignore` holding `*` inside the directory
+ * itself. Checks people and models write ("only plan.md changed") read git,
+ * and a visible session directory made such a check fail forever
+ * (fix-state-dir-self-ignore). The user's own ignore files are never edited,
+ * and .git/info/exclude is avoided: worktrees do not read it, and a sandboxed
+ * agent could use it to hide files. An existing file is left alone; failure
+ * to write one never blocks a session.
+ */
+export async function ignoreStateDir(stateRoot: string): Promise<void> {
+  try {
+    await mkdir(stateRoot, { recursive: true });
+    await writeFile(join(stateRoot, ".gitignore"), "# Created by xeno: session state is not project source.\n*\n", { flag: "wx" });
+  } catch { /* present already, or not writable: either way nothing to do */ }
+}

package/src/store/workspace-clone.ts

@@ -0,0 +1,42 @@
+/**
+ * A disposable copy of a workspace, for running a check somewhere it cannot
+ * touch the real files (feat-counter-check).
+ *
+ * Copy-on-write where the filesystem offers it -- APFS clonefile through
+ * `cp -c`, reflinks through `cp --reflink=auto` -- so a workspace with large
+ * dependency trees costs metadata, not bytes. Where it does not, cp falls back
+ * to a real copy, bounded by the deadline below.
+ */
+import { mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+/**
+ * Assumed, not measured: a clone is metadata-only on APFS and reflink
+ * filesystems; a full copy that takes longer than this is better reported as
+ * unavailable than waited on.
+ */
+export const CLONE_TIMEOUT_MS = 60_000;
+
+export type WorkspaceClone = { ok: true; path: string; dispose: () => Promise<void> } | { ok: false; reason: string };
+
+export async function cloneWorkspace(root: string, signal?: AbortSignal): Promise<WorkspaceClone> {
+  const parent = await mkdtemp(join(tmpdir(), "xeno-counter-check-")), path = join(parent, "workspace");
+  const dispose = () => rm(parent, { recursive: true, force: true });
+  const attempts = process.platform === "darwin" ? [["cp", "-cR", root, path], ["cp", "-R", root, path]] : [["cp", "-a", "--reflink=auto", root, path]];
+  let reason = "the workspace could not be copied";
+  for (const argv of attempts) {
+    if (signal?.aborted) { await dispose(); return { ok: false, reason: "cancelled" }; }
+    await rm(path, { recursive: true, force: true });
+    const child = Bun.spawn(argv, { stdout: "ignore", stderr: "pipe" });
+    const timer = setTimeout(() => child.kill(), CLONE_TIMEOUT_MS);
+    const abort = () => child.kill();
+    signal?.addEventListener("abort", abort, { once: true });
+    const [exit, stderr] = await Promise.all([child.exited, new Response(child.stderr).text()]);
+    clearTimeout(timer); signal?.removeEventListener("abort", abort);
+    if (exit === 0) return { ok: true, path, dispose };
+    reason = child.signalCode ? `copying the workspace exceeded ${CLONE_TIMEOUT_MS / 1000}s` : `the workspace could not be copied: ${stderr.trim().split("\n").at(-1) ?? `exit ${exit}`}`;
+  }
+  await dispose();
+  return { ok: false, reason };
+}