@warren-dean/code-kit 0.21.0 → 0.22.1

package/hooks/lib/sessions.mjs

@@ -0,0 +1,223 @@
+// Sessions as members of the team (docs/specs/23-the-team.md, SESS-1 to SESS-5). Several Claude Code
+// sessions can work one project at once; each is a member, the person and the session, as spec 16 makes
+// each developer one. One is the lead session (the loop runs there, dispatches start from it); the rest
+// are working sessions, which stay quiet and record an ad hoc task, with the paths it leases, before
+// they change code. A session's id is Claude Code's: `session_id` in hooks, `$.session.id()` in the mod,
+// `CLAUDE_CODE_SESSION_ID` in every command an agent runs. Kept in the main checkout, one file per session,
+// so every session and worktree on the machine reads the same: this is the local provider of SESS-1.
+import { mkdirSync, readFileSync, readdirSync, writeFileSync } from 'node:fs';
+import { userInfo } from 'node:os';
+import { join } from 'node:path';
+import { matchesAny } from './glob.mjs';
+import { CLI, projectWorktrees } from './rules.mjs';
+import { shortSession } from './laneclaims.mjs';
+
+export { shortSession };
+export const SESSIONS_DIR = '.claude/state/sessions';
+/** A session seen within this is live; one not seen for longer has ended, whether or not it said so. */
+export const SESSION_LIVE_MS = 15 * 60_000;
+/** Hooks note that a session is still there at most this often. */
+const SEEN_EVERY_MS = 60_000;
+/** The uncommitted files a session wrote, kept for SESS-5: at most this many. */
+const WROTE_KEPT = 500;
+
+const main = (root) => projectWorktrees(root)[0] ?? root;
+const dirOf = (root) => join(main(root), SESSIONS_DIR);
+const safe = (id) => String(id).replace(/[^\w.-]/g, '_');
+const fileOf = (root, id) => join(dirOf(root), `${safe(id)}.json`);
+
+/** The person at this machine: their GitHub login if code-kit has it cached, or the OS user. */
+export function personHere(root) {
+  try {
+    const cached = JSON.parse(readFileSync(join(main(root), '.claude/state/whoami.json'), 'utf8'));
+    if (cached?.login) return cached.login;
+  } catch {
+    // not cached: the OS user
+  }
+  try {
+    return userInfo().username || null;
+  } catch {
+    return null;
+  }
+}
+
+/** SESS-1: who a claim, approval, question or decision belongs to: `<person>/<short id>`. */
+export const memberOf = (record) =>
+  record ? `${record.person ?? 'someone'}/${shortSession(record.id)}` : null;
+
+export function readSession(root, id) {
+  if (!id) return null;
+  try {
+    return JSON.parse(readFileSync(fileOf(root, id), 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+function write(root, record) {
+  mkdirSync(dirOf(root), { recursive: true });
+  writeFileSync(fileOf(root, record.id), `${JSON.stringify(record)}\n`);
+  return record;
+}
+
+const isLive = (r, now) => !r.ended && now - Date.parse(r.seen ?? r.started) < SESSION_LIVE_MS;
+
+/** Every session the project has seen: [{ ...record, live }], the newest first. */
+export function sessions(root, now = Date.now()) {
+  let files = [];
+  try {
+    files = readdirSync(dirOf(root)).filter((f) => f.endsWith('.json'));
+  } catch {
+    return [];
+  }
+  return files
+    .flatMap((f) => {
+      try {
+        const r = JSON.parse(readFileSync(join(dirOf(root), f), 'utf8'));
+        return r?.id ? [{ ...r, live: isLive(r, now) }] : [];
+      } catch {
+        return [];
+      }
+    })
+    .sort((a, b) => Date.parse(b.started) - Date.parse(a.started));
+}
+
+/** SESS-2: the live lead session, or null. */
+export const leadSession = (root, now = Date.now()) =>
+  sessions(root, now).find((s) => s.live && s.role === 'lead') ?? null;
+
+/**
+ * SESS-2: a session starting (or resumed). It's the lead when no other live session is; otherwise a
+ * working session. A resumed session keeps the role it had, unless it was the lead and another session
+ * has led since.
+ */
+export function startSession(root, id, now = Date.now()) {
+  const at = new Date(now).toISOString();
+  const had = readSession(root, id);
+  const lead = leadSession(root, now);
+  return write(root, {
+    id,
+    person: had?.person ?? personHere(root),
+    role: lead && lead.id !== id ? 'working' : 'lead',
+    started: had?.started ?? at,
+    seen: at,
+    ended: null,
+    task: had?.task ?? null,
+    wrote: had?.wrote ?? [],
+  });
+}
+
+/** A hook saw the session act: it's still there. A session code-kit hadn't seen starts here. */
+export function seeSession(root, id, now = Date.now()) {
+  if (!id) return null;
+  const had = readSession(root, id);
+  if (!had || had.ended) return startSession(root, id, now);
+  // A lead that went quiet past SESSION_LIVE_MS, while another session took the lead, works now.
+  const lead = had.role === 'lead' ? leadSession(root, now) : null;
+  const demoted = lead && lead.id !== id;
+  if (!demoted && now - Date.parse(had.seen) < SEEN_EVERY_MS) return had;
+  return write(root, {
+    ...had,
+    seen: new Date(now).toISOString(),
+    ...(demoted ? { role: 'working' } : {}),
+  });
+}
+
+/** The session ended: it's no longer live, and leads nothing. Its task stays, stale, for SESS-4. */
+export function endSession(root, id, now = Date.now()) {
+  const had = readSession(root, id);
+  if (!had) return null;
+  return write(root, { ...had, ended: new Date(now).toISOString() });
+}
+
+/** SESS-2: the person chose this session to lead: it does, and the session that led becomes a working one. */
+export function makeLead(root, id, now = Date.now()) {
+  for (const s of sessions(root, now))
+    if (s.role === 'lead' && s.id !== id) write(root, { ...strip(s), role: 'working' });
+  const had = readSession(root, id) ?? startSession(root, id, now);
+  return write(root, { ...had, role: 'lead', seen: new Date(now).toISOString(), ended: null });
+}
+
+const strip = ({ live: _live, ...r }) => r;
+
+/** SESS-4: the session's task: { title, paths, branch, started }, or null to end it. */
+export function setTask(root, id, task, now = Date.now()) {
+  const had = readSession(root, id) ?? startSession(root, id, now);
+  return write(root, {
+    ...had,
+    task: task ? { ...task, started: had.task?.started ?? new Date(now).toISOString() } : null,
+  });
+}
+
+/**
+ * SESS-4: `taker` takes over the task of the session `from` (by its id or short id): the task, and its
+ * decisions with it (OWN-4), move to the session running the command. { ok, task, from } or { ok: false, why }.
+ */
+export function takeTask(root, from, taker, now = Date.now()) {
+  const source = sessions(root, now).find((s) => s.id === from || shortSession(s.id) === from);
+  if (!source?.task) return { ok: false, why: `No session ${from} has a task.` };
+  if (source.id === taker) return { ok: false, why: 'That task is already this session’s.' };
+  if (source.live)
+    return {
+      ok: false,
+      why: `Session ${shortSession(source.id)} is still working on it; ask it to finish with \`code-kit task done\` first.`,
+    };
+  write(root, { ...strip(source), task: null });
+  const took = setTask(root, taker, source.task, now);
+  // OWN-4: the task's decisions come with it.
+  write(root, {
+    ...took,
+    took: [...new Set([...(took.took ?? []), source.id, ...(source.took ?? [])])],
+  });
+  return { ok: true, task: source.task, from: source };
+}
+
+/**
+ * SESS-4: why `session` may not write `rel`, because another live session's task leases it, or null.
+ * A stale task (its session has ended) leases nothing.
+ */
+export function taskRefusal(root, session, rel, now = Date.now()) {
+  const other = sessions(root, now).find(
+    (s) => s.live && s.id !== session && s.task?.paths?.length && matchesAny(rel, s.task.paths),
+  );
+  if (!other) return null;
+  return `${rel} is leased by another session (${memberOf(other)}), working on "${other.task.title}". Leave it to that session, wait until it finishes (\`code-kit task done\` there), or work on something else.`;
+}
+
+/** SESS-5: a file a session wrote in a checkout, kept while it may still be uncommitted. */
+export function noteWrite(root, id, rel, now = Date.now()) {
+  if (!id || !rel) return;
+  const had = readSession(root, id) ?? startSession(root, id, now);
+  const wrote = [rel, ...(had.wrote ?? []).filter((f) => f !== rel)].slice(0, WROTE_KEPT);
+  if (wrote.join('\n') === (had.wrote ?? []).join('\n')) return;
+  write(root, { ...had, wrote });
+}
+
+/** SESS-5: the sessions, other than `session`, that wrote each of `files`: { file: [record] }. */
+export function writersOf(root, files, session = null, now = Date.now()) {
+  const all = sessions(root, now).filter((s) => s.id !== session);
+  return Object.fromEntries(
+    files
+      .map((f) => [f, all.filter((s) => (s.wrote ?? []).includes(f))])
+      .filter(([, w]) => w.length),
+  );
+}
+
+/**
+ * SESS-4, SESS-5: why this write may not happen because of the sessions working the project, or null.
+ * Another live session's task leases the path; or this is a working session's own main agent, which
+ * writes in a worktree of its own (the main checkout is every session's) and records its task first.
+ * code-kit's state, and paths outside the project, are never held back.
+ */
+export function sessionWriteProblem({ project, root, rel, actor, session, now = Date.now() }) {
+  if (!session || !rel || rel.startsWith('..') || rel.startsWith('.claude/state/')) return null;
+  const leased = taskRefusal(project, session, rel, now);
+  if (leased) return leased;
+  const me = readSession(project, session);
+  if (actor?.kind !== 'lead' || me?.role !== 'working') return null;
+  if (root === main(project))
+    return `this is a working session (another session leads the project), and ${rel} is in the main checkout, which every session shares: your uncommitted files there would block the other sessions' git. Work in a worktree of your own: start the session with \`claude --worktree\`, or move it into one (EnterWorktree), then record your task and go on.`;
+  if (!me.task)
+    return `this is a working session (another session leads the project): record what you're doing before you change code, so the other sessions see it and leave your files alone:\n  node "${CLI}" task "<what you're doing, in a line>" --touches "<globs of the paths you'll change>"`;
+  return null;
+}

package/hooks/lib/snapshot.mjs

@@ -24,8 +24,10 @@ import {
   sourceOf,
 } from './standards.mjs';
 
-/** 2 adds the project's standards (code-kit spec 22). */
-export const SNAPSHOT_VERSION = 2;
+import { slicesOf } from './schedule.mjs';
+
+/** 2 adds the project's standards (code-kit spec 22); 3 the plan's slices (spec 23, SCHED-2). */
+export const SNAPSHOT_VERSION = 3;
 
 /** A story's stage, as a report names it. */
 export const STAGES = [
@@ -52,6 +54,8 @@ export const SNAPSHOT_SCHEMA = {
   version: 'count',
   project: { repository: 'name?', base: 'name', codeKit: 'name', at: 'ms' },
   milestones: [{ name: 'name', target: 'date?', stories: ['id'] }],
+  // SCHED-2: each slice in plan order, whether it's open or done, and its stories. Added in version 3.
+  slices: [{ name: 'name', open: 'bool', done: 'bool', stories: ['id'] }],
   stories: [
     {
       id: 'id',
@@ -117,7 +121,7 @@ export const SNAPSHOT_SCHEMA = {
 };
 
 /** Parts a report from an older code-kit doesn't have yet: valid when missing, checked when there. */
-export const LATER_PARTS = ['standards'];
+export const LATER_PARTS = ['standards', 'slices'];
 
 const ONE_LINE = (max) => (v) => typeof v === 'string' && v.length <= max && !/[\r\n]/.test(v);
 const KINDS = {
@@ -170,6 +174,7 @@ export function snapshotHash(snapshot, parts = null) {
 /** The parts whose change is sent at once (HUBR-3); usage alone waits for the ten minutes. */
 export const EVENT_PARTS = [
   'milestones',
+  'slices',
   'stories',
   'sendBacks',
   'requirements',
@@ -363,6 +368,7 @@ export function buildSnapshot({
       at: now,
     },
     milestones,
+    slices: slicesOf(status.stories).map((sl) => ({ ...sl, name: line(sl.name).slice(0, 120) })),
     stories,
     sendBacks: sendBackList,
     requirements,

package/hooks/mod/decisions.mjs

@@ -8,7 +8,6 @@ import { approvalLabel, askWords, commandItself } from './view.mjs';
 export const DECISION_KINDS = new Set([
   'held',
   'approvals',
-  'stalled',
   'proposal',
   'queue',
   'review',
@@ -20,7 +19,6 @@ export const DECISION_KINDS = new Set([
   'teamDrift',
   'question',
   'brief',
-  'denied',
   'report',
   'waiting',
 ]);
@@ -51,10 +49,6 @@ const EFFECT = {
   answer: 'Type your answer; the lead is told it and carries on.',
   answerBrief: "Type your answer; the lead records it in the brief's decisions and builds on it.",
   laterBrief: 'It waits; it comes back next session.',
-  runDenied:
-    'Puts it in your prompt after !, so you run it yourself; press Enter to run it, then Done it.',
-  deniedDone: 'The lead is told you ran it, or allowed it, and carries on.',
-  deniedNo: "The lead is told you won't run it now, and carries on with other work.",
   answerLead: 'The lead is told your answer and carries on.',
   answerLeadText: 'Type your answer; the lead is told it and carries on.',
   askAgain: 'The lead is asked to take this step again now.',
@@ -93,17 +87,6 @@ function eachDecision(line) {
       text: `From your brief: ${b.question}`,
       brief: b,
     }));
-  if (line.kind === 'denied')
-    return (line.denials ?? [line.denial]).map((d) => ({
-      ...line,
-      text: `Claude Code refused ${d.who}'s ${d.what}`,
-      denial: d,
-      actions: [
-        ...(d.command ? [{ id: 'runDenied', label: 'Put it in the prompt' }] : []),
-        { id: 'deniedDone', label: 'Done it' },
-        { id: 'deniedNo', label: 'Not now' },
-      ],
-    }));
   if (line.kind === 'report')
     return (line.reports ?? [line.report]).map((r) => ({ ...line, text: r.title, report: r }));
   return [line];
@@ -164,7 +147,6 @@ const TAG = {
   notice: 'notice',
   question: 'question',
   brief: 'your brief',
-  denied: 'refused',
   report: 'bug report',
   waiting: 'the lead',
 };
@@ -211,11 +193,6 @@ function headlineOf(line, story) {
       headline: line.brief.question,
       sub: `open in ${line.brief.path}${line.brief.blocks ? ` · holds up ${line.brief.blocks}` : ''}`,
     };
-  if (line.kind === 'denied')
-    return {
-      headline: `Claude Code refused ${line.denial.who}'s call`,
-      sub: clip(line.denial.command ?? line.denial.what, 80),
-    };
   if (line.kind === 'report')
     return { headline: line.report.title, sub: "drafted by an agent, for code-kit's GitHub" };
   if (line.kind === 'waiting' && line.waiting.question)
@@ -261,8 +238,6 @@ function whyOf(line, check) {
     );
   if (line.kind === 'brief')
     return `It's an open question in ${line.brief.path}, left for you: what gets built depends on your answer. Not sure what it means? Ask about it when you answer.`;
-  if (line.kind === 'denied')
-    return `Claude Code's own permission check refused it${line.denial.reason ? ` (${line.denial.reason})` : ''}, which code-kit can't approve past: only you can run it or allow it.`;
   if (line.kind === 'waiting' && line.waiting.kind === 'person')
     return "The lead's last reply waits on you, so the loop doesn't prompt it again until you answer, here or in the chat.";
   if (line.kind === 'waiting' && line.waiting.kind === 'stopped')
@@ -391,7 +366,7 @@ export function contextOf(card) {
 }
 
 /** DECIDE-4: the kinds of decision settled with a choice, asked in Claude Code's own question dialog. */
-export const NATIVE_KINDS = new Set(['proposal', 'stalled', 'teamStale', 'question', 'waiting']);
+export const NATIVE_KINDS = new Set(['proposal', 'teamStale', 'question', 'waiting']);
 
 /** One sentence ended as a question asks. */
 const asked = (text, question) => `${String(text).replace(/[.\s]+$/, '')}. ${question}`;
@@ -461,8 +436,6 @@ const NOTIFY_TITLE = {
   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

@@ -218,6 +218,14 @@ export function restartPrompt({ type, id, story, minutes }) {
   return `${type} (agent ${id}) on ${story} has made no tool call for ${minutes} minutes. Stop it with TaskStop, then dispatch ${story} again with the same brief on the same branch: /code-kit:dispatch ${story}`;
 }
 
+/**
+ * WHO-4: a lane stalled past its restarts is the lead's to sort out, not the person's: what it tried,
+ * and the lead's three ways on (a narrower brief, smaller stories, or the story handed back).
+ */
+export function stalledPrompt({ type, id, lane, story, restarts, last = null }) {
+  return `${type} (agent ${id}) on ${story} has stalled again after ${restarts} restart${restarts === 1 ? '' : 's'}${last ? `; its last call was ${last}` : ''}. Stop it with TaskStop, read its report and what it committed on its branch, then decide: dispatch ${story} again with a brief that names what it got stuck on, split ${story} into smaller stories in the plan, or hand it back to the ${lane} lane's queue with the reason. Ask the person only if the story needs a product decision.`;
+}
+
 /** The message a quiet agent gets (LOOP-3). */
 export const nudgeText = (minutes) =>
   `No tool call for ${minutes} minutes: report where you are, or carry on.`;

package/hooks/mod/mission.mjs

@@ -50,7 +50,8 @@ export function missionLines({
 }) {
   if (state?.kind !== 'ok') return [];
   const working = state.lanes.filter((l) => l.name !== 'lead' && l.active && live[l.name]);
-  const loopOn = Boolean(loop?.started) && !['off', 'stopped', 'elsewhere'].includes(loop?.state);
+  const away = ['elsewhere', 'unled'].includes(loop?.state);
+  const loopOn = Boolean(loop?.started) && !['off', 'stopped'].includes(loop?.state) && !away;
   if (!leadBusy && !working.length && !loopOn) return [];
   const rows = [];
   const goal = goalOf(state.stories);
@@ -65,28 +66,29 @@ export function missionLines({
     : 'lead idle';
   const loopWord =
     loop?.state === 'elsewhere'
-      ? 'loop in another session'
-      : loop?.state === 'paused'
-        ? 'loop paused'
-        : loop?.state === 'off'
-          ? 'loop off'
-          : loop?.state === 'done'
-            ? 'milestone done'
-            : loopOn
-              ? `loop ${loop.autonomy === 'propose' ? 'proposing' : 'on'}${loop.last ? ` · last: ${loop.last}` : ''}`
-              : null;
+      ? 'the lead is in another session'
+      : loop?.state === 'unled'
+        ? 'no session leads the project'
+        : loop?.state === 'paused'
+          ? 'loop paused'
+          : loop?.state === 'off'
+            ? 'loop off'
+            : loop?.state === 'done'
+              ? 'milestone done'
+              : loopOn
+                ? `loop ${loop.autonomy === 'propose' ? 'proposing' : 'on'}${loop.last ? ` · last: ${loop.last}` : ''}`
+                : null;
   rows.push({
     kind: 'now',
     label: 'now',
     text: [lead, loopWord].filter(Boolean).join(' · '),
-    actions:
-      loop?.state === 'elsewhere'
-        ? [{ id: 'leadHere', label: 'Lead from here' }]
-        : loop?.state === 'paused'
-          ? [{ id: 'resume', label: 'Resume' }]
-          : loopOn && loop?.state === 'running'
-            ? [{ id: 'pause', label: 'Pause' }]
-            : [],
+    actions: away
+      ? [{ id: 'leadHere', label: 'Lead from here' }]
+      : loop?.state === 'paused'
+        ? [{ id: 'resume', label: 'Resume' }]
+        : loopOn && loop?.state === 'running'
+          ? [{ id: 'pause', label: 'Pause' }]
+          : [],
   });
   const next = nextText(nextStep);
   if (next && loop?.state !== 'done') rows.push({ kind: 'next', label: 'next', text: next });