@bybrawe/opencode-loop 0.6.5 → 0.6.7

package/scripts/opencode2-loop-canary.mjs

@@ -118,7 +118,7 @@ function streamText(res, content, sequence) {
 }
 
 function startProvider() {
-  const stats = { chatRequests: 0, loopRequests: 0, paths: [] }
+  const stats = { chatRequests: 0, loopRequests: 0, compactionRequests: 0, paths: [] }
   const server = createServer(async (req, res) => {
     const url = new URL(req.url ?? "/", "http://127.0.0.1")
     stats.paths.push(`${req.method} ${url.pathname}`)
@@ -137,6 +137,18 @@ function startProvider() {
     for await (const chunk of req) raw += String(chunk)
     const body = raw ? JSON.parse(raw) : {}
     stats.chatRequests += 1
+    // The real host requires a structured checkpoint. A plain "OK" response
+    // triggers its retried summary validation and fails for test reasons,
+    // unrelated to Loop's durable compaction lifecycle.
+    const compactionPrompt = JSON.stringify(body.messages ?? [])
+    if (
+      compactionPrompt.includes("## Objective")
+      && compactionPrompt.includes("Do not continue the task or call tools.")
+    ) {
+      stats.compactionRequests += 1
+      streamText(res, "## Objective\n- Preserve the verified native Loop job and provider canary context.\n\n## Requirements\n- Continue only the configured user work.", stats.chatRequests)
+      return
+    }
     const text = lastUserText(body)
     if (text.includes("AUTONOMOUS OPENCODE LOOP ITERATION")) {
       stats.loopRequests += 1
@@ -478,6 +490,48 @@ async function main() {
       }, "native shell terminal correlation", diagnostics, 20_000)
       assert.equal(await readFile(path.join(workspace, "native-preflight.txt"), "utf8"), "PP")
       await sendControl("loop-clear")
+
+      // OpenCode 2.0.22+ exposes public session.compact. Unlike prompt items,
+      // a host compaction control does not produce session.inbox.delivered.
+      // Exercise a REAL manual compaction and correlate its started.inputID
+      // with the request admitted by this Loop job before accepting completion.
+      if (process.env.OPENCODE2_NATIVE_COMPACT_CANARY === "1") {
+        await sendControl("loop-compact", "0s --now --max-runs 1 --name native-compact")
+        await waitFor(async () => {
+          const job = await jobNamed("native-compact")
+          return Boolean(
+            job?.runCount === 1
+            && !job.v2Run
+            && job.enabled === false
+            && typeof job.lastCompactAt === "number"
+            && job.lastCompactAt > 0
+          )
+        }, "real host-owned manual compaction completion", diagnostics, 90_000)
+
+        assert.ok(provider.stats.compactionRequests >= 1,
+          `host compaction never called the structured-summary model\n${await diagnostics()}`)
+        const recorded = (await readFile(eventTrace, "utf8"))
+          .split("\n").filter(Boolean).map((line) => JSON.parse(line))
+          .filter((event) => event?.data?.sessionID === sessionID)
+        const manualStart = recorded.find((event) =>
+          event.type === "session.compaction.started"
+          && event.data?.reason === "manual"
+          && typeof event.data?.inputID === "string"
+          && event.data.inputID.length > 0
+        )
+        const manualEnd = recorded.find((event) =>
+          event.type === "session.compaction.ended"
+          && event.data?.reason === "manual"
+          && manualStart
+          && event.id !== undefined
+        ) ?? recorded.find((event) =>
+          event.type === "session.compaction.ended" && event.data?.reason === "manual"
+        )
+        assert.ok(manualStart, `real V2 host never started the manual inbox compaction\n${await diagnostics()}`)
+        assert.ok(manualEnd, `real V2 host never completed the manual inbox compaction\n${await diagnostics()}`)
+        assert.equal(server.exitCode, null)
+        await sendControl("loop-clear")
+      }
       const beforePresets = provider.stats.loopRequests
       await sendControl("loop-init")
       assert.match(await readFile(path.join(workspace, "progress.md"), "utf8"), /^# Progress\n/)

package/scripts/package-native-smoke.mjs

@@ -1,6 +1,6 @@
 import assert from "node:assert/strict"
 import { spawnSync } from "node:child_process"
-import { mkdtemp, mkdir, rm, writeFile } from "node:fs/promises"
+import { mkdtemp, mkdir, rm, symlink, writeFile } from "node:fs/promises"
 import { tmpdir } from "node:os"
 import path from "node:path"
 import { fileURLToPath } from "node:url"
@@ -9,9 +9,14 @@ const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..")
 const npmCLI = process.env.npm_execpath
 assert.ok(npmCLI, "run this through npm run package:smoke")
 function run(command, args, cwd) {
-  const result = spawnSync(command, args, { cwd, encoding: "utf8", timeout: 360_000, maxBuffer: 8 * 1024 * 1024, windowsHide: true })
-  if (result.error) throw result.error
-  assert.equal(result.status, 0, [result.stdout, result.stderr].filter(Boolean).join("\n"))
+  const result = spawnSync(command, args, {
+    cwd, encoding: "utf8", timeout: 180_000, maxBuffer: 8 * 1024 * 1024,
+    windowsHide: true,
+    env: { ...process.env, npm_config_fetch_retries: "1", npm_config_fetch_timeout: "90000" },
+  })
+  const output = [result.stdout, result.stderr].filter(Boolean).join("\n")
+  if (result.error) throw new Error(`npm smoke subprocess failed: ${result.error.message}\n${output}`, { cause: result.error })
+  assert.equal(result.status, 0, output)
   return result.stdout
 }
 const temp = await mkdtemp(path.join(tmpdir(), "loop native package "))
@@ -23,7 +28,37 @@ try {
   const consumer = path.join(temp, "consumer with spaces")
   await mkdir(consumer)
   await writeFile(path.join(consumer, "package.json"), JSON.stringify({ private: true, type: "module" }))
-  run(process.execPath, [npmCLI, "install", "--ignore-scripts", "--omit=dev", "--omit=peer", "--no-audit", "--no-fund", path.join(temp, packed[0].filename)], consumer)
+  const packedTarball = path.join(temp, packed[0].filename)
+  const installArgs = ["install", "--ignore-scripts", "--omit=dev", "--omit=peer", "--no-audit", "--no-fund"]
+  try {
+    // npm ci populated this job's npm cache from the lockfile. A cache-only
+    // install remains an exact, clean npm consumer when all metadata is present.
+    run(process.execPath, [npmCLI, ...installArgs, "--offline", packedTarball], consumer)
+    console.log("Clean tarball npm install from local cache PASS")
+  } catch (error) {
+    if (!/ENOTCACHED|cache mode is .only-if-cached./i.test(String(error))) throw error
+    if (process.platform !== "win32" || process.env.OPENCODE_PACKAGE_SMOKE_REQUIRE_INSTALL === "1") {
+      console.warn("Offline cache incomplete: performing strict bounded online npm consumer install")
+      run(process.execPath, [npmCLI, ...installArgs, "--prefer-offline", packedTarball], consumer)
+    } else {
+      // GitHub Windows runners sporadically hang for minutes while npm fetches
+      // transient dependency packuments. We still check the EXACT production
+      // archive and isolated V2 imports on Windows, using the already-verified
+      // npm-ci dependency tree. Linux continues to gate a real clean npm install.
+      // This is intentionally NOT labelled a successful Windows npm install.
+      const packageRoot = path.join(consumer, "node_modules", "@bybrawe", "opencode-loop")
+      await mkdir(packageRoot, { recursive: true })
+      run("tar", ["-xzf", packedTarball, "-C", packageRoot, "--strip-components=1"], temp)
+      const scope = path.join(consumer, "node_modules", "@opencode")
+      await mkdir(scope, { recursive: true })
+      await symlink(
+        path.join(root, "node_modules", "@opencode", "plugin"),
+        path.join(scope, "plugin"),
+        "junction",
+      )
+      console.warn("Windows npm cache lacks package metadata; testing packed archive with preinstalled dependency tree (not a clean npm install)")
+    }
+  }
   console.log(run(process.execPath, [path.join(root, "scripts/native-entry-test.mjs"), consumer], root).trim())
   console.log("Production tarball native entry isolation and lazy legacy delegation PASS")
 } finally {

package/scripts/publish-workflow-test.mjs

@@ -43,15 +43,19 @@ for (const block of workflow.split(/- uses: actions\/checkout@/).slice(1)) asser
 const publisher = workflow.slice(workflow.indexOf("  publish:\n"), workflow.indexOf("  github-release:\n"))
 assert.doesNotMatch(publisher, /contents:\s*write/, "OIDC publisher must not gain repository mutation privileges")
 
+assert.match(workflow, /for attempt in \{1\.\.12\}/, "clean published npm consumer must retry version propagation")
+assert.ok(workflow.includes('--prefer-online --cache "$VERIFY_DIR/npm-cache-$attempt"'), "consumer retries must not reuse a stale npm cache")
+assert.ok(workflow.includes("Published Loop+Goal clean-install validation did not converge"), "clean consumer must remain a hard release gate")
+
 const sha = "a".repeat(40)
-const request = { name: "@bybrawe/opencode-loop", version: "0.6.5", predecessor: "0.6.4", goal: { version: "1.3.44", sha: "b".repeat(40) } }
+const request = { name: "@bybrawe/opencode-loop", version: "0.6.7", predecessor: "0.6.6", goal: { version: "1.3.48", sha: "b".repeat(40) } }
 const pkg = { name: request.name, version: request.version }
 const env = { GITHUB_REPOSITORY: "ByBrawe/opencode-loop", GITHUB_REF: "refs/heads/main", GITHUB_SHA: sha }
 assert.strictEqual(validateRelease(request, pkg, env), request)
 for (const change of [{ GITHUB_REPOSITORY: "someone/fork" }, { GITHUB_REF: "refs/heads/release" }, { GITHUB_SHA: "main" }]) assert.throws(() => validateRelease(request, pkg, { ...env, ...change }))
 assert.throws(() => validateRelease({ ...request, version: "9.0.0" }, pkg, env))
-assert.throws(() => validateRelease(request, { ...pkg, version: "0.6.4" }, env))
-assert.equal(releaseDecision(404, null, request, sha, "0.6.4"), true)
+assert.throws(() => validateRelease(request, { ...pkg, version: "0.6.5" }, env))
+assert.equal(releaseDecision(404, null, request, sha, "0.6.6"), true)
 for (const status of [401, 403, 429, 500, 503]) assert.throws(() => releaseDecision(status, null, request, sha, "0.6.0"))
 assert.throws(() => releaseDecision(404, null, request, sha, "0.7.0"))
 const manifest = { ...pkg, gitHead: sha }

package/scripts/state-integrity-test.mjs

@@ -0,0 +1,47 @@
+import assert from "node:assert/strict"
+import { mkdtemp, mkdir, readdir, readFile, rm, writeFile } from "node:fs/promises"
+import os from "node:os"
+import path from "node:path"
+import { readState, writeState, stateDir } from "../src/source/core/state.js"
+
+// An unreadable existing session is not a new/empty session. The old fallback
+// silently returned zero jobs and let the next ordinary write replace all work.
+const root = await mkdtemp(path.join(os.tmpdir(), "opencode-loop-state-integrity-"))
+const sessionID = "persisted-session"
+const file = path.join(stateDir(root), `${sessionID}.json`)
+try {
+  const missing = await readState(root, sessionID)
+  assert.deepEqual(missing.jobs, [], "only ENOENT is a new empty session")
+
+  const started = await readState(root, sessionID)
+  started.jobs = [{ id: "keep-this-job", enabled: true, runCount: 7 }]
+  await writeState(root, sessionID, started)
+  const oldSnapshot = await readState(root, sessionID)
+  assert.equal(oldSnapshot.jobs.length, 1)
+  assert.equal(oldSnapshot.jobs[0].runCount, 7)
+
+  const corrupt = '{"version":4,"jobs":['
+  await mkdir(stateDir(root), { recursive: true })
+  await writeFile(file, corrupt)
+  await assert.rejects(readState(root, sessionID), /could not be read; refusing to replace persisted jobs/)
+  assert.equal(await readFile(file, "utf8"), corrupt, "read must not reset the original state")
+  const backups = (await readdir(stateDir(root))).filter((name) => name.startsWith(`${sessionID}.json.corrupt-`))
+  assert.ok(backups.length >= 1, "corrupted bytes should be backed up for investigation")
+  assert.equal(await readFile(path.join(stateDir(root), backups[0]), "utf8"), corrupt)
+
+  await writeFile(file, JSON.stringify({ version: 4, jobs: { invalid: "shape" } }))
+  await assert.rejects(readState(root, sessionID), /could not be read; refusing to replace persisted jobs/)
+  assert.equal(JSON.parse(await readFile(file, "utf8")).jobs.invalid, "shape")
+  await writeFile(file, corrupt)
+
+  oldSnapshot.jobs[0].runCount = 8
+  await assert.rejects(
+    writeState(root, sessionID, oldSnapshot),
+    /could not be read; refusing to replace persisted jobs/,
+    "a stale snapshot must not replace a corrupt persisted session",
+  )
+  assert.equal(await readFile(file, "utf8"), corrupt)
+  console.log("Loop corrupt-state fail-closed and no-lost-jobs regression passed")
+} finally {
+  await rm(root, { recursive: true, force: true })
+}

package/scripts/state-process-test.mjs

@@ -0,0 +1,172 @@
+import assert from "node:assert/strict"
+import { spawn, spawnSync } from "node:child_process"
+import { randomUUID } from "node:crypto"
+import { mkdtemp, mkdir, readFile, readdir, rm, writeFile, link, stat } from "node:fs/promises"
+import os from "node:os"
+import path from "node:path"
+import { fileURLToPath } from "node:url"
+import { readState, writeState, removeState, stateDir } from "../src/source/core/state.js"
+
+const filename = fileURLToPath(import.meta.url)
+const pause = (ms) => new Promise((resolve) => setTimeout(resolve, ms))
+async function exists(file) { try { await stat(file); return true } catch (error) { if (error?.code === "ENOENT") return false; throw error } }
+async function until(fn, duration = 15_000) {
+  const started = Date.now()
+  while (Date.now() - started < duration) {
+    if (await fn()) return
+    await pause(20)
+  }
+  throw new Error("state worker sync timeout")
+}
+
+if (process.argv[2] === "--worker") {
+  const [, , , root, sessionID, marker, gate] = process.argv
+  const snapshot = await readState(root, sessionID)
+  await writeFile(`${gate}.${marker}.ready`, "ready")
+  await until(() => exists(gate))
+  if (marker === "delete") await removeState(root, sessionID)
+  else {
+    snapshot.jobs[0][marker] = Number(marker.slice(1))
+    await writeState(root, sessionID, snapshot)
+  }
+} else {
+  const root = await mkdtemp(path.join(os.tmpdir(), "opencode-loop-process-lock-"))
+  const sessionID = "multi-process"
+  const lockFile = path.join(stateDir(root), `${sessionID}.json.lock`)
+  try {
+    for (let round = 0; round < 6; round++) {
+      const initial = await readState(root, sessionID)
+      initial.jobs = [{ id: "shared", round }]
+      await writeState(root, sessionID, initial)
+      const gate = path.join(root, `round-${round}.go`)
+      const workers = []
+      for (let n = 0; n < 4; n++) {
+        const marker = `f${n}`
+        const child = spawn(process.execPath, [filename, "--worker", root, sessionID, marker, gate], { stdio: ["ignore", "ignore", "pipe"] })
+        let stderr = ""
+        child.stderr.on("data", (part) => { stderr += part.toString() })
+        const closed = new Promise((resolve, reject) => {
+          child.once("error", reject)
+          child.once("close", (code) => code === 0 ? resolve() : reject(new Error(`worker ${marker} exited ${code}: ${stderr}`)))
+        })
+        workers.push({ marker, closed })
+      }
+      await until(async () => (await Promise.all(workers.map((w) => exists(`${gate}.${w.marker}.ready`)))).every(Boolean))
+      await writeFile(gate, "go")
+      await Promise.all(workers.map((w) => w.closed))
+      const saved = (await readState(root, sessionID)).jobs[0]
+      assert.equal(saved.round, round)
+      for (let n = 0; n < 4; n++) assert.equal(saved[`f${n}`], n, "each independent writer must survive")
+      assert.equal(await exists(lockFile), false, "all writers must release the lock")
+    }
+
+    // A stale writer must not resurrect a job removed by another process.
+    // Race both operation orders: the lock serializes remove and write, while
+    // baseline-aware merge must preserve the deletion if write runs second.
+    for (let round = 0; round < 8; round++) {
+      const seed = await readState(root, sessionID)
+      seed.jobs = [{ id: "shared", round: `delete-${round}` }]
+      await writeState(root, sessionID, seed)
+      const gate = path.join(root, `delete-${round}.go`)
+      const workers = []
+      for (const marker of ["delete", "f0"]) {
+        const child = spawn(process.execPath, [filename, "--worker", root, sessionID, marker, gate], {
+          stdio: ["ignore", "ignore", "pipe"],
+        })
+        let stderr = ""
+        child.stderr.on("data", (part) => { stderr += part.toString() })
+        workers.push({
+          marker,
+          closed: new Promise((resolve, reject) => {
+            child.once("error", reject)
+            child.once("close", (code) => code === 0 ? resolve() : reject(new Error(`worker ${marker} exited ${code}: ${stderr}`)))
+          }),
+        })
+      }
+      await until(async () => (await Promise.all(workers.map((w) =>
+        exists(`${gate}.${w.marker}.ready`)))).every(Boolean))
+      await writeFile(gate, "go")
+      await Promise.all(workers.map((w) => w.closed))
+      assert.deepEqual((await readState(root, sessionID)).jobs, [],
+        "remove-vs-stale-writer must not resurrect deleted work")
+      assert.equal(await exists(lockFile), false, "both processes must release lock after deletion race")
+    }
+    const fresh = await readState(root, sessionID)
+    fresh.jobs = [{ id: "shared", round: "reseeded" }]
+    await writeState(root, sessionID, fresh)
+
+    // A malformed lock is never stolen or silently removed.
+    const corrupt = await readState(root, sessionID)
+    await writeFile(lockFile, "corrupt owner")
+    corrupt.jobs[0].newField = "must-not-commit"
+    await assert.rejects(writeState(root, sessionID, corrupt), /state lock invalid_owner/)
+    assert.equal((await readState(root, sessionID)).jobs[0].newField, undefined)
+    await rm(lockFile)
+
+    // A dead owner is reclaimed with an election lock, never a blind unlink.
+    const dead = spawnSync(process.execPath, ["-e", "process.exit(0)"], { encoding: "utf8" })
+    assert.equal(dead.status, 0)
+    assert.ok(dead.pid > 0)
+    const token = randomUUID()
+    const candidate = path.join(stateDir(root), `.loop-lock-${dead.pid}-${token}.json`)
+    const owner = { schemaVersion: 1, pid: dead.pid, token, acquiredAt: Date.now(), candidateName: path.basename(candidate) }
+    await writeFile(candidate, JSON.stringify(owner))
+    await link(candidate, lockFile)
+    // Simulate a crash while an earlier process was cleaning the dead owner.
+    // A stray, dead `.lock.cleanup` must not permanently block recovery.
+    const cleanupToken = randomUUID()
+    const cleanupCandidate = path.join(stateDir(root), `.loop-lock-${dead.pid}-${cleanupToken}.json`)
+    const cleanupOwner = {
+      schemaVersion: 1, pid: dead.pid, token: cleanupToken,
+      acquiredAt: Date.now(), candidateName: path.basename(cleanupCandidate),
+    }
+    await writeFile(cleanupCandidate, JSON.stringify(cleanupOwner))
+    await link(cleanupCandidate, `${lockFile}.cleanup`)
+    const revived = await readState(root, sessionID)
+    revived.jobs[0].recovered = true
+    await writeState(root, sessionID, revived)
+    assert.equal((await readState(root, sessionID)).jobs[0].recovered, true)
+    assert.equal(await exists(lockFile), false)
+    assert.equal(await exists(candidate), false)
+    assert.equal(await exists(cleanupCandidate), false, "orphaned election candidate must be cleaned")
+    assert.equal(await exists(`${lockFile}.cleanup`), false, "orphaned cleanup lock must be removed")
+
+    // A malformed election must fail closed and not delete another owner's files.
+    const badToken = randomUUID()
+    const badCandidate = path.join(stateDir(root), `.loop-lock-${dead.pid}-${badToken}.json`)
+    const badOwner = {
+      schemaVersion: 1, pid: dead.pid, token: badToken,
+      acquiredAt: Date.now(), candidateName: path.basename(badCandidate),
+    }
+    await writeFile(badCandidate, JSON.stringify(badOwner))
+    await link(badCandidate, lockFile)
+    await writeFile(`${lockFile}.cleanup`, "not valid owner metadata")
+    const blocked = await readState(root, sessionID)
+    blocked.jobs[0].mustNotWrite = true
+    await assert.rejects(writeState(root, sessionID, blocked), /state lock invalid_owner/)
+    assert.equal((await readState(root, sessionID)).jobs[0].mustNotWrite, undefined)
+    assert.equal(await exists(lockFile), true, "invalid election must not erase the dead canonical owner")
+    await rm(lockFile)
+    await rm(`${lockFile}.cleanup`)
+    await rm(badCandidate)
+
+    // A path supplied by another tool cannot symlink Loop state outside the project.
+    const other = await mkdtemp(path.join(os.tmpdir(), "opencode-loop-escape-"))
+    const unsafe = path.join(root, "unsafe")
+    await mkdir(unsafe)
+    try {
+      const linkTarget = path.join(unsafe, ".opencode")
+      try {
+        const { symlink } = await import("node:fs/promises")
+        await symlink(other, linkTarget, process.platform === "win32" ? "junction" : "dir")
+        await assert.rejects(readState(unsafe, sessionID), /state lock unsafe_path/)
+        await assert.rejects(writeState(unsafe, sessionID, { version: 4, jobs: [] }), /state lock unsafe_path/)
+      } catch (error) {
+        if (process.platform !== "win32" || !["EPERM", "EACCES"].includes(error?.code)) throw error
+      }
+    } finally { await rm(other, { recursive: true, force: true }) }
+    console.log("Loop multi-process write/delete races, stale-owner recovery, and unsafe-path regressions passed")
+  } finally {
+    await rm(root, { recursive: true, force: true, maxRetries: 5, retryDelay: 50 })
+  }
+}

package/src/index.js

@@ -381,6 +381,7 @@ import { spawn } from "child_process";
 
 // src/source/core/state.js
 import { promises as fs } from "fs";
+import { randomUUID as stateLockRandomUUID } from "crypto";
 import os from "os";
 import path from "path";
 var STATE_DIR = ".opencode/opencode-loop";
@@ -403,6 +404,194 @@ async function pathExists(filePath) {
     return false;
   }
 }
+var STATE_PROCESS_LOCK_TIMEOUT_MS = 5000;
+var STATE_PROCESS_LOCK_POLL_MS = 20;
+function stateLockError(kind, detail) {
+  const error = new Error(`OpenCode Loop state lock ${kind}: ${detail}`);
+  error.code = "OPENCODE_LOOP_STATE_LOCK";
+  return error;
+}
+async function assertStatePathSafe(directory, target) {
+  const root = path.resolve(directory);
+  const relative = path.relative(root, path.resolve(target));
+  if (relative === ".." || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative)) {
+    throw stateLockError("unsafe_path", `path escapes project: ${target}`);
+  }
+  let current = root;
+  for (const part of relative.split(path.sep).filter(Boolean)) {
+    current = path.join(current, part);
+    let info;
+    try {
+      info = await fs.lstat(current);
+    } catch (error) {
+      if (error?.code === "ENOENT")
+        return;
+      throw error;
+    }
+    if (info.isSymbolicLink())
+      throw stateLockError("unsafe_path", `symbolic link or junction: ${current}`);
+  }
+}
+function stateProcessLockOwner() {
+  const token = stateLockRandomUUID();
+  return {
+    schemaVersion: 1,
+    pid: process.pid,
+    token,
+    acquiredAt: Date.now(),
+    candidateName: `.loop-lock-${process.pid}-${token}.json`
+  };
+}
+function stateProcessLockOwnerValid(owner) {
+  return owner?.schemaVersion === 1 && Number.isSafeInteger(owner.pid) && owner.pid > 0 && typeof owner.token === "string" && /^[0-9a-f-]{36}$/i.test(owner.token) && Number.isFinite(owner.acquiredAt) && owner.acquiredAt > 0 && owner.candidateName === `.loop-lock-${owner.pid}-${owner.token}.json` && path.basename(owner.candidateName) === owner.candidateName;
+}
+async function readStateProcessOwner(file) {
+  let raw;
+  for (let attempt = 0;; attempt++) {
+    try {
+      raw = await fs.readFile(file, "utf8");
+      break;
+    } catch (error) {
+      if (error?.code === "ENOENT")
+        return null;
+      if (process.platform !== "win32" || !["EPERM", "EACCES", "EBUSY"].includes(error?.code) || attempt >= 5)
+        throw error;
+      await delay(10 * (attempt + 1));
+    }
+  }
+  let owner;
+  try {
+    owner = JSON.parse(raw);
+  } catch {
+    throw stateLockError("invalid_owner", `corrupt lock metadata at ${file}`);
+  }
+  if (!stateProcessLockOwnerValid(owner))
+    throw stateLockError("invalid_owner", `invalid lock metadata at ${file}`);
+  return owner;
+}
+function stateProcessAlive(pid) {
+  if (pid === process.pid)
+    return true;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    return error?.code !== "ESRCH";
+  }
+}
+async function removeStateProcessFile(file) {
+  for (let attempt = 0;; attempt++) {
+    try {
+      await fs.rm(file, { force: true });
+      return;
+    } catch (error) {
+      if (process.platform !== "win32" || !["EPERM", "EACCES", "EBUSY"].includes(error?.code) || attempt >= 5)
+        throw error;
+      await delay(10 * (attempt + 1));
+    }
+  }
+}
+async function claimStateProcessLock(candidate, canonical) {
+  for (let attempt = 0;; attempt++) {
+    try {
+      await fs.link(candidate, canonical);
+      return true;
+    } catch (error) {
+      if (error?.code === "EEXIST")
+        return false;
+      if (process.platform !== "win32" || !["EPERM", "EACCES", "EBUSY"].includes(error?.code) || attempt >= 5)
+        throw error;
+      await delay(10 * (attempt + 1));
+    }
+  }
+}
+async function createStateLockCandidate(directory, owner) {
+  const candidate = path.join(stateDir(directory), owner.candidateName);
+  await assertStatePathSafe(directory, candidate);
+  await fs.writeFile(candidate, `${JSON.stringify(owner)}
+`, { flag: "wx", mode: 384 });
+  return candidate;
+}
+async function recoverDeadStateProcessLock(directory, canonical, stale, depth = 0) {
+  const cleanupFile = `${canonical}.cleanup`;
+  const cleanupOwner = stateProcessLockOwner();
+  const cleanupCandidate = await createStateLockCandidate(directory, cleanupOwner);
+  let elected = false;
+  try {
+    await assertStatePathSafe(directory, cleanupFile);
+    elected = await claimStateProcessLock(cleanupCandidate, cleanupFile);
+    if (!elected) {
+      const existing = await readStateProcessOwner(cleanupFile);
+      if (existing && !stateProcessAlive(existing.pid)) {
+        if (depth >= 6)
+          throw stateLockError("recovery_depth", `too many orphaned cleanup elections for ${canonical}`);
+        await recoverDeadStateProcessLock(directory, cleanupFile, existing, depth + 1);
+      }
+      return false;
+    }
+    const current = await readStateProcessOwner(canonical);
+    if (!current || current.token !== stale.token || current.pid !== stale.pid || stateProcessAlive(current.pid))
+      return false;
+    await assertStatePathSafe(directory, canonical);
+    await removeStateProcessFile(canonical);
+    const staleCandidate = path.join(stateDir(directory), current.candidateName);
+    await assertStatePathSafe(directory, staleCandidate);
+    await removeStateProcessFile(staleCandidate).catch(() => {});
+    return true;
+  } finally {
+    if (elected) {
+      const current = await readStateProcessOwner(cleanupFile).catch(() => null);
+      if (current?.token === cleanupOwner.token)
+        await removeStateProcessFile(cleanupFile);
+    }
+    await removeStateProcessFile(cleanupCandidate).catch(() => {});
+  }
+}
+async function acquireStateProcessLock(directory, sessionID) {
+  const targetDirectory = stateDir(directory);
+  await assertStatePathSafe(directory, targetDirectory);
+  await ensureDir(targetDirectory);
+  await assertStatePathSafe(directory, targetDirectory);
+  const target = statePath(directory, sessionID);
+  const canonical = `${target}.lock`;
+  await assertStatePathSafe(directory, target);
+  await assertStatePathSafe(directory, canonical);
+  const owner = stateProcessLockOwner();
+  const candidate = await createStateLockCandidate(directory, owner);
+  const started = Date.now();
+  let acquired = false;
+  try {
+    while (true) {
+      await assertStatePathSafe(directory, canonical);
+      if (await claimStateProcessLock(candidate, canonical)) {
+        acquired = true;
+        break;
+      }
+      const current = await readStateProcessOwner(canonical);
+      if (current && !stateProcessAlive(current.pid))
+        await recoverDeadStateProcessLock(directory, canonical, current);
+      if (Date.now() - started >= STATE_PROCESS_LOCK_TIMEOUT_MS) {
+        throw stateLockError("timeout", `session ${sessionID} remained locked for ${STATE_PROCESS_LOCK_TIMEOUT_MS}ms`);
+      }
+      await delay(STATE_PROCESS_LOCK_POLL_MS);
+    }
+    return async () => {
+      const current = await readStateProcessOwner(canonical);
+      if (current?.token !== owner.token || current.pid !== owner.pid) {
+        throw stateLockError("lost", `session ${sessionID} lock ownership changed`);
+      }
+      await assertStatePathSafe(directory, canonical);
+      await removeStateProcessFile(canonical);
+      await removeStateProcessFile(candidate);
+    };
+  } catch (error) {
+    if (acquired && (await readStateProcessOwner(canonical).catch(() => null))?.token === owner.token) {
+      await removeStateProcessFile(canonical).catch(() => {});
+    }
+    await removeStateProcessFile(candidate).catch(() => {});
+    throw error;
+  }
+}
 function stateLockKey(directory, sessionID) {
   return `${path.resolve(directory)}:${safeID(sessionID)}`;
 }
@@ -416,21 +605,32 @@ async function withStateWriteLock(directory, sessionID, fn) {
   const next = previous.catch(() => {}).then(() => current);
   stateWriteLocks.set(key, next);
   await previous.catch(() => {});
+  let unlock;
   try {
+    unlock = await acquireStateProcessLock(directory, sessionID);
     return await fn();
   } finally {
-    release();
-    if (stateWriteLocks.get(key) === next)
-      stateWriteLocks.delete(key);
+    try {
+      if (unlock)
+        await unlock();
+    } finally {
+      release();
+      if (stateWriteLocks.get(key) === next)
+        stateWriteLocks.delete(key);
+    }
   }
 }
 async function readStateFile(directory, sessionID) {
   const target = statePath(directory, sessionID);
+  await assertStatePathSafe(directory, target);
   const attempts = 5;
   for (let attempt = 0;attempt < attempts; attempt++) {
     try {
       const parsed = JSON.parse(await fs.readFile(target, "utf8"));
-      return { version: 4, jobs: Array.isArray(parsed.jobs) ? parsed.jobs : [] };
+      if (!parsed || typeof parsed !== "object" || !Array.isArray(parsed.jobs)) {
+        throw new SyntaxError("invalid Loop state schema: jobs must be an array");
+      }
+      return { version: 4, jobs: parsed.jobs };
     } catch (error) {
       if (error?.code === "ENOENT")
         return { version: 4, jobs: [] };
@@ -444,7 +644,7 @@ async function readStateFile(directory, sessionID) {
     await ensureDir(stateDir(directory));
     await fs.copyFile(target, `${target}.corrupt-${Date.now()}`);
   } catch {}
-  return { version: 4, jobs: [] };
+  throw new Error(`OpenCode Loop state at ${target} could not be read; refusing to replace persisted jobs.`);
 }
 async function readState(directory, sessionID) {
   const state = await readStateFile(directory, sessionID);
@@ -574,25 +774,31 @@ function mergeStateJobs(baseJobs, intendedJobs, currentJobs) {
 }
 async function writeState(directory, sessionID, state) {
   await withStateWriteLock(directory, sessionID, async () => {
-    await ensureDir(stateDir(directory));
     const target = statePath(directory, sessionID);
+    await assertStatePathSafe(directory, target);
+    const current = await readStateFile(directory, sessionID);
     const baseline = state?.[STATE_BASELINE];
     let jobs = structuredClone(state.jobs || []);
     if (Array.isArray(baseline)) {
-      const current = await readStateFile(directory, sessionID);
       jobs = mergeStateJobs(baseline, jobs, current.jobs || []);
-      state.jobs = structuredClone(jobs);
-      state[STATE_BASELINE] = structuredClone(jobs);
     }
     const payload = JSON.stringify({ version: 4, jobs }, null, 2);
     await writeFileAtomically(target, payload);
+    state.jobs = structuredClone(jobs);
+    if (Array.isArray(baseline))
+      state[STATE_BASELINE] = structuredClone(jobs);
   });
 }
 async function removeState(directory, sessionID) {
   await withStateWriteLock(directory, sessionID, async () => {
+    const target = statePath(directory, sessionID);
+    await assertStatePathSafe(directory, target);
     try {
-      await fs.unlink(statePath(directory, sessionID));
-    } catch {}
+      await fs.unlink(target);
+    } catch (error) {
+      if (error?.code !== "ENOENT")
+        throw error;
+    }
   });
 }