omakit 0.5.0 → 0.6.1

package/tools/subject/resolve.mjs

@@ -3,9 +3,9 @@
 //   reviewer mode - <https url>@<40-char sha>, fetched read-only into
 //                   .cache/subjects/<owner>__<repo>/ and never executed.
 import { execFileSync } from "node:child_process"
-import { existsSync, mkdirSync } from "node:fs"
+import { existsSync, realpathSync, statSync, mkdirSync } from "node:fs"
 import { homedir } from "node:os"
-import { join, resolve } from "node:path"
+import { dirname, join, resolve } from "node:path"
 
 export class SubjectError extends Error {
   constructor(code, message) {
@@ -15,7 +15,7 @@ export class SubjectError extends Error {
 }
 
 function git(dir, args) {
-  return execFileSync("git", ["-C", dir, ...args], { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] })
+  return execFileSync("git", ["-C", dir, ...args], { timeout: 300_000, encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] })
 }
 
 /** "https://github.com/owner/repo(.git)" -> { owner, repository, url } or null. */
@@ -62,9 +62,22 @@ export function resolveSubject(target, options) {
   const parsed = parseTarget(target)
   if (parsed.mode === "author") {
     if (!existsSync(parsed.path)) throw new SubjectError("subject-not-found", `no such directory: ${parsed.path}`)
+    // A file where a directory is meant is said so: `git -C <file>` fails
+    // and read as "not inside a Git repository" although it was (measured
+    // on 2026-09-19 by a first user passing a plugin's README.md;
+    // docs/evidence/ux/2026-09-19-first-user-test.json, finding 7).
+    if (!statSync(parsed.path).isDirectory()) throw new SubjectError("not-a-directory", `${parsed.path} is a file; the target is the plugin's repository directory, the one with its manifest.json (${dirname(parsed.path)}?)`)
+    // The real path, once, here: git reports the top level as a real path,
+    // and a target reached through a symbolic link compared against it
+    // made a subdirectory that does not exist. Measured on 2026-09-19:
+    // `inspect /tmp/tm-link` (a link to /tmp/tm) looked for a manifest at
+    // /tmp/tm/link and exited 2 while verify and submit, which read the
+    // top level alone, resolved it (docs/evidence/ux/2026-09-19-acceptance.json,
+    // finding 5). Every command resolves its subject through this function.
+    const real = realpathSync(parsed.path)
     let top
     try {
-      top = git(parsed.path, ["rev-parse", "--show-toplevel"]).trim()
+      top = git(real, ["rev-parse", "--show-toplevel"]).trim()
     } catch {
       throw new SubjectError("not-a-git-repository", `${parsed.path} is not inside a Git repository`)
     }
@@ -90,7 +103,7 @@ export function resolveSubject(target, options) {
     return {
       mode: "author",
       dir: top,
-      subdir: resolve(parsed.path) === top ? "" : resolve(parsed.path).slice(top.length + 1),
+      subdir: real === top ? "" : real.startsWith(`${top}/`) ? real.slice(top.length + 1) : "",
       commit,
       clean,
       uncommittedFiles: status.length,
@@ -102,7 +115,7 @@ export function resolveSubject(target, options) {
   const dir = join(resolve(options.cacheRoot), "subjects", `${gh.owner}__${gh.repository}`)
   if (!existsSync(join(dir, ".git"))) {
     mkdirSync(dir, { recursive: true })
-    execFileSync("git", ["init", "-q", dir], { encoding: "utf8" })
+    execFileSync("git", ["init", "-q", dir], { timeout: 60_000, encoding: "utf8" })
     git(dir, ["remote", "add", "origin", gh.url])
   }
   let present = false

package/tools/weigh/audit.mjs

@@ -3,15 +3,19 @@
 // `planWeigh()` reads and decides: the shell that runs, whether the session is
 // locked, what is installed and enabled, which plugins will be measured, how
 // many restarts that is and how long it will take. It writes nothing, so the
-// confirmation is made from it and a refusal costs nothing.
+// confirmation is made from it and a refusal costs nothing; a backup an
+// earlier measurement left beside shell.json is a refusal too.
 //
 // `measureWeigh()` is the half that changes the user's machine, and the only
 // one in omakit that does. For every run: write a configuration, restart the
 // shell, wait until every installed plugin is reported, settle, sample; then
-// the next configuration. The backup is taken before the first write and
-// restored in a `finally` that every exit path passes through: a completed
-// run, a restart that did not answer, a thrown error, and an interrupt, which
-// arrives here as an aborted signal rather than a dead process.
+// the next configuration. It takes the consent as an argument and refuses
+// without it. The backup is taken before the first write and restored in a
+// `finally` that every exit path passes through: a completed run, a restart
+// that did not answer, a thrown error, and an interrupt (SIGINT, SIGTERM or
+// SIGHUP), which arrives here as an aborted signal rather than a dead
+// process. A SIGKILL is the one exit no code runs on: it leaves the backup
+// beside shell.json, and the next `planWeigh` names it.
 //
 // The method is a port of the audit described in docs/WEIGH.md, and that
 // document is the contract for what comes out; the bash it was ported from
@@ -23,7 +27,7 @@ import { existsSync, readFileSync, writeFileSync, mkdirSync } from "node:fs"
 import { hostname } from "node:os"
 import { dirname, join, resolve } from "node:path"
 import { run } from "./commands.mjs"
-import { backupConfig, configPaths, md5, restoreConfig, verifyRestore, without, writeConfig } from "./config.mjs"
+import { backupConfig, backupsBeside, configPaths, md5, restoreConfig, verifyRestore, without, writeConfig } from "./config.mjs"
 import { childTicks, cpuTicks, descendants, PROC, pssKb, rssKb } from "./proc.mjs"
 import { median, stats, tickPercent, verdict } from "./stats.mjs"
 import { omakitStateDir } from "../marketplace/paths.mjs"
@@ -218,6 +222,18 @@ export function planWeigh({ target, all = false, runs = DEFAULTS.runs, windowSec
   audited = audited.map((plugin) => ({ id: plugin.id, name: plugin.name || plugin.id, kinds: plugin.kinds || [], firstParty: plugin.firstParty === true, sourceDir: sourceDirOf(plugin.id) }))
 
   const { file: configFile } = configPaths(env)
+  // A backup already beside shell.json is a measurement that never reached
+  // its verification, or one whose restore did not verify: the person has
+  // not seen it yet, and a second measurement over it would bury it. So it
+  // is named, with the restore, and nothing starts until it is gone.
+  // Measured on 2026-09-19: a second consented run started 3 m 14 s after
+  // the first had died with its backup in place, and the backup was found
+  // by a third party the next hour (docs/evidence/ux/2026-09-19-acceptance.json, finding 1).
+  const backups = backupsBeside(configFile)
+  if (backups.length) {
+    const newest = backups.at(-1)
+    throw new WeighError("backup-present", `${newest.file} is a backup a measurement started at ${newest.startedAt} left beside ${configFile}${backups.length > 1 ? ` (${backups.length} such backups)` : ""}; the measurement did not finish its restore, or the restore did not verify, and nothing is weighed over it`, `Compare it with ${configFile}; if the difference is not yours, \`cp ${newest.file} ${configFile}\` and run omarchy-restart-shell; then remove the backup${backups.length > 1 ? "s" : ""} and run weigh again.`)
+  }
   const stateDir = omakitStateDir("weigh", env)
   const timing = restartTiming(stateDir)
   const restarts = (1 + audited.length) * runs
@@ -250,10 +266,17 @@ export function planWeigh({ target, all = false, runs = DEFAULTS.runs, windowSec
   }
 }
 
+/** The stop as an error: `interrupted`, carrying the signal name the controller was aborted with (`SIGINT`, `SIGTERM`, `SIGHUP`) so the exit status can follow it. */
+function interrupted(signal) {
+  const error = new WeighError("interrupted", "interrupted")
+  error.signal = typeof signal?.reason === "string" ? signal.reason : null
+  return error
+}
+
 function sleep(ms, signal) {
   return new Promise((resolveSleep, reject) => {
     if (signal?.aborted) {
-      reject(new WeighError("interrupted", "interrupted"))
+      reject(interrupted(signal))
       return
     }
     const timer = setTimeout(() => {
@@ -262,14 +285,14 @@ function sleep(ms, signal) {
     }, ms)
     function onAbort() {
       clearTimeout(timer)
-      reject(new WeighError("interrupted", "interrupted"))
+      reject(interrupted(signal))
     }
     signal?.addEventListener("abort", onAbort, { once: true })
   })
 }
 
 function checkAbort(signal) {
-  if (signal?.aborted) throw new WeighError("interrupted", "interrupted")
+  if (signal?.aborted) throw interrupted(signal)
 }
 
 /** Wait until listPlugins reports every installed plugin, polling once a second; null when it does not within the timeout. */
@@ -306,11 +329,11 @@ function shellPid(omarchyPath, env) {
  * the sample, or `{ failed }` with the reason when the shell did not come
  * back or did not report every plugin; nothing is estimated in its place.
  */
-async function sampleConfig({ label, runIndex, config, plan, env, procRoot, signal, onPhase, restartTimes }) {
+async function sampleConfig({ label, runIndex, config, plan, lease, env, procRoot, signal, onPhase, restartTimes }) {
   const { configFile, omarchyPath, windowSeconds, settleSeconds, readyTimeoutSeconds, sampleIntervalMs, clockTicksPerSecond: clk } = plan
   const expectedCount = plan.installed.length
   onPhase(`run ${runIndex} of ${plan.runs}: ${label}, restarting the shell`)
-  writeConfig(configFile, config)
+  writeConfig(lease, config)
   const restartStarted = Date.now()
   const restart = run("restartShell", { env, timeoutMs: 120_000 })
   if (!restart.ok) return { label, run: runIndex, failed: "the shell did not answer after the restart" }
@@ -589,11 +612,19 @@ export function buildDocument(plan, samples, { started, ended, config, host = ho
  * the user's own configuration; the document records the md5 before and
  * after and whether they matched.
  *
+ * The consent is an argument, not a flag read somewhere else: `{ consented:
+ * true, how }` is what cli.mjs hands over after `--yes` or a `y` at the
+ * terminal, and without it nothing here writes; `backupConfig` refuses
+ * too, so no caller can reach shell.json around this function.
+ *
  * @param {ReturnType<typeof planWeigh>} plan
- * @param {{ env?: NodeJS.ProcessEnv, procRoot?: string, signal?: AbortSignal, omakitVersion?: string,
- *           onPhase?: (text: string) => void, onLine?: (line: { state: string, text: string }) => void }} [options]
+ * @param {{ consent: { consented: boolean, how?: string }, env?: NodeJS.ProcessEnv, procRoot?: string, signal?: AbortSignal, omakitVersion?: string,
+ *           onPhase?: (text: string) => void, onLine?: (line: { state: string, text: string }) => void }} options
  */
-export async function measureWeigh(plan, { env = plan.env || process.env, procRoot = PROC, signal, omakitVersion = "unknown", onPhase = () => {}, onLine = () => {} } = {}) {
+export async function measureWeigh(plan, { consent, env = plan.env || process.env, procRoot = PROC, signal, omakitVersion = "unknown", onPhase = () => {}, onLine = () => {} } = {}) {
+  if (consent?.consented !== true) throw new WeighError("not-confirmed", "no consented measurement is running, so shell.json is not touched", "Run it again and answer y, or pass --yes when the person whose shell it is has agreed.")
+  // The backup's name is the UTC second the measurement began: the moment
+  // shell.json was first touched, readable from the file name alone.
   const stamp = fileStamp().replace(/[-T]/g, "").replace(/Z$/, "")
   const ids = plan.audited.map((plugin) => plugin.id)
   plan.baselineConfig = without(plan.effective, ids, plan.installed)
@@ -602,7 +633,7 @@ export async function measureWeigh(plan, { env = plan.env || process.env, procRo
     configs.push({ label: plugin.id, config: without(plan.effective, ids.filter((id) => id !== plugin.id), plan.installed) })
   }
   mkdirSync(dirname(plan.configFile), { recursive: true })
-  const backup = backupConfig(plan.configFile, stamp)
+  const backup = backupConfig(plan.configFile, stamp, consent)
   onLine({ state: "info", text: backup.bytes === null
     ? `${plan.configFile} does not exist; it will be removed again afterwards`
     : `${plan.configFile} backed up to ${backup.backupFile}, md5 ${backup.md5Before}` })
@@ -622,7 +653,7 @@ export async function measureWeigh(plan, { env = plan.env || process.env, procRo
     for (let runIndex = 1; runIndex <= plan.runs; runIndex += 1) {
       for (const { label, config } of configs) {
         checkAbort(signal)
-        const sample = await sampleConfig({ label, runIndex, config, plan, env, procRoot, signal, onPhase, restartTimes })
+        const sample = await sampleConfig({ label, runIndex, config, plan, lease: backup, env, procRoot, signal, onPhase, restartTimes })
         // One line per configuration, on the record: a forty-restart run
         // in a pipe would otherwise be silent for half an hour, and the
         // figures here are the raw samples a reader can check the medians

package/tools/weigh/config.mjs

@@ -8,10 +8,22 @@
 // its bytes are read once and written to a timestamped backup beside it, and
 // those same bytes are written back over it on the way out. Nothing here
 // re-serialises what the user wrote.
+//
+// Nothing here writes without a lease, and a lease is opened only with the
+// person's consent in hand: `backupConfig()` refuses `consented: true`
+// absent, and the two writes that follow take the lease it returned, so
+// there is no order of calls in which a measurement configuration reaches
+// shell.json before its backup exists or before anyone agreed. Measured on
+// 2026-09-19: two omakit backups appeared beside a person's shell.json in a
+// window when they had authorised no weighing on their own machine; the
+// writes came from consented runs in another session, but the code allowed
+// a write with nothing but a path (docs/evidence/ux/2026-09-19-acceptance.json,
+// finding 1). Every write is a whole file renamed into place, so a process
+// killed mid-write leaves the old file whole, never a truncated one.
 
 import { createHash } from "node:crypto"
-import { existsSync, readFileSync, statSync, unlinkSync, writeFileSync } from "node:fs"
-import { join } from "node:path"
+import { closeSync, existsSync, fsyncSync, openSync, readdirSync, readFileSync, renameSync, statSync, unlinkSync, writeFileSync } from "node:fs"
+import { basename, dirname, join } from "node:path"
 
 /** Where Omarchy keeps the shell configuration: `~/.config/omarchy/shell.json`, the path the shell itself reads. */
 export function configPaths(env = process.env) {
@@ -24,6 +36,36 @@ export function md5(bytes) {
   return createHash("md5").update(bytes).digest("hex")
 }
 
+/** The name every backup carries: `shell.json.omakit-backup-<UTC stamp, YYYYMMDDHHMMSS>`, the second the measurement began. */
+export const BACKUP_SUFFIX = ".omakit-backup-"
+const BACKUP_NAME = /\.omakit-backup-(\d{14})$/
+
+/**
+ * The backups already beside the configuration, oldest first: each one is
+ * a measurement that did not reach its verification, or one whose restore
+ * did not verify, and `planWeigh` refuses to start another until the
+ * person has looked at it (docs/WEIGH.md).
+ *
+ * @returns {{ file: string, stamp: string, startedAt: string }[]}
+ */
+export function backupsBeside(configFile) {
+  const dir = dirname(configFile)
+  const name = basename(configFile)
+  let entries = []
+  try {
+    entries = readdirSync(dir)
+  } catch {
+    return []
+  }
+  return entries
+    .filter((entry) => entry.startsWith(`${name}${BACKUP_SUFFIX}`) && BACKUP_NAME.test(entry))
+    .sort()
+    .map((entry) => {
+      const stamp = entry.match(BACKUP_NAME)[1]
+      return { file: join(dir, entry), stamp, startedAt: `${stamp.slice(0, 4)}-${stamp.slice(4, 6)}-${stamp.slice(6, 8)}T${stamp.slice(8, 10)}:${stamp.slice(10, 12)}:${stamp.slice(12, 14)}Z` }
+    })
+}
+
 /**
  * The effective configuration with a set of plugin ids removed: every bar
  * layout entry with that id, every `plugins[]` entry with that id, and for
@@ -55,47 +97,87 @@ export function without(config, ids, installed) {
   return out
 }
 
+/** A refusal from this module: no lease, or a lease nobody consented to. */
+export class ConsentError extends Error {
+  constructor(message) {
+    super(message)
+    this.name = "ConsentError"
+    this.code = "not-confirmed"
+  }
+}
+
+function requireLease(lease, what) {
+  if (!lease || lease.consented !== true || typeof lease.configFile !== "string" || typeof lease.backupFile !== "string") {
+    throw new ConsentError(`${what} needs the lease backupConfig() returns after consent; nothing was written`)
+  }
+}
+
+/**
+ * The whole file, then the name: written to `<target>.part` beside its
+ * target, fsynced, and renamed into place, so at every instant the target
+ * is either the old file or the new one. The mode is set on the part file
+ * before the rename, so a 0600 shell.json stays 0600.
+ */
+function writeWhole(target, bytes, mode) {
+  const part = `${target}.part`
+  const fd = openSync(part, "w", mode)
+  try {
+    writeFileSync(fd, bytes)
+    fsyncSync(fd)
+  } finally {
+    closeSync(fd)
+  }
+  renameSync(part, target)
+}
+
 /**
  * Read the configuration file and write its bytes to a timestamped backup
- * beside it. Returns what the restore needs: the bytes, the backup path and
- * the md5. A missing file is recorded as such and restored by removal.
+ * beside it. Returns the lease every later write needs: the bytes, the
+ * backup path, the md5 and the mode. A missing file is recorded as such
+ * and restored by removal. Refuses without `consented: true`.
  *
  * @param {string} configFile
  * @param {string} stamp UTC, `YYYYMMDDHHMMSS`
+ * @param {{ consented: boolean }} consent
  */
-export function backupConfig(configFile, stamp) {
+export function backupConfig(configFile, stamp, { consented = false } = {}) {
+  if (consented !== true) throw new ConsentError("a backup of shell.json is the first write of a measurement, and no measurement was consented to; nothing was written")
   let bytes = null
+  let mode = 0o600
   try {
     bytes = readFileSync(configFile)
+    // The same mode as the original: shell.json is 0600 on an Omarchy
+    // install, and a copy of a private file is a private file.
+    mode = statSync(configFile).mode & 0o777
   } catch (error) {
     if (error.code !== "ENOENT") throw error
   }
-  const backupFile = `${configFile}.omakit-backup-${stamp}`
-  // The same mode as the original: shell.json is 0600 on an Omarchy install,
-  // and a copy of a private file is a private file.
-  if (bytes !== null) writeFileSync(backupFile, bytes, { mode: statSync(configFile).mode & 0o777 })
-  return { configFile, backupFile, bytes, md5Before: bytes === null ? null : md5(bytes) }
+  const backupFile = `${configFile}${BACKUP_SUFFIX}${stamp}`
+  if (bytes !== null) writeWhole(backupFile, bytes, mode)
+  return { configFile, backupFile, bytes, mode, md5Before: bytes === null ? null : md5(bytes), consented: true }
 }
 
 /**
  * Write one configuration for a run. The document is serialised the way
  * `jq .` would, two-space indented, so the shell reads exactly what the
- * transform produced.
+ * transform produced. Takes the lease, never a bare path.
  */
-export function writeConfig(configFile, config) {
-  writeFileSync(configFile, `${JSON.stringify(config, null, 2)}\n`)
+export function writeConfig(lease, config) {
+  requireLease(lease, "writing a measurement configuration")
+  writeWhole(lease.configFile, Buffer.from(`${JSON.stringify(config, null, 2)}\n`), lease.mode)
 }
 
 /**
- * Put the user's bytes back. Verification is a separate step, after the
- * shell has been restarted on them: a shell that rewrites the file as it
- * starts is exactly what the md5 has to catch, so it is read after the
+ * Put the user's bytes back, whole. Verification is a separate step, after
+ * the shell has been restarted on them: a shell that rewrites the file as
+ * it starts is exactly what the md5 has to catch, so it is read after the
  * restart and not before.
  *
- * @param {{ configFile: string, bytes: Buffer|null }} backup
+ * @param {{ configFile: string, bytes: Buffer|null, mode: number, consented: true }} lease
  */
-export function restoreConfig(backup) {
-  const { configFile, bytes } = backup
+export function restoreConfig(lease) {
+  requireLease(lease, "restoring shell.json")
+  const { configFile, bytes, mode } = lease
   if (bytes === null) {
     try {
       unlinkSync(configFile)
@@ -104,7 +186,7 @@ export function restoreConfig(backup) {
     }
     return
   }
-  writeFileSync(configFile, bytes)
+  writeWhole(configFile, bytes, mode)
 }
 
 /**
@@ -112,11 +194,11 @@ export function restoreConfig(backup) {
  * of the backup. The backup is removed only when they are equal; otherwise
  * it stays and the caller says so.
  *
- * @param {{ configFile: string, backupFile: string, bytes: Buffer|null, md5Before: string|null }} backup
+ * @param {{ configFile: string, backupFile: string, bytes: Buffer|null, md5Before: string|null }} lease
  * @returns {{ md5After: string|null, restored: boolean, backupRemoved: boolean }}
  */
-export function verifyRestore(backup) {
-  const { configFile, backupFile, bytes, md5Before } = backup
+export function verifyRestore(lease) {
+  const { configFile, backupFile, bytes, md5Before } = lease
   if (bytes === null) return { md5After: null, restored: !existsSync(configFile), backupRemoved: false }
   let md5After = null
   try {
@@ -128,4 +210,3 @@ export function verifyRestore(backup) {
   if (restored) unlinkSync(backupFile)
   return { md5After, restored, backupRemoved: restored }
 }
-

package/tools/weigh/list.mjs

@@ -51,7 +51,16 @@ export function lastWeighings(stateDir) {
  */
 export function installedPlugins({ env = process.env } = {}) {
   const listed = run("listPlugins", { env })
-  if (!listed.ok) throw new WeighError("shell-not-running", "omarchy plugin list did not answer, and the list is what the shell has installed", "omarchy-restart-shell")
+  // The reason travels with the refusal: what the command said on stderr
+  // and how it exited. Measured on 2026-09-19 by a first user whose piped
+  // `omakit audit` reported only "did not answer" while the unpiped one
+  // audited 19 plugins; without the child's own words nothing could tell
+  // the two apart (docs/evidence/ux/2026-09-19-first-user-test.json).
+  if (!listed.ok) {
+    const said = String(listed.stderr || "").trim().split("\n").filter(Boolean).at(-1)
+    const how = listed.missing ? "omarchy is not on PATH" : `exit ${listed.status === null ? "on a signal or the 30 s deadline" : listed.status}${said ? `: ${said}` : ", nothing on stderr"}`
+    throw new WeighError("shell-not-running", `omarchy plugin list did not answer (${how}), and the list is what the shell has installed`, listed.missing ? "Run this on an Omarchy machine, with omarchy on PATH." : "omarchy-restart-shell, or run it from the session: it needs OMARCHY_PATH and the Wayland display the session sets.")
+  }
   let installed
   try {
     installed = JSON.parse(listed.stdout)