pantheon-opencode 1.6.0-beta.10 → 1.6.0-beta.12

package/scripts/install/shared.mjs

@@ -4,11 +4,12 @@
 
 import { spawnSync } from 'node:child_process'
 import {
-  copyFileSync,
-  cpSync,
+  chmodSync,
+  closeSync,
   existsSync,
   lstatSync,
   mkdirSync,
+  openSync,
   readdirSync,
   readFileSync,
   renameSync,
@@ -16,17 +17,35 @@ import {
   statSync,
   writeFileSync,
 } from 'node:fs'
-import { basename, dirname, join } from 'node:path'
+import { dirname, join } from 'node:path'
 import { fileURLToPath } from 'node:url'
+import { isSupportedNodeVersion, MIN_SUPPORTED_NODE_VERSION } from '../node-engine-policy.mjs'
 
-const REQUIRED_NODE_MAJOR = 18
-if (parseInt(process.versions.node.split('.')[0], 10) < REQUIRED_NODE_MAJOR) {
-  console.error(`❌ Node.js >= ${REQUIRED_NODE_MAJOR} required (current: ${process.versions.node})`)
+if (!isSupportedNodeVersion(process.versions.node)) {
+  console.error(
+    `❌ Pantheon requires Node.js >= ${MIN_SUPPORTED_NODE_VERSION} (current: ${process.versions.node})`,
+  )
   process.exit(1)
 }
 
 import { dump, load } from 'js-yaml'
 
+import {
+  ACTIONS,
+  fingerprintOutput,
+  isRecording,
+  recordChange,
+  recordRemovalTree,
+  removeReviewedTree,
+} from './plan.mjs'
+import {
+  assertNoSymlinkAncestors,
+  assertPathWithin,
+  assertSafeRemoval,
+  verifyPathRemoved,
+  verifyRegularFile,
+} from './verify.mjs'
+
 export const __dirname = dirname(fileURLToPath(import.meta.url))
 export const ROOT = join(__dirname, '..', '..')
 export const AGENTS_DIR = join(ROOT, 'src', 'agents')
@@ -141,33 +160,6 @@ export function resolveTarget(target) {
   return join(process.cwd(), target)
 }
 
-export function createBackup(target) {
-  const timestamp = new Date().toISOString().replace(/[:.]/g, '-').slice(0, 19)
-  const backupDir = join(target, '..', `.pantheon-bak-${basename(target)}-${timestamp}`)
-
-  console.log(`\n  💾 Creating backup: ${backupDir}`)
-  mkdirSync(backupDir, { recursive: true })
-
-  // Copy only relevant Pantheon directories/files
-  const items = ['agents', 'skills', 'commands', 'instructions', 'opencode.json', 'tui.json']
-  let count = 0
-  for (const item of items) {
-    const src = join(target, item)
-    try {
-      cpSync(src, join(backupDir, item), {
-        recursive: true,
-        errorOnExist: false,
-      })
-      count++
-    } catch {
-      // File or directory doesn't exist in target — skip silently
-    }
-  }
-
-  console.log(`  ✅ Backed up ${count} items to: ${backupDir}`)
-  return backupDir
-}
-
 export function detectAndReport(target) {
   const found = detectPlatforms(target).length > 0
 
@@ -197,6 +189,7 @@ export function sourceDirValid(dir) {
 }
 
 export function copyFiles(srcDir, dstDir, dryRun, renameMap = null, clean = false) {
+  assertNoSymlinkAncestors(dstDir)
   const entries = readdirSync(srcDir)
   let created = 0
   let skipped = 0
@@ -212,6 +205,8 @@ export function copyFiles(srcDir, dstDir, dryRun, renameMap = null, clean = fals
     dstNames.add(dstName)
 
     const dstFile = join(dstDir, dstName)
+    assertPathWithin(dstDir, dstFile)
+    assertNoSymlinkAncestors(dstFile)
 
     if (statSync(srcFile).isDirectory()) continue
     const content = readFileSync(srcFile, 'utf8')
@@ -222,14 +217,10 @@ export function copyFiles(srcDir, dstDir, dryRun, renameMap = null, clean = fals
         skipped++
         continue
       }
-      if (!dryRun) {
-        writeFileSync(dstFile, content, 'utf8')
-      }
+      writeIfChanged(dstFile, content, dryRun)
       created++
     } else {
-      if (!dryRun) {
-        writeFileSync(dstFile, content, 'utf8')
-      }
+      writeIfChanged(dstFile, content, dryRun)
       created++
     }
   }
@@ -239,17 +230,21 @@ export function copyFiles(srcDir, dstDir, dryRun, renameMap = null, clean = fals
   // (lowercase name + .md/.mdc extension), regardless of AGENT_NAMES membership.
   // This handles deleted canonical agents (e.g., agora) whose source file is gone.
   if (clean && existsSync(dstDir)) {
+    assertNoSymlinkAncestors(dstDir)
     const dstEntries = readdirSync(dstDir)
     const agentPattern = /^[a-z-]+\.(md|mdc)$/
     for (const entry of dstEntries) {
       if (dstNames.has(entry)) continue // still in source
       const dstFile = join(dstDir, entry)
+      assertSafeRemoval(dstDir, dstFile)
       if (!statSync(dstFile).isFile()) continue
       // Safety: only remove files that match agent file naming pattern
       // (user custom files with different naming patterns are untouched)
       if (!agentPattern.test(entry)) continue
       if (!dryRun) {
+        assertSafeRemoval(dstDir, dstFile)
         rmSync(dstFile, { force: true })
+        verifyPathRemoved(dstFile)
       }
       created++
     }
@@ -302,35 +297,71 @@ function readFileOrNull(filePath) {
  *   filesystem CAS: the final re-read and the rename are still two syscalls, so
  *   a writer that lands between them is not prevented. What it does close is
  *   the window the installer actually races with — a config the caller parsed
- *   going stale during the same run — and it keeps the target and the `.bak`
- *   consistent with the bytes that were checked.
+ *   going stale during the same run — and it keeps the target consistent with
+ *   the bytes that were checked.
  * @param {(existing: string|null) => void} [options.beforeRecheck] - runs after
  *   the initial content check and before the last-moment re-read. Injection
  *   point so tests can simulate a concurrent writer landing in the window;
  *   production callers omit it (undefined is a no-op).
  * @param {(existing: string|null) => void} [options.beforeSwap] - runs after the
- *   expected-content checks pass and immediately before the rename, so side
- *   effects that must not fire on a conflict (e.g. the `.bak` copy) live here.
+ *   expected-content checks pass and immediately before the rename, for side
+ *   effects that must not fire on a conflict.
+ * @param {(change: object) => void} [options.recorder] - optional change
+ *   recorder. When supplied, the outcome is recorded (path + action + byte
+ *   size only) so `--dry-run` can print the real per-file plan. Defaults to
+ *   the module-level no-op singleton, so an uninstrumented caller is
+ *   byte-identical to before.
+ * @param {number} [options.mode] - mode for a newly created file; existing
+ *   destination modes are preserved.
+ * @param {boolean} [options.scored] - set `false` when this write is not part
+ *   of the install summary (e.g. stale-ref cleanup), so it is shown in the plan
+ *   but excluded from the consistency guard.
  * @returns {'created'|'skipped'|'conflict'}
  */
 export function writeIfChanged(filePath, content, dryRun, options = {}) {
-  const { expectedContent, beforeSwap, beforeRecheck } = options
+  const { expectedContent, beforeSwap, beforeRecheck, recorder, scored, mode } = options
 
-  // Refuse to write through/over a symlink. A dangling symlink is invisible to
-  // existsSync, and rename-over-link would replace the link rather than its
-  // target — both are silent redirections the installer must not perform.
+  // A linked parent redirects both the atomic temp write and the eventual
+  // rename, so validate the full path rather than only its final component.
+  assertNoSymlinkAncestors(filePath)
   const stat = lstatOrNull(filePath)
   if (stat?.isSymbolicLink()) {
     throw new Error(`Refusing to write through symlink: ${filePath}`)
   }
+  // Preserve the destination's access mode across the atomic rename. A mode
+  // supplied by the caller is used only for a newly created destination.
+  const targetMode = stat === null ? mode : stat.mode & 0o777
 
   const existing = stat === null ? null : readFileOrNull(filePath)
+  const record = (outcome) => {
+    if (!isRecording(recorder)) return
+    const action =
+      outcome === 'conflict'
+        ? ACTIONS.CONFLICT
+        : outcome === 'skipped'
+          ? ACTIONS.UNCHANGED
+          : existing === null
+            ? ACTIONS.CREATE
+            : ACTIONS.UPDATE
+    recordChange(
+      {
+        path: filePath,
+        action,
+        bytes: Buffer.byteLength(content, 'utf8'),
+        outputFingerprint: fingerprintOutput(content),
+        scored,
+      },
+      recorder,
+    )
+  }
   if (existing === content) {
+    record('skipped')
     return 'skipped'
   }
   if (expectedContent !== undefined && existing !== expectedContent) {
     // The file changed since the caller read it (or appeared/disappeared).
     // Do not clobber the newer content; the caller decides how to react.
+    record('conflict')
     return 'conflict'
   }
   if (!dryRun) {
@@ -342,36 +373,71 @@ export function writeIfChanged(filePath, content, dryRun, options = {}) {
     // crash mid-write can never leave a truncated file behind (rename is
     // atomic within the same directory).
     const tmpPath = `${filePath}.tmp-${process.pid}`
-    writeFileSync(tmpPath, content, 'utf8')
-
-    // Last-moment re-read. The initial compare and this rename are separate
-    // syscalls, so a concurrent writer can land in between; re-check the
-    // expected bytes immediately before the swap. On a mismatch, drop the temp
-    // and leave the target AND any existing `.bak` byte-identical.
-    if (expectedContent !== undefined) {
-      const current = readFileOrNull(filePath)
-      if (current !== expectedContent) {
-        rmSync(tmpPath, { force: true })
-        return 'conflict'
+    assertNoSymlinkAncestors(tmpPath)
+    let fd
+    let createdTemporary = false
+    try {
+      // Exclusive creation establishes ownership. Cleanup below is limited to
+      // this exact path and only runs after this invocation opened it.
+      fd = openSync(tmpPath, 'wx', targetMode)
+      createdTemporary = true
+      writeFileSync(fd, content, { encoding: 'utf8' })
+      closeSync(fd)
+      fd = undefined
+      if (targetMode !== undefined) chmodSync(tmpPath, targetMode)
+
+      // Last-moment re-read. The initial compare and this rename are separate
+      // syscalls, so a concurrent writer can land in between; re-check the
+      // expected bytes immediately before the swap. On a mismatch, leave the
+      // target byte-identical; finally removes only the temp created above.
+      if (expectedContent !== undefined) {
+        const current = readFileOrNull(filePath)
+        if (current !== expectedContent) {
+          record('conflict')
+          return 'conflict'
+        }
       }
-    }
 
-    if (typeof beforeSwap === 'function') beforeSwap(existing)
-    renameSync(tmpPath, filePath)
+      if (typeof beforeSwap === 'function') beforeSwap(existing)
+      assertNoSymlinkAncestors(filePath)
+      renameSync(tmpPath, filePath)
+      createdTemporary = false
+      verifyRegularFile(filePath, content)
+    } finally {
+      if (fd !== undefined) {
+        try {
+          closeSync(fd)
+        } catch {
+          // Preserve the write error; closing a failed descriptor is best-effort.
+        }
+      }
+      if (createdTemporary) {
+        try {
+          assertSafeRemoval(dirname(tmpPath), tmpPath)
+          rmSync(tmpPath, { force: true })
+          verifyPathRemoved(tmpPath)
+        } catch {
+          // Preserve the write error and never follow an unsafe temp path.
+        }
+      }
+    }
   }
+  record('created')
   return 'created'
 }
 
 /**
- * beta.5: write the user's opencode.json with a same-directory backup of the
- * previous content. The installer rewrites the whole config; a `.bak` gives
- * the user a one-step recovery if a merge ever goes wrong.
+ * Write a config file atomically, honoring the compare-before-write guard.
+ * This used to always keep a `<config>.bak` sidecar; the main `opencode.json`
+ * no longer does — the target-scoped exact backup set
+ * (scripts/install/backup.mjs) preserves it byte-for-byte and
+ * `pantheon-opencode restore` reverts it.
  *
- * The backup is created INSIDE the `beforeSwap` hook, so it fires only after
- * both expected-content checks pass (the initial compare and the last-moment
- * re-read before the rename). A conflict observed at either point leaves the
- * target AND any pre-existing `.bak` untouched, rather than overwriting the
- * user's last known-good backup with a stale copy on a no-op write.
+ * A caller may still supply `beforeSwap` for a file the exact set does NOT
+ * cover: the GLOBAL `opencode-vision.json` lives outside the config dir, so
+ * vision-prompt passes a `beforeSwap` that keeps its `<file>.bak` recovery.
+ * New config files default to mode `0600`; existing destination modes survive
+ * replacement.
  *
  * @param {string} filePath
  * @param {string} content
@@ -382,14 +448,10 @@ export function writeConfigWithBackup(filePath, content, dryRun, options = {}) {
   return writeIfChanged(filePath, content, dryRun, {
     expectedContent: options.expectedContent,
     beforeRecheck: options.beforeRecheck,
-    beforeSwap: (existing) => {
-      if (existing === null) return
-      try {
-        copyFileSync(filePath, `${filePath}.bak`)
-      } catch {
-        // Best-effort: a backup failure must not block the install.
-      }
-    },
+    beforeSwap: options.beforeSwap,
+    recorder: options.recorder,
+    scored: options.scored,
+    mode: options.mode ?? 0o600,
   })
 }
 
@@ -403,7 +465,10 @@ export function checkRuntimePrerequisites(env = process.env) {
   const problems = []
   const checks = [
     { cmd: 'python3', hint: 'install Python 3.10+ (https://www.python.org/downloads/)' },
-    { cmd: 'npm', hint: 'install Node.js 22+ (https://nodejs.org) — npm ships with it' },
+    {
+      cmd: 'npm',
+      hint: `install Node.js >= ${MIN_SUPPORTED_NODE_VERSION} (https://nodejs.org) — npm ships with it`,
+    },
   ]
   for (const { cmd, hint } of checks) {
     const probe = spawnSync(cmd, ['--version'], { encoding: 'utf8', timeout: 10_000, env })
@@ -455,9 +520,27 @@ export function serializeFm(fm) {
   })
 }
 
-export function installSkills(skills, target, dryRun, subDir = '.opencode') {
+function recordDirectoryOutcomes(srcDir, dstDir, recorder) {
+  recordChange({ path: dstDir, action: ACTIONS.UNCHANGED, bytes: 0, scored: false }, recorder)
+  for (const entry of readdirSync(srcDir, { withFileTypes: true })) {
+    if (!entry.isDirectory()) continue
+    recordDirectoryOutcomes(join(srcDir, entry.name), join(dstDir, entry.name), recorder)
+  }
+}
+
+export function installSkills(
+  skills,
+  target,
+  dryRun,
+  subDir = '.opencode',
+  recorder = null,
+  reviewedRemovals = null,
+  reviewedSnapshots = null,
+  clean = false,
+) {
   const srcSkillsDir = join(ROOT, 'src', 'skills')
   const dstSkillsDir = join(target, subDir, 'skills')
+  assertNoSymlinkAncestors(dstSkillsDir)
 
   let created = 0
   let skipped = 0
@@ -466,7 +549,12 @@ export function installSkills(skills, target, dryRun, subDir = '.opencode') {
     const src = join(srcSkillsDir, skill)
     const dst = join(dstSkillsDir, skill)
 
-    if (!dryRun) mkdirSync(dst, { recursive: true })
+    if (!dryRun) {
+      assertPathWithin(dstSkillsDir, dst)
+      assertNoSymlinkAncestors(dst)
+      mkdirSync(dst, { recursive: true })
+      assertNoSymlinkAncestors(dst)
+    }
 
     function copyDirRecursive(from, to) {
       const entries = readdirSync(from)
@@ -474,15 +562,47 @@ export function installSkills(skills, target, dryRun, subDir = '.opencode') {
         const srcPath = join(from, entry)
         const dstPath = join(to, entry)
         if (statSync(srcPath).isDirectory()) {
-          if (!dryRun) mkdirSync(dstPath, { recursive: true })
+          if (!dryRun) {
+            assertPathWithin(dstSkillsDir, dstPath)
+            assertNoSymlinkAncestors(dstPath)
+            mkdirSync(dstPath, { recursive: true })
+            assertNoSymlinkAncestors(dstPath)
+          }
           copyDirRecursive(srcPath, dstPath)
         } else {
           const content = readFileSync(srcPath, 'utf8')
-          const existing = existsSync(dstPath) ? readFileSync(dstPath, 'utf8') : null
+          const dstStat = lstatOrNull(dstPath)
+          if (dstStat?.isSymbolicLink()) {
+            throw new Error(`Refusing to read through symlink: ${dstPath}`)
+          }
+          const existing = dstStat === null ? null : readFileSync(dstPath, 'utf8')
           if (existing === content) {
             skipped++
+            if (isRecording(recorder)) {
+              recordChange(
+                {
+                  path: dstPath,
+                  action: ACTIONS.UNCHANGED,
+                  bytes: Buffer.byteLength(content, 'utf8'),
+                  outputFingerprint: fingerprintOutput(content),
+                },
+                recorder,
+              )
+            }
           } else {
-            if (!dryRun) writeFileSync(dstPath, content, 'utf8')
+            if (!dryRun) {
+              writeIfChanged(dstPath, content, false, { recorder })
+            } else if (isRecording(recorder)) {
+              recordChange(
+                {
+                  path: dstPath,
+                  action: existing === null ? ACTIONS.CREATE : ACTIONS.UPDATE,
+                  bytes: Buffer.byteLength(content, 'utf8'),
+                  outputFingerprint: fingerprintOutput(content),
+                },
+                recorder,
+              )
+            }
             created++
           }
         }
@@ -490,20 +610,29 @@ export function installSkills(skills, target, dryRun, subDir = '.opencode') {
     }
 
     copyDirRecursive(src, dst)
+    if (clean && existsSync(dst)) recordDirectoryOutcomes(src, dst, recorder)
   }
 
   // Remove stale skills that exist in dst but not in skills list
   if (existsSync(dstSkillsDir)) {
+    assertNoSymlinkAncestors(dstSkillsDir)
     const dstEntries = readdirSync(dstSkillsDir)
     for (const entry of dstEntries) {
       const dstPath = join(dstSkillsDir, entry)
+      assertSafeRemoval(dstSkillsDir, dstPath)
       if (!statSync(dstPath).isDirectory()) continue
       if (!skills.includes(entry)) {
-        if (!dryRun) {
-          rmSync(dstPath, { recursive: true, force: true })
+        if (dryRun) {
+          recordRemovalTree(dstPath, recorder)
+        } else {
+          assertSafeRemoval(dstSkillsDir, dstPath)
+          removeReviewedTree(dstPath, reviewedRemovals, reviewedSnapshots)
           console.log(`    🗑️  Removed stale skill: ${entry}`)
         }
         created++
+        // A stale removal increments `created` (a change), so it must also be
+        // recorded or the preview would under-report on a non-fresh target.
+        recordChange({ path: dstPath, action: ACTIONS.REMOVE, bytes: 0 }, recorder)
       }
     }
   }
@@ -511,18 +640,35 @@ export function installSkills(skills, target, dryRun, subDir = '.opencode') {
   return { created, skipped }
 }
 
-export function syncDir(src, dst, dryRun, clean = false, filter = null) {
+export function syncDir(
+  src,
+  dst,
+  dryRun,
+  clean = false,
+  filter = null,
+  recorder = null,
+  reviewedRemovals = null,
+  reviewedSnapshots = null,
+) {
   if (!existsSync(src)) return { created: 0, skipped: 0 }
   let created = 0
   let skipped = 0
+  const cleanTargetExisted = clean && existsSync(dst)
 
-  if (clean && existsSync(dst)) {
-    if (!dryRun) {
-      rmSync(dst, { recursive: true, force: true })
+  if (cleanTargetExisted) {
+    if (dryRun) {
+      recordRemovalTree(dst, recorder)
+    } else {
+      assertSafeRemoval(dirname(dst), dst)
+      removeReviewedTree(dst, reviewedRemovals, reviewedSnapshots)
     }
   }
 
-  if (!dryRun) mkdirSync(dst, { recursive: true })
+  if (!dryRun) {
+    assertNoSymlinkAncestors(dst)
+    mkdirSync(dst, { recursive: true })
+    assertNoSymlinkAncestors(dst)
+  }
 
   const entries = readdirSync(src)
   for (const entry of entries) {
@@ -530,20 +676,29 @@ export function syncDir(src, dst, dryRun, clean = false, filter = null) {
     const srcPath = join(src, entry)
     const dstPath = join(dst, entry)
     if (statSync(srcPath).isDirectory()) {
-      const sub = syncDir(srcPath, dstPath, dryRun, false, filter)
+      const sub = syncDir(
+        srcPath,
+        dstPath,
+        dryRun,
+        false,
+        filter,
+        recorder,
+        reviewedRemovals,
+        reviewedSnapshots,
+      )
       created += sub.created
       skipped += sub.skipped
     } else {
       const content = readFileSync(srcPath, 'utf8')
-      const existing = existsSync(dstPath) ? readFileSync(dstPath, 'utf8') : null
-      if (existing === content) {
+      const status = writeIfChanged(dstPath, content, dryRun, { recorder })
+      if (status === 'skipped') {
         skipped++
       } else {
-        if (!dryRun) writeFileSync(dstPath, content, 'utf8')
         created++
       }
     }
   }
+  if (cleanTargetExisted) recordDirectoryOutcomes(src, dst, recorder)
   return { created, skipped }
 }
 

package/scripts/install/state.mjs

@@ -20,27 +20,57 @@
  *       "skills": { "version": 1, "status": "installed" },
  *       "plugins": { "version": 1, "status": "installed" },
  *       "runtime": { "version": 1, "status": "installed" }
+ *     },
+ *     "file_inventory": {
+ *       "schema_version": 1, "target_root": "/absolute/target",
+ *       "legacy_unknown": false, "entries": []
  *     }
  *   }
  */
 
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs'
-import { join } from 'node:path'
+import { existsSync, mkdirSync, readFileSync } from 'node:fs'
+import { join, resolve } from 'node:path'
+import { assertNoSymlinkAncestors, writeFileAtomically } from './verify.mjs'
 
 const STATE_FILE = 'install-state.json'
 const STATE_DIR = '.pantheon'
 
+function emptyFileInventory(legacyUnknown = true) {
+  return {
+    schema_version: 1,
+    target_root: null,
+    legacy_unknown: legacyUnknown,
+    entries: [],
+  }
+}
+
+function invalidFileInventory() {
+  return { schema_version: 0, target_root: null, legacy_unknown: true, entries: [] }
+}
+
+function normalizeFileInventory(state) {
+  if (!Object.hasOwn(state, 'file_inventory')) return emptyFileInventory(true)
+  if (
+    !state.file_inventory ||
+    typeof state.file_inventory !== 'object' ||
+    Array.isArray(state.file_inventory)
+  ) {
+    return invalidFileInventory()
+  }
+  return state.file_inventory
+}
+
 /**
  * Create a fresh v2 state object for a new install.
  * @param {string} version - Pantheon version string
  * @returns {object} v2 state
  */
-export function createInitialState(version) {
+export function createInitialState(version, updatedAt = new Date().toISOString()) {
   return {
     schema_version: 2,
     pantheon_version: version || '0.0.0',
     previous_version: null,
-    updated_at: new Date().toISOString(),
+    updated_at: updatedAt,
     migration_checkpoint: null,
     applied_migrations: [],
     components: {
@@ -49,6 +79,7 @@ export function createInitialState(version) {
       plugins: { version: 1, status: 'pending' },
       runtime: { version: 1, status: 'pending' },
     },
+    file_inventory: emptyFileInventory(false),
   }
 }
 
@@ -104,6 +135,7 @@ export function upgradeStateV1toV2(state) {
             plugins: { version: 1, status: 'unknown' },
             runtime: { version: 1, status: 'unknown' },
           },
+    file_inventory: normalizeFileInventory(state),
   }
 }
 
@@ -129,6 +161,14 @@ function ensureV2Shape(state) {
   ) {
     state.components = upgradeStateV1toV2(state).components
   }
+  if (!Object.hasOwn(state, 'file_inventory')) state.file_inventory = emptyFileInventory(true)
+  else if (
+    !state.file_inventory ||
+    typeof state.file_inventory !== 'object' ||
+    Array.isArray(state.file_inventory)
+  ) {
+    state.file_inventory = invalidFileInventory()
+  }
   return state
 }
 
@@ -149,15 +189,30 @@ function normalizeState(state) {
  * @param {string} target - Installation directory
  * @param {object} state - v2 state object
  */
-export function writeState(target, state) {
+export function writeState(target, state, options = {}) {
   const stateDir = join(target, STATE_DIR)
+  const stateFile = join(stateDir, STATE_FILE)
+  assertNoSymlinkAncestors(stateFile)
   if (!existsSync(stateDir)) {
     mkdirSync(stateDir, { recursive: true })
   }
-  const stateFile = join(stateDir, STATE_FILE)
-  state.updated_at = new Date().toISOString()
+  assertNoSymlinkAncestors(stateFile)
+  state.updated_at = options.updatedAt ?? new Date().toISOString()
   state.schema_version = 2
-  writeFileSync(stateFile, `${JSON.stringify(state, null, 2)}\n`, 'utf8')
+  if (!Object.hasOwn(state, 'file_inventory')) {
+    state.file_inventory = emptyFileInventory(true)
+  } else if (
+    !state.file_inventory ||
+    typeof state.file_inventory !== 'object' ||
+    Array.isArray(state.file_inventory)
+  ) {
+    state.file_inventory = invalidFileInventory()
+  }
+  if (state.file_inventory.target_root == null) {
+    state.file_inventory.target_root = resolve(target)
+  }
+  const content = `${JSON.stringify(state, null, 2)}\n`
+  writeFileAtomically(stateFile, content)
 }
 
 /**