simt-dev 0.7.0 → 0.8.0

package/src/commands/init-scan.mjs

@@ -0,0 +1,90 @@
+// The read-only half of `init`: the conflict scan and the pre-write escape hatch.
+//
+// Split out of init.mjs when it reached the repository ceiling. Neither function writes
+// the manifest; both answer a question the command asks before it does.
+
+import { mkdir, readFile, symlink } from 'node:fs/promises';
+import { git as sysGit } from '../sys/git.mjs';
+import { rulePaths, scanDocument, summarise } from '../projection/conflicts.mjs';
+import { parse as parseRegion } from '../projection/markers.mjs';
+
+const BACKUP_TAG = 'backup-before-simt-dev';
+const ADOPT_BRANCH = 'simt-dev/adopt';
+
+async function scanRepo(root) {
+  const findings = [];
+  for (const path of await rulePaths(root)) {
+    let text;
+    try {
+      text = await readFile(path, 'utf8');
+    } catch {
+      continue;
+    }
+    const region = parseRegion(text);
+    const handWritten = region.status === 'ok' ? `${region.before}\n${region.after}` : text;
+    findings.push(...scanDocument(handWritten, path));
+  }
+  return findings;
+}
+
+/**
+ * The opt-in escape hatch before the first write, taken when --backup is passed
+ * (ADR-063 amended plan 0002 §8.2 item 3 from "always" to on request). Both operations
+ * are best-effort: a repo that is not a git repo, or has no commits yet, must still be
+ * adoptable. Failure is reported as a note rather than blocking, because refusing
+ * to initialise an unborn repo would be worse than proceeding without a backup.
+ */
+async function establishEscapeHatch(root) {
+  const result = { branch: null, tag: null, from: null, notes: [] };
+  const isRepo = await git(root, ['rev-parse', '--is-inside-work-tree']);
+  if (!isRepo.ok) {
+    result.notes.push('not a git work tree; no backup branch or tag created');
+    return result;
+  }
+
+  const dirty = await git(root, ['status', '--porcelain']);
+  if (dirty.ok && dirty.stdout.trim() !== '') {
+    result.notes.push('worktree already dirty; left untouched, existing changes are not staged');
+  }
+
+  const head = await git(root, ['rev-parse', '--verify', 'HEAD']);
+  if (!head.ok) {
+    result.notes.push('no commits yet; nothing to tag');
+  } else {
+    const hasTag = await git(root, ['rev-parse', '--verify', `refs/tags/${BACKUP_TAG}`]);
+    if (hasTag.ok) {
+      result.tag = BACKUP_TAG;
+    } else {
+      const tag = await git(root, ['tag', BACKUP_TAG]);
+      if (tag.ok) result.tag = BACKUP_TAG;
+      else result.notes.push(`could not create tag ${BACKUP_TAG}: ${tag.stderr.trim()}`);
+    }
+  }
+
+  const current = await git(root, ['rev-parse', '--abbrev-ref', 'HEAD']);
+  if (current.ok && current.stdout.trim() !== ADOPT_BRANCH) {
+    // Recorded rather than re-read by the caller: only this function knows what the
+    // branch was before it moved it, and a second `rev-parse` would answer with the new
+    // value and make every "you were on X" line read as "you were on Y".
+    result.from = current.stdout.trim();
+    const branch = await git(root, ['checkout', '-b', ADOPT_BRANCH]);
+    if (branch.ok) result.branch = ADOPT_BRANCH;
+    else result.notes.push(`could not create branch ${ADOPT_BRANCH}: ${branch.stderr.trim()}`);
+  } else if (current.ok) {
+    result.branch = ADOPT_BRANCH;
+  }
+
+  return result;
+}
+
+async function git(cwd, args) {
+  try {
+    const stdout = await sysGit(cwd, args);
+    return { ok: true, stdout, stderr: '' };
+  } catch (error) {
+    return { ok: false, stdout: error.stdout ?? '', stderr: error.stderr ?? '' };
+  }
+}
+
+
+export { ADOPT_BRANCH, BACKUP_TAG, establishEscapeHatch, git, scanRepo };

package/src/commands/init.mjs

@@ -15,10 +15,9 @@
 //   6. write               only with --yes
 // Never commits, never pushes (ADR-001).
 
-import { execFile } from 'node:child_process';
-import { promisify } from 'node:util';
 import { mkdir, readFile, symlink } from 'node:fs/promises';
 import { commitJournal, ignoreJournal, journaledWriteFile } from '../journal.mjs';
+import { applyPlan, change } from '../write/plan.mjs';
 import { invalidateCheckCache } from '../status.mjs';
 import { dirname, join } from 'node:path';
 
@@ -47,6 +46,7 @@ import { pointerState, pointerTargets } from '../projection/project.mjs';
 import { surfacesLine } from '../projection/surfaces.mjs';
 import { plan, provenanceDigest, PRIMARY_TARGET, LOCAL_PROFILE_DIR } from '../projection/project.mjs';
 import { planAgents, writeAgentPlan, writeSkillFile } from '../agents/render.mjs';
+import { applyAgentHooks, planAgentHooks } from './agenthook.mjs';
 import { computeLock } from '../projection/lock.mjs';
 import { parse as parseRegion } from '../projection/markers.mjs';
 import { reindex, SQLITE_FILE } from '../index/store.mjs';
@@ -55,14 +55,13 @@ import { MANIFEST_FILE } from '../name.mjs';
 import { packageVersion, hasNpm } from '../package-version.mjs';
 import { resolveNodeRunner } from '../ecosystem/node-runner.mjs';
 import { PACKAGE_NAME } from '../name.mjs';
+import { commandRoot } from '../repo-root.mjs';
+import { git as sysGit } from '../sys/git.mjs';
+import { ADOPT_BRANCH, BACKUP_TAG, establishEscapeHatch, git, scanRepo } from './init-scan.mjs';
 
-const run = promisify(execFile);
-
-const BACKUP_TAG = 'backup-before-simt-dev';
-const ADOPT_BRANCH = 'simt-dev/adopt';
 
 export async function initCommand(positional, flags) {
-  const root = flags.root ?? positional[0] ?? process.cwd();
+  const root = commandRoot(flags, positional);
 
   const detected = await fingerprint(root);
   if (detected.error) {
@@ -170,10 +169,29 @@ export async function initCommand(positional, flags) {
   const ci = await planWorkflow(root);
   const dependabot = await planDependabot(root);
   const tsconfigBase = await planTsconfigBase(root);
+  // `--no-agents` opts out of the agent files and the agent-hooks in one flag: they are
+  // the two halves of the same decision — which harnesses this adoption speaks to — and
+  // splitting them into two flags would let a reader ask for the files without the hooks
+  // and end up with an agent the repository's own gate does not enforce. The parser's
+  // `no-` convention delivers it as the positive `agents` set to false.
+  const noAgents = flags.agents === false;
   // ADR-111. The one agent this tool ships, planned with the rest so the operator sees
   // it in the same preview that lists everything else. Written in the apply path with
-  // everything else, journaled the same way.
-  const agentPlan = await planAgents(root);
+  // everything else, journaled the same way. `--harness` narrows it to one reader, the
+  // same axis as the agent-hooks below, so the files and the hooks speak to the same set
+  // of harnesses (the rule surfaces are a separate axis: `--surfaces`).
+  const agentPlan = noAgents ? [] : await planAgents(root, { harness: flags.harness });
+  // The agent-hooks entry, absorbed into this run so the adoption enforces its own
+  // projection while the agent works. Planned with the rest for the same reason, and
+  // written into this run's journal (committed with the rest, not a second journal).
+  // `--harness` narrows it to the same reader the agent files are narrowed to.
+  let agentHooks = null;
+  if (!noAgents) {
+    agentHooks = await planAgentHooks(root, { harness: flags.harness });
+    if (agentHooks.error) {
+      return fail(agentHooks.error, EXIT.USAGE, agentHooks.remedy);
+    }
+  }
   // Per-developer, and planned with the rest so the operator sees it in the same
   // preview that lists everything else. `exists` short-circuits the write: a
   // repository that already has one keeps it exactly as it is.
@@ -255,6 +273,18 @@ export async function initCommand(positional, flags) {
     // plans strip their rendered bytes; the apply path writes from `agentPlan`, which
     // keeps it.
     agents: agentPlan.map(({ text, ...rest }) => rest),
+    // The agent-hooks entry the apply path will write, absorbed into this run so the
+    // adoption enforces its own projection while the agent works. `text` is stripped the
+    // same way; the apply path writes from `agentHooks`, which keeps it. `null` when
+    // `--no-agents` opted out of the hooks (and the agent files with them).
+    agentHooks: agentHooks
+      ? {
+          plan: agentHooks.plan.map(({ text, ...rest }) => rest),
+          shim: agentHooks.shim.row,
+          notWritten: agentHooks.others,
+          refused: agentHooks.refused.map(({ text, ...rest }) => rest),
+        }
+      : null,
     adoption,
     manifest: { file: MANIFEST, action: manifestAction, path: manifestFile },
     // Local state, not a repository file: gitignored, rebuildable from `git ls-files -s`,
@@ -349,6 +379,28 @@ export async function initCommand(positional, flags) {
     );
   }
 
+  // An unreadable hooks config is a refusal, not a failure to try harder: init inherits
+  // the standalone command's refusal and blocks the whole run, because writing the other
+  // hooks while one is unreadable would leave the adoption in a state where the report it
+  // just printed is no longer true. The remedy names the opt-out, because a repository
+  // that cannot be read by one harness can still be adopted without the agent layer.
+  if (agentHooks !== null && agentHooks.refused.length > 0) {
+    payload.ok = false;
+    payload.blockedBy = 'agent-hooks-refused';
+    if (isJson(flags)) {
+      emitJson(payload);
+    } else {
+      emit(render(payload, manifest, { npm, manager, version }));
+      note('');
+      note(`refused  ${agentHooks.refused.length} hooks config(s) could not be read; nothing written`);
+    }
+    return fail(
+      `${root} has a hooks config init cannot read: ${agentHooks.refused.map((p) => `${p.path} (${p.error})`).join('; ')}`,
+      EXIT.FAIL,
+      `fix or remove the named config file, then rerun: ${CLI} init --yes | or opt out of the agent layer: ${CLI} init --no-agents --yes`,
+    );
+  }
+
   // One malformed target refuses the whole adoption, not just that file. Writing the
   // others first would leave the repo half-adopted with the half that failed having
   // produced no change at all — indistinguishable, in the diff, from never running.
@@ -407,6 +459,7 @@ export async function initCommand(positional, flags) {
         after: renderDependabot(payload.dependabot.facts, {
           stack: payload.dependabot.stack,
           own: payload.dependabot.own,
+          root: payload.dependabot.root,
         }),
       });
     }
@@ -537,6 +590,7 @@ export async function initCommand(positional, flags) {
       renderDependabot(payload.dependabot.facts, {
         stack: payload.dependabot.stack,
         own: payload.dependabot.own,
+        root: payload.dependabot.root,
       }),
     );
     note(
@@ -547,26 +601,32 @@ export async function initCommand(positional, flags) {
   // scaffolds the manifest and one region but leaves the `.mdc` rules for a later
   // `sync` produces a repo whose `check` fails on files the user was never told
   // about — which reads as a broken adoption rather than an unfinished one.
+  //
+  // The malformed guard runs before anything is applied. A target this run cannot write
+  // has to stop the run, not leave the earlier targets written and the late one reported.
+  const badTarget = projected.targets.find((t) => t.action === 'malformed');
+  if (badTarget) {
+    // Checked before any write above; reaching here means the guard moved.
+    return fail(
+      `${badTarget.file}: ${badTarget.reason}`,
+      EXIT.FAIL,
+      `fix the markers at ${badTarget.file}:${badTarget.line}, then rerun: ${CLI} init --yes`,
+    );
+  }
+  // `before` is read, not inferred from `target.action`: the engine derives create from
+  // missing before-bytes, and a writer that passes its own action is the bug it removes.
+  const targetChanges = await Promise.all(
+    projected.targets
+      .filter((t) => t.action !== 'unchanged')
+      .map(async (t) =>
+        change({ path: t.path, before: await readBefore(t.path), after: t.text, owner: 'init', reason: t.action }),
+      ),
+  );
+  // The caller's journal, committed once below with the manifest and identity writes.
+  await applyPlan(root, targetChanges, { mode: { apply: true }, journal, commit: false });
   for (const target of projected.targets) {
-    if (target.action === 'unchanged') {
-      note(`current  ${target.file} (already up to date)`);
-      continue;
-    }
-    if (target.action === 'malformed') {
-      // Checked before any write above; reaching here means the guard moved.
-      return fail(
-        `${target.file}: ${target.reason}`,
-        EXIT.FAIL,
-        `fix the markers at ${target.file}:${target.line}, then rerun: ${CLI} init --yes`,
-      );
-    }
-    // A per-rule target lives in `.cursor/rules/`, `.claude/rules/`,
-    // `.agents/rules/` or `.github/instructions/` — four directories a repo that had
-    // no such configuration at all will not have. Creating them is part of adopting,
-    // not a detail of writing the file.
-    await mkdir(dirname(target.path), { recursive: true });
-    await journaledWriteFile(root, journal, target.path, target.text);
-    note(`wrote    ${target.file} (${target.action})`);
+    if (target.action === 'unchanged') note(`current  ${target.file} (already up to date)`);
+    else note(`wrote    ${target.file} (${target.action})`);
   }
 
   // Pointers, after the file they point at exists. A regular file already at one of
@@ -593,6 +653,20 @@ export async function initCommand(positional, flags) {
   // which keeps the rendered bytes the display payload strips.
   const agentWritten = await writeAgentPlan(root, journal, agentPlan);
   for (const f of agentWritten) note(`wrote    ${f} (agent)`);
+  // The agent-hooks entry, written into this run's journal and committed with the rest of
+  // the adoption. It is part of the adoption, not a second run: a second journal would
+  // make `undo` restore the hooks separately from the files they enforce, and the reader
+  // would not know the two moves belong together.
+  if (agentHooks !== null) {
+    const { written, shimWritten } = await applyAgentHooks(root, journal, {
+      plan: agentHooks.plan,
+      shim: agentHooks.shim,
+      owner: 'init',
+    });
+    for (const p of written) note(`wrote    ${p.path} (agent-hooks)`);
+    if (shimWritten) note(`wrote    ${agentHooks.shim.row.path} (agent-hooks shim)`);
+    if (written.length === 0 && !shimWritten) note('agent-hooks  every documented config already carried this tools entry');
+  }
   await commitJournal(root, 'init', journal);
   // The tree changed, so the last `check` no longer describes it: the line
   // goes back to "no cache" rather than reporting the tree as it was (R48).
@@ -644,81 +718,6 @@ export async function initCommand(positional, flags) {
 /** Scan whichever rule files exist, named or globbed. A missing file is not a
  *  finding. Generated regions are skipped: quoting a ruling is not a conflict with
  *  it, and the region is rewritten by `sync` anyway. */
-async function scanRepo(root) {
-  const findings = [];
-  for (const path of await rulePaths(root)) {
-    let text;
-    try {
-      text = await readFile(path, 'utf8');
-    } catch {
-      continue;
-    }
-    const region = parseRegion(text);
-    const handWritten = region.status === 'ok' ? `${region.before}\n${region.after}` : text;
-    findings.push(...scanDocument(handWritten, path));
-  }
-  return findings;
-}
-
-/**
- * The opt-in escape hatch before the first write, taken when --backup is passed
- * (ADR-063 amended plan 0002 §8.2 item 3 from "always" to on request). Both operations
- * are best-effort: a repo that is not a git repo, or has no commits yet, must still be
- * adoptable. Failure is reported as a note rather than blocking, because refusing
- * to initialise an unborn repo would be worse than proceeding without a backup.
- */
-async function establishEscapeHatch(root) {
-  const result = { branch: null, tag: null, from: null, notes: [] };
-  const isRepo = await git(root, ['rev-parse', '--is-inside-work-tree']);
-  if (!isRepo.ok) {
-    result.notes.push('not a git work tree; no backup branch or tag created');
-    return result;
-  }
-
-  const dirty = await git(root, ['status', '--porcelain']);
-  if (dirty.ok && dirty.stdout.trim() !== '') {
-    result.notes.push('worktree already dirty; left untouched, existing changes are not staged');
-  }
-
-  const head = await git(root, ['rev-parse', '--verify', 'HEAD']);
-  if (!head.ok) {
-    result.notes.push('no commits yet; nothing to tag');
-  } else {
-    const hasTag = await git(root, ['rev-parse', '--verify', `refs/tags/${BACKUP_TAG}`]);
-    if (hasTag.ok) {
-      result.tag = BACKUP_TAG;
-    } else {
-      const tag = await git(root, ['tag', BACKUP_TAG]);
-      if (tag.ok) result.tag = BACKUP_TAG;
-      else result.notes.push(`could not create tag ${BACKUP_TAG}: ${tag.stderr.trim()}`);
-    }
-  }
-
-  const current = await git(root, ['rev-parse', '--abbrev-ref', 'HEAD']);
-  if (current.ok && current.stdout.trim() !== ADOPT_BRANCH) {
-    // Recorded rather than re-read by the caller: only this function knows what the
-    // branch was before it moved it, and a second `rev-parse` would answer with the new
-    // value and make every "you were on X" line read as "you were on Y".
-    result.from = current.stdout.trim();
-    const branch = await git(root, ['checkout', '-b', ADOPT_BRANCH]);
-    if (branch.ok) result.branch = ADOPT_BRANCH;
-    else result.notes.push(`could not create branch ${ADOPT_BRANCH}: ${branch.stderr.trim()}`);
-  } else if (current.ok) {
-    result.branch = ADOPT_BRANCH;
-  }
-
-  return result;
-}
-
-async function git(cwd, args) {
-  try {
-    const { stdout, stderr } = await run('git', args, { cwd });
-    return { ok: true, stdout, stderr };
-  } catch (error) {
-    return { ok: false, stdout: error.stdout ?? '', stderr: error.stderr ?? '' };
-  }
-}
-
 /** Every line is a decision with a reason. Nothing is silent. */
 function render(payload, manifest, { npm = true, manager = null, version } = {}) {
   const lines = [
@@ -829,6 +828,26 @@ function render(payload, manifest, { npm = true, manager = null, version } = {})
     lines.push(`  ${a.action.padEnd(9)} ${a.path}  agent (ADR-111)`);
   }
 
+  // The agent-hooks entry, absorbed into the run so the adoption enforces its own
+  // projection while the agent works. Printed with the same shape the standalone command
+  // uses: one line per config the tool writes, the shim, and the readers it narrows past.
+  // `--no-agents` suppresses the section and says so, because a line that appears after
+  // the run without being in the plan is the same silent write as any other.
+  if (payload.agentHooks === null) {
+    lines.push(`  ${'skip'.padEnd(9)} agent-hooks  opted out with --no-agents; the agent files are skipped with it`);
+  } else {
+    for (const p of payload.agentHooks.plan) {
+      lines.push(`  ${p.action.padEnd(9)} ${p.path}  agent-hooks${p.error ? `  (${p.error})` : ''}`);
+    }
+    const shim = payload.agentHooks.shim;
+    lines.push(`  ${shim.action.padEnd(9)} ${shim.path}  agent-hooks shim`);
+    for (const o of payload.agentHooks.notWritten ?? []) {
+      if (o.state === 'skipped') {
+        lines.push(`  ${'skip'.padEnd(9)} ${o.id}  ${o.note}`);
+      }
+    }
+  }
+
   // The CI gate is listed as its own kind because it is the one plan entry whose
   // absence is a decision rather than a default. Skipped states its reason inline so
   // a reader can tell "this repo does not use GitHub Actions" from "this repo was
@@ -862,7 +881,7 @@ function render(payload, manifest, { npm = true, manager = null, version } = {})
   // produced by two hand-written renderers.
   const db = payload.dependabot;
   if (db && db.action === 'create') {
-    lines.push(`  ${'create'.padEnd(9)} ${db.file}  ${renderDependabot(db.facts, { stack: db.stack, own: db.own }).length} bytes`);
+    lines.push(`  ${'create'.padEnd(9)} ${db.file}  ${renderDependabot(db.facts, { stack: db.stack, own: db.own, root: db.root }).length} bytes`);
     lines.push(
       db.own
         ? `            watches ${db.ecosystems.join(', ')}; ${CLI} ci --yes refreshes this copy when the template changes`
@@ -911,4 +930,4 @@ function render(payload, manifest, { npm = true, manager = null, version } = {})
   }
   if (summary.total === 0) lines.push('', 'CONFLICTS none detected');
   return lines.filter((l) => l !== undefined).join('\n');
-}
+}

package/src/commands/lease.mjs

@@ -20,18 +20,22 @@ import {
   DEFAULT_TTL_SECONDS,
   activeLeases,
   canonicalLeasePath,
+  flattenLease,
+  leaseCovers,
   readLeases,
   withLeaseLock,
   writeLeases,
 } from '../lease.mjs';
 import { coreIgnoreCase } from '../repo-root.mjs';
+import { noteEvent } from '../state/events.mjs';
 import { SESSION_ENV } from '../agenthooks/policy.mjs';
 import { CLI } from '../name.mjs';
+import { commandRoot } from '../repo-root.mjs';
 
 const ISO = (ms) => new Date(ms).toISOString();
 
 export async function leaseCommand(args, flags) {
-  const root = flags.root ?? process.cwd();
+  const root = commandRoot(flags);
   const [sub, ...rest] = args;
   // The denial tells a blocked session to ask the holder to release the path,
   // so releasing is a subcommand, not a missing flag (review 0003 Q20).
@@ -59,6 +63,8 @@ export async function leaseCommand(args, flags) {
 
   const wanted = [];
   const seen = new Set();
+  // A trailing slash asks for the directory (Q74): one claim covering every path under it.
+  const kinds = new Map();
   // The claim is stored in the one spelling the hook's comparison will produce:
   // a claim taken as `src/Keep.mjs` and an edit that spells `src/keep.mjs` must
   // be the same claim on a case-insensitive volume, so the stored path is
@@ -72,19 +78,36 @@ export async function leaseCommand(args, flags) {
     if (!seen.has(rel)) {
       seen.add(rel);
       wanted.push(rel);
+      kinds.set(rel, String(arg).endsWith('/') ? 'dir' : 'path');
     }
   }
 
   // Older claim files hold the pre-canonical spelling, so a stored path is
   // canonicalised before it is compared: a claim written before the resolver
   // existed must still conflict with a claim taken for the same file.
-  const keyOf = (l) => canonicalLeasePath(root, l.path, { ignoreCase }) ?? l.path;
-  const newClaim = (expiresAt) =>
-    wanted.map((path) => ({ path, session, expiresAt, ...(harness === null ? {} : { harness }) }));
+  // A claim and a target overlap when either covers the other: claiming `src/` while
+  // `src/a.mjs` is held is the conflict the directory claim exists to catch (Q74).
+  const overlaps = (l) =>
+    wanted.some(
+      (rel) =>
+        leaseCovers(l, rel) ||
+        (kinds.get(rel) === 'dir' && (l.path === rel || l.path.startsWith(`${rel}/`))),
+    );
+  const newClaim = (expiresAt, held) =>
+    wanted.map((path) => {
+      const fences = held.filter((l) => leaseCovers(l, path)).map((l) => Number(l.fence) || 0);
+      return flattenLease({
+        resource: { kind: kinds.get(path) ?? 'path', id: path },
+        holder: { session, harness },
+        fence: 1 + (fences.length === 0 ? 0 : Math.max(...fences)),
+        acquiredAt: Date.now(),
+        expiresAt,
+      });
+    });
 
   const mode = writeMode(flags);
   if (!mode.apply) {
-    const mine = newClaim(Date.now() + ttl * 1000);
+    const mine = newClaim(Date.now() + ttl * 1000, []);
     const apply = `run: ${CLI} lease ${wanted.map((p) => JSON.stringify(p)).join(' ')} --session ${session} --yes`;
     if (isJson(flags)) {
       emitJson({ ok: true, command: 'lease', root, dryRun: true, session, ttl, leases: mine, remedy: apply });
@@ -97,7 +120,7 @@ export async function leaseCommand(args, flags) {
       ...mine.map((l) => `would    lease ${l.path} until ${ISO(l.expiresAt)}`),
       `apply    ${apply}`,
     ];
-    emit(lines.join('\n'), { maxBytes: flags.maxBytes ?? 0 });
+    emit(lines.join('\n'));
     return EXIT.OK;
   }
 
@@ -108,12 +131,12 @@ export async function leaseCommand(args, flags) {
     const read = await readLeases(root);
     if (read.error !== null) return { error: read.error, path: read.path };
     const held = activeLeases(read);
-    const conflicts = held.filter((l) => seen.has(keyOf(l)) && l.session !== session);
+    const conflicts = held.filter((l) => overlaps(l) && l.session !== session);
     if (conflicts.length > 0) return { conflicts };
     // Keep every other live claim, refresh ours, and let an expired one fall out:
     // the write is also the only sweep the file ever gets.
-    const others = held.filter((l) => !seen.has(keyOf(l)));
-    const mine = newClaim(Date.now() + ttl * 1000);
+    const others = held.filter((l) => !overlaps(l));
+    const mine = newClaim(Date.now() + ttl * 1000, held);
     const path = await writeLeases(root, [...others, ...mine]);
     return { mine, path };
   });
@@ -128,6 +151,15 @@ export async function leaseCommand(args, flags) {
     );
   }
   const { mine, path } = claimed;
+  // Coordination state a hook acts on belongs in the log a UI can tail, not only in a
+  // file a person has to open (Q73).
+  await noteEvent(root, {
+    kind: 'lease.acquired',
+    session,
+    harness: harness ?? null,
+    subject: mine.map((l) => l.path).join(','),
+    data: { ttl, fence: mine[0]?.fence ?? null },
+  });
 
   if (isJson(flags)) {
     emitJson({ ok: true, command: 'lease', root, session, ttl, dryRun: false, leases: mine, file: path });
@@ -139,7 +171,7 @@ export async function leaseCommand(args, flags) {
     `ttl      ${ttl}s`,
     ...mine.map((l) => `LEASED   ${l.path}  until ${ISO(l.expiresAt)}`),
   ];
-  emit(lines.join('\n'), { maxBytes: flags.maxBytes ?? 0 });
+  emit(lines.join('\n'));
   return EXIT.OK;
 }
 
@@ -151,6 +183,7 @@ function resolveTargets(root, args, session, verb) {
   const ignoreCase = coreIgnoreCase(root);
   const wanted = [];
   const seen = new Set();
+  const kinds = new Map();
   for (const arg of args) {
     const rel = canonicalLeasePath(root, arg, { ignoreCase });
     if (rel === null) {
@@ -159,9 +192,10 @@ function resolveTargets(root, args, session, verb) {
     if (!seen.has(rel)) {
       seen.add(rel);
       wanted.push(rel);
+      kinds.set(rel, String(arg).endsWith('/') ? 'dir' : 'path');
     }
   }
-  return { wanted, seen, ignoreCase };
+  return { wanted, seen, ignoreCase, kinds };
 }
 
 function claimSession(flags) {
@@ -177,23 +211,28 @@ async function releaseLeases(root, args, flags) {
   if (sessionError !== undefined) return sessionError;
   const resolved = resolveTargets(root, args, session, 'release');
   if (resolved.error !== undefined) return resolved.error;
-  const { wanted, seen, ignoreCase } = resolved;
-  const keyOf = (l) => canonicalLeasePath(root, l.path, { ignoreCase }) ?? l.path;
+  const { wanted, seen, ignoreCase, kinds } = resolved;
+  const overlaps = (l) =>
+    wanted.some(
+      (rel) =>
+        leaseCovers(l, rel) ||
+        (kinds.get(rel) === 'dir' && (l.path === rel || l.path.startsWith(`${rel}/`))),
+    );
   const mode = writeMode(flags);
 
   const released = await withLeaseLock(root, async () => {
     const read = await readLeases(root);
     if (read.error !== null) return { error: read.error, path: read.path };
     const held = activeLeases(read);
-    const foreign = held.filter((l) => seen.has(keyOf(l)) && l.session !== session);
+    const foreign = held.filter((l) => overlaps(l) && l.session !== session);
     if (foreign.length > 0) {
       return {
         conflicts: foreign.map((c) => `${c.path} is leased by ${c.session} until ${ISO(c.expiresAt)}`).join('; '),
       };
     }
-    const dropped = held.filter((l) => seen.has(keyOf(l)));
+    const dropped = held.filter((l) => overlaps(l));
     if (!mode.apply) return { preview: dropped };
-    const kept = held.filter((l) => !seen.has(keyOf(l)));
+    const kept = held.filter((l) => !overlaps(l));
     const path = await writeLeases(root, kept);
     return { dropped, path };
   });
@@ -212,9 +251,15 @@ async function releaseLeases(root, args, flags) {
       `apply    run: ${CLI} lease release ${wanted.map((p) => JSON.stringify(p)).join(' ')} --session ${session} --yes`,
     ];
     if (isJson(flags)) emitJson({ ok: true, command: 'lease release', root, dryRun: true, session, leases: released.preview });
-    else emit(lines.join('\n'), { maxBytes: flags.maxBytes ?? 0 });
+    else emit(lines.join('\n'));
     return EXIT.OK;
   }
+  await noteEvent(root, {
+    kind: 'lease.released',
+    session,
+    subject: released.dropped.map((l) => l.path).join(','),
+    data: { released: released.dropped.length },
+  });
   for (const l of released.dropped) note(`note     released ${l.path} (was held by ${l.session})`);
   if (isJson(flags)) emitJson({ ok: true, command: 'lease release', root, dryRun: false, session, leases: released.dropped });
   else {
@@ -225,7 +270,6 @@ async function releaseLeases(root, args, flags) {
         ...released.dropped.map((l) => `RELEASED ${l.path}`),
         ...(released.dropped.length === 0 ? ['(no active claims on those paths)'] : []),
       ].join('\n'),
-      { maxBytes: flags.maxBytes ?? 0 },
     );
   }
   return EXIT.OK;
@@ -236,27 +280,32 @@ async function renewLeases(root, args, flags) {
   if (sessionError !== undefined) return sessionError;
   const resolved = resolveTargets(root, args, session, 'renew');
   if (resolved.error !== undefined) return resolved.error;
-  const { wanted, seen, ignoreCase } = resolved;
+  const { wanted, seen, ignoreCase, kinds } = resolved;
   const ttl = flags.ttl === undefined ? DEFAULT_TTL_SECONDS : Number(flags.ttl);
   if (!Number.isInteger(ttl) || ttl < 1) {
     return fail(`--ttl must be a positive number of seconds, received ${flags.ttl}`, EXIT.USAGE, `example: run: ${CLI} lease renew <paths> --ttl 900`);
   }
-  const keyOf = (l) => canonicalLeasePath(root, l.path, { ignoreCase }) ?? l.path;
+  const overlaps = (l) =>
+    wanted.some(
+      (rel) =>
+        leaseCovers(l, rel) ||
+        (kinds.get(rel) === 'dir' && (l.path === rel || l.path.startsWith(`${rel}/`))),
+    );
   const mode = writeMode(flags);
 
   const renewed = await withLeaseLock(root, async () => {
     const read = await readLeases(root);
     if (read.error !== null) return { error: read.error, path: read.path };
     const held = activeLeases(read);
-    const foreign = held.filter((l) => seen.has(keyOf(l)) && l.session !== session);
+    const foreign = held.filter((l) => overlaps(l) && l.session !== session);
     if (foreign.length > 0) {
       return {
         conflicts: foreign.map((c) => `${c.path} is leased by ${c.session} until ${ISO(c.expiresAt)}`).join('; '),
       };
     }
     const expiresAt = Date.now() + ttl * 1000;
-    const mine = held.map((l) => (seen.has(keyOf(l)) ? { ...l, expiresAt } : l));
-    const touched = held.filter((l) => seen.has(keyOf(l)));
+    const mine = held.map((l) => (overlaps(l) ? { ...l, expiresAt } : l));
+    const touched = held.filter((l) => overlaps(l));
     if (!mode.apply) return { preview: touched.map((l) => ({ ...l, expiresAt })) };
     const path = await writeLeases(root, mine);
     return { touched: touched.map((l) => ({ ...l, expiresAt })), path };
@@ -278,7 +327,6 @@ async function renewLeases(root, args, flags) {
         ...rows.map((l) => `${mode.apply ? 'RENEWED  ' : 'would    renew '} ${l.path} until ${ISO(l.expiresAt)}`),
         ...(rows.length === 0 ? ['(no active claims on those paths)'] : []),
       ].join('\n'),
-      { maxBytes: flags.maxBytes ?? 0 },
     );
   }
   return EXIT.OK;
@@ -299,6 +347,6 @@ async function listLeases(root, flags) {
     ...held.map((l) => `LEASED   ${l.path}  ${l.session}${l.harness ? `/${l.harness}` : ''}  until ${ISO(l.expiresAt)}`),
   ];
   if (held.length === 0) lines.push(`(no active leases)`);
-  emit(lines.join('\n'), { maxBytes: flags.maxBytes ?? 0 });
+  emit(lines.join('\n'));
   return EXIT.OK;
 }