Keep agent state layout self-contained and safely ignored (#123)

FileSnapshotStore now accepts a top-level state directory, resolves it at construction time, owns the <root>/sessions layout, and best-effort appends that root to the containing worktree's .gitignore. Consumers no longer precompute sessions directories or maintain ignore entries independently.

This keeps session storage stable even if process.cwd() changes after store construction, and it aligns the shipped release notes with the public rootDir/sessionsDir getter contract.

Constraint: Preserve #124's edge-safe runtime import changes while rebasing onto current main

Rejected: Leave relative rootDir values as-is | contradicted the resolved-path contract and made later cwd changes affect save/load paths

Confidence: high

Scope-risk: moderate

Directive: Do not reintroduce caller-managed /sessions paths without updating downstream env names and migration notes

Tested: pnpm run typecheck; pnpm run test; pnpm run build; pnpm run check

Not-tested: Live model-backed minimal-agent session

Author: minpeter

.changeset/file-snapshot-store-top-level-dir.md

@@ -0,0 +1,19 @@
+---
+"@ai-sdk-tool/harness": patch
+"@plugsuits/minimal-agent": patch
+"@plugsuits/tgbot": patch
+"plugsuits": patch
+---
+
+`FileSnapshotStore` now takes a top-level directory (e.g. `.plugsuits`, `.minimal-agent`) and manages its internal layout itself: session snapshots land in `<root>/sessions/*.jsonl`. The public `rootDir` / `sessionsDir` getters expose the resolved paths for consumers that want to co-locate related files (e.g. session memory).
+
+When the root directory lives inside a git worktree (detected by a sibling `.git` marker, directory or file), the store appends the top-level directory to that worktree's `.gitignore` if not already listed. The update is concurrency-safe: an exclusive `.gitignore.lock` (via `openSync(path, "wx")`) serializes writers, and the content swap is atomic (temp-file + rename). Stale locks older than 30s are reclaimed so a crashed writer can't wedge the next caller. The file's existing line-ending convention is preserved (LF or CRLF), and the helper refuses to write to any ancestor `.gitignore` that is not at a verified worktree root — so it cannot accidentally modify a parent repo's or a user's home-level ignore file. Disable with `new FileSnapshotStore(dir, { autoGitignore: false })`.
+
+Env var migrations (no backward compatibility):
+
+- `minimal-agent`: `SESSION_DIR` → `MINIMAL_AGENT_DIR` (default `.minimal-agent`)
+- `tgbot`: `SESSION_DIR` → `TGBOT_DIR` (default `<tmpdir>/tgbot`)
+
+CEA now constructs its store with `.plugsuits` as the top-level directory and derives its session-memory path from `store.sessionsDir`.
+
+The previously-undocumented `getFilePath` fallback for unencoded session filenames has been removed; session files always live at `<sessionsDir>/<encodeSessionId(sessionId)>.jsonl`.

AGENTS.md

@@ -120,7 +120,17 @@ const history = new CheckpointHistory({ compaction: {...} });
 
 // 2. File-persisted (recommended for most consumers)
 import { FileSnapshotStore } from "@ai-sdk-tool/harness/sessions";
-const store = new FileSnapshotStore(".plugsuits/sessions");
+// Pass a top-level directory (e.g. ".plugsuits", ".minimal-agent").
+// The store manages its internal layout: <root>/sessions/*.jsonl
+// Auto-gitignore: when the root dir lives inside a git worktree (detected by
+// a sibling `.git` marker, dir or file), the store appends the top-level dir
+// to that worktree's `.gitignore` if not already listed. The update is atomic
+// (lockfile + temp-file rename) and preserves LF/CRLF line endings. It
+// refuses to modify any ancestor `.gitignore` that is not at a verified
+// worktree root. Disable with `{ autoGitignore: false }`.
+const store = new FileSnapshotStore(".plugsuits");
+// store.sessionsDir is resolved, e.g. "<cwd>/.plugsuits/sessions"
+// (use for co-located files).
 const history = await CheckpointHistory.fromSnapshot(store, sessionId, { compaction });
 // After each turn — caller decides when:
 await store.save(sessionId, history.snapshot());

packages/cea/src/entrypoints/main.ts

@@ -1,4 +1,4 @@
-import { mkdirSync, readFileSync } from "node:fs";
+import { readFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 import {
@@ -142,16 +142,14 @@ if (!sessionManagerScope.__ceaSessionManager) {
   sessionManagerScope.__ceaSessionManager = new SessionManager();
 }
 const sessionManager = sessionManagerScope.__ceaSessionManager;
-const sessionStoreBaseDir = join(process.cwd(), ".plugsuits", "sessions");
-mkdirSync(sessionStoreBaseDir, { recursive: true });
-const store = new FileSnapshotStore(sessionStoreBaseDir);
+const store = new FileSnapshotStore(join(process.cwd(), ".plugsuits"));
 const userPreferencesBundle = createUserPreferencesStore();
 configurePreferencesPersistence({
   bundle: userPreferencesBundle.bundle,
   workspaceStore: userPreferencesBundle.workspaceStore,
 });
 const resolveSessionMemoryStorePath = (sessionId: string): string =>
-  join(sessionStoreBaseDir, sessionId, "session-memory.md");
+  join(store.sessionsDir, sessionId, "session-memory.md");
 const createSessionMemoryStore = (sessionId: string): FileMemoryStore =>
   new FileMemoryStore(resolveSessionMemoryStorePath(sessionId));
 let messageHistory: CheckpointHistory;

packages/harness/README.md

@@ -38,7 +38,7 @@ const assistant = defineAgent({
 const runtime = await createAgentRuntime({
   name: "my-assistant",
   agents: [assistant],
-  persistence: { snapshotStore: new FileSnapshotStore(".sessions") },
+  persistence: { snapshotStore: new FileSnapshotStore(".my-assistant") },
 });
 
 const session = await runtime.openSession();

packages/harness/src/file-snapshot-store.test.ts

@@ -1,4 +1,13 @@
-import { appendFileSync, mkdtempSync, rmSync } from "node:fs";
+import {
+  appendFileSync,
+  existsSync,
+  mkdirSync,
+  mkdtempSync,
+  readFileSync,
+  realpathSync,
+  rmSync,
+  writeFileSync,
+} from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { afterEach, beforeEach, describe, expect, it } from "vitest";
@@ -11,7 +20,7 @@ describe("FileSnapshotStore", () => {
 
   beforeEach(() => {
     tmpDir = mkdtempSync(join(tmpdir(), "file-snapshot-store-test-"));
-    store = new FileSnapshotStore(tmpDir);
+    store = new FileSnapshotStore(tmpDir, { autoGitignore: false });
   });
 
   afterEach(() => {
@@ -180,9 +189,9 @@ describe("FileSnapshotStore", () => {
     });
   });
 
-  it("loads existing legacy JSONL sessions", async () => {
-    const sessionId = "legacy_session";
-    const filePath = join(tmpDir, `${sessionId}.jsonl`);
+  it("loads existing JSONL sessions written in legacy line formats", async () => {
+    const sessionId = "legacy-session";
+    const filePath = join(tmpDir, "sessions", `${sessionId}.jsonl`);
 
     appendFileSync(
       filePath,
@@ -223,6 +232,98 @@ describe("FileSnapshotStore", () => {
     });
   });
 
+  it("exposes rootDir and sessionsDir paths", () => {
+    expect(store.rootDir).toBe(tmpDir);
+    expect(store.sessionsDir).toBe(join(tmpDir, "sessions"));
+    expect(existsSync(store.sessionsDir)).toBe(true);
+  });
+
+  it("resolves relative root dirs at construction time", async () => {
+    const originalCwd = process.cwd();
+    const worktree = realpathSync(
+      mkdtempSync(join(tmpdir(), "file-snapshot-relative-"))
+    );
+    const otherDir = realpathSync(
+      mkdtempSync(join(tmpdir(), "file-snapshot-other-"))
+    );
+    try {
+      process.chdir(worktree);
+      const relativeStore = new FileSnapshotStore(".state", {
+        autoGitignore: false,
+      });
+
+      expect(relativeStore.rootDir).toBe(join(worktree, ".state"));
+      expect(relativeStore.sessionsDir).toBe(
+        join(worktree, ".state", "sessions")
+      );
+
+      process.chdir(otherDir);
+      await relativeStore.save("session-abc", {
+        messages: [],
+        revision: 0,
+        contextLimit: 0,
+        systemPromptTokens: 0,
+        toolSchemasTokens: 0,
+      });
+
+      expect(
+        existsSync(join(worktree, ".state", "sessions", "session-abc.jsonl"))
+      ).toBe(true);
+      expect(
+        existsSync(join(otherDir, ".state", "sessions", "session-abc.jsonl"))
+      ).toBe(false);
+    } finally {
+      process.chdir(originalCwd);
+      rmSync(worktree, { recursive: true, force: true });
+      rmSync(otherDir, { recursive: true, force: true });
+    }
+  });
+
+  it("writes sessions into the <root>/sessions subdirectory", async () => {
+    const snapshot: HistorySnapshot = {
+      messages: [],
+      revision: 0,
+      contextLimit: 0,
+      systemPromptTokens: 0,
+      toolSchemasTokens: 0,
+    };
+    await store.save("session-abc", snapshot);
+
+    const sessionFile = join(tmpDir, "sessions", "session-abc.jsonl");
+    expect(existsSync(sessionFile)).toBe(true);
+  });
+
+  it("appends the top-level dir to the worktree .gitignore by default", () => {
+    const worktree = realpathSync(
+      mkdtempSync(join(tmpdir(), "file-snapshot-worktree-"))
+    );
+    try {
+      mkdirSync(join(worktree, ".git"));
+      const gitignorePath = join(worktree, ".gitignore");
+      writeFileSync(gitignorePath, "node_modules/\n", "utf8");
+      const root = join(worktree, ".test-store");
+      new FileSnapshotStore(root);
+      const contents = readFileSync(gitignorePath, "utf8");
+      expect(contents).toContain(".test-store");
+    } finally {
+      rmSync(worktree, { recursive: true, force: true });
+    }
+  });
+
+  it("skips gitignore update when root dir is outside any git worktree", () => {
+    const outside = realpathSync(
+      mkdtempSync(join(tmpdir(), "file-snapshot-no-repo-"))
+    );
+    try {
+      const gitignorePath = join(outside, ".gitignore");
+      writeFileSync(gitignorePath, "node_modules/\n", "utf8");
+      new FileSnapshotStore(join(outside, ".test-store"));
+      expect(readFileSync(gitignorePath, "utf8")).toBe("node_modules/\n");
+    } finally {
+      rmSync(outside, { recursive: true, force: true });
+    }
+  });
+
   it("writes snapshot atomically over existing content", async () => {
     await store.save("session", {
       messages: [

packages/harness/src/file-snapshot-store.ts

@@ -6,19 +6,38 @@ import {
   rmSync,
   writeFileSync,
 } from "node:fs";
-import { join } from "node:path";
+import { join, resolve } from "node:path";
 import type { MessageLine, SessionFileLine } from "./compaction-types";
+import { ensureDirIgnoredByGit } from "./gitignore-sync";
 import type { HistorySnapshot } from "./history-snapshot";
 import { encodeSessionId, type SessionData } from "./session-store";
 import type { SnapshotStore } from "./snapshot-store";
 import { createRuntimeUUID } from "./uuid";
 
+export const SESSIONS_SUBDIR = "sessions";
+
+export interface FileSnapshotStoreOptions {
+  /**
+   * When true (default), append the configured top-level directory to the
+   * nearest ancestor `.gitignore` if not already listed. Best-effort — never
+   * fails initialization. Set to `false` to disable, e.g. in tests or when
+   * writing outside of a git worktree on purpose.
+   */
+  autoGitignore?: boolean;
+}
+
 export class FileSnapshotStore implements SnapshotStore {
-  private readonly baseDir: string;
+  readonly rootDir: string;
+  readonly sessionsDir: string;
 
-  constructor(baseDir: string) {
-    mkdirSync(baseDir, { recursive: true });
-    this.baseDir = baseDir;
+  constructor(rootDir: string, options: FileSnapshotStoreOptions = {}) {
+    this.rootDir = resolve(rootDir);
+    this.sessionsDir = join(this.rootDir, SESSIONS_SUBDIR);
+    mkdirSync(this.sessionsDir, { recursive: true });
+
+    if (options.autoGitignore !== false) {
+      ensureDirIgnoredByGit(this.rootDir);
+    }
   }
 
   load(sessionId: string): Promise<HistorySnapshot | null> {
@@ -109,17 +128,7 @@ export class FileSnapshotStore implements SnapshotStore {
 
   private getFilePath(sessionId: string): string {
     const encoded = encodeSessionId(sessionId);
-    const primary = join(this.baseDir, `${encoded}.jsonl`);
-    if (existsSync(primary)) {
-      return primary;
-    }
-
-    const legacy = join(this.baseDir, `${sessionId}.jsonl`);
-    if (existsSync(legacy)) {
-      return legacy;
-    }
-
-    return primary;
+    return join(this.sessionsDir, `${encoded}.jsonl`);
   }
 
   private loadSession(sessionId: string): SessionData | null {

packages/harness/src/gitignore-sync.concurrent-worker.mjs

@@ -0,0 +1,9 @@
+import { ensureGitignoreEntry } from "./gitignore-sync.ts";
+
+const [, , gitignorePath, entry] = process.argv;
+if (!(gitignorePath && entry)) {
+  process.exit(2);
+}
+
+ensureGitignoreEntry(gitignorePath, entry);
+process.exit(0);