Skip to content

Local-first 🧠 memory for Hermes Agent that lives in your Obsidian vault and remembers project context. Nightly 😴 dream passes turn repeat corrections into confirmed preferences with measurable confidence. Adapters ship for Claude Code, Codex, and OpenClaw, with an MCP server for anything else.

TypeScript
31.1 KB
Raw Blame
/**
 * Fail-closed session continuation (context-integrity-gates, Unit C /
 * Task 11).
 *
 * The interim crutch used to resolve a multi-candidate set by picking
 * the most recent predecessor, and to report every refusal as a bare
 * `null` that four distinct causes collapsed into. Both are pinned here
 * as defects: ambiguity must ABSTAIN, and every refusal must name its
 * own reason. Repo, branch and commit join `cwd` as required-match
 * predicates, captured through the hardened git argv reader under a
 * bounded timeout and canonicalized so a credential-bearing clone is
 * the same identity as a credential-free one - and so the credential
 * never reaches a recorded field.
 */

import { afterEach, beforeEach, describe, expect, setDefaultTimeout, test } from "bun:test";
import { execFileSync } from "node:child_process";
import { mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
import { join } from "node:path";

import {
  DEGRADATION_CODE,
  type DegradationNotice,
} from "../../../src/core/integrity/degradation.ts";
import {
  canonicalizeGitRemote,
  type GitWorkspaceIdentity,
  readGitWorkspaceIdentity,
} from "../../../src/core/brain/git/reader.ts";
import { CRUTCH_ABSTENTION, resolveCrutchLineage } from "../../../src/core/brain/lineage/crutch.ts";
import {
  CRUTCH_LINK_WINDOW_MS,
  LINEAGE_RECORD_STATUS,
  lineageGapSessionIds,
  readLineageLedger,
  recordLineageObservation,
  sessionLineageLedgerPath,
} from "../../../src/core/brain/lineage/ledger.ts";
import { acquireLockSync } from "../../../src/core/brain/sync-lockfile.ts";
import {
  resolveSessionLineage,
  resolveSessionLineageDetailed,
} from "../../../src/core/brain/lineage/resolve.ts";
import { captureSessionLifecycleEvent } from "../../../src/core/brain/session-lifecycle.ts";
import { bootstrapBrain } from "../../../src/core/brain/init.ts";
import { tempDirs } from "../../helpers/temp-dir.ts";
import { CLI_SPAWN_BUDGET_MS } from "../../helpers/cli-timeout.ts";

// Tests here spawn processes; see tests/helpers/cli-timeout.ts.
setDefaultTimeout(CLI_SPAWN_BUDGET_MS);

// Every test's throwaway workspace is minted through the tracked helper
// so a directory is owned twice over: the afterEach removes the current
// test's directory, and the helper's file-end sweep removes any directory
// whose afterEach did not get to run. The run's temp-hygiene guard
// (tests/setup.ts) fails the whole run on a single survivor, so cleanup
// here may not depend on one hook firing exactly once.
const mkTemp = tempDirs();

let tmp: string;

beforeEach(() => {
  tmp = mkTemp("o2b-continuation-");
  // A legacy Brain/ tree: an unswitched machine (a vault without one is store-only).
  mkdirSync(join(tmp, "Brain"), { recursive: true });
});

afterEach(() => {
  rmSync(tmp, { recursive: true, force: true });
});

const T0 = Date.parse("2026-06-10T08:00:00Z");

// ----- git fixture ---------------------------------------------------------

/** A remote whose credentials must never survive canonicalization. */
const SECRET_REMOTE = "https://alice:[email protected]:8443/org/repo.git/";
const SECRET_REMOTE_IDENTITY = "https://git.example.invalid/org/repo";

function git(dir: string, args: ReadonlyArray<string>): void {
  execFileSync("git", ["-C", dir, ...args], { stdio: "ignore" });
}

function initRepo(dir: string, opts: { remote?: string; branch?: string } = {}): string {
  mkdirSync(dir, { recursive: true });
  execFileSync("git", ["init", "--quiet", `--initial-branch=${opts.branch ?? "main"}`, dir], {
    stdio: "ignore",
  });
  git(dir, ["config", "user.email", "[email protected]"]);
  git(dir, ["config", "user.name", "Fixture"]);
  git(dir, ["config", "commit.gpgsign", "false"]);
  if (opts.remote !== undefined) git(dir, ["remote", "add", "origin", opts.remote]);
  writeFileSync(join(dir, "a.txt"), "one\n", "utf8");
  git(dir, ["add", "a.txt"]);
  git(dir, ["commit", "--quiet", "--no-gpg-sign", "-m", "one"]);
  return dir;
}

function commitAgain(dir: string, text: string): void {
  writeFileSync(join(dir, "a.txt"), text, "utf8");
  git(dir, ["add", "a.txt"]);
  git(dir, ["commit", "--quiet", "--no-gpg-sign", "-m", text]);
}

// ----- the canonicalizer ---------------------------------------------------

describe("canonicalizeGitRemote — a comparable identity, not a redaction", () => {
  test("strips userinfo, port, .git suffix and trailing slash", () => {
    expect(canonicalizeGitRemote(SECRET_REMOTE)).toBe(SECRET_REMOTE_IDENTITY);
  });

  test("a credential-bearing clone is the SAME identity as a credential-free one", () => {
    const withCreds = canonicalizeGitRemote("https://u:[email protected]/org/repo.git");
    const withOther = canonicalizeGitRemote("https://other:[email protected]/org/repo");
    const without = canonicalizeGitRemote("https://github.com/org/repo");
    expect(withCreds).toBe(without!);
    expect(withOther).toBe(without!);
  });

  test("never carries the credential through", () => {
    const out = canonicalizeGitRemote(SECRET_REMOTE)!;
    expect(out.includes("s3cr3t-token")).toBe(false);
    expect(out.includes("alice")).toBe(false);
    expect(out.includes("@")).toBe(false);
  });

  test("scp-style and ssh-url forms normalize to one identity", () => {
    const scp = canonicalizeGitRemote("[email protected]:org/repo.git");
    expect(scp).toBe("ssh://github.com/org/repo");
    expect(canonicalizeGitRemote("ssh://[email protected]:22/org/repo.git/")).toBe(scp!);
  });

  test("host case is normalized, path case is not", () => {
    expect(canonicalizeGitRemote("https://GitHub.COM/Org/Repo.git")).toBe(
      "https://github.com/Org/Repo",
    );
  });

  test("a local path remote becomes a file identity", () => {
    expect(canonicalizeGitRemote("/srv/git/thing.git/")).toBe("file:///srv/git/thing");
  });

  test("a Windows drive-path remote becomes a file identity, either separator", () => {
    // `new URL("C:\\srv\\...")` parses a `c:` scheme with no host, which
    // the hostless guard turned into a null identity.
    expect(canonicalizeGitRemote("C:\\srv\\git\\thing.git")).toBe("file:///C:/srv/git/thing");
    expect(canonicalizeGitRemote("C:/srv/git/thing.git/")).toBe("file:///C:/srv/git/thing");
  });

  // A path remote is placed into a `file:`/`ssh:` URL to be parsed. `#`,
  // `?` and `%` are legal in directory names and are URL syntax, so left
  // raw they cut the path short (`c#1` and `c#2` both read as `c`) or a
  // literal `%23` reads as the escape for `#`.
  const DISTINCT_PATH_REMOTES: ReadonlyArray<{
    readonly why: string;
    readonly a: string;
    readonly b: string;
  }> = [
    { why: "drive path, '#'", a: "C:\\repos\\c#1\\x.git", b: "C:\\repos\\c#2\\x.git" },
    { why: "drive path, '%' vs '#'", a: "C:\\repos\\c%231\\x.git", b: "C:\\repos\\c#1\\x.git" },
    { why: "POSIX path, '#'", a: "/srv/c#1/x.git", b: "/srv/c#2/x.git" },
    { why: "POSIX path, '?'", a: "/srv/q?1/x.git", b: "/srv/q?2/x.git" },
    { why: "POSIX path, '%20' vs space", a: "/srv/a%20b/x.git", b: "/srv/a b/x.git" },
    { why: "scp path, '#'", a: "[email protected]:org/c#1.git", b: "[email protected]:org/c#2.git" },
  ];

  for (const { why, a, b } of DISTINCT_PATH_REMOTES) {
    test(`URL syntax in a path remote stays part of the path (${why})`, () => {
      const left = canonicalizeGitRemote(a);
      const right = canonicalizeGitRemote(b);
      expect(left).not.toBeNull();
      expect(right).not.toBeNull();
      expect(left).not.toBe(right!);
    });
  }

  test("an escaped path remote reads back as its percent-encoded path", () => {
    expect(canonicalizeGitRemote("C:\\repos\\c#1\\x.git")).toBe("file:///C:/repos/c%231/x");
    expect(canonicalizeGitRemote("/srv/q?1/c%1.git")).toBe("file:///srv/q%3F1/c%251");
    expect(canonicalizeGitRemote("[email protected]:org/c#1.git")).toBe(
      "ssh://host.invalid/org/c%231",
    );
  });

  test("the drive letter's case is one identity; the rest of the path keeps its case", () => {
    const upper = canonicalizeGitRemote("C:\\Srv\\git\\thing.git");
    expect(upper).toBe("file:///C:/Srv/git/thing");
    expect(canonicalizeGitRemote("c:\\Srv\\git\\thing.git")).toBe(upper!);
    expect(canonicalizeGitRemote("c:/Srv/git/thing.git")).toBe(upper!);
    // The identity an older version recorded for a lower-case drive is
    // itself a remote, and canonicalizes to the same identity.
    expect(canonicalizeGitRemote("file:///c:/Srv/git/thing")).toBe(upper!);
    expect(canonicalizeGitRemote("C:\\srv\\git\\thing.git")).not.toBe(upper!);
  });

  test("a UNC remote is a file identity on the server's host", () => {
    const unc = canonicalizeGitRemote("\\\\server\\share\\repo.git");
    expect(unc).toBe("file://server/share/repo");
    expect(canonicalizeGitRemote("\\\\SERVER\\share\\repo.git\\")).toBe(unc!);
    expect(canonicalizeGitRemote("\\\\server\\share\\c#1.git")).toBe("file://server/share/c%231");
    expect(canonicalizeGitRemote("\\\\other\\share\\repo.git")).not.toBe(unc!);
  });

  test("blank or hostless input is null, never a placeholder", () => {
    expect(canonicalizeGitRemote("")).toBeNull();
    expect(canonicalizeGitRemote("   ")).toBeNull();
    expect(canonicalizeGitRemote("https://")).toBeNull();
  });
});

// ----- the probe -----------------------------------------------------------

describe("readGitWorkspaceIdentity — hardened, bounded probe", () => {
  test("reads repo, branch and commit from a throwaway repository", () => {
    const repo = initRepo(join(tmp, "repo"), { remote: SECRET_REMOTE, branch: "trunk" });
    const identity = readGitWorkspaceIdentity(repo);
    expect(identity).not.toBeNull();
    expect(identity!.repo).toBe(SECRET_REMOTE_IDENTITY);
    expect(identity!.branch).toBe("trunk");
    expect(identity!.commit).toMatch(/^[0-9a-f]{40}$/);
  });

  test("the recorded repo identity never carries the clone credential", () => {
    const repo = initRepo(join(tmp, "repo"), { remote: SECRET_REMOTE });
    const identity = readGitWorkspaceIdentity(repo)!;
    expect(JSON.stringify(identity).includes("s3cr3t-token")).toBe(false);
  });

  test("a SUBDIRECTORY of the repository resolves the same identity", () => {
    const repo = initRepo(join(tmp, "repo"), { remote: SECRET_REMOTE });
    const sub = join(repo, "src", "deep");
    mkdirSync(sub, { recursive: true });
    expect(readGitWorkspaceIdentity(sub)).toEqual(readGitWorkspaceIdentity(repo)!);
  });

  test("a new commit changes the identity", () => {
    const repo = initRepo(join(tmp, "repo"), { remote: SECRET_REMOTE });
    const before = readGitWorkspaceIdentity(repo)!;
    commitAgain(repo, "two\n");
    const after = readGitWorkspaceIdentity(repo)!;
    expect(after.commit).not.toBe(before.commit!);
    expect(after.repo).toBe(before.repo!);
  });

  test("a directory that is not a repository reads as no identity", () => {
    const plain = join(tmp, "plain");
    mkdirSync(plain, { recursive: true });
    expect(readGitWorkspaceIdentity(plain)).toBeNull();
    expect(readGitWorkspaceIdentity(join(tmp, "does-not-exist"))).toBeNull();
  });

  test("a repository with no remote still reports branch and commit", () => {
    const repo = initRepo(join(tmp, "bare-remote"));
    const identity = readGitWorkspaceIdentity(repo)!;
    expect(identity.repo).toBeNull();
    expect(identity.branch).toBe("main");
  });

  test("the probe is bounded: an exhausted budget yields no identity, never a hang", () => {
    const repo = initRepo(join(tmp, "repo"), { remote: SECRET_REMOTE });
    // An exhausted budget is stated, not approximated. This assertion
    // previously passed `1`, which leaves the first invocation a whole
    // millisecond of budget and so asserted only that this machine's git
    // is slower than that - true on a loaded developer box, false on a
    // fast runner, and a claim about hardware either way.
    expect(readGitWorkspaceIdentity(repo, { timeoutMs: 0 })).toBeNull();
    expect(readGitWorkspaceIdentity(repo, { timeoutMs: -1 })).toBeNull();
  });

  test("a budget that is not a number is a caller bug, and is named", () => {
    const repo = initRepo(join(tmp, "nan-budget"), { remote: SECRET_REMOTE });
    // Silently substituting the default would hand back a two-second
    // probe to a caller who believes it asked for something else.
    expect(() => readGitWorkspaceIdentity(repo, { timeoutMs: Number.NaN })).toThrow(/timeoutMs/);
  });
});

// ----- the resolver --------------------------------------------------------

function seed(opts: {
  sessionId: string;
  atMs?: number;
  cwd?: string;
  evidence?: boolean;
  workspace?: GitWorkspaceIdentity;
}): void {
  recordLineageObservation(tmp, {
    sessionId: opts.sessionId,
    at: new Date(opts.atMs ?? T0).toISOString(),
    cwd: opts.cwd ?? "/work",
    event: opts.evidence === false ? "Stop" : "PostCompact",
    ...(opts.evidence === false ? {} : { compressionEvidence: true }),
    ...(opts.workspace !== undefined ? { workspace: opts.workspace } : {}),
  });
}

const WS_MAIN: GitWorkspaceIdentity = {
  repo: "https://git.example.invalid/org/repo",
  branch: "main",
  commit: "a".repeat(40),
};

function outcome(
  sessionId: string,
  over: Partial<Parameters<typeof resolveCrutchLineage>[0]> = {},
) {
  return resolveCrutchLineage({
    sessionId,
    cwd: "/work",
    ledger: readLineageLedger(tmp),
    nowMs: T0 + 30_000,
    ...over,
  });
}

describe("resolveCrutchLineage — every refusal names itself", () => {
  test("links a single surviving candidate", () => {
    seed({ sessionId: "s-old" });
    const result = outcome("s-new");
    expect(result.kind).toBe("linked");
    if (result.kind !== "linked") throw new Error("unreachable");
    expect(result.lineage).toEqual({
      rootId: "s-old",
      parentId: "s-old",
      depth: 1,
      source: "crutch",
    });
  });

  test("TWO surviving candidates ABSTAIN instead of taking the most recent", () => {
    seed({ sessionId: "s-a", atMs: T0 });
    seed({ sessionId: "s-b", atMs: T0 + 10_000 });
    const result = outcome("s-new");
    expect(result.kind).toBe("abstained");
    if (result.kind !== "abstained") throw new Error("unreachable");
    expect(result.reason).toBe(CRUTCH_ABSTENTION.ambiguous);
    expect(result.considered).toBe(2);
    expect(result.detail.length).toBeGreaterThan(0);
  });

  test("no ledger at all abstains with no-candidate", () => {
    const result = outcome("s-new");
    expect(result).toMatchObject({ kind: "abstained", reason: CRUTCH_ABSTENTION.noCandidate });
  });

  test("a session with its own unlinked history abstains with self-known", () => {
    seed({ sessionId: "s-old" });
    seed({ sessionId: "s-new", atMs: T0 - 120_000, evidence: false });
    const result = outcome("s-new");
    expect(result).toMatchObject({ kind: "abstained", reason: CRUTCH_ABSTENTION.selfKnown });
  });

  test("an absent working directory abstains with no-workspace", () => {
    seed({ sessionId: "s-old" });
    expect(outcome("s-new", { cwd: undefined })).toMatchObject({
      kind: "abstained",
      reason: CRUTCH_ABSTENTION.noWorkspace,
    });
    expect(outcome("s-new", { cwd: "" })).toMatchObject({
      kind: "abstained",
      reason: CRUTCH_ABSTENTION.noWorkspace,
    });
  });

  test("a candidate outside the freshness window abstains with stale", () => {
    seed({ sessionId: "s-old" });
    const result = outcome("s-new", { nowMs: T0 + CRUTCH_LINK_WINDOW_MS + 1 });
    expect(result).toMatchObject({ kind: "abstained", reason: CRUTCH_ABSTENTION.stale });
  });

  test("a candidate without compression evidence abstains with evidence-missing", () => {
    seed({ sessionId: "s-old", evidence: false });
    const result = outcome("s-new");
    expect(result).toMatchObject({
      kind: "abstained",
      reason: CRUTCH_ABSTENTION.evidenceMissing,
    });
  });

  test("a candidate in another working directory is no-candidate, not a near miss", () => {
    seed({ sessionId: "s-old", cwd: "/elsewhere" });
    expect(outcome("s-new")).toMatchObject({
      kind: "abstained",
      reason: CRUTCH_ABSTENTION.noCandidate,
    });
  });

  test("a predecessor another session already continued from is not a candidate", () => {
    // A -> B is recorded; C must resolve to B alone, not read A and B
    // as an ambiguous pair. A compaction boundary has one successor.
    seed({ sessionId: "s-a", atMs: T0 });
    recordLineageObservation(tmp, {
      sessionId: "s-b",
      at: new Date(T0 + 10_000).toISOString(),
      cwd: "/work",
      event: "PostCompact",
      compressionEvidence: true,
      lineage: { rootId: "s-a", parentId: "s-a", depth: 1, source: "crutch" },
    });
    const result = outcome("s-c");
    expect(result.kind).toBe("linked");
    if (result.kind !== "linked") throw new Error("unreachable");
    expect(result.lineage).toEqual({
      rootId: "s-a",
      parentId: "s-b",
      depth: 2,
      source: "crutch",
    });
  });

  test("the nearest miss wins: evidence-missing outranks stale", () => {
    seed({ sessionId: "s-stale", atMs: T0 - CRUTCH_LINK_WINDOW_MS - 1 });
    seed({ sessionId: "s-noevidence", evidence: false });
    expect(outcome("s-new")).toMatchObject({
      kind: "abstained",
      reason: CRUTCH_ABSTENTION.evidenceMissing,
    });
  });
});

describe("resolveCrutchLineage — repo, branch and commit are match predicates", () => {
  test("an identical workspace identity links", () => {
    seed({ sessionId: "s-old", workspace: WS_MAIN });
    expect(outcome("s-new", { workspace: WS_MAIN }).kind).toBe("linked");
  });

  test("a different BRANCH does not link", () => {
    seed({ sessionId: "s-old", workspace: WS_MAIN });
    const result = outcome("s-new", { workspace: { ...WS_MAIN, branch: "feature" } });
    expect(result.kind).toBe("abstained");
  });

  test("a different COMMIT does not link", () => {
    seed({ sessionId: "s-old", workspace: WS_MAIN });
    const result = outcome("s-new", { workspace: { ...WS_MAIN, commit: "b".repeat(40) } });
    expect(result.kind).toBe("abstained");
  });

  test("a different REPO does not link", () => {
    seed({ sessionId: "s-old", workspace: WS_MAIN });
    const result = outcome("s-new", {
      workspace: { ...WS_MAIN, repo: "https://git.example.invalid/org/other" },
    });
    expect(result.kind).toBe("abstained");
  });

  test("an attested candidate against an unattested session abstains with evidence-missing", () => {
    seed({ sessionId: "s-old", workspace: WS_MAIN });
    expect(outcome("s-new")).toMatchObject({
      kind: "abstained",
      reason: CRUTCH_ABSTENTION.evidenceMissing,
    });
  });

  test("an unattested candidate against an attested session abstains with evidence-missing", () => {
    seed({ sessionId: "s-old" });
    expect(outcome("s-new", { workspace: WS_MAIN })).toMatchObject({
      kind: "abstained",
      reason: CRUTCH_ABSTENTION.evidenceMissing,
    });
  });

  test("two unattested sides still link — a non-git workspace is not a refusal", () => {
    seed({ sessionId: "s-old" });
    expect(outcome("s-new").kind).toBe("linked");
  });
});

// ----- the ledger carries the identity -------------------------------------

describe("lineage ledger — workspace identity round-trip", () => {
  test("records and reads back repo, branch and commit", () => {
    seed({ sessionId: "s-1", workspace: WS_MAIN });
    expect(readLineageLedger(tmp).get("s-1")?.workspace).toEqual(WS_MAIN);
  });

  test("compaction preserves the workspace identity", () => {
    // Compaction retains the most recent LINES verbatim, so the line
    // under test has to be inside the retention window when the rewrite
    // runs - which is the realistic case, the ledger being append-only.
    const filler = (from: number, count: number): void => {
      for (let i = from; i < from + count; i++) {
        recordLineageObservation(tmp, {
          sessionId: `filler-${i}`,
          at: new Date(T0 + i * 1_000).toISOString(),
          event: "Stop",
        });
      }
    };
    filler(0, 510);
    seed({ sessionId: "s-keep", atMs: T0 + 510_000, workspace: WS_MAIN });
    filler(511, 5); // crosses the cap and rewrites the file
    expect(readLineageLedger(tmp).get("s-keep")?.workspace).toEqual(WS_MAIN);
  });

  test("a repo recorded before the drive letter was folded still matches today's", () => {
    // Earlier versions kept the drive letter as git reported it. Their
    // lines are read back in today's canonical form, so a session in the
    // same checkout is not refused over a case difference in `c:`.
    const old: GitWorkspaceIdentity = { ...WS_MAIN, repo: "file:///c:/srv/git/thing" };
    const today: GitWorkspaceIdentity = { ...WS_MAIN, repo: "file:///C:/srv/git/thing" };
    seed({ sessionId: "s-old", workspace: old });
    expect(readLineageLedger(tmp).get("s-old")?.workspace?.repo).toBe(today.repo);
    expect(outcome("s-new", { workspace: today }).kind).toBe("linked");
  });
});

// ----- resolution surface --------------------------------------------------

describe("resolveSessionLineageDetailed — the abstention reaches the caller", () => {
  test("carries the crutch outcome alongside the lineage", () => {
    seed({ sessionId: "s-a", atMs: T0 });
    seed({ sessionId: "s-b", atMs: T0 + 10_000 });
    const resolution = resolveSessionLineageDetailed(
      { sessionId: "s-new", cwd: "/work" },
      { ledger: readLineageLedger(tmp), nowMs: T0 + 30_000 },
    );
    expect(resolution.lineage.source).toBe("flat");
    expect(resolution.crutch).toMatchObject({
      kind: "abstained",
      reason: CRUTCH_ABSTENTION.ambiguous,
    });
  });

  test("an ambiguous abstention emits a sessionLinkAbstained notice", () => {
    seed({ sessionId: "s-a", atMs: T0 });
    seed({ sessionId: "s-b", atMs: T0 + 10_000 });
    const notices: DegradationNotice[] = [];
    resolveSessionLineageDetailed(
      { sessionId: "s-new", cwd: "/work" },
      { ledger: readLineageLedger(tmp), nowMs: T0 + 30_000, notices },
    );
    expect(notices).toHaveLength(1);
    expect(notices[0]!.code).toBe(DEGRADATION_CODE.sessionLinkAbstained);
    expect(notices[0]!.detail).toContain(CRUTCH_ABSTENTION.ambiguous);
  });

  test("the ordinary flat path emits NO notice", () => {
    const notices: DegradationNotice[] = [];
    resolveSessionLineageDetailed(
      { sessionId: "s-new", cwd: "/work" },
      { ledger: readLineageLedger(tmp), nowMs: T0 + 30_000, notices },
    );
    expect(notices).toHaveLength(0);
  });

  test("a link emits no notice", () => {
    seed({ sessionId: "s-old" });
    const notices: DegradationNotice[] = [];
    const resolution = resolveSessionLineageDetailed(
      { sessionId: "s-new", cwd: "/work" },
      { ledger: readLineageLedger(tmp), nowMs: T0 + 30_000, notices },
    );
    expect(resolution.lineage.source).toBe("crutch");
    expect(notices).toHaveLength(0);
  });

  test("resolveSessionLineage stays flat on an abstention and never throws", () => {
    seed({ sessionId: "s-a", atMs: T0 });
    seed({ sessionId: "s-b", atMs: T0 + 10_000 });
    expect(
      resolveSessionLineage(
        { sessionId: "s-new", cwd: "/work" },
        { ledger: readLineageLedger(tmp), nowMs: T0 + 30_000 },
      ),
    ).toEqual({ rootId: "s-new", parentId: null, depth: 0, source: "flat" });
  });
});

// ----- a dropped observation is still the session's own history ------------

describe("resolveCrutchLineage — a DROPPED observation cannot become a FALSE STITCH", () => {
  /**
   * Rule 1 ("a session with its own ledger history is parallel, never a
   * continuation") is tested by the presence of the session's own ledger
   * line. A writer-lock drop removes exactly that evidence, so without
   * the gap sidecar the resolver reads a session that DID speak as one
   * that never has - and stitches it onto an unrelated parallel session.
   * A false stitch is strictly worse than a missed one, and the
   * anticipatory cache derives its file from the lineage root, so this
   * redirects one conversation's cache into another's.
   */
  function dropObservation(sessionId: string, atMs: number): void {
    const handle = acquireLockSync(sessionLineageLedgerPath(tmp));
    try {
      const result = recordLineageObservation(tmp, {
        sessionId,
        at: new Date(atMs).toISOString(),
        cwd: "/work",
        event: "Stop",
      });
      expect(result.status).toBe(LINEAGE_RECORD_STATUS.dropped);
    } finally {
      handle.release();
    }
  }

  test("a session whose only observation was dropped abstains with self-known", () => {
    seed({ sessionId: "s-parallel", atMs: T0 });
    dropObservation("s-spoke", T0 + 5_000);
    expect(readLineageLedger(tmp).has("s-spoke")).toBe(false);

    const result = outcome("s-spoke", { gapSessionIds: lineageGapSessionIds(tmp) });
    expect(result).toMatchObject({
      kind: "abstained",
      reason: CRUTCH_ABSTENTION.selfKnown,
    });
  });

  test("without the gap set the same ledger produces the false stitch", () => {
    // Pins WHY the observation has to be threaded: the ledger alone
    // cannot tell "never spoke" from "spoke and was dropped".
    seed({ sessionId: "s-parallel", atMs: T0 });
    dropObservation("s-spoke", T0 + 5_000);
    expect(outcome("s-spoke").kind).toBe("linked");
  });

  test("a session with no gap and no history still links normally", () => {
    seed({ sessionId: "s-parallel", atMs: T0 });
    dropObservation("s-spoke", T0 + 5_000);
    const result = outcome("s-fresh", { gapSessionIds: lineageGapSessionIds(tmp) });
    expect(result.kind).toBe("linked");
  });

  test("resolveSessionLineageDetailed threads the gap set through", () => {
    seed({ sessionId: "s-parallel", atMs: T0 });
    dropObservation("s-spoke", T0 + 5_000);
    const resolution = resolveSessionLineageDetailed(
      { sessionId: "s-spoke", cwd: "/work" },
      {
        ledger: readLineageLedger(tmp),
        gapSessionIds: lineageGapSessionIds(tmp),
        nowMs: T0 + 30_000,
      },
    );
    expect(resolution.lineage.source).toBe("flat");
    expect(resolution.crutch).toMatchObject({ reason: CRUTCH_ABSTENTION.selfKnown });
  });
});

// ----- the hook path -------------------------------------------------------

describe("captureSessionLifecycleEvent — fail-closed, fail-soft, credential-free", () => {
  let vault: string;
  let repo: string;

  beforeEach(() => {
    vault = join(tmp, "vault");
    // A legacy Brain/ tree: an unswitched machine (a vault without one is store-only).
    mkdirSync(join(vault, "Brain"), { recursive: true });
    bootstrapBrain(vault);
    repo = initRepo(join(tmp, "repo"), { remote: SECRET_REMOTE });
  });

  test("stamps the canonical workspace identity onto the ledger observation", async () => {
    await captureSessionLifecycleEvent(
      vault,
      { hook_event_name: "UserPromptSubmit", session_id: "g-1", cwd: repo, prompt: "hi" },
      { agent: "tester", now: new Date(T0) },
    );
    const entry = readLineageLedger(vault).get("g-1");
    expect(entry?.workspace?.repo).toBe(SECRET_REMOTE_IDENTITY);
    expect(entry?.workspace?.commit).toMatch(/^[0-9a-f]{40}$/);
  });

  test("the clone credential never reaches the ledger file", async () => {
    await captureSessionLifecycleEvent(
      vault,
      { hook_event_name: "UserPromptSubmit", session_id: "g-2", cwd: repo, prompt: "hi" },
      { agent: "tester", now: new Date(T0) },
    );
    const raw = readFileSync(sessionLineageLedgerPath(vault), "utf8");
    expect(raw.includes("s3cr3t-token")).toBe(false);
    expect(raw.includes("alice")).toBe(false);
  });

  test("stitches within one repository state and REFUSES after a new commit", async () => {
    await captureSessionLifecycleEvent(
      vault,
      { hook_event_name: "PostCompact", session_id: "g-old", cwd: repo },
      { agent: "tester", now: new Date(T0) },
    );
    const linked = await captureSessionLifecycleEvent(
      vault,
      { hook_event_name: "UserPromptSubmit", session_id: "g-mid", cwd: repo, prompt: "go" },
      { agent: "tester", now: new Date(T0 + 60_000) },
    );
    expect(linked.lineage?.source).toBe("crutch");

    await captureSessionLifecycleEvent(
      vault,
      { hook_event_name: "PostCompact", session_id: "g-mid", cwd: repo },
      { agent: "tester", now: new Date(T0 + 70_000) },
    );
    commitAgain(repo, "moved on\n");
    const refused = await captureSessionLifecycleEvent(
      vault,
      { hook_event_name: "UserPromptSubmit", session_id: "g-next", cwd: repo, prompt: "go" },
      { agent: "tester", now: new Date(T0 + 80_000) },
    );
    expect("lineage" in refused).toBe(false);
  });

  test("two concurrent sessions in one repository state both abstain", async () => {
    // Two conversations running side by side in one working tree: each
    // is already known to the ledger before either compacts, so neither
    // is the other's continuation, and both compact inside the window.
    // Sequential by construction: the ledger state each call observes is
    // the state the previous call left behind, so these cannot be
    // collapsed into a parallel await.
    const capture = (payload: Record<string, unknown>, atMs: number): Promise<unknown> =>
      captureSessionLifecycleEvent(vault, payload, {
        agent: "tester",
        now: new Date(atMs),
      });
    await capture(
      { hook_event_name: "UserPromptSubmit", session_id: "c-a", cwd: repo, prompt: "work" },
      T0,
    );
    await capture(
      { hook_event_name: "UserPromptSubmit", session_id: "c-b", cwd: repo, prompt: "work" },
      T0,
    );
    await capture({ hook_event_name: "PostCompact", session_id: "c-a", cwd: repo }, T0 + 10_000);
    await capture({ hook_event_name: "PostCompact", session_id: "c-b", cwd: repo }, T0 + 10_000);
    const result = await captureSessionLifecycleEvent(
      vault,
      { hook_event_name: "UserPromptSubmit", session_id: "c-new", cwd: repo, prompt: "go" },
      { agent: "tester", now: new Date(T0 + 60_000) },
    );
    expect("lineage" in result).toBe(false);
    // The refusal is not merely silent-and-flat: it is on the record.
    const audit = readFileSync(result.audit_path!, "utf8");
    expect(audit).toContain(DEGRADATION_CODE.sessionLinkAbstained);
    expect(audit).toContain(CRUTCH_ABSTENTION.ambiguous);
  });

  test("a dropped observation reaches the audit record instead of being discarded", async () => {
    // `recordLineageObservation` returns a NAMED notice when the writer
    // lock refuses the append; the call site used to be a bare statement
    // that threw it away, which is a silent failure with extra steps.
    const handle = acquireLockSync(sessionLineageLedgerPath(vault));
    let result;
    try {
      result = await captureSessionLifecycleEvent(
        vault,
        { hook_event_name: "UserPromptSubmit", session_id: "d-1", cwd: repo, prompt: "hi" },
        { agent: "tester", now: new Date(T0) },
      );
    } finally {
      handle.release();
    }
    const audit = JSON.parse(
      readFileSync(result.audit_path!, "utf8").trim().split("\n").at(-1)!,
    ) as { details: Record<string, unknown> };
    const dropped = audit.details["lineage_dropped"] as string[];
    expect(dropped).toBeDefined();
    expect(dropped[0]).toContain(DEGRADATION_CODE.lineageObservationDropped);
    expect(dropped[0]).toContain("d-1");
  });

  test("a successful append leaves the audit shape unchanged", async () => {
    const result = await captureSessionLifecycleEvent(
      vault,
      { hook_event_name: "UserPromptSubmit", session_id: "d-2", cwd: repo, prompt: "hi" },
      { agent: "tester", now: new Date(T0) },
    );
    expect(readFileSync(result.audit_path!, "utf8")).not.toContain("lineage_dropped");
  });
});