@brainervirus/workit-core 8.13.1 → 8.14.1

package/package.json

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

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 |
 | --- | --- | --- |

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/task-contract.ts

@@ -33,6 +33,9 @@ const text = z.string().check((ctx) => {
     ctx.issues.push({ code: "custom", input: ctx.value, message: "invalid Unicode", path: [] });
 });
 const id = text.regex(uuidPattern, "expected lowercase UUID");
+/** A full id or an unambiguous lowercase prefix of one (the 8-char short id other surfaces print). */
+export const idRefPattern = /^[0-9a-f][0-9a-f-]{7,35}$/;
+const idRef = text.regex(idRefPattern, "expected a UUID or an id prefix of 8+ characters");
 const digest = text.regex(digestPattern, "expected lowercase SHA-256 digest");
 const revision = text.regex(uuidPattern, "expected UUID revision");
 const validUtc = (value: string): boolean => {
@@ -598,7 +601,7 @@ export const workerReportSchema = z
     outcome: z.enum(["completed", "failed", "cancelled"]),
     summary: text,
     evidenceIds: z.array(id),
-    findingIds: z.array(id),
+    findingIds: z.array(idRef),
   })
   .strict();
 export type WorkerReport = z.infer<typeof workerReportSchema>;
@@ -938,7 +941,7 @@ const findingOperations = {
     action: z.literal("resolve"),
     ...taskId,
     expectedRevision: revision.optional(),
-    findingId: id,
+    findingId: idRef,
     disposition: z.enum(["open", "fixed", "dismissed", "deferred"]),
     reason: text,
     evidenceIds: z.array(id),
@@ -980,7 +983,7 @@ const workerOperations = {
     ...taskId,
     expectedRevision: revision.optional(),
     expectedWorkspaceRevision: revision.optional(),
-    workerId: id,
+    workerId: idRef,
     report: workerReportSchema,
   }),
   cancel: operation({
@@ -988,7 +991,7 @@ const workerOperations = {
     ...taskId,
     ...revisions,
     expectedWorkspaceRevision: revision.optional(),
-    workerId: id,
+    workerId: idRef,
     reason: text,
   }),
 };
@@ -1118,6 +1121,21 @@ export const failure = (
   details: ErrorDetails = {},
 ): Result<never> => ({ ok: false, schemaVersion: 1, code, error, details });
 
+/**
+ * Resolve a full id or an unambiguous prefix against the ids a task holds.
+ * An exact match always wins; several prefix matches fail listing the candidates.
+ */
+export function resolveIdRef(kind: string, ref: string, ids: readonly string[]): Result<string> {
+  if (ids.includes(ref)) return success(null, null, ref);
+  const matches = ids.filter((candidate) => candidate.startsWith(ref));
+  if (matches.length === 1) return success(null, null, matches[0]);
+  if (matches.length === 0) return failure("not_found", `${kind} not found`);
+  return failure(
+    "invalid_input",
+    `${kind} prefix ${ref} is ambiguous; candidates: ${matches.join(", ")}`,
+  );
+}
+
 export function parseOperation(family: OperationFamily, input: unknown): Result<OperationRequest> {
   if (
     typeof input === "object" &&

package/src/core/task-engine.ts

@@ -15,6 +15,7 @@ import {
   legacyAssessmentSchema,
   newId,
   parseOperation,
+  resolveIdRef,
   rewriteRecordRefs,
   success,
   type Candidate,
@@ -391,6 +392,8 @@ const TASK_SCOPED_ACTIONS: ReadonlySet<string> = new Set([
   "state.export",
 ]);
 /** Worker actions that name their worker: they resolve to that worker's task. */
+const ONLY_OWN_REPORT = "workers can submit only their own report";
+const NO_HELPER_CONTROL = "helpers cannot cancel or control workers";
 const WORKER_ADDRESSED_ACTIONS: ReadonlySet<string> = new Set(["worker.cancel", "worker.report"]);
 /**
  * The exact CLI command that runs worker `request` (cancel or report, with a
@@ -1524,6 +1527,13 @@ export class WorkitCore {
       return success(changed.data.revision, null, changed.data.findings.at(-1)!);
     }
     if (helper?.ok) return failure("permission_denied", "helpers cannot resolve findings");
+    const findingRef = resolveIdRef(
+      "finding",
+      input.findingId,
+      task.data.findings.map((entry) => entry.id),
+    );
+    if (!findingRef.ok) return findingRef;
+    input.findingId = findingRef.data;
     const finding = task.data.findings.find((entry) => entry.id === input.findingId);
     if (!finding) return failure("not_found", "finding not found");
     if (!input.reason.trim())
@@ -1738,13 +1748,39 @@ export class WorkitCore {
       );
     }
 
+    // A helper may only address itself: resolving against its own id alone keeps
+    // another worker's id out of any ambiguity error.
+    const workerRef = resolveIdRef(
+      "worker",
+      input.workerId,
+      helperId === null ? task.data.workers.map((candidate) => candidate.id) : [helperId],
+    );
+    if (!workerRef.ok)
+      return helperId === null
+        ? workerRef
+        : failure(
+            "permission_denied",
+            input.action === "report" ? ONLY_OWN_REPORT : NO_HELPER_CONTROL,
+          );
+    input.workerId = workerRef.data;
     const entry = task.data.workers.find((candidate) => candidate.id === input.workerId);
     if (!entry) return failure("not_found", "worker not found");
     if (input.action === "report") {
       if (helperId === null || helperId !== input.workerId)
-        return failure("permission_denied", "workers can submit only their own report");
+        return failure("permission_denied", ONLY_OWN_REPORT);
       const helper = this.helperEntry(task.data, true, true);
       if (!helper.ok) return helper;
+      const ownFindings = task.data.findings
+        .filter((candidate) => candidate.provenance.workerId === helperId)
+        .map((candidate) => candidate.id);
+      const reported: string[] = [];
+      for (const findingRef of input.report.findingIds) {
+        const found = resolveIdRef("finding", findingRef, ownFindings);
+        if (found.ok) reported.push(found.data);
+        else if (found.code === "not_found") reported.push(findingRef);
+        else return found;
+      }
+      input.report.findingIds = reported;
       const evidence = task.data.evidence.filter((candidate) =>
         input.report.evidenceIds.includes(candidate.id),
       );
@@ -1800,8 +1836,7 @@ export class WorkitCore {
         : failure("recovery_required", "worker disappeared during report");
     }
 
-    if (helperId !== null)
-      return failure("permission_denied", "helpers cannot cancel or control workers");
+    if (helperId !== null) return failure("permission_denied", NO_HELPER_CONTROL);
     if (task.data.status === "closed")
       return failure("invalid_transition", "closed task cannot cancel workers");
     if (entry.data.state === "stopped") {

package/src/core/task-store.ts

@@ -47,6 +47,8 @@ import {
   success,
   taskRecordSchema,
   workspaceRecordSchema,
+  idRefPattern,
+  resolveIdRef,
   type Id,
   type Intent,
   type Provenance,
@@ -728,20 +730,23 @@ export class TaskStore {
    * the branch checked out now (#264). Null when no open task has it.
    */
   taskForWorker(workerId: unknown): Result<Id | null> {
-    if (typeof workerId !== "string" || !validId(workerId))
+    if (typeof workerId !== "string" || !idRefPattern.test(workerId))
       return failure(
         "invalid_input",
         "needs a worker id: `workit worker cancel|report <workerId>`",
       );
     const listed = this.listTaskIndex();
     if (!listed.ok) return listed;
+    const owners = new Map<string, Id>();
     for (const entry of listed.data) {
       if (entry.status === "closed") continue;
       const loaded = this.load(entry.id);
       if (!loaded.ok) return loaded;
-      if (loaded.data?.record.workers.some((worker) => worker.id === workerId))
-        return success(null, null, entry.id);
+      for (const worker of loaded.data?.record.workers ?? []) owners.set(worker.id, entry.id);
     }
+    const resolved = resolveIdRef("worker", workerId, [...owners.keys()]);
+    if (resolved.ok) return success(null, null, owners.get(resolved.data) ?? null);
+    if (resolved.code !== "not_found") return resolved;
     return success(null, null, null);
   }
 

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 = (

package/src/fanout-brief.ts

@@ -17,6 +17,7 @@
 // the integration tip before reporting, and nothing else. It only reads, apart
 // from hiding `.workit-scratch/` in the repository's info/exclude.
 import { createHash } from "node:crypto";
+import { workspaceTierModel } from "./core/workspaces";
 import { activeStanding, readLedger, type LedgerActor } from "./ledger";
 import { branchRef, fanoutFail, planLeads, type FanoutFile, type FanoutResult } from "./fanout";
 import {
@@ -38,6 +39,8 @@ export type BriefOutcome = {
   branch: string;
   base: string;
   tier: string;
+  /** The model `fanout.tierModels` names for the tier on the lead's host, else null. */
+  model: string | null;
   /** Absolute when the slice's worktree exists, else relative to the worker's worktree root. */
   scratch: string;
   /** The id a worker exports, or null when its host issues or derives it. */
@@ -171,6 +174,7 @@ export function renderBrief(
     what: String(row.what),
   }));
   const identity = identityOf(input.actor.host);
+  const model = workspaceTierModel(cwd, slice.tier, input.actor.host);
   const minted = workerSession(sessionSafe(input.actor.session), slice.id, input.attempt);
   const session = identity === "declared" ? minted : null;
   const fanIn =
@@ -200,6 +204,9 @@ export function renderBrief(
     ...slice.acceptance.map((line) => `  - ${line}`),
     `VERIFY: ${slice.verify.join("; ")}`,
     `TIER: ${slice.tier}`,
+    ...(model
+      ? [`  model: ${model.model}  (fanout.tierModels in workspace ${model.workspace})`]
+      : []),
     `TIMEBOX: ${slice.timebox ?? DEFAULT_TIMEBOX}; past it without a new commit you will be replaced`,
     scratchLine,
     `FORBIDDEN: ${slice.forbidden.join("; ")}`,
@@ -222,6 +229,7 @@ export function renderBrief(
       branch,
       base: slice.base,
       tier: slice.tier,
+      model: model?.model ?? null,
       scratch,
       session,
       standing,

package/src/fanout-status.ts

@@ -18,7 +18,8 @@
 import { parseDuration } from "./duration";
 import { checksState, gatingChecks, missingRequired, type ChecksState } from "./forge/report";
 import type { ResolvedForge } from "./forge/resolve";
-import { checkVerdicts, readLedger, type ReadRow, type VerdictBasis } from "./ledger";
+import { workspaceTierModel } from "./core/workspaces";
+import { actorFromEnv, checkVerdicts, readLedger, type ReadRow, type VerdictBasis } from "./ledger";
 import { sliceLandings } from "./fanout-check";
 import { forgeBreaker, inSliceRun } from "./fanout-landed";
 import {
@@ -74,6 +75,8 @@ export type StatusOutcome = {
   landingOrder: string[];
   /** Not started; every dependency landed (or, stacked, its parent has an accepted verdict). */
   spawnable: string[];
+  /** The model `fanout.tierModels` names for each spawnable slice's TIER on this host. */
+  spawnModels: Record<string, string>;
   stuck: string[];
   next: string;
   notes: string[];
@@ -85,6 +88,8 @@ export type StatusOptions = {
   forgeError?: string | null;
   stuckAfterMs?: number | null;
   now?: Date;
+  /** The lead's host, for `fanout.tierModels`; default: the environment's (WORKIT_HOST…). */
+  host?: string | null;
 };
 
 /** A TIMEBOX such as `45 minutes`, `2h` or `1h30m`, in ms; null without a unit or otherwise. */
@@ -279,6 +284,16 @@ export function fanoutStatus(
     if (row.waitsFor.length && !suggested.includes(id))
       row.reasons.push(`waits for ${row.waitsFor.join(", ")}`);
   }
+  const host = options.host === undefined ? actorFromEnv(process.env).host : options.host;
+  const spawnModels: Record<string, string> = {};
+  for (const id of spawnable) {
+    const tier = plan.slices.find((slice) => slice.id === id)?.tier;
+    const model = tier ? workspaceTierModel(cwd, tier, host) : null;
+    if (model) spawnModels[id] = model.model;
+  }
+  const spawnList = spawnable
+    .map((id) => (spawnModels[id] ? `${id} (model ${spawnModels[id]})` : id))
+    .join(", ");
   const stuck = order.filter((id) => out.get(id)?.stuck);
   const down = breaker.down();
   if (down)
@@ -300,7 +315,7 @@ export function fanoutStatus(
       : noPr.length
         ? `open PRs for ${noPr.join(", ")}: workit git push && workit pr create --fill on each branch`
         : spawnable.length
-          ? `spawn ${spawnable.join(", ")} (workit fanout worktree create <slice> on hosts without native worktrees)`
+          ? `spawn ${spawnList} (workit fanout worktree create <slice> on hosts without native worktrees)`
           : order.every((id) => out.get(id)?.landed)
             ? "every slice has landed"
             : "wait for workers, then workit fanout status again";
@@ -317,6 +332,7 @@ export function fanoutStatus(
       slices: order.map((id) => out.get(id) as SliceStatusRow),
       landingOrder: suggested,
       spawnable,
+      spawnModels,
       stuck,
       next,
       notes,

package/src/hooks/handle.ts

@@ -26,7 +26,8 @@ import {
   withContextLine,
 } from "./skill-nudge";
 import { stopDecision } from "./stop";
-import { shellWrites, writeGate } from "./write-gate";
+import { liveOwner } from "../core/live-session";
+import { shellGate, writeGate } from "./write-gate";
 import type { HookDecision, HookEventKind, HookInput, HostAdapter, RenderedHook } from "./protocol";
 
 export type HookDeps = { descriptor: HostDescriptor; addendum: string | null };
@@ -156,10 +157,10 @@ export function handleHook(input: HookInput, deps: HookDeps): HookDecision {
       if (!postTool) settlePendingCommit(input);
       const raw = canDeny ? rawGitPre(input, event.command, { nudge: false }) : NONE;
       if (raw.kind === "deny") return raw;
-      const writes = usable(descriptor.events["write.pre"].support)
-        ? shellWrites(event.command)
-        : { writes: false, targets: null };
-      const gate = writes.writes ? writeGate(input.cwd, writes.targets) : NONE;
+      // The before-write gate and the live-session guard (#274).
+      const gate = usable(descriptor.events["write.pre"].support)
+        ? shellGate(input.cwd, event.command, liveOwner(input, descriptor.transport), event.dialect)
+        : NONE;
       if (gate.kind === "deny") return gate;
       // The command will run: note HEAD so the post-tool hook (or the next
       // command, without one) can tell whether a raw commit moved it.
@@ -182,7 +183,7 @@ export function handleHook(input: HookInput, deps: HookDeps): HookDecision {
       return NONE;
     case "write.pre":
       return usable(descriptor.events["write.pre"].support)
-        ? writeGate(input.cwd, event.paths)
+        ? writeGate(input.cwd, event.paths, liveOwner(input, descriptor.transport))
         : NONE;
     case "subagent.start":
       return {

package/src/hooks/index.ts

@@ -19,7 +19,8 @@ export {
   type SessionHandle,
 } from "./context";
 export { shellPolicy } from "./policy";
-export { shellWrites, writeGate } from "./write-gate";
+export { shellGate, shellWrites, writeGate } from "./write-gate";
+export { liveOwner } from "../core/live-session";
 export { asksUser, stopDecision, stopObligation, type StopObligation } from "./stop";
 export { callKey, noteRawCommit, rawGitPost, rawGitPre } from "./raw-git";
 export { promptNudge, recordSkillLoad, shellNudge, skillFileIn } from "./skill-nudge";

package/src/hooks/write-gate.ts

@@ -5,13 +5,28 @@
 // Reads only the task index, one task snapshot and the ledger; never
 // migrates, never captures a candidate, and fails open on any state error.
 import { realpathSync } from "node:fs";
+import os from "node:os";
 import path from "node:path";
 import { fileSignature, TaskStore } from "../core/task-store";
 import { latestJudgment, writeBlockers, type WriteBlocker } from "../core/policy/derive";
 import { applicableDecision } from "../core/task-evaluation";
-import { ledgerPath } from "../ledger";
+import {
+  claimLiveSession,
+  liveConflict,
+  type LiveConflict,
+  type LiveDeps,
+  type LiveOwner,
+} from "../core/live-session";
+import { workspaceLiveSessionGuard } from "../core/workspaces";
+import { appendHookObserved, ledgerPath } from "../ledger";
 import type { HookDecision } from "./protocol";
-import { segmentsOf } from "./shell-words";
+import {
+  inWorkitWorkspace,
+  rawInvocations,
+  workitInvocations,
+  type RawInvocation,
+} from "./raw-git";
+import { segmentsOf, type ShellDialect } from "./shell-words";
 
 const NONE: HookDecision = { kind: "none" };
 
@@ -204,13 +219,298 @@ const gateFor = (cwd: string): Gate | null => {
   return gate;
 };
 
+// --- the live-session guard (#274) ------------------------------------------
+
+/** git subcommands that change a checkout's files, index or HEAD. */
+const MUTATING_GIT = new Set([
+  "add",
+  "am",
+  "apply",
+  "checkout",
+  "cherry-pick",
+  "clean",
+  "commit",
+  "merge",
+  "mv",
+  "pull",
+  "rebase",
+  "reset",
+  "restore",
+  "revert",
+  "rm",
+  "stash",
+  "switch",
+]);
+/** Subcommands whose `-n` means `--dry-run` (for `commit`, `-n` skips hooks). */
+const DRY_N = new Set(["add", "clean", "rm", "mv"]);
+/** `workit git` verbs that commit or move HEAD in the checkout. */
+const MUTATING_WORKIT_GIT = new Set(["commit", "branch"]);
+
+/** A placeholder file name that stands for its directory (an unknown write, a git command). */
+const DIR_TARGET = ".workit-live-target";
+
+/** A one-command override: `WORKIT_LIVE_SESSION=override <command>`. */
+const OVERRIDE = "WORKIT_LIVE_SESSION=override";
+
+/** Only asks for help or a dry run: changes nothing. */
+const inert = (args: readonly string[], sub: string): boolean =>
+  args.some(
+    (arg) =>
+      arg === "--help" ||
+      arg === "-h" ||
+      arg === "--dry-run" ||
+      (DRY_N.has(sub) && /^-[a-zA-Z]*n[a-zA-Z]*$/.test(arg) && !arg.startsWith("--")),
+  );
+
+/**
+ * The directories mutating git commands in `command` run in (raw-git's
+ * analysis: `cd`/`pushd`, groups, `-C`, env and wrapper prefixes, `bash -c`,
+ * `$(…)`, `eval`, `xargs`, `find -exec`, PowerShell, `cmd /c`). A command
+ * whose directory cannot be known is skipped, never denied.
+ */
+const gitMutationDirs = (cwd: string, command: string, dialect: ShellDialect): string[] => {
+  let invocations: readonly RawInvocation[];
+  try {
+    invocations = rawInvocations(command, dialect);
+  } catch {
+    return [];
+  }
+  return invocations.flatMap((invocation) => {
+    if (invocation.tool !== "git" || invocation.dir === undefined) return [];
+    const at = invocation.args.findIndex((arg) => !arg.startsWith("-"));
+    const sub = invocation.args[at] ?? "";
+    const rest = invocation.args.slice(at + 1);
+    if (!MUTATING_GIT.has(sub) || inert(rest, sub)) return [];
+    // `git stash list|show` only reads.
+    if (sub === "stash" && ["list", "show"].includes(rest[0] ?? "")) return [];
+    return [path.resolve(cwd, invocation.dir ?? ".")];
+  });
+};
+
+const CD = new Set(["cd", "chdir", "set-location", "sl"]);
+const PUSHD = new Set(["pushd", "push-location"]);
+const POPD = new Set(["popd", "pop-location"]);
+
+/** A `cd` operand resolved against `dir`; undefined when it cannot be known. */
+const cdInto = (dir: string | undefined, words: string[]): string | undefined => {
+  const target = words.slice(1).find((word) => !word.startsWith("-") || word === "-");
+  // Only a leading `~` expands; a mid-path `~` is literal (Windows 8.3
+  // short names like RUNNER~1).
+  if (dir === undefined || target === "-" || (target && /^~|[$`*?]/.test(target))) return undefined;
+  return target === undefined ? os.homedir() : path.resolve(dir, target);
+};
+
+const quoteWord = (word: string): string =>
+  /^[\w@%+=:,./-]+$/.test(word) ? word : `'${word.replaceAll("'", "'\\''")}'`;
+
+/**
+ * Per top-level segment, the files it writes (redirects, `touch`, `rm`,
+ * `sed -i`…) and `workit git commit|branch`, resolved against the
+ * directory that segment runs in (`cd`, `pushd`/`popd`, `( … )` groups). A
+ * relative target in an unknown directory is skipped.
+ */
+const segmentTargets = (cwd: string, command: string, dialect: ShellDialect): string[] => {
+  const targets: string[] = [];
+  let dir: string | undefined = cwd;
+  let stack: Array<string | undefined> = [];
+  const groups: Array<{ dir: string | undefined; stack: Array<string | undefined> }> = [];
+  const at = (file: string) =>
+    path.isAbsolute(file) ? file : dir === undefined ? null : path.resolve(dir, file);
+  for (const segment of segmentsOf(command, dialect)) {
+    if (segment.group === "open") {
+      groups.push({ dir, stack: [...stack] });
+      continue;
+    }
+    if (segment.group === "close") {
+      const saved = groups.pop();
+      if (saved) ({ dir, stack } = saved);
+      continue;
+    }
+    const lead = segment.words.findIndex((word) => !/^\w+=/.test(word));
+    const words = lead < 0 ? [] : segment.words.slice(lead);
+    const name = (words[0]?.split(/[\\/]/).at(-1) ?? "").toLowerCase();
+    if (CD.has(name)) {
+      dir = cdInto(dir, words);
+      continue;
+    }
+    if (PUSHD.has(name)) {
+      stack.push(dir);
+      dir = cdInto(dir, words);
+      continue;
+    }
+    if (POPD.has(name)) {
+      dir = stack.length ? stack.pop() : undefined;
+      continue;
+    }
+    for (const file of segment.redirects)
+      if (!/^\/dev\/(?:null|stdout|stderr|tty)$/.test(file)) {
+        const resolved = at(file);
+        if (resolved) targets.push(resolved);
+      }
+    const edits = editsOf(segment.words);
+    if (edits === null) {
+      if (dir !== undefined) targets.push(path.join(dir, DIR_TARGET));
+    } else
+      for (const file of edits) {
+        const resolved = at(file);
+        if (resolved) targets.push(resolved);
+      }
+    if (
+      dir !== undefined &&
+      workitInvocations(segment.words.map(quoteWord).join(" "), "posix").some(
+        (args) =>
+          args[0] === "git" && MUTATING_WORKIT_GIT.has(args[1] ?? "") && !inert(args.slice(2), ""),
+      )
+    )
+      targets.push(path.join(dir, DIR_TARGET));
+  }
+  return targets;
+};
+
+/** The command is one simple command led by `WORKIT_LIVE_SESSION=override`. */
+const overridden = (command: string, dialect: ShellDialect): boolean => {
+  const segments = segmentsOf(command, dialect);
+  if (segments.length !== 1 || segments[0].group || segments[0].subs?.length) return false;
+  const words = segments[0].words;
+  const lead = words.findIndex((word) => !/^\w+=/.test(word));
+  return lead > 0 && words.slice(0, lead).includes(OVERRIDE);
+};
+
+const HOST_LABELS: Readonly<Record<string, string>> = {
+  claude_code: "Claude Code",
+  opencode: "OpenCode",
+  codex_cli: "Codex CLI",
+  codex_desktop: "Codex Desktop",
+  cursor: "Cursor",
+  pi: "Pi",
+};
+
+const ageText = (ms: number): string => {
+  const seconds = Math.max(0, Math.round(ms / 1000));
+  return seconds < 120 ? `${seconds}s` : `${Math.round(seconds / 60)} min`;
+};
+
+const liveDeny = ({ marker, checkout, ageMs, file }: LiveConflict): HookDecision => {
+  const unblock = `Work in your own worktree (\`git worktree add <path> -b <branch>\`, or \`workit fanout worktree create <slice>\`). Only if the user confirms that session is finished: release it with \`rm '${file}'\`, or prefix one command with ${OVERRIDE}.`;
+  return {
+    kind: "deny",
+    reason: `workit live-session guard: ${checkout} belongs to another live agent session, ${HOST_LABELS[marker.host] ?? marker.host} session ${marker.session}${marker.pid === null ? "" : ` (pid ${marker.pid})`}, last active ${ageText(ageMs)} ago. Do not edit a checkout another session is working in; read-only commands stay allowed. ${unblock}`,
+    unblock,
+  };
+};
+
+/** One target per directory. */
+const guarded = (targets: readonly string[]): string[] => {
+  const seen = new Set<string>();
+  return targets.filter((target) => {
+    const dir = path.dirname(target);
+    if (seen.has(dir)) return false;
+    seen.add(dir);
+    return true;
+  });
+};
+
+/**
+ * Deny when a target's checkout belongs to another live session and its
+ * workspace keeps `liveSessionGuard` on. Fails open.
+ */
+const liveGate = (owner: LiveOwner, targets: readonly string[], deps?: LiveDeps): HookDecision => {
+  try {
+    for (const target of guarded(targets)) {
+      const conflict = liveConflict(target, owner, deps);
+      if (conflict && workspaceLiveSessionGuard(conflict.checkout)) return liveDeny(conflict);
+    }
+  } catch {
+    // Fail open.
+  }
+  return NONE;
+};
+
+const claimAll = (owner: LiveOwner, targets: readonly string[], deps?: LiveDeps): void => {
+  for (const target of guarded(targets)) claimLiveSession(target, owner, deps);
+};
+
+/** The absolute paths an edit touches: its files, or cwd itself when unknown. */
+const liveTargets = (cwd: string, paths: readonly string[] | null): string[] =>
+  paths?.length ? paths.map((file) => path.resolve(cwd, file)) : [path.join(cwd, DIR_TARGET)];
+
 /**
  * Deny a working-tree edit while the branch task has unmet before-write
  * requirements. `paths` are the files the tool writes, or null when unknown
  * (a shell write, a patch whose headers cannot be read); unknown or empty
  * targets are gated, and an edit touching only exempt files is always allowed.
+ * With `owner` (the hook's session), the live-session guard runs first, and
+ * an allowed edit refreshes the owner's marker in each checkout it touches.
+ */
+export function writeGate(
+  cwd: string,
+  paths: readonly string[] | null,
+  owner?: LiveOwner | null,
+  deps?: LiveDeps,
+): HookDecision {
+  if (!owner) return beforeWriteGate(cwd, paths);
+  const targets = liveTargets(cwd, paths);
+  const live = liveGate(owner, targets, deps);
+  if (live.kind !== "none") return live;
+  const decision = beforeWriteGate(cwd, paths);
+  if (decision.kind === "none") claimAll(owner, targets, deps);
+  return decision;
+}
+
+/**
+ * The write gates on one shell command: the live-session guard on its writes
+ * and mutating git commands in the directories they run in, then the
+ * before-write gate on its writes. A command that is only
+ * `WORKIT_LIVE_SESSION=override <command>` skips the guard and leaves a
+ * ledger row. An allowed mutation refreshes the owner's marker.
  */
-export function writeGate(cwd: string, paths: readonly string[] | null): HookDecision {
+export function shellGate(
+  cwd: string,
+  command: string,
+  owner: LiveOwner | null,
+  dialect: ShellDialect = "posix",
+  deps?: LiveDeps,
+): HookDecision {
+  const writes = shellWrites(command);
+  let targets: string[] = [];
+  if (owner) {
+    try {
+      targets = [
+        ...segmentTargets(cwd, command, dialect),
+        ...gitMutationDirs(cwd, command, dialect).map((dir) => path.join(dir, DIR_TARGET)),
+      ];
+    } catch {
+      targets = [];
+    }
+  }
+  if (owner && targets.length) {
+    const live = liveGate(owner, targets, deps);
+    if (live.kind !== "none") {
+      if (!overridden(command, dialect)) return live;
+      noteOverride(cwd, owner, command);
+    }
+  }
+  const decision = writes.writes ? beforeWriteGate(cwd, writes.targets) : NONE;
+  if (owner && targets.length && decision.kind === "none") claimAll(owner, targets, deps);
+  return decision;
+}
+
+/** A ledger row for an override that let a command past the guard (managed repositories only). */
+const noteOverride = (cwd: string, owner: LiveOwner, command: string): void => {
+  try {
+    if (!inWorkitWorkspace(cwd)) return;
+    appendHookObserved(cwd, {
+      type: "live_session.override",
+      actor: { host: owner.host, session: owner.session, agentId: null },
+      session: owner.session,
+      command: command.slice(0, 200),
+    });
+  } catch {
+    // A note never blocks the command.
+  }
+};
+
+function beforeWriteGate(cwd: string, paths: readonly string[] | null): HookDecision {
   try {
     const gate = gateFor(cwd);
     if (!gate || gate.blockers.length === 0) return NONE;