@warren-dean/code-kit 0.17.0 → 0.19.0

package/hooks/lib/instructions.mjs

@@ -0,0 +1,126 @@
+// ONB-8: the parts of a project's instructions that are code-kit's own: the lead's section of CLAUDE.md
+// and the "Always:" rules of each lane agent. Each is rendered from code-kit's templates and the
+// project's config, and kept between markers, so a newer code-kit can tell they're out of date and bring
+// them up to date exactly, leaving everything the project wrote around them as it is.
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+/** The version of code-kit's instructions: raised whenever the templates' rules change. */
+export const INSTRUCTIONS_VERSION = 5;
+
+const TEMPLATES = fileURLToPath(new URL('../../templates/', import.meta.url));
+const BEGIN = (v) => `<!-- code-kit:begin v${v} -->`;
+const END = '<!-- code-kit:end -->';
+const MARKED = /<!-- code-kit:begin v(\d+) -->\n[\s\S]*?<!-- code-kit:end -->/;
+const CI_WORKFLOW = '.github/workflows/code-kit.yml';
+
+/** `{{if key}}…{{end}}` kept where `facts[key]`, dropped otherwise; `{{key}}` replaced by `facts[key]`. */
+function fill(text, facts) {
+  return text
+    .replace(/^([ \t]*- )?\{\{if ([\w.]+)\}\}([\s\S]*?)\{\{end\}\}\n?/gm, (_, item, key, body) =>
+      facts[key] ? `${item ?? ''}${body}\n` : '',
+    )
+    .replace(/\{\{([\w.]+)\}\}/g, (whole, key) => (key in facts ? String(facts[key]) : whole))
+    .replace(/\n{3,}/g, '\n\n');
+}
+
+/** What the templates need from the project: everything the config and the repository say. */
+function factsOf(root, config) {
+  const delegated = new Set(config.approvals?.delegate?.protected ?? []);
+  const kept = [];
+  for (const p of config.protected ?? []) {
+    if (p.approval === 'kit' || delegated.has(p.approval)) continue;
+    if (!kept.some((k) => k.approval === p.approval)) kept.push(p);
+  }
+  return {
+    layers: (config.layers ?? []).map((l) => l.name).join(', ') || 'none set',
+    designGate: config.designGate ? '; designs approved before screens' : '',
+    personKeeps: kept.length
+      ? kept.map((p) => `\`${p.approval}\` (${p.why})`).join(', ')
+      : 'changes to the rules themselves',
+    'approvals.lead': Boolean(config.approvals?.lead),
+    'harness.report.on': Boolean(config.harness?.report?.on),
+    ci: existsSync(join(root, CI_WORKFLOW)),
+    'docs.specs': config.docs?.specs ?? 'the specs',
+    'docs.plan': config.docs?.plan ?? 'the plan',
+    'docs.principles': config.docs?.principles ?? "the project's principles",
+  };
+}
+
+const marked = (body) => `${BEGIN(INSTRUCTIONS_VERSION)}\n${body.trim()}\n${END}`;
+
+/** The lead's section of CLAUDE.md, between its markers. */
+export function leadSection(root, config) {
+  return marked(fill(readFileSync(join(TEMPLATES, 'claude-md.md'), 'utf8'), factsOf(root, config)));
+}
+
+/** A lane agent's "Always:" rules, between their markers. */
+export function agentRules(root, config) {
+  const template = readFileSync(join(TEMPLATES, 'agent.md'), 'utf8');
+  return marked(fill(template.slice(template.indexOf('Always:')), factsOf(root, config)));
+}
+
+/** Whether two renderings say the same, whatever their whitespace and list indentation. */
+const same = (a, b) => a.replace(/\s+/g, ' ').trim() === b.replace(/\s+/g, ' ').trim();
+
+const LEAD_LEGACY = /^## Enforced, not advised\s*$/;
+const AGENT_LEGACY = /^Always:\s*$/;
+
+/**
+ * Where a file's code-kit part stands: `current`; `stale` (marked, from an older code-kit or an older
+ * config); `legacy` (written before the markers, often tailored by hand, so merged once by the lead, not
+ * overwritten); or `missing` (none yet).
+ */
+function stateOf(text, block, legacy) {
+  const m = MARKED.exec(text);
+  // A formatter that rewraps the project's markdown doesn't make code-kit's part out of date.
+  if (m) return { state: same(m[0], block) ? 'current' : 'stale', version: Number(m[1]) };
+  if (text.split('\n').some((l) => legacy.test(l))) return { state: 'legacy', version: 0 };
+  return { state: 'missing', version: null };
+}
+
+/**
+ * Each file holding code-kit's instructions: `{ file, kind, state, version, block, next }`, `next` being
+ * the file brought up to date (null for a legacy one, which the lead merges). The lead's CLAUDE.md, and
+ * the agent file of every lane whose agent file exists.
+ */
+export function instructionsState(root, config) {
+  const lead = leadSection(root, config);
+  const rules = agentRules(root, config);
+  const files = [
+    { file: 'CLAUDE.md', kind: 'lead', block: lead, legacy: LEAD_LEGACY },
+    ...[...new Set(Object.values(config.lanes ?? {}).map((l) => l.agent))]
+      .map((agent) => ({
+        file: `.claude/agents/${agent}.md`,
+        kind: 'lane',
+        block: rules,
+        legacy: AGENT_LEGACY,
+      }))
+      .filter((f) => existsSync(join(root, f.file))),
+  ];
+  return files.map(({ file, kind, block, legacy }) => {
+    const path = join(root, file);
+    const text = existsSync(path) ? readFileSync(path, 'utf8') : '';
+    const { state, version } = stateOf(text, block, legacy);
+    const next =
+      state === 'stale'
+        ? text.replace(MARKED, block)
+        : state === 'missing'
+          ? `${text.replace(/\s*$/, '')}${text.trim() ? '\n\n' : ''}${block}\n`
+          : null;
+    return { file, kind, state, version, block, next };
+  });
+}
+
+/** Brings every marked or missing part of code-kit's instructions up to date; the files it changed. */
+export function writeInstructions(root, config) {
+  const changed = [];
+  for (const f of instructionsState(root, config)) {
+    if (!f.next) continue;
+    mkdirSync(dirname(join(root, f.file)), { recursive: true });
+    writeFileSync(join(root, f.file), f.next);
+    changed.push(f.file);
+  }
+  return changed;
+}

package/hooks/lib/next.mjs

@@ -1,7 +1,7 @@
 // What to do next, from the project's state alone: no docs → spec-design; a spec still being shaped →
 // spec-design; a ready spec or existing code without the kit → init; then, from the plan and git:
 // review finished stories, dispatch ready ones, wait on running ones, or plan the next milestone.
-import { execFileSync } from 'node:child_process';
+import { execFileSync, spawnSync } from 'node:child_process';
 import { existsSync, readdirSync, readFileSync } from 'node:fs';
 import { join, posix } from 'node:path';
 import { loadConfig, mergeDelegation } from './config.mjs';
@@ -10,6 +10,7 @@ import { pendingSetup } from './adapters/index.mjs';
 import { CONFIG_FILE, SETUP_VERSION } from './config.mjs';
 import { readQueue, waiting } from './queue.mjs';
 import { decidedBy, laneOf, openRequests } from './rules.mjs';
+import { instructionsState } from './instructions.mjs';
 import { SECURITY_AGENT_FILE } from './security.mjs';
 
 export const DRAFT_FILE = '.claude/code-kit.draft.json';
@@ -253,6 +254,30 @@ export function nextStep(root, base) {
     attention.push(
       `${unbuildable.join(', ')} can't be dispatched until the plan's gaps are fixed.`,
     );
+  // LEAN-6: worktrees whose story is merged and which hold nothing uncommitted are only disk space.
+  const leftovers = mergedWorktrees(root, config);
+  if (leftovers)
+    attention.push(
+      `${leftovers} worktree${leftovers === 1 ? ' is' : 's are'} merged and clean; \`code-kit worktrees prune\` removes them, keeping their reports.`,
+    );
+  // ONB-8: code-kit's own instructions to the lead and the lanes, brought up to date before the next step:
+  // a newer code-kit's rules reach the agents only through them.
+  const instructions = instructionsState(root, config);
+  const behind = instructions.filter((f) => ['stale', 'legacy'].includes(f.state));
+  // A file with no code-kit part may be one the project keeps without it: said, not insisted on.
+  const none = instructions.filter((f) => f.state === 'missing');
+  if (none.length)
+    attention.push(
+      `${none.map((f) => f.file).join(', ')} ${none.length === 1 ? 'has' : 'have'} none of code-kit's instructions; \`code-kit instructions --write\` adds them.`,
+    );
+  if (behind.length) {
+    const legacy = behind.filter((f) => f.state === 'legacy');
+    return result(
+      'instructions',
+      `code-kit's instructions in ${behind.map((f) => f.file).join(', ')} are behind this code-kit${legacy.length ? `; ${legacy.length === behind.length ? 'they were' : `${legacy.map((f) => f.file).join(', ')} were`} written before code-kit marked its part, so merge ${legacy.length === 1 ? 'it' : 'them'} once by hand, keeping the project's own lines` : ''}.`,
+      { args: legacy.length ? 'merge' : 'write' },
+    );
+  }
   // HELM-4: a lane waiting on something the lead decides goes first: the lane can't go on without it.
   const forLeadToDecide = openRequests(root).flatMap((r, i) =>
     r.lane && decidedBy(r.names, config) === 'lead' ? [{ ...r, n: i + 1 }] : [],
@@ -466,3 +491,23 @@ export function missingSkills(root) {
   }
   return out;
 }
+
+/** LEAN-6: how many of the project's worktrees have a merged branch and nothing uncommitted. */
+function mergedWorktrees(root, config) {
+  const list = git(root, 'worktree', 'list', '--porcelain');
+  if (!list) return 0;
+  const from = config.branches?.protected?.[0];
+  if (!from || !git(root, 'rev-parse', '--verify', '-q', from)) return 0;
+  let n = 0;
+  for (const block of list.split('\n\n').slice(1)) {
+    const path = /^worktree (.+)$/m.exec(block)?.[1];
+    const branch = /^branch refs\/heads\/(.+)$/m.exec(block)?.[1];
+    if (!path || !branch) continue;
+    const merged =
+      spawnSync('git', ['merge-base', '--is-ancestor', branch, from], { cwd: root }).status === 0;
+    if (!merged) continue;
+    const status = spawnSync('git', ['-C', path, 'status', '--porcelain'], { encoding: 'utf8' });
+    if (status.status === 0 && !status.stdout.trim()) n++;
+  }
+  return n;
+}

package/hooks/lib/rules.mjs

@@ -205,8 +205,9 @@ export function approvalsGiven(root) {
 export function realPath(path) {
   let dir = resolve(path);
   const rest = [];
+  // basename, not a slice after dirname: dirname('/x') is '/', so slicing past it cut the name's first letter.
   while (!existsSync(dir)) {
-    rest.unshift(dir.slice(dirname(dir).length + 1));
+    rest.unshift(basename(dir));
     dir = dirname(dir);
   }
   return join(realpathSync(dir), ...rest);
@@ -775,9 +776,14 @@ export function writeProblem(actor, rel, root, config) {
 const readonlyProblem = (actor, rel) =>
   `${actor.label} is read-only; it may not write ${rel}. If a command you ran changed it (a build, a formatter or a code generator), put it back with git restore -- ${rel} (or delete it if it's new), and run such commands only in a throwaway worktree of the branch.`;
 
+// Claude Code's own temporary folders (a session's scratchpad, its tool output): no repository's files.
+const CLAUDE_TEMP = ['/private/tmp/claude-*/**', '/tmp/claude-*/**'];
+
 function outsideAllowed(actor, rel, root, config) {
-  if (actor.kind !== 'lead') return false;
   const target = resolve(root, rel);
+  // A lane's scratch files go where Claude Code's own do, outside every repository.
+  if (actor.kind === 'lane') return CLAUDE_TEMP.some((g) => globToRegExp(g).test(target));
+  if (actor.kind !== 'lead') return false;
   return config.lead.outside.some((g) =>
     globToRegExp(resolve(root, g.replace(/^~(?=\/)/, homedir()))).test(target),
   );

package/hooks/mod/decisions.mjs

@@ -437,3 +437,32 @@ export function nativeChoice(card) {
       card.kind === 'question' ? 'answerTyped' : card.kind === 'waiting' ? 'answerLeadTyped' : null,
   };
 }
+
+/** NOTIFY-1: a decision's identity across refreshes: its kind and what it asks. */
+export const decisionKey = (card) => `${card.kind}|${card.headline}`;
+
+/**
+ * NOTIFY-1: the decisions that weren't waiting at the last look, each as a system notification: what it
+ * asks, headed by what kind of decision it is. `seen` holds the keys from the last look.
+ */
+export function newDecisions(cards, seen) {
+  return cards
+    .filter((c) => NOTIFY_TITLE[c.kind] && !seen.has(decisionKey(c)))
+    .map((c) => ({
+      key: decisionKey(c),
+      title: `code-kit: ${NOTIFY_TITLE[c.kind] ?? 'a decision for you'}`,
+      text: `${c.headline}${c.story ? ` (${c.story.id})` : ''}`,
+    }));
+}
+
+const NOTIFY_TITLE = {
+  held: 'an approval to give',
+  approvals: 'an approval to give',
+  question: 'the lead asks you',
+  brief: 'a question in your brief',
+  waiting: 'the lead waits on you',
+  stalled: 'a lane stalled',
+  denied: 'Claude Code refused a call',
+  proposal: 'a step to approve',
+  queue: 'a merge for you',
+};

package/hooks/mod/loop.mjs

@@ -4,6 +4,7 @@
 
 /** The steps the loop hands the lead; the rest (spec-design, init, check) wait for the person. */
 const LEAD_STEPS = new Set([
+  'instructions',
   'decide',
   'dispatch',
   'review',
@@ -96,13 +97,16 @@ export function parkWatch(id, on = [], stories = []) {
 }
 
 /**
- * LOOP-13: where the watched stories stand, as one string: each one's state, its branch's commit and
- * whether an agent is at work on it. A parked story wakes when this changes.
+ * LOOP-13: where the watched stories stand, as one string. The parked story itself (the first) counts
+ * its state, its branch's commit and whether an agent is at work on it; each story it waits on counts its
+ * state alone, so the commits of a story still being built don't wake the one waiting for it to finish.
+ * A parked story wakes when this changes.
  */
 export function storiesSignature(ids, stories = [], heads = new Map(), inFlight = new Set()) {
   return ids
-    .map((id) => {
+    .map((id, i) => {
       const s = stories.find((x) => x.id === id);
+      if (i > 0) return `${id}:${s?.state ?? '?'}`;
       return `${id}:${s?.state ?? '?'}:${s?.branch ? (heads.get(s.branch) ?? '') : ''}:${inFlight.has(id) ? 'busy' : ''}`;
     })
     .join('|');
@@ -134,6 +138,14 @@ export function leadPrompt(step, { cli = 'code-kit' } = {}) {
   // SETUP-2: the base has no rules yet; the lead puts the approved ones there, then merges as usual.
   if (step.step === 'rules')
     return `Put code-kit's approved rules onto ${ids[0] ?? 'the base'}: run node "${cli}" queue rules. It commits the rules as committed on this branch, without switching branches; after it, merge the queue as usual.`;
+  // ONB-8: code-kit's instructions brought up to date, then committed like any change to the kit.
+  if (step.step === 'instructions') {
+    const how =
+      step.args === 'merge'
+        ? `Run node "${cli}" instructions to see which files, then merge each one: replace its old code-kit part with what node "${cli}" instructions show lead (CLAUDE.md) or show lane (an agent file) prints, and keep every line the project wrote itself outside the markers, under a heading of its own. Then run node "${cli}" instructions --write for the rest.`
+        : `Run node "${cli}" instructions --write.`;
+    return `${step.why ?? "code-kit's instructions are behind."} ${how} Commit the change on a branch and merge it like your own stories, so new lane agents start with the current rules.`;
+  }
   // HELM-4: a lane waits on the lead's decision; the decide skill takes each request on its merits.
   if (step.step === 'decide')
     return ids.length
@@ -175,6 +187,7 @@ export function stepLabel(step) {
   const verb =
     {
       decide: 'Decide requests',
+      instructions: 'Update the instructions',
       dispatch: 'Dispatch',
       review: 'Review',
       lead: 'Build',
@@ -327,10 +340,27 @@ export function milestonesDone(stories = []) {
   return [...by].filter(([, list]) => list.every((s) => s.state === 'done')).map(([m]) => m);
 }
 
-/** LEAN-3: what the lead's summary keeps when its context is compacted after a milestone. */
-export const compactInstructions = (milestone) =>
+/** LEAN-3, LEAN-4: what the lead's summary keeps when its context is compacted, after a milestone or not. */
+export const compactInstructions = (milestone = null) =>
   [
-    `${milestone} is done; the build goes on with the next milestone.`,
+    milestone
+      ? `${milestone} is done; the build goes on with the next milestone.`
+      : "The lead's context is compacted between turns; the build goes on.",
     'Keep: the milestone just finished, in a line; every story in flight now, with its lane, its branch and where it stands (building, in review, in the merge queue, waiting and on what); the decisions and questions waiting on the person; what the person decided or asked for in this session that still applies; and the rules and preferences they set.',
     "Drop: the finished stories' details, lane reports and hand-backs, command output, diffs and file contents. Each is in git, the plan or the lanes' report files, to read again when it's needed.",
   ].join('\n');
+
+/** LEAN-5: the context a model request carried: what it sent, read from the cache, and wrote to it. */
+export const requestContext = (usage) =>
+  (usage?.input_tokens ?? 0) +
+  (usage?.cache_read_input_tokens ?? 0) +
+  (usage?.cache_creation_input_tokens ?? 0);
+
+/** LEAN-5: what a lane agent past its context limit is told. */
+export const wrapUpText = (limit) =>
+  `Your context is past ${Math.round(limit / 1000)}k tokens, and every step from here rereads all of it. Finish the step you're on, commit your work, write your report, and hand back now. The lead carries the story on with a fresh agent that reads your report.`;
+
+/** LEAN-5, LEAN-6: the lead's prompt to carry a story on with a fresh agent once its agent handed back at the limit. */
+export function continuePrompt({ type, story, branch, cli = 'code-kit' }) {
+  return `${type} handed ${story} back at its context limit, with its work committed${branch ? ` on ${branch}` : ''}. Carry the story on with a fresh agent: run node "${cli}" worktrees release ${branch ?? '<branch>'} (it keeps the commits and moves the report to the main checkout), then dispatch ${story} again with the same brief, adding "Read your earlier report first: .claude/state/reports/${(branch ?? '<branch>').replace(/[^\w.-]+/g, '_')}.md in the main checkout": /code-kit:dispatch ${story}`;
+}

package/hooks/mod/panes.mjs

@@ -120,6 +120,8 @@ export function laneActions(lane, { queue = [], held = [], requests = [] } = {})
   const head = queue.find((e) => ['waiting', 'merging'].includes(e.state));
   if (head && head.branch === lane.branch) acts.push({ id: 'merge', label: 'Merge', hotkey: 'm' });
   if (lane.active && lane.agent) {
+    // WATCH-1: the lane agent's own transcript, in the main view.
+    acts.push({ id: 'watch', label: 'Watch', hotkey: 'w' });
     acts.push({ id: 'nudge', label: 'Nudge', hotkey: 'n' });
     acts.push({ id: 'stop', label: 'Stop', hotkey: 'x' });
   }

package/hooks/mod/register.mjs

@@ -61,6 +61,9 @@ import {
   COMPACT_FLOOR,
   PARK_MS,
   compactInstructions,
+  continuePrompt,
+  requestContext,
+  wrapUpText,
   milestonesDone,
   parkWatch,
   readOutcome,
@@ -74,7 +77,7 @@ import {
   withoutInFlight,
 } from './loop.mjs';
 import { goalOf, nextText } from './mission.mjs';
-import { contextOf, decisionCards, nativeChoice } from './decisions.mjs';
+import { contextOf, decisionCards, decisionKey, nativeChoice, newDecisions } from './decisions.mjs';
 import { DEFAULT_TEAM_UI, TEAM_ID, teamFrame } from './teamview.mjs';
 import { glowOf, mapStoryOf, touchOf } from './codemap.mjs';
 import { harnessSettings } from '../lib/harness.mjs';
@@ -144,6 +147,8 @@ let turnQuestions = []; // the open questions as the lead's running turn started
 // DECIDE-4: decisions asked in Claude Code's own question dialog this session, and whether one is open.
 const offered = new Set();
 let offering = false;
+// NOTIFY-1: the decisions waiting at the last look, by key; null until the first look.
+let notified = null;
 /** LOOP-8: the times in a row the lead is prompted with one step before the person is asked. */
 const ASK_LIMIT = 2;
 let leadTurn = null; // the lead's running turn, if any
@@ -1047,6 +1052,23 @@ export function register(on) {
         const who = attribution(agentId, agentsSeen.get(agentId) ?? null, model.check, model.state);
         ledger = withUsage(ledger, who, usage);
         $.ui.invalidate('ui.render');
+        // LEAN-5: a lane agent past its context limit is told to wrap up; its story goes on fresh.
+        const limit = harness().agents.lanes.contextLimit;
+        const agent = agentId ? agentsSeen.get(agentId) : null;
+        const lane = Object.entries(model.check?.lanes ?? {}).find(
+          ([, l]) => l.agent === agent?.type,
+        );
+        if (!limit || !lane || requestContext(usage) < limit) return;
+        const a = activityOf(agentId, await $.clock.now());
+        if (a.overflow) return;
+        a.overflow = true;
+        a.lane = lane[0];
+        a.story = who.story ?? a.story ?? lane[0];
+        await act.record(
+          'wrap up',
+          `${lane[0]} · ${a.story} at ${Math.round(requestContext(usage) / 1000)}k`,
+        );
+        await $.session.send({ to: { agentId }, text: wrapUpText(limit) }).catch(() => {});
       },
       // --- the lead loop (spec 05) ---------------------------------------------------------------
       record: async (kind, target, prompt) => {
@@ -1063,10 +1085,19 @@ export function register(on) {
       ) => {
         loop.started = true;
         loop.proposal = null;
-        loop.sent = { prompt, key, label, kind, target };
+        const sent = { prompt, key, label, kind, target, before: new Map() };
+        loop.sent = sent;
         // LOOP-12: a design story is handed to the lead once; the person designs it with the lead.
         if (kind === 'design')
           for (const id of String(target).split(/\s+/).filter(Boolean)) loop.handedDesign.add(id);
+        // LOOP-13: where the step's stories stood when the lead was prompted, to tell after its turn
+        // whether it moved them.
+        // A design is made with the person over many turns (LOOP-12), so it's never counted as unmoved.
+        const ids = kind === 'design' ? [] : stepStories({ kind, target });
+        if (ids.length) {
+          const seen = await act.storiesNow();
+          for (const id of ids) sent.before.set(id, seen.sig([id]));
+        }
         await act.record(kind, target, prompt);
         $.ui.invalidate('ui.render');
         $.prompt.submit({ text: prompt }).catch((err) => {
@@ -1141,6 +1172,16 @@ export function register(on) {
         }
         $.ui.invalidate('ui.render');
       },
+      // LOOP-13: the stories of the step the lead was prompted with that its turn left where they stood.
+      parkUnmoved: async (sent, reason) => {
+        if (!sent?.before?.size) return;
+        const seen = await act.storiesNow();
+        await act.park(
+          [...sent.before]
+            .filter(([id, sig]) => !loop.parked.has(id) && seen.sig([id]) === sig)
+            .map(([id]) => ({ id, on: [], why: reason ?? "the lead's turn didn't move it" })),
+        );
+      },
       // LOOP-13: a parked story wakes when anything it watches moves, or after PARK_MS with nothing moving.
       unpark: async () => {
         if (!loop.parked.size) return;
@@ -1156,14 +1197,15 @@ export function register(on) {
         const done = milestonesDone(model.state?.stories ?? []);
         if (loop.milestones === null) {
           loop.milestones = new Set(done);
-          return false;
+          return act.compactAtThreshold();
         }
         const fresh = done.filter((m) => !loop.milestones.has(m));
-        if (!fresh.length) return false;
+        // LEAN-4: past compact.at, the lead's context is compacted between turns, milestone or not.
+        if (!fresh.length) return act.compactAtThreshold();
         const mode = harness().compact?.milestone ?? 'ask';
         if (mode === 'off' || offering || !where.interactive || (lease.other && !lease.mine)) {
           for (const m of fresh) loop.milestones.add(m);
-          return false;
+          return act.compactAtThreshold();
         }
         const box = await $.prompt.read().catch(() => null);
         if (box?.text?.trim()) return false;
@@ -1198,6 +1240,25 @@ export function register(on) {
           });
         return true;
       },
+      // LEAN-4: the lead's context compacted at once when it's past compact.at; true when it took over.
+      compactAtThreshold: async () => {
+        const at = harness().compact?.at ?? 40;
+        if (!at || offering || !where.interactive || (lease.other && !lease.mine)) return false;
+        const percent = (await $.session.usage().catch(() => null))?.context?.percent ?? 0;
+        if (percent < Math.max(at, COMPACT_FLOOR)) return false;
+        const box = await $.prompt.read().catch(() => null);
+        if (box?.text?.trim()) return false;
+        Promise.resolve()
+          .then(() => $.session.compact({ instructions: compactInstructions() }))
+          .catch((err) => ({ skip: String(err?.message ?? err) }))
+          .then(async (r) => {
+            if (r?.skip) notice = `The lead's context wasn't compacted: ${r.skip}`;
+            await act.record('compact', `at ${Math.round(percent)}%`);
+            $.ui.invalidate('ui.render');
+            await act.step('resume').catch(() => {});
+          });
+        return true;
+      },
       // LOOP-11: the lead's last reply, read once before the loop prompts it again. A reply that waits on
       // the person, or a turn they stopped, holds the loop until they speak; a step the lead didn't take
       // holds that step while it's still next.
@@ -1236,10 +1297,16 @@ export function register(on) {
           $.ui.invalidate('ui.render');
           return;
         }
-        if (!reply.text.trim()) return;
-        const said = await act.sideCall(
-          outcomePrompt({ prompt: sent?.prompt ?? null, answer: reply.text }),
-        );
+        if (!reply.text.trim()) return act.parkUnmoved(sent, null);
+        // LEAN-6: the reply and the prompt it answered are enough to read it, so a small model reads
+        // them, instead of a fork over the lead's whole conversation on its own model at every turn's end.
+        const said = await $.model
+          .complete({
+            model: 'sonnet',
+            prompt: outcomePrompt({ prompt: sent?.prompt ?? null, answer: reply.text }),
+            maxTokens: 600,
+          })
+          .catch(() => ({ isAnswered: false }));
         const heard = said.isAnswered ? readOutcome(said.text) : null;
         // Spec 05's data: what came of the step, once known.
         const record = sent ? loop.steps.findLast((x) => x.prompt === sent.prompt) : null;
@@ -1259,6 +1326,10 @@ export function register(on) {
             })),
           );
         }
+        // LOOP-13: a story the lead's turn left exactly where it stood wasn't taken, whatever the reply
+        // reads as; it's parked like one the lead said waits, so the loop doesn't prompt it again until
+        // it moves.
+        if (heard?.outcome !== 'needs-person') await act.parkUnmoved(sent, heard?.reason);
         if (heard?.outcome === 'needs-person')
           loop.waiting = {
             kind: 'person',
@@ -1310,6 +1381,28 @@ export function register(on) {
       // DECIDE-4: the next decision the person settles with a choice, asked in Claude Code's own question
       // dialog while the lead is idle. Each is asked once: dismissed, it stays in the band and the
       // Decisions tab. Never in a session another one runs the loop for, nor over what the person types.
+      // NOTIFY-1: what newly needs the person, as a system notification, from the session that runs the
+      // loop. What waited before this session looked isn't news. On a Claude Code without $.ui.notify,
+      // the call fails and nothing is raised.
+      notifyNew: async () => {
+        if (model.state?.kind !== 'ok' || !where.interactive) return;
+        const cards = cardsNow(await $.clock.now());
+        const fresh = newDecisions(cards, notified ?? new Set());
+        const first = notified === null;
+        notified = new Set(cards.map(decisionKey));
+        if (first || !fresh.length || harness().notify?.on === false) return;
+        if (lease.other && !lease.mine) return;
+        const one =
+          fresh.length === 1
+            ? fresh[0]
+            : {
+                title: `code-kit: ${fresh.length} things need you`,
+                text: fresh.map((f) => f.text).join('; '),
+              };
+        await Promise.resolve()
+          .then(() => $.ui.notify(one.text, { title: one.title }))
+          .catch(() => {});
+      },
       offer: async () => {
         if (offering || leadTurn || loop.sent || !where.interactive) return;
         if (lease.other && !lease.mine) return;
@@ -1631,6 +1724,24 @@ export function register(on) {
         ((await $.agent.list().catch(() => [])) ?? []).find(
           (a) => a.status === 'running' && a.type === lane.agent,
         ) ?? null,
+      // WATCH-1: the person's press puts the lane agent's transcript in the main view, as the tasks list
+      // does; the tasks list (or Escape there) brings the main conversation back.
+      watchLane: async (lane) => {
+        const agent = await act.runningAgentOf(lane);
+        if (!agent) {
+          notice = `No agent is at work in the ${lane.name} lane to watch.`;
+          $.ui.invalidate('ui.render');
+          return;
+        }
+        const r = await Promise.resolve()
+          .then(() => $.ui.view({ agentId: agent.id }))
+          .catch(() => ({
+            deny: 'this Claude Code shows an agent only from its tasks list (2.1.301 or later shows it from here)',
+          }));
+        notice = r?.deny ? `Couldn't show the ${lane.name} lane's agent: ${r.deny}.` : null;
+        if (!r?.deny) await act.record('watch', `${lane.name} · ${agent.type}`);
+        $.ui.invalidate('ui.render');
+      },
       nudgeLane: async (lane) => {
         const agent = await act.runningAgentOf(lane);
         if (!agent) return;
@@ -1737,6 +1848,7 @@ export function register(on) {
           return act.review({ story: { ...lane.story, branch: lane.branch } });
         if (id === 'merge') return act.mergeQueue({ branch: lane.branch });
         if (id === 'sendBack') return act.sendBack(lane);
+        if (id === 'watch') return act.watchLane(lane);
         if (id === 'nudge') return act.nudgeLane(lane);
         if (id === 'stop') return act.stopLane(lane);
       },
@@ -1758,6 +1870,7 @@ export function register(on) {
         // LOOP-10: the lead session renews its lease; DECIDE-4: with the lead idle, a decision waiting.
         if (lease.mine) await act.lead();
         if (!leadTurn) act.offer().catch(() => {});
+        await act.notifyNew().catch(() => {});
         await act.stalls();
         await act.animate();
         const now = await act.fingerprint();
@@ -1954,6 +2067,16 @@ export function register(on) {
   // SET-4: a lane agent starts on the lane model the person set, unless the lead's call names one or
   // the lane's agent file sets its own.
   on('agent.spawn', async ($, e, next) => {
+    // LEAN-7: the security reviewer runs on the reviewers' model, unless the call or its file names one.
+    const reviewerModel = harness().agents.reviewer.model;
+    if (e.subagentType === 'security-reviewer' && reviewerModel && !e.model) {
+      const file = where
+        ? await $.fs.read(`${where.cwd}/.claude/agents/security-reviewer.md`).catch(() => null)
+        : null;
+      const own = typeof file === 'string' ? agentFileModel(file) : null;
+      if (!own || own === 'inherit') return next({ ...e, model: reviewerModel });
+      return next(e);
+    }
     const setting = harness().agents.lanes.model;
     const lanes = model.check?.lanes ?? {};
     if (!setting || e.model || !Object.values(lanes).some((l) => l.agent === e.subagentType))
@@ -2011,7 +2134,25 @@ export function register(on) {
     const res = await next(e);
     // LOOP-3: a lane agent that has handed back its work isn't stalled while it waits; a message that
     // starts it again shows as its next tool call.
-    if (e.agentId) activityOf(e.agentId, await $.clock.now()).handedBack = true;
+    if (e.agentId) {
+      const a = activityOf(e.agentId, await $.clock.now());
+      a.handedBack = true;
+      // LEAN-5: an agent that handed back at its limit: the lead carries its story on with a fresh one.
+      if (a.overflow && !a.continued && act) {
+        a.continued = true;
+        const agent = agentsSeen.get(e.agentId);
+        const story = (model.state?.stories ?? []).find((s) => s.id === a.story);
+        loop.pending.push({
+          story: a.story,
+          prompt: continuePrompt({
+            type: agent?.type ?? 'The lane agent',
+            story: a.story,
+            branch: story?.branch ?? null,
+            cli: where?.cli,
+          }),
+        });
+      }
+    }
     // REVW-3: a subagent's last turn may be the reviewer's report.
     if (e.agentId && act) await act.reviewed(e.agentId, e.answer).catch(() => {});
     // LOOP-1: the lead is idle; the loop's next step, if one is due (submitted from turn.complete,