@opendash-ai/cli 0.1.0-beta.1

package/test/server/workflows-route.test.ts

@@ -0,0 +1,363 @@
+import { afterEach, describe, expect, test } from "bun:test"
+import { Effect, Exit, Cause } from "effect"
+import { Log } from "../../src/util"
+import { Instance } from "../../src/project/instance"
+import { Server } from "../../src/server/server"
+import { Session } from "../../src/session"
+import { WorkflowPersistence } from "../../src/workflow/persistence"
+import { WorkflowRuntime } from "../../src/workflow/runtime"
+import { workflowRef } from "../../src/workflow/runtime-ref"
+import { provideTmpdirServer, tmpdir } from "../fixture/fixture"
+import { testEffect } from "../lib/effect"
+import { makeLayer, ref, providerCfg } from "../workflow/lib"
+
+void Log.init({ print: false })
+
+afterEach(async () => {
+  workflowRef.current = undefined
+  await Instance.disposeAll()
+})
+
+describe("workflows routes", () => {
+  test("GET /workflows returns [] when the workflow runtime is not running", async () => {
+    await using tmp = await tmpdir({ git: true })
+    await Instance.provide({
+      directory: tmp.path,
+      fn: async () => {
+        // #given the workflow runtime layer is not running (late-bound ref unset)
+        workflowRef.current = undefined
+
+        // #when — a valid session-shaped sessionID (now REQUIRED) is supplied
+        const app = Server.Default().app
+        const response = await app.request("/workflows?sessionID=ses_16ec185f2ffexEGkbWeMqWSucv", { method: "GET" })
+
+        // #then — runtime absent short-circuits to [] (the session passes validation)
+        expect(response.status).toBe(200)
+        expect(await response.json()).toEqual([])
+      },
+    })
+  })
+
+  test("POST /workflows/:runID/resume returns { resumed: false } when the runtime is not running", async () => {
+    await using tmp = await tmpdir({ git: true })
+    await Instance.provide({
+      directory: tmp.path,
+      fn: async () => {
+        // #given the workflow runtime layer is not running
+        workflowRef.current = undefined
+
+        // #when — a real minted-shape runID (wf_ + 26 base62) with no persisted run
+        const app = Server.Default().app
+        const response = await app.request("/workflows/wf_16ec185f2ffexEGkbWeMqWSucv/resume", { method: "POST" })
+
+        // #then
+        expect(response.status).toBe(200)
+        expect(await response.json()).toEqual({ runID: "wf_16ec185f2ffexEGkbWeMqWSucv", resumed: false })
+      },
+    })
+  })
+
+  // ── P0 (MR104 #3): path traversal via unvalidated runID ──────────────────
+  // resume(runID) → readScript(runID) → scriptPath = join(scriptDir, runID + ".js").
+  // A traversal runID escapes scriptDir, so the route MUST reject any runID that
+  // is not exactly `wf_` + base62. The proof is that the request is REFUSED at the
+  // route's param validator (400) — it never reaches the runtime/launch, so no file
+  // outside scriptDir is ever opened.
+  for (const evil of [
+    "../../../etc/passwd",
+    "../../foo",
+    "/etc/passwd",
+    "wf_../../../etc/passwd", // defeats a prefix-only (startsWith "wf") check
+    "wf_..", // bare dot-dot after a legit prefix
+  ]) {
+    test(`POST /workflows/:runID/resume REJECTS traversal runID ${JSON.stringify(evil)}`, async () => {
+      await using tmp = await tmpdir({ git: true })
+      await Instance.provide({
+        directory: tmp.path,
+        fn: async () => {
+          // #given the runtime is absent — so if validation let this through it would
+          // hit the early `{ resumed: false }`; the only way to a 400 is param rejection.
+          workflowRef.current = undefined
+
+          // #when
+          const app = Server.Default().app
+          const response = await app.request(`/workflows/${encodeURIComponent(evil)}/resume`, { method: "POST" })
+
+          // #then — rejected by the param validator before any path.join / file read.
+          expect(response.status).toBe(400)
+        },
+      })
+    })
+  }
+
+  // ── Regression: read routes must accept a NESTED child runID ──────────────
+  // A top-level run is `wf_` + 26 base62; a nested workflow() child is `wf_` + 64
+  // hex (sha256). The transcript/structure routes previously validated only the
+  // 26-char form, so every nested-workflow detail page got a 400 and rendered blank.
+  // The routes short-circuit to empty when the runtime is absent, so a 200 here
+  // proves the param validator ACCEPTED the 64-hex id (a regression would 400).
+  const childRunID = "wf_" + "a".repeat(64)
+  for (const path of [`/workflows/${childRunID}/transcript`, `/workflows/${childRunID}/structure`]) {
+    test(`GET ${path} accepts a 64-hex child runID (200, not 400)`, async () => {
+      await using tmp = await tmpdir({ git: true })
+      await Instance.provide({
+        directory: tmp.path,
+        fn: async () => {
+          workflowRef.current = undefined
+          const response = await Server.Default().app.request(path, { method: "GET" })
+          expect(response.status).toBe(200)
+        },
+      })
+    })
+  }
+
+  for (const path of ["/workflows/wf_..%2F..%2Fetc/transcript", "/workflows/not-a-run/structure"]) {
+    test(`GET ${path} still REJECTS a malformed runID (400)`, async () => {
+      await using tmp = await tmpdir({ git: true })
+      await Instance.provide({
+        directory: tmp.path,
+        fn: async () => {
+          workflowRef.current = undefined
+          const response = await Server.Default().app.request(path, { method: "GET" })
+          expect(response.status).toBe(400)
+        },
+      })
+    })
+  }
+
+  // ── P0 (MR104 #3): GET /workflows must NOT leak all-session runs ──────────
+  test("GET /workflows with NO sessionID returns 400 (does not list all runs)", async () => {
+    await using tmp = await tmpdir({ git: true })
+    await Instance.provide({
+      directory: tmp.path,
+      fn: async () => {
+        // #given a live-enough runtime is irrelevant: the missing required query param
+        // is rejected at the validator. (Keep it unset so a regression that drops the
+        // requirement would surface as a 200 [] rather than passing by accident.)
+        workflowRef.current = undefined
+
+        // #when — omit sessionID entirely
+        const app = Server.Default().app
+        const response = await app.request("/workflows", { method: "GET" })
+
+        // #then — rejected, NOT a 200 with the unfiltered all-runs branch.
+        expect(response.status).toBe(400)
+      },
+    })
+  })
+
+  test("GET /workflows with a non-session-shaped sessionID returns 400", async () => {
+    await using tmp = await tmpdir({ git: true })
+    await Instance.provide({
+      directory: tmp.path,
+      fn: async () => {
+        workflowRef.current = undefined
+        const app = Server.Default().app
+        const response = await app.request("/workflows?sessionID=not-a-session", { method: "GET" })
+        expect(response.status).toBe(400)
+      },
+    })
+  })
+
+  // ── P0 (MR104 #3): defense-in-depth at the persistence layer ──────────────
+  // readScript / journal IO are reachable from the tool + TUI, not only the HTTP
+  // route, so the persistence path functions must themselves refuse a traversal
+  // runID. A direct readScript("../../../etc/passwd") must FAIL (the guard throws,
+  // surfacing as an Effect defect) rather than open a file outside scriptDir.
+  test("WorkflowPersistence.readScript fails safely on a traversal runID (no out-of-dir read)", async () => {
+    await using tmp = await tmpdir({ git: true })
+    await Instance.provide({
+      directory: tmp.path,
+      fn: async () => {
+        const exit = await Effect.runPromiseExit(WorkflowPersistence.readScript("../../../etc/passwd"))
+        // #then — the GUARD must reject it. Asserting only Exit.isFailure would
+        // also pass against unguarded code (ENOENT on `…/etc/passwd.js`), so assert
+        // the failure carries the guard's message — this fails closed if safeRunID
+        // is ever removed.
+        expect(Exit.isFailure(exit)).toBe(true)
+        if (Exit.isFailure(exit)) {
+          expect(Cause.pretty(exit.cause)).toContain("invalid workflow runID")
+        }
+      },
+    })
+  })
+
+  test("WorkflowPersistence.readScript still reads a legit wf_ runID", async () => {
+    await using tmp = await tmpdir({ git: true })
+    await Instance.provide({
+      directory: tmp.path,
+      fn: async () => {
+        // #given a normally-minted runID with a persisted script
+        const runID = "wf_16ec185f2ffexEGkbWeMqWSucv"
+        await Effect.runPromise(WorkflowPersistence.writeScript(runID, "export const meta = {}\n"))
+        // #then — the guard does NOT break the legit path
+        const body = await Effect.runPromise(WorkflowPersistence.readScript(runID))
+        expect(body).toContain("export const meta")
+      },
+    })
+  })
+})
+
+// The LIVE path the TUI /workflows dialog consumes: the route returns REAL run
+// data (not the degenerate []). These run under the workflow test layer
+// (makeLayer) so WorkflowRuntime.layer is live and populates the module-global
+// `workflowRef` that the route reads through. Crucially the data path is the
+// process-global `:memory:` DB (test/preload sets OPENDASH_DB=:memory:, and the
+// storage Client is a per-process singleton): the run writes its WorkflowRunTable
+// row there, and the route's handler — run via AppRuntime, NOT this layer — reads
+// the SAME DB. So `Server.Default().app.request("/workflows")` genuinely
+// exercises the HTTP route end-to-end against a real run. The
+// `x-opendash-directory` header makes InstanceMiddleware re-enter the SAME cached
+// tmpdir Instance the run used (one entry per directory in Instance's cache), so
+// resume's re-launch spawns in the run's own session context. We filter list by
+// sessionID to stay robust against any residue in the shared in-memory DB.
+const it = testEffect(makeLayer())
+
+// Test ORDER is deliberate: the sandbox-free resume test runs FIRST and the
+// agent-spawning list test runs LAST. An agent() run forks a quickjs sandbox
+// (evalScript) whose teardown is CPU-sensitive — under load the 1ms pump interval
+// can starve, leaving the forked fiber uninterruptible at scope close (the
+// pre-existing quickjs-under-Bun condition; see runtime.test.ts). Keeping the only
+// sandbox-bearing test last means its residue has no following evalScript test to
+// destabilize. Verified 0 flakes across 16 process runs UNDER heavy CPU contention
+// in this order; the reverse order flakes ~30%+.
+//
+// NOTE on resume coverage: we assert the resume route over a LIVE runtime returns
+// the real { resumed: false } for an unknown run — this proves the route reaches
+// the live `runtime.resume()` (distinct from the degenerate case above, where the
+// runtime is absent and the route short-circuits before calling resume). We do NOT
+// add an HTTP test for the positive { resumed: true } re-launch: a successful
+// resume forks a fresh evalScript whose teardown deadlocks under CI CPU load
+// regardless of how it is driven (HTTP or the service directly) — a runtime/sandbox
+// limitation we cannot fix from a test. The re-launch semantics (resumed: true,
+// cached replay, zero-spawn resume) are covered in the warmed-up
+// test/workflow/runtime.test.ts suite.
+describe("workflows routes — live runtime", () => {
+  it.live("POST /workflows/:runID/resume reaches the LIVE runtime (resumed: false for an unknown run)", () =>
+    provideTmpdirServer(
+      Effect.fnUntraced(function* ({ dir }) {
+        // #given the workflow runtime IS live (the layer set the late-bound ref) —
+        // this is what distinguishes this from the degenerate test above, where the
+        // ref is undefined and the route returns early without calling resume().
+        expect(workflowRef.current).toBeDefined()
+
+        // #when — POST resume over the REAL route for a runID with no persisted run.
+        // Use a valid minted-shape runID (wf_ + 26 base62) so it passes the param
+        // validator and genuinely reaches the live runtime.resume(), which loads no
+        // row and returns { resumed: false }. (async wrapper normalizes Hono's
+        // `Promise<Response> | Response` overload for Effect.promise.)
+        const response = yield* Effect.promise(async () =>
+          Server.Default().app.request(`/workflows/wf_00000000000000000000000000/resume`, {
+            method: "POST",
+            headers: { "x-opendash-directory": dir },
+          }),
+        )
+
+        // #then — the live runtime's real verdict flows back through the HTTP route.
+        expect(response.status).toBe(200)
+        expect(yield* Effect.promise(() => response.json())).toEqual({
+          runID: "wf_00000000000000000000000000",
+          resumed: false,
+        })
+      }),
+      { git: true, config: providerCfg },
+    ),
+  )
+
+  it.live("GET /workflows returns a live run with real status + counters", () =>
+    provideTmpdirServer(
+      Effect.fnUntraced(function* ({ dir, llm }) {
+        const runtime = yield* WorkflowRuntime.Service
+        const session = yield* Session.Service
+        const parent = yield* session.create({
+          title: "wf route live",
+          permission: [{ permission: "*", pattern: "*", action: "allow" }],
+        })
+        yield* llm.text("done") // one reply for the single agent() spawn
+        const script = [`export const meta = { name: "t", description: "d" }`, `return await agent("x")`].join("\n")
+        const { runID } = yield* runtime.start({ script, sessionID: parent.id, parentActorID: "main", model: ref })
+        const outcome = yield* runtime.wait({ runID, timeoutMs: 8000 })
+        expect(outcome.status).toBe("completed")
+
+        // #when — drive the REAL HTTP route the TUI list reads. The directory header
+        // makes InstanceMiddleware re-enter the same cached tmpdir Instance the run
+        // used; sessionID scopes to this run. app.request's Hono overload is
+        // `Promise<Response> | Response`, so the async wrapper normalizes it to a
+        // Promise for Effect.promise.
+        const response = yield* Effect.promise(async () =>
+          Server.Default().app.request(`/workflows?sessionID=${parent.id}`, {
+            method: "GET",
+            headers: { "x-opendash-directory": dir },
+          }),
+        )
+        expect(response.status).toBe(200)
+        const rows = (yield* Effect.promise(() => response.json())) as Array<{
+          runID: string
+          status: string
+          succeeded: number
+        }>
+
+        // #then — the live run is visible over HTTP with its real fields: this is
+        // the exact data path the TUI /workflows list reads (counter from a real spawn).
+        const row = rows.find((r) => r.runID === runID)
+        expect(row).toBeDefined()
+        expect(row!.status).toBe("completed")
+        expect(row!.succeeded).toBeGreaterThanOrEqual(1)
+      }),
+      { git: true, config: providerCfg },
+    ),
+    // Headroom over the default 5s: this exercises a full Instance bootstrap +
+    // a real runtime run + an HTTP round-trip, and runs alongside the heavy
+    // live workflow/server suites where CI load can push past 5s.
+    15000,
+  )
+
+  it.live("GET /workflows/:runID/transcript and /structure return the run's full data", () =>
+    provideTmpdirServer(
+      Effect.fnUntraced(function* ({ dir, llm }) {
+        const runtime = yield* WorkflowRuntime.Service
+        const session = yield* Session.Service
+        const parent = yield* session.create({
+          title: "wf route detail",
+          permission: [{ permission: "*", pattern: "*", action: "allow" }],
+        })
+        yield* llm.text("done")
+        const script = [
+          `export const meta = { name: "t", description: "d" }`,
+          `phase("Plan")`,
+          `return await agent("x")`,
+        ].join("\n")
+        const { runID } = yield* runtime.start({ script, sessionID: parent.id, parentActorID: "main", model: ref })
+        const outcome = yield* runtime.wait({ runID, timeoutMs: 8000 })
+        expect(outcome.status).toBe("completed")
+
+        const tRes = yield* Effect.promise(async () =>
+          Server.Default().app.request(`/workflows/${runID}/transcript`, {
+            method: "GET",
+            headers: { "x-opendash-directory": dir },
+          }),
+        )
+        expect(tRes.status).toBe(200)
+        const tBody = (yield* Effect.promise(() => tRes.json())) as {
+          runID: string
+          transcript: { kind: string; text: string }[]
+        }
+        expect(tBody.runID).toBe(runID)
+        expect(tBody.transcript.some((e) => e.kind === "phase")).toBe(true)
+
+        const sRes = yield* Effect.promise(async () =>
+          Server.Default().app.request(`/workflows/${runID}/structure`, {
+            method: "GET",
+            headers: { "x-opendash-directory": dir },
+          }),
+        )
+        expect(sRes.status).toBe(200)
+        const sBody = (yield* Effect.promise(() => sRes.json())) as { runID: string; nodes: { type: string }[] }
+        expect(sBody.runID).toBe(runID)
+        expect(sBody.nodes.some((n) => n.type === "agent")).toBe(true)
+      }),
+      { git: true, config: providerCfg },
+    ),
+    15000,
+  )
+})

package/test/session/bootstrap-skip-system.test.ts

@@ -0,0 +1,121 @@
+import { describe, expect, test } from "bun:test"
+import { Effect, Layer } from "effect"
+import * as fs from "fs/promises"
+import { Bus } from "../../src/bus"
+import { Config } from "../../src/config"
+import { Memory } from "../../src/memory"
+import { ActorRegistry } from "../../src/actor/registry"
+import { Actor } from "../../src/actor/spawn"
+import { TaskRegistry } from "../../src/task/registry"
+import { SessionCheckpoint } from "../../src/session/checkpoint"
+import { Log } from "../../src/util"
+import { provideTmpdirInstance } from "../fixture/fixture"
+import { Session as SessionNs } from "../../src/session"
+import { MessageID, PartID } from "../../src/session/schema"
+import { ProviderID, ModelID } from "../../src/provider/schema"
+import { checkpointPath } from "../../src/session/checkpoint-paths"
+import * as CrossSpawnSpawner from "../../src/effect/cross-spawn-spawner"
+
+void Log.init({ print: false })
+
+const ref = {
+  providerID: ProviderID.make("test"),
+  modelID: ModelID.make("test-model"),
+}
+
+const stubActorRegistry = Layer.succeed(
+  ActorRegistry.Service,
+  ActorRegistry.Service.of({
+    register: () => Effect.die("not used"),
+    updateStatus: () => Effect.void,
+    updateTurn: () => Effect.void,
+    get: () => Effect.succeed(undefined),
+    listBySession: () => Effect.succeed([]),
+    listActive: () => Effect.succeed([]),
+    listByParent: () => Effect.succeed([]),
+    renderForAgent: () => Effect.succeed(""),
+    agentTypeFor: () => Effect.succeed("main"),
+    // Force the guard inside tryStartCheckpointWriter to fire by always reporting true.
+    isSystemSpawned: () => Effect.succeed(true),
+    allocateActorID: () => Effect.die("not used"),
+  }),
+)
+
+// The system-spawn guard short-circuits before Actor.spawn is reached, so this
+// stub never gets called — but we still need to satisfy the SessionCheckpoint
+// layer's Actor.Service requirement at construction time.
+const stubActor = Layer.succeed(
+  Actor.Service,
+  Actor.Service.of({
+    spawn: () => Effect.die("Actor.spawn unexpectedly called in system-spawn skip path"),
+    cancel: () => Effect.die("Actor.cancel unexpectedly called in system-spawn skip path"),
+    getForkContext: () => Effect.succeed(undefined),
+  }),
+)
+
+const deps = Layer.mergeAll(
+  Bus.layer,
+  Config.defaultLayer,
+  Memory.defaultLayer,
+  TaskRegistry.defaultLayer,
+  stubActorRegistry,
+  stubActor,
+)
+
+const env = Layer.mergeAll(
+  SessionNs.defaultLayer,
+  CrossSpawnSpawner.defaultLayer,
+  SessionCheckpoint.layer.pipe(Layer.provide(SessionNs.defaultLayer), Layer.provideMerge(deps)),
+)
+
+describe("SessionCheckpoint.tryStartCheckpointWriter — system-spawn skip", () => {
+  test("returns 'skipped' and does NOT bootstrap checkpoint.md when isSystemSpawned=true", async () => {
+    await Effect.runPromise(
+      provideTmpdirInstance(() =>
+        Effect.gen(function* () {
+          const svc = yield* SessionCheckpoint.Service
+          const ssn = yield* SessionNs.Service
+          const info = yield* ssn.create({})
+
+          // Seed enough state that the empty-message guard would not fire — so
+          // we know it's the system-spawn guard short-circuiting the bootstrap.
+          const user = yield* ssn.updateMessage({
+            id: MessageID.ascending(),
+            role: "user",
+            sessionID: info.id,
+            agent: "build",
+            model: ref,
+            time: { created: Date.now() },
+          })
+          yield* ssn.updatePart({
+            id: PartID.ascending(),
+            messageID: user.id,
+            sessionID: info.id,
+            type: "text",
+            text: "seed",
+          })
+
+          const outcome = yield* svc.tryStartCheckpointWriter({
+            sessionID: info.id,
+            model: { providerID: "test", modelID: "test-model" },
+            promptOps: {} as any,
+          })
+          expect(outcome).toBe("skipped")
+
+          // Bootstrap helpers (ensureCheckpointTemplate / ensureMemoryTemplate)
+          // run AFTER the system-spawn guard. With the guard active, no
+          // checkpoint.md should appear on disk.
+          const cpPath = checkpointPath(info.id)
+          const exists = yield* Effect.promise(() =>
+            fs.stat(cpPath).then(() => true).catch(() => false),
+          )
+          expect(exists).toBe(false)
+
+          // Sanity: the writer table should not have been updated either.
+          const running = yield* svc.isWriterRunning(info.id)
+          expect(running).toBe(false)
+        }),
+      ).pipe(Effect.scoped, Effect.provide(env)),
+    )
+  })
+})

package/test/session/boundary.test.ts

@@ -0,0 +1,33 @@
+import { describe, expect, test } from "bun:test"
+import { adjustBoundaryForApiInvariants } from "../../src/session/boundary"
+
+type Msg = { role: "user" | "assistant" | "tool"; content: any[]; id?: string }
+
+describe("adjustBoundaryForApiInvariants", () => {
+  test("walks back to include tool_use when tool_result is in tail", () => {
+    const msgs: Msg[] = [
+      { role: "user", content: [{ type: "text", text: "hello" }] },
+      { role: "assistant", content: [{ type: "tool_use", id: "X", name: "read" }] },
+      { role: "tool", content: [{ type: "tool_result", tool_use_id: "X", text: "result" }] },
+      { role: "assistant", content: [{ type: "text", text: "done" }] },
+    ]
+    // Candidate boundary at idx=2 (tail starts with tool_result)
+    // Should walk back to idx=1 (include the tool_use)
+    expect(adjustBoundaryForApiInvariants(msgs, 2)).toBe(1)
+  })
+
+  test("returns boundary unchanged when no orphans", () => {
+    const msgs: Msg[] = [
+      { role: "user", content: [{ type: "text", text: "hi" }] },
+      { role: "assistant", content: [{ type: "text", text: "hi back" }] },
+      { role: "user", content: [{ type: "text", text: "more" }] },
+    ]
+    expect(adjustBoundaryForApiInvariants(msgs, 2)).toBe(2)
+  })
+
+  test("returns boundary unchanged when 0 or full length", () => {
+    const msgs: Msg[] = [{ role: "user", content: [] }]
+    expect(adjustBoundaryForApiInvariants(msgs, 0)).toBe(0)
+    expect(adjustBoundaryForApiInvariants(msgs, 1)).toBe(1)
+  })
+})

package/test/session/budgeted-read.test.ts

@@ -0,0 +1,74 @@
+import { describe, test, expect } from "bun:test"
+import { readBudgeted, readBudgetedSectionAware } from "../../src/session/budgeted-read"
+import * as fs from "fs/promises"
+import * as path from "path"
+import * as os from "os"
+
+describe("readBudgeted", () => {
+  const tmpDir = os.tmpdir()
+
+  test("returns full content when under budget", async () => {
+    const file = path.join(tmpDir, "budgeted-test-small.md")
+    await fs.writeFile(file, "short content")
+    const result = await readBudgeted(file, 1000)
+    expect(result?.truncated).toBe(false)
+    expect(result?.text).toBe("short content")
+  })
+
+  test("truncates with Read hint when over budget", async () => {
+    const file = path.join(tmpDir, "budgeted-test-large.md")
+    await fs.writeFile(file, "word ".repeat(5000)) // ~5000 tokens
+    const result = await readBudgeted(file, 100)
+    expect(result?.truncated).toBe(true)
+    expect(result?.text).toContain("Truncated at ~100 tokens")
+    expect(result?.text).toContain("Read(")
+    expect(result?.text).toContain("offset=")
+  })
+
+  test("returns undefined for missing file", async () => {
+    const result = await readBudgeted("/tmp/nonexistent-xyz.md", 1000)
+    expect(result).toBeUndefined()
+  })
+})
+
+describe("readBudgetedSectionAware", () => {
+  const tmpDir = os.tmpdir()
+
+  test("preserves all section headers when content truncated", async () => {
+    const file = path.join(tmpDir, "section-aware.md")
+    const content = `# Title
+## §1 Active intent
+_instruction_
+
+${"x ".repeat(2000)}
+
+## §2 Next action
+_instruction_
+
+short
+`
+    await fs.writeFile(file, content)
+    const result = await readBudgetedSectionAware(file, 100)
+    expect(result?.text).toContain("## §1 Active intent")
+    expect(result?.text).toContain("## §2 Next action")
+    expect(result?.text).toContain("_instruction_")
+  })
+
+  test("preserves spillover index lines (- See ...md) even when truncated", async () => {
+    const file = path.join(tmpDir, "spill-aware.md")
+    const content = `# Title
+## §7 Discovered knowledge
+_instruction_
+
+${"y ".repeat(3000)}
+- See checkpoint-lexer.md (15 items) — Position type, Token shape
+
+## §9 Live resources
+_instruction_
+short
+`
+    await fs.writeFile(file, content)
+    const result = await readBudgetedSectionAware(file, 100)
+    expect(result?.text).toContain("- See checkpoint-lexer.md")
+  })
+})

package/test/session/checkpoint-align.test.ts

@@ -0,0 +1,58 @@
+import { describe, expect, test } from "bun:test"
+import { alignToNonToolResultUser } from "../../src/session/checkpoint-align"
+
+// Minimal shape: alignToNonToolResultUser only needs `info.role` and
+// `parts[].type`. Use literal objects rather than full MessageV2.WithParts
+// — the helper should be schema-light.
+type Msg = {
+  info: { role: "user" | "assistant"; id: string }
+  parts: Array<{ type: string }>
+}
+
+const u = (id: string, partTypes: string[] = ["text"]): Msg => ({
+  info: { role: "user", id },
+  parts: partTypes.map((t) => ({ type: t })),
+})
+const a = (id: string, partTypes: string[] = ["text"]): Msg => ({
+  info: { role: "assistant", id },
+  parts: partTypes.map((t) => ({ type: t })),
+})
+
+describe("alignToNonToolResultUser", () => {
+  test("returns the input idx when it already points at a non-tool-result-only user", () => {
+    const msgs = [u("u1", ["text"]), a("a1"), u("u2", ["text"])]
+    expect(alignToNonToolResultUser(msgs, 2)).toBe(2)
+  })
+
+  test("walks back past assistant tool_use to the previous user", () => {
+    const msgs = [u("u1"), a("a1", ["tool_use"]), u("u2", ["tool_result"]), a("a2", ["text"])]
+    // idx=2 (u2 with tool_result-only parts) must back up to idx=0 (u1 plain text)
+    expect(alignToNonToolResultUser(msgs, 2)).toBe(0)
+  })
+
+  test("treats user message with mixed parts (tool_result + text) as valid", () => {
+    const msgs = [u("u1"), a("a1", ["tool_use"]), u("u2", ["tool_result", "text"])]
+    expect(alignToNonToolResultUser(msgs, 2)).toBe(2)
+  })
+
+  test("returns 0 when no qualifying message exists in [0, idx]", () => {
+    // Degenerate: only tool-result-only users + assistants
+    const msgs = [u("u1", ["tool_result"]), a("a1", ["tool_use"]), u("u2", ["tool_result"])]
+    expect(alignToNonToolResultUser(msgs, 2)).toBe(0)
+  })
+
+  test("returns idx itself when idx is past the end (empty delta intent)", () => {
+    const msgs = [u("u1"), a("a1")]
+    expect(alignToNonToolResultUser(msgs, 2)).toBe(2)
+  })
+
+  test("idx 0 with valid first message returns 0", () => {
+    const msgs = [u("u1")]
+    expect(alignToNonToolResultUser(msgs, 0)).toBe(0)
+  })
+
+  test("treats user with empty parts as valid (cannot be orphan tool_result)", () => {
+    const msgs: Msg[] = [u("u1", ["tool_result"]), a("a1", ["tool_use"]), { info: { role: "user", id: "u2" }, parts: [] }]
+    expect(alignToNonToolResultUser(msgs, 2)).toBe(2)
+  })
+})