@brainervirus/workit-core 8.13.0 → 8.14.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@brainervirus/workit-core",
-  "version": "8.13.0",
+  "version": "8.14.0",
   "private": false,
   "description": "Workit shared core — task, policy, evidence, review, decision, worker, and writer state for agentic coding workflows",
   "keywords": [

package/scripts/rewrite-workspace-deps.ts

@@ -29,9 +29,9 @@ for (const pkg of [
 ]) {
   const file = resolve(root, `packages/${pkg}/package.json`);
   const data = JSON.parse(readFileSync(file, "utf8"));
-  // devDependencies too: the Claude Code plugin bundles core and the CLI into
-  // dist/, so they are build-time only, but a published manifest must still
-  // never carry workspace:*.
+  // devDependencies too: every adapter bundles core (and the MCP server) into
+  // dist/, so they are build-time only (N19) and npm never installs them, but
+  // a published manifest must still never carry workspace:*.
   const groups = [data.dependencies, data.devDependencies].filter(Boolean);
   if (groups.length === 0) continue;
   for (const deps of groups)

package/skills/workit-fanout/SKILL.md

@@ -25,9 +25,9 @@ ceremony; do it yourself. Workit never spawns agents; you do.
    it; change the plan or the standing orders and render again.
 4. **Spawn in a rolling window**, in the background, each in its own worktree:
    keep 4-6 in flight and refill from `spawnable` in `workit fanout status` as
-   each one finishes. Pick the model from TIER (`references/orchestration.md`).
-   Claude Code: the `implementer` agent; elsewhere first `workit fanout
-   worktree create <slice>`.
+   each one finishes. Model: the brief's `model:` line, else TIER
+   (`references/orchestration.md`). Claude Code: the `implementer` agent;
+   elsewhere first `workit fanout worktree create <slice>`.
 5. **Judge liveness by side effects only:** `workit fanout status` (head age,
    PR, CI, verdict, landed; STUCK past the TIMEBOX). Stop a stuck worker and
    observe that it exited (a timeout is not proof). Removing a worktree drops
@@ -53,7 +53,7 @@ ceremony; do it yourself. Workit never spawns agents; you do.
    status` order, release the worktrees you made, and `workit ledger standing
    clear`. Only you touch topology: workers never rebase, retarget or merge,
    except the integration-tip merge in integration mode. Then ship
-   (workit-ship).
+   (workit-ship) up to `defaultEndpoint` from `workit grant show`.
 
 ## Example
 

package/skills/workit-fanout/references/orchestration.md

@@ -5,8 +5,10 @@ and fans in. Workit records and checks; the host's own subagents run the work.
 
 ## TIER to model
 
-TIER is a field of each slice and of its brief. Map it where the host lets you
-pick a model per spawn; nothing in the workspace config routes it.
+TIER is a field of each slice and of its brief. When the workspace sets
+`fanout.tierModels`, the brief has a `model:` line under TIER and `workit
+fanout status` names the model next to each spawnable slice: use that model.
+Without one, map TIER where the host lets you pick a model per spawn:
 
 | TIER | Claude Code (`model` on the Agent call) | Hosts without a per-spawn model |
 | --- | --- | --- |
@@ -72,11 +74,12 @@ Which session id a verdict carries, per host:
 
 - Claude Code: subagents inherit your `WORKIT_SESSION_ID`, so the
   SubagentStart hook names each `verifier` and `reviewer` its own session
-  (`<lead>:<agent id>`), passed exactly as `--session`: the hook records the
-  ids it issues, and only those are accepted. An `implementer` is issued
+  (`<lead>:<agent id>`) and a token only that subagent sees, passed exactly as
+  `--session` and `--token`: the hook records the ids it issues, and only
+  those, with their token, are accepted. An `implementer` is issued
   none: it keeps your id in its env for its workit commands and commits.
 - Codex: the `workit-verifier` and `workit-reviewer` agents get the same
-  issued `--session` from SubagentStart; any other verifier passes
+  issued `--session` and `--token` from SubagentStart; any other verifier passes
   `--as verifier`.
 - OpenCode: a child session's shell already has
   `WORKIT_SESSION_ID=<lead>:<child>`; Pi: a supervised worker's shell has

package/skills/workit-review/SKILL.md

@@ -8,7 +8,7 @@ description: Independent review of a diff, branch or PR - intent fidelity and st
 Review the candidate, never the author's summary of it. A session that wrote a
 commit on the branch cannot record a passing verdict: if that is you, hand the
 review to a fresh agent with its own host-derived session: Claude Code and
-Codex, the `reviewer` or `verifier` agent (`--session` from SubagentStart);
+Codex, the `reviewer` or `verifier` agent (`--session` and `--token` from SubagentStart);
 OpenCode, a child session; Pi, a supervised worker. Never hand-mint one such
 as `<lead>-v1`: it is refused as `forged_session`.
 An author's `--self` verdict reads self-reviewed and never counts as

package/src/core/hygiene.ts

@@ -1,4 +1,5 @@
-import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { spawnSync } from "node:child_process";
+import { existsSync, readFileSync, readdirSync, writeFileSync } from "node:fs";
 import path from "node:path";
 import { changelogUnreleasedStats } from "./changelog";
 import { assetRoot } from "./package-root";
@@ -75,6 +76,41 @@ export const hygieneFiles = (
   return { state, openSource };
 };
 
+export type ProjectTarget = { ok: true; root: string } | { ok: false; refused: string };
+
+/**
+ * Where project files (gitignore, hygiene) belong: the git toplevel of `dir`.
+ * Outside a repository there is no project to scaffold, and a folder holding
+ * several projects must never receive them, so the answer is a refusal naming
+ * the way out: the child repositories found one level down, or `cd <repo>`.
+ */
+export const projectTarget = (dir: string): ProjectTarget => {
+  const start = path.resolve(dir);
+  const top = spawnSync("git", ["rev-parse", "--show-toplevel"], { cwd: start, encoding: "utf8" });
+  const root = top.status === 0 ? (top.stdout ?? "").trim() : "";
+  if (root) return { ok: true, root: path.resolve(root) };
+  let children: string[] = [];
+  try {
+    children = readdirSync(start, { withFileTypes: true })
+      .filter((entry) => entry.isDirectory() && existsSync(path.join(start, entry.name, ".git")))
+      .map((entry) => path.join(start, entry.name))
+      .toSorted();
+  } catch {
+    children = [];
+  }
+  const where =
+    children.length > 0
+      ? `run it inside one of its repositories: ${children
+          .slice(0, 5)
+          .map((child) => `cd ${child}`)
+          .join(", ")}${children.length > 5 ? ` (+${children.length - 5} more)` : ""}`
+      : "cd <repo> (or git init here) and run workit init again";
+  return {
+    ok: false,
+    refused: `${start} is not a git repository, so no project files were added there; ${where}`,
+  };
+};
+
 // Pure planner: which hygiene files would be created and with what content,
 // without touching the filesystem. Drives the wizard preview (WZ-08) and the
 // apply path; ensureHygieneFiles is just "plan then write".

package/src/core/live-session.ts

@@ -0,0 +1,333 @@
+// Live-session markers (#274): which agent session last wrote in a checkout,
+// so another session's write gate can refuse to edit a checkout a live agent
+// owns. One marker per checkout (a worktree's top level: worktrees of one
+// repository are distinct checkouts) in the per-user state dir, so nothing is
+// written into a repository Workit does not manage:
+// `<state>/live-sessions/<hash of the checkout>.json`, holding the owner's
+// session, lead, host, process id, machine and heartbeat. The hooks each host
+// already runs write it on every allowed edit or mutating command.
+//
+// A marker is live while its heartbeat is younger than LIVE_SESSION_TTL_MS
+// and, on the same machine, its process still runs. The owning session, its
+// subagents (`<lead>:<agent>`, `<lead>-w-<slice>`, a parent session) and any
+// session in the same host process are never refused. Every state error reads
+// as "no marker": the guard fails open.
+import { spawnSync } from "node:child_process";
+import { createHash } from "node:crypto";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { resolveStore } from "../store/paths";
+import { resolveStateDir } from "./logger";
+import { processStartOf } from "./store-lock";
+
+export const LIVE_SESSION_TTL_MS = 15 * 60_000;
+/** Rewrite a live marker of one's own at most this often. */
+const HEARTBEAT_EVERY_MS = 30_000;
+
+export type LiveOwner = {
+  host: string;
+  session: string;
+  /** Lead ids this session counts as (its own lead, its parent's). */
+  leads: string[];
+  /**
+   * The host process (null when it cannot be told), read lazily: off Linux
+   * it costs `ps` calls, so only a write or a foreign marker asks for it.
+   */
+  pid: () => number | null;
+};
+
+export type LiveMarker = {
+  version: 1;
+  session: string;
+  leads: string[];
+  host: string;
+  pid: number | null;
+  /** The pid's start time, so a reused pid does not keep the marker alive. */
+  pidStart: string | null;
+  machine: string;
+  checkout: string;
+  heartbeatAt: string;
+};
+
+export type LiveDeps = {
+  now?: Date;
+  alive?: (pid: number) => boolean;
+  machine?: string;
+  ttlMs?: number;
+};
+
+/**
+ * What reads the process table; tests swap it to count `ps` calls or to act
+ * as another platform.
+ */
+export const liveProbe = {
+  platform: process.platform as string,
+  run: (args: string[]): string =>
+    spawnSync("ps", args, { encoding: "utf8", timeout: 2_000 }).stdout ?? "",
+  start: (pid: number): string | null => processStartOf(pid),
+};
+
+/** A session's lead: the part before `:` (an issued subagent id), minus a fanout `-w-<slice>` tail. */
+export const leadOf = (session: string): string =>
+  session.split(":")[0].replace(/-w-.*$/su, "") || session;
+
+const familyOf = (host: string): string => host.replace(/_(?:cli|desktop)$/u, "");
+
+const processAlive = (pid: number): boolean => {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    return (error as NodeJS.ErrnoException).code === "EPERM";
+  }
+};
+
+/** Parent pid and command line of `pid`: /proc on Linux, `ps` on other POSIX systems. */
+const processInfo = (pid: number): { ppid: number; command: string } | null => {
+  try {
+    if (liveProbe.platform === "linux") {
+      const stat = fs.readFileSync(`/proc/${pid}/stat`, "utf8");
+      const ppid = Number(stat.slice(stat.lastIndexOf(")") + 2).split(" ")[1]);
+      const command = fs.readFileSync(`/proc/${pid}/cmdline`, "utf8").replaceAll("\0", " ");
+      return Number.isInteger(ppid) ? { ppid, command: command.trim() } : null;
+    }
+    if (liveProbe.platform === "win32") return null;
+    const match = /^\s*(\d+)\s+(.*)$/su.exec(
+      liveProbe.run(["-o", "ppid=,command=", "-p", String(pid)]),
+    );
+    return match ? { ppid: Number(match[1]), command: match[2].trim() } : null;
+  } catch {
+    return null;
+  }
+};
+
+/** A process that only launches the hook and exits with it: a shell, npx, the Cursor launcher. */
+const WRAPPER =
+  /^(?:\S*\/)?(?:sh|bash|dash|zsh|ash|ksh|fish|env|timeout|npx|npm|bunx|cmd\.exe|pwsh|powershell)(?:\s|$)|launch\.mjs|npx-cli\.js/u;
+
+const PIDS = new Map<string, number | null>();
+
+/**
+ * The long-lived host process behind this hook: the plugin's own process for
+ * an in-process host (OpenCode, Pi); for a hook process (Claude Code, Codex,
+ * Cursor), the nearest ancestor that is not a launcher wrapper. Null when the
+ * ancestry cannot be read (Windows). Cached per process.
+ */
+export const hostPid = (transport: string): number | null => {
+  if (transport !== "hook-process") return process.pid;
+  const key = `${liveProbe.platform}\0${process.ppid}`;
+  if (PIDS.has(key)) return PIDS.get(key) ?? null;
+  // Windows: no ancestry to walk, so no owner pid at all.
+  if (liveProbe.platform === "win32") {
+    PIDS.set(key, null);
+    return null;
+  }
+  let pid = process.ppid;
+  for (let hop = 0; hop < 4; hop++) {
+    const info = processInfo(pid);
+    if (!info || !WRAPPER.test(info.command) || info.ppid <= 1) break;
+    pid = info.ppid;
+  }
+  PIDS.set(key, pid);
+  return pid;
+};
+
+const sessionSafe = (value: string): string => value.replace(/[^A-Za-z0-9_.:@/+-]/gu, "-");
+
+/** The owner a hook acts for, or null without a session id (never refused, never recorded). */
+export const liveOwner = (
+  input: { host: string; session: { id: string; parentId: string | null } },
+  transport: string,
+  env: NodeJS.ProcessEnv = process.env,
+): LiveOwner | null => {
+  const session = input.session.id?.trim();
+  if (!session) return null;
+  const leads = new Set([leadOf(sessionSafe(session))]);
+  if (input.session.parentId) leads.add(leadOf(sessionSafe(input.session.parentId)));
+  // A Pi worker's hooks see its own Pi session; its workit id names the lead.
+  if (env.WORKIT_PI_WORKER_SESSION && env.WORKIT_SESSION_ID)
+    leads.add(leadOf(sessionSafe(env.WORKIT_SESSION_ID)));
+  return {
+    host: input.host,
+    session: sessionSafe(session),
+    leads: [...leads],
+    pid: () => hostPid(transport),
+  };
+};
+
+/** The checkout (worktree top level) holding `target`; null outside git. */
+const checkoutOf = (target: string): string | null => {
+  let dir = path.resolve(target);
+  // A path that does not exist yet: its nearest existing ancestor.
+  while (!fs.existsSync(dir) && path.dirname(dir) !== dir) dir = path.dirname(dir);
+  if (fs.existsSync(dir) && !fs.statSync(dir).isDirectory()) dir = path.dirname(dir);
+  // Inside a `.git` directory: the checkout it belongs to.
+  const parts = dir.split(path.sep);
+  const dotGit = parts.lastIndexOf(".git");
+  if (dotGit > 0) dir = parts.slice(0, dotGit).join(path.sep) || path.sep;
+  const location = resolveStore(dir);
+  if (location instanceof Error || !location.shared || !location.top) return null;
+  let top = location.top;
+  try {
+    top = fs.realpathSync.native(top);
+  } catch {
+    // keep git's spelling
+  }
+  return top;
+};
+
+/** The marker file of a checkout. */
+export const markerFile = (top: string): string =>
+  path.join(
+    resolveStateDir(),
+    "live-sessions",
+    `${createHash("sha256").update(checkoutKey(top)).digest("hex").slice(0, 32)}.json`,
+  );
+
+/**
+ * One spelling per checkout, however the path was written: resolved through
+ * symlinks and Windows 8.3 short names (`RUNNER~1`), native separators, and
+ * on Windows a lower-cased path (drive letter included).
+ */
+export const checkoutKey = (top: string, platform: string = process.platform): string => {
+  let key = path.resolve(top);
+  try {
+    key = fs.realpathSync.native(key);
+  } catch {
+    // a path that does not exist keeps its resolved spelling
+  }
+  return platform === "win32" ? key.replaceAll("/", "\\").toLowerCase() : key;
+};
+
+const readMarker = (file: string): LiveMarker | null => {
+  try {
+    const value = JSON.parse(fs.readFileSync(file, "utf8")) as Partial<LiveMarker>;
+    if (
+      value?.version !== 1 ||
+      typeof value.session !== "string" ||
+      typeof value.host !== "string" ||
+      typeof value.heartbeatAt !== "string" ||
+      Number.isNaN(Date.parse(value.heartbeatAt))
+    )
+      return null;
+    return {
+      version: 1,
+      session: value.session,
+      leads: Array.isArray(value.leads)
+        ? value.leads.filter((item) => typeof item === "string")
+        : [],
+      host: value.host,
+      pid: typeof value.pid === "number" ? value.pid : null,
+      pidStart: typeof value.pidStart === "string" ? value.pidStart : null,
+      machine: typeof value.machine === "string" ? value.machine : "",
+      checkout: typeof value.checkout === "string" ? value.checkout : "",
+      heartbeatAt: value.heartbeatAt,
+    };
+  } catch {
+    return null;
+  }
+};
+
+const ageOf = (marker: LiveMarker, now: Date): number =>
+  now.getTime() - Date.parse(marker.heartbeatAt);
+
+/**
+ * Whether the marker's owner still counts: a fresh heartbeat and, on this
+ * machine, a running process that is still the one recorded (same start time).
+ */
+const isLive = (marker: LiveMarker, deps: LiveDeps): boolean => {
+  const age = ageOf(marker, deps.now ?? new Date());
+  if (age > (deps.ttlMs ?? LIVE_SESSION_TTL_MS)) return false;
+  if (marker.machine !== (deps.machine ?? os.hostname()) || marker.pid === null) return true;
+  if (!(deps.alive ?? processAlive)(marker.pid)) return false;
+  if (marker.pidStart === null) return true;
+  const start = liveProbe.start(marker.pid);
+  return start === null || start === marker.pidStart;
+};
+
+/** The same session, one of its subagents or fanout workers, or its lead: ids alone, no I/O. */
+const sameLead = (marker: LiveMarker, owner: LiveOwner): boolean =>
+  marker.session === owner.session ||
+  owner.leads.some((lead) => lead === marker.session || marker.leads.includes(lead));
+
+/**
+ * The same session, one of its subagents or its lead, or another session of
+ * the same host process. Where a pid is unknown (Windows), any session of the
+ * same host family counts as the owner: the guard cannot tell a subagent or a
+ * cleared session from another window there, and never denies on a guess.
+ */
+export const sameOwner = (marker: LiveMarker, owner: LiveOwner, machine: string): boolean => {
+  if (sameLead(marker, owner)) return true;
+  if (marker.machine !== machine) return false;
+  const pid = owner.pid();
+  // Without a pid and its start time the process cannot be told apart.
+  if (pid === null || marker.pid === null || marker.pidStart === null)
+    return familyOf(marker.host) === familyOf(owner.host);
+  return marker.pid === pid;
+};
+
+export type LiveConflict = { marker: LiveMarker; file: string; ageMs: number; checkout: string };
+
+/** The live marker of another session in `target`'s checkout, or null (also on any error). */
+export const liveConflict = (
+  target: string,
+  owner: LiveOwner,
+  deps: LiveDeps = {},
+): LiveConflict | null => {
+  try {
+    const checkout = checkoutOf(target);
+    if (!checkout) return null;
+    const file = markerFile(checkout);
+    const marker = readMarker(file);
+    // Ids first: the owner's own marker never costs a process-table read.
+    if (!marker || sameLead(marker, owner) || !isLive(marker, deps)) return null;
+    if (sameOwner(marker, owner, deps.machine ?? os.hostname())) return null;
+    return { marker, file, ageMs: ageOf(marker, deps.now ?? new Date()), checkout };
+  } catch {
+    return null;
+  }
+};
+
+/**
+ * Record `owner` as the live session of `target`'s checkout (a fresh
+ * heartbeat), unless another live session owns it; one's own marker is
+ * rewritten at most every 30 s. Two sessions claiming a free checkout at
+ * the same instant race: each writes a temp file and renames it, the last
+ * rename wins, and the loser is refused from its next write on. Never throws.
+ */
+export const claimLiveSession = (target: string, owner: LiveOwner, deps: LiveDeps = {}): void => {
+  try {
+    const checkout = checkoutOf(target);
+    if (!checkout) return;
+    const file = markerFile(checkout);
+    const now = deps.now ?? new Date();
+    const machine = deps.machine ?? os.hostname();
+    const current = readMarker(file);
+    if (current) {
+      const age = ageOf(current, now);
+      // One's own fresh marker: nothing to read or write.
+      if (sameLead(current, owner) && age >= 0 && age < HEARTBEAT_EVERY_MS) return;
+      if (!sameLead(current, owner) && isLive(current, deps) && !sameOwner(current, owner, machine))
+        return;
+    }
+    const pid = owner.pid();
+    const marker: LiveMarker = {
+      version: 1,
+      session: owner.session,
+      leads: owner.leads,
+      host: owner.host,
+      pid,
+      pidStart: pid === null ? null : liveProbe.start(pid),
+      machine,
+      checkout,
+      heartbeatAt: now.toISOString(),
+    };
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    const temp = `${file}.${process.pid}.tmp`;
+    fs.writeFileSync(temp, JSON.stringify(marker));
+    fs.renameSync(temp, file);
+  } catch {
+    // Fail open: without a marker nobody is refused.
+  }
+};

package/src/core/store-lock.ts

@@ -44,8 +44,16 @@ export const RECLAIM_GUARD_TTL_MS = 30_000;
  * wait blocks the calling thread, so in-process hosts (OpenCode, MCP, Pi) keep
  * the short default; the CLI raises it for its own process.
  */
-let defaultLockTimeoutMs = 250;
+export const IN_PROCESS_LOCK_TIMEOUT_MS = 250;
+let defaultLockTimeoutMs = IN_PROCESS_LOCK_TIMEOUT_MS;
 export const defaultLockTimeout = (): number => defaultLockTimeoutMs;
+/**
+ * The wait for a lock that a CLI process may hold longer (the ledger's
+ * network-filesystem lock): `cliMs` once the process raised the default
+ * (the CLI does), else the in-process cap.
+ */
+export const hostAwareLockTimeout = (cliMs: number): number =>
+  defaultLockTimeoutMs > IN_PROCESS_LOCK_TIMEOUT_MS ? cliMs : IN_PROCESS_LOCK_TIMEOUT_MS;
 export const setDefaultLockTimeout = (ms: number): void => {
   defaultLockTimeoutMs = ms;
 };

package/src/core/workspaces.ts

@@ -149,6 +149,16 @@ const workspaceConfigSchema = z
      * authorship lives in the ledger only (`commit.recorded`).
      */
     trailers: z.boolean().optional(),
+    /**
+     * Whether the live-session guard denies edits in a checkout another live
+     * agent session owns (default true; core/live-session.ts).
+     */
+    liveSessionGuard: z.boolean().optional(),
+    /**
+     * Fanout settings. `tierModels` names the model per slice TIER, as one
+     * name or per host family; read leniently (workspaceTierModel).
+     */
+    fanout: z.object({ tierModels: z.unknown().optional() }).passthrough().optional(),
     /** Autonomy grants (D15): only ever set here, by the user. */
     autonomy: z
       .object(
@@ -695,35 +705,145 @@ export const resolveRuntimeReleaseTracks = (
     : null;
 };
 
+type RuntimeEntry = Record<string, unknown> & { name: string };
+
 /**
- * Whether commits in cwd's workspace carry the `Workit-Session:` trailer.
- * The selected workspace's own `trailers` wins; unset, it inherits from the
- * nearest enclosing workspace that also matches cwd (a repo workspace nested
- * in `work`), and defaults to true. Read leniently: no workspace, or an
- * unreadable workspaces.json, keeps the trailer. `from` names the entry the
- * value came from (null for the default).
+ * The workspace selected for cwd and the entry a setting comes from: the
+ * selected workspace when `has(entry)`, else the nearest enclosing workspace
+ * that also matches cwd (a repo workspace nested in `work`). Read leniently:
+ * no workspace, or an unreadable workspaces.json, reads as null.
  */
-export const workspaceTrailers = (
+const inheritedSetting = (
   cwd: string,
-  dir?: string,
-): { enabled: boolean; workspace: string | null; from: string | null } => {
+  dir: string | undefined,
+  has: (entry: RuntimeEntry) => boolean,
+): { workspace: string; source: RuntimeEntry | null } | null => {
   let matched: ReturnType<typeof matchRuntimeWorkspace>;
   try {
     matched = matchRuntimeWorkspace(cwd, dir);
   } catch {
-    return { enabled: true, workspace: null, from: null };
+    return null;
   }
-  if (!matched) return { enabled: true, workspace: null, from: null };
+  if (!matched) return null;
   const { selected, matches } = matched;
   const enclosing = matches
     .filter((entry) => entry !== selected)
     .toSorted((a, b) => globSpecificity(b.glob) - globSpecificity(a.glob));
-  const source = [selected, ...enclosing].find((entry) => typeof entry.trailers === "boolean");
+  return { workspace: selected.name, source: [selected, ...enclosing].find(has) ?? null };
+};
+
+/**
+ * Whether commits in cwd's workspace carry the `Workit-Session:` trailer.
+ * The selected workspace's own `trailers` wins; unset, it inherits from the
+ * nearest enclosing workspace that also matches cwd, and defaults to true.
+ * No workspace, or an unreadable workspaces.json, keeps the trailer. `from`
+ * names the entry the value came from (null for the default).
+ */
+export const workspaceTrailers = (
+  cwd: string,
+  dir?: string,
+): { enabled: boolean; workspace: string | null; from: string | null } => {
+  const found = inheritedSetting(cwd, dir, (entry) => typeof entry.trailers === "boolean");
   return {
-    enabled: source?.trailers !== false,
-    workspace: selected.name,
-    from: source?.name ?? null,
+    enabled: found?.source?.trailers !== false,
+    workspace: found?.workspace ?? null,
+    from: found?.source?.name ?? null,
+  };
+};
+
+/**
+ * Whether the live-session guard runs for cwd's workspace (`liveSessionGuard`,
+ * default true; inherited like `trailers`). An unreadable workspaces.json
+ * keeps it on: the guard itself fails open on any state error.
+ */
+export const workspaceLiveSessionGuard = (cwd: string, dir?: string): boolean =>
+  inheritedSetting(cwd, dir, (entry) => typeof entry.liveSessionGuard === "boolean")?.source
+    ?.liveSessionGuard !== false;
+
+const hostFamily = (host: string): string => host.replace(/_(?:cli|desktop)$/u, "");
+
+const TIER_KEYS = new Set(["mundane", "standard", "hard"]);
+const TIER_HOSTS = new Set([
+  "claude_code",
+  "opencode",
+  "codex",
+  "codex_cli",
+  "codex_desktop",
+  "cursor",
+  "pi",
+  "default",
+]);
+
+/**
+ * What `fanout.tierModels` in cwd's workspaces holds that Workit ignores: an
+ * unknown tier or host key, or a value that is not a model name. Read
+ * leniently (each one is skipped, never an error); `workit grant show`
+ * reports them.
+ */
+export const workspaceTierModelIssues = (cwd: string, dir?: string): string[] => {
+  let matched: ReturnType<typeof matchRuntimeWorkspace>;
+  try {
+    matched = matchRuntimeWorkspace(cwd, dir);
+  } catch {
+    return [];
+  }
+  const issues: string[] = [];
+  for (const entry of matched?.matches ?? []) {
+    const models = (entry.fanout as { tierModels?: unknown } | undefined)?.tierModels;
+    if (models === undefined) continue;
+    const where = `workspace ${entry.name} fanout.tierModels`;
+    if (!models || typeof models !== "object" || Array.isArray(models)) {
+      issues.push(`${where} is not an object; ignored`);
+      continue;
+    }
+    for (const [tier, value] of Object.entries(models)) {
+      if (!TIER_KEYS.has(tier)) issues.push(`${where}.${tier}: unknown tier; ignored`);
+      else if (typeof value === "string") {
+        if (!value.trim()) issues.push(`${where}.${tier}: empty model name; ignored`);
+      } else if (!value || typeof value !== "object" || Array.isArray(value))
+        issues.push(`${where}.${tier}: not a model name or a per-host object; ignored`);
+      else
+        for (const [host, model] of Object.entries(value)) {
+          if (!TIER_HOSTS.has(host)) issues.push(`${where}.${tier}.${host}: unknown host; ignored`);
+          else if (typeof model !== "string" || !model.trim())
+            issues.push(`${where}.${tier}.${host}: not a model name; ignored`);
+        }
+    }
+  }
+  return issues;
+};
+
+/**
+ * The model `fanout.tierModels` names for a tier on a host, or null (the
+ * fanout skill's TIER guidance applies). A tier maps to one model name for
+ * every host, or to `{ <host>: <model> }` keyed by host family (claude_code,
+ * opencode, codex, cursor, pi) with an optional `default`. Inherited like
+ * `trailers`, per tier; anything malformed reads as unset.
+ */
+export const workspaceTierModel = (
+  cwd: string,
+  tier: string,
+  host: string | null,
+  dir?: string,
+): { model: string; workspace: string } | null => {
+  const pick = (entry: RuntimeEntry): string | null => {
+    const fanout = entry.fanout as { tierModels?: unknown } | undefined;
+    const models = fanout?.tierModels;
+    if (!models || typeof models !== "object" || !Object.hasOwn(models, tier)) return null;
+    const value = (models as Record<string, unknown>)[tier];
+    if (typeof value === "string") return value.trim() || null;
+    if (!value || typeof value !== "object") return null;
+    const byHost = value as Record<string, unknown>;
+    const family = host ? hostFamily(host) : null;
+    const named =
+      (family && Object.hasOwn(byHost, family) ? byHost[family] : undefined) ??
+      (host && Object.hasOwn(byHost, host) ? byHost[host] : undefined) ??
+      (Object.hasOwn(byHost, "default") ? byHost.default : undefined);
+    return typeof named === "string" && named.trim() ? named.trim() : null;
   };
+  const found = inheritedSetting(cwd, dir, (entry) => pick(entry) !== null);
+  const model = found?.source ? pick(found.source) : null;
+  return model && found?.source ? { model, workspace: found.source.name } : null;
 };
 
 const resolveRuntimeWorkspaceCandidate = (