@litfamily/litcodex 1.0.31 → 1.0.32

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (65) hide show
  1. package/README-Ko-KR.md +11 -10
  2. package/README.md +11 -10
  3. package/TRADEMARK.md +12 -0
  4. package/marketplace/plugins/litcodex/.codex-plugin/plugin.json +1 -1
  5. package/marketplace/plugins/litcodex/components/auto-update/package.json +1 -1
  6. package/marketplace/plugins/litcodex/components/comment-checker/package.json +1 -1
  7. package/marketplace/plugins/litcodex/components/git-bash/package.json +1 -1
  8. package/marketplace/plugins/litcodex/components/lit-loop/directives/lit-adhd.md +12 -9
  9. package/marketplace/plugins/litcodex/components/lit-loop/directives/lit-plan.md +2 -1
  10. package/marketplace/plugins/litcodex/components/lit-loop/dist/card-status.d.ts +3 -0
  11. package/marketplace/plugins/litcodex/components/lit-loop/dist/card-status.js +4 -1
  12. package/marketplace/plugins/litcodex/components/lit-loop/dist/hook-cli.js +8 -2
  13. package/marketplace/plugins/litcodex/components/lit-loop/dist/plan-persistence.d.ts +1 -1
  14. package/marketplace/plugins/litcodex/components/lit-loop/dist/plan-persistence.js +28 -2
  15. package/marketplace/plugins/litcodex/components/lit-loop/dist/plan-scope-roots.d.ts +7 -0
  16. package/marketplace/plugins/litcodex/components/lit-loop/dist/plan-scope-roots.js +76 -0
  17. package/marketplace/plugins/litcodex/components/lit-loop/dist/restart-chip.d.ts +6 -0
  18. package/marketplace/plugins/litcodex/components/lit-loop/dist/restart-chip.js +59 -0
  19. package/marketplace/plugins/litcodex/components/lit-loop/dist/rewind-go.js +11 -1
  20. package/marketplace/plugins/litcodex/components/lit-loop/dist/rewind.d.ts +13 -7
  21. package/marketplace/plugins/litcodex/components/lit-loop/dist/rewind.js +143 -49
  22. package/marketplace/plugins/litcodex/components/lit-loop/dist/route-heads.js +1 -1
  23. package/marketplace/plugins/litcodex/components/lit-loop/dist/session-liveness.d.ts +16 -0
  24. package/marketplace/plugins/litcodex/components/lit-loop/dist/session-liveness.js +90 -0
  25. package/marketplace/plugins/litcodex/components/lit-loop/dist/threads.js +7 -2
  26. package/marketplace/plugins/litcodex/components/lit-loop/dist/workflow-stack.d.ts +9 -2
  27. package/marketplace/plugins/litcodex/components/lit-loop/dist/workflow-stack.js +35 -5
  28. package/marketplace/plugins/litcodex/components/lit-loop/package.json +1 -1
  29. package/marketplace/plugins/litcodex/components/lsp/package.json +1 -1
  30. package/marketplace/plugins/litcodex/components/rules/package.json +1 -1
  31. package/marketplace/plugins/litcodex/components/start-work-continuation/package.json +1 -1
  32. package/marketplace/plugins/litcodex/components/telemetry/package.json +1 -1
  33. package/marketplace/plugins/litcodex/components/wikify-knowledge/package.json +1 -1
  34. package/marketplace/plugins/litcodex/skills/lit-adhd/SKILL.md +15 -11
  35. package/marketplace/plugins/litcodex/skills/lit-adhd/references/card-examples.md +23 -7
  36. package/marketplace/plugins/litcodex/skills/lit-adhd/references/status-taxonomy.md +12 -4
  37. package/marketplace/plugins/litcodex/skills/lit-plan/SKILL.md +3 -2
  38. package/marketplace/plugins/litcodex/skills/lit-plan/references/full-workflow.md +2 -1
  39. package/marketplace/plugins/litcodex/skills/start-work/SKILL.md +1 -1
  40. package/node_modules/@litcodex/lit-loop/directives/lit-adhd.md +12 -9
  41. package/node_modules/@litcodex/lit-loop/directives/lit-plan.md +2 -1
  42. package/node_modules/@litcodex/lit-loop/dist/card-status.d.ts +3 -0
  43. package/node_modules/@litcodex/lit-loop/dist/card-status.js +4 -1
  44. package/node_modules/@litcodex/lit-loop/dist/hook-cli.js +8 -2
  45. package/node_modules/@litcodex/lit-loop/dist/plan-persistence.d.ts +1 -1
  46. package/node_modules/@litcodex/lit-loop/dist/plan-persistence.js +28 -2
  47. package/node_modules/@litcodex/lit-loop/dist/plan-scope-roots.d.ts +7 -0
  48. package/node_modules/@litcodex/lit-loop/dist/plan-scope-roots.js +76 -0
  49. package/node_modules/@litcodex/lit-loop/dist/restart-chip.d.ts +6 -0
  50. package/node_modules/@litcodex/lit-loop/dist/restart-chip.js +59 -0
  51. package/node_modules/@litcodex/lit-loop/dist/rewind-go.js +11 -1
  52. package/node_modules/@litcodex/lit-loop/dist/rewind.d.ts +13 -7
  53. package/node_modules/@litcodex/lit-loop/dist/rewind.js +143 -49
  54. package/node_modules/@litcodex/lit-loop/dist/route-heads.js +1 -1
  55. package/node_modules/@litcodex/lit-loop/dist/session-liveness.d.ts +16 -0
  56. package/node_modules/@litcodex/lit-loop/dist/session-liveness.js +90 -0
  57. package/node_modules/@litcodex/lit-loop/dist/threads.js +7 -2
  58. package/node_modules/@litcodex/lit-loop/dist/workflow-stack.d.ts +9 -2
  59. package/node_modules/@litcodex/lit-loop/dist/workflow-stack.js +35 -5
  60. package/node_modules/@litcodex/lit-loop/package.json +1 -1
  61. package/node_modules/@litcodex/lit-loop/skills/lit-adhd/SKILL.md +15 -11
  62. package/node_modules/@litcodex/lit-loop/skills/lit-plan/SKILL.md +3 -2
  63. package/node_modules/@litcodex/lit-loop/skills/start-work/SKILL.md +1 -1
  64. package/package.json +3 -2
  65. package/readme-assets/badge-version.svg +1 -1
@@ -5,8 +5,9 @@ export declare const ACTIVE_MS: number;
5
5
  export declare const GO_WINDOW_MS: number;
6
6
  export declare const DEFAULT_SINCE_MS: number;
7
7
  export declare const DEFAULT_MAX = 12;
8
- export type SessionStatus = "waiting-on-user" | "active" | "ended" | "unknown";
9
- export type NextKind = "resume-frame" | "approve-boundary" | "continue-work" | "start-plan" | "none";
8
+ export type SessionStatus = "waiting-on-user" | "active" | "idle" | "done" | "ended" | "unknown";
9
+ /** `handoff` is shown, never run: a `go` over it starts nothing. */
10
+ export type NextKind = "resume-frame" | "approve-boundary" | "continue-work" | "start-plan" | "handoff" | "none";
10
11
  export interface NextStep {
11
12
  readonly kind: NextKind;
12
13
  readonly text: string;
@@ -67,6 +68,10 @@ export interface RewindWorktree {
67
68
  readonly gauge: string | null;
68
69
  } | null;
69
70
  readonly openPlans: readonly OpenPlan[];
71
+ /** Plans in the window with every row ticked; they count as done. */
72
+ readonly finishedPlans: readonly string[];
73
+ /** Plan files too large to read, counted so the brief can say it left them out. */
74
+ readonly skippedPlans: number;
70
75
  /** Recent commits (done, dated), the step under way, and the next open plan rows. */
71
76
  readonly milestones: readonly RewindMilestone[];
72
77
  readonly paused: readonly {
@@ -125,7 +130,7 @@ export interface RewindOptions {
125
130
  export declare function parseSince(text: string): number | null;
126
131
  /** UUIDv7 ids open with a timestamp, so sessions started minutes apart share the first 8 characters; use the random tail then. */
127
132
  export declare function shortIdOf(id: string): string;
128
- interface OpenPlan {
133
+ export interface OpenPlan {
129
134
  readonly name: string;
130
135
  readonly done: number;
131
136
  readonly total: number;
@@ -133,6 +138,8 @@ interface OpenPlan {
133
138
  /** When the plan file last changed; null when that cannot be read. */
134
139
  readonly changedMs: number | null;
135
140
  }
141
+ /** The open plan `name` (a file under `.litcodex/plans`), or null when it is finished, a scaffold or missing. */
142
+ export declare function openPlanNamed(cwd: string, name: string): OpenPlan | null;
136
143
  /**
137
144
  * The one step worth taking next, in priority order: the paused frame of this session's stack, then a boundary
138
145
  * waiting for an answer (shown, never started), then work already under way, then the single open plan.
@@ -147,16 +154,15 @@ export declare function collectRewind(options: RewindOptions): RewindResult;
147
154
  * open plan item, the latest other active session, the latest other ended one. It is shown, never recorded.
148
155
  */
149
156
  export declare function suggestionOf(sessions: readonly RewindSession[], worktrees: readonly RewindWorktree[]): string;
150
- /** The one-line headline: how many sessions, what waits on the person, and the one next step. */
157
+ /** The three-line opener in plain words: done so far, doing now, next. */
151
158
  export declare function briefHeadline(result: RewindResult): string;
152
159
  /** Ended sessions, one table row each, newest first: they are history, so no card. One line per row at 120 columns. */
153
160
  export declare function endedTable(sessions: readonly RewindSession[], now: number, width?: number): string[];
154
161
  /**
155
162
  * The brief as Markdown limited to what the Codex terminal draws: bold, emoji, lists, a table and a fenced box.
156
- * Never `#` headings or `>` quotes, which it prints as raw marks. A headline, live session cards (waiting or
157
- * running) grouped by worktree with each worktree's roadmap (done ✓ with its date, now ▶, later ○), one table
163
+ * Never `#` headings or `>` quotes, which it prints as raw marks. A three-line opener, a card for every session
164
+ * that has not ended, grouped by worktree with each worktree's roadmap (done ✓ with its date, now ▶, later ○), one table
158
165
  * row for every ended session, and the one recommended next step in a box. A progress gauge appears only when
159
166
  * both counts are real; otherwise the known facts are written out in words.
160
167
  */
161
168
  export declare function renderBrief(result: RewindResult, width?: number): string;
162
- export {};
@@ -5,8 +5,8 @@
5
5
  // writes one file, the next-step note `.litcodex/adhd/next-<session>.json` that a following `go` consumes,
6
6
  // and nothing else. Every string that leaves is redacted and stripped of control characters; a source it
7
7
  // cannot read is named `unknown` instead of guessed. The brief itself is composed by the model from the
8
- // JSON; `renderBrief` is the Markdown draft of the same parts: a headline, live session cards, one table row for
9
- // each ended session, a roadmap and one boxed next step.
8
+ // JSON; `renderBrief` is the Markdown draft of the same parts: a three-line opener (done so far, doing now, next),
9
+ // session cards, one table row for each ended session, a roadmap and one boxed next step.
10
10
  import { execFileSync } from "node:child_process";
11
11
  import { existsSync, lstatSync, mkdirSync, readdirSync, readFileSync, rmSync } from "node:fs";
12
12
  import { homedir } from "node:os";
@@ -16,8 +16,9 @@ import { displayWidth, fit } from "./hud.js";
16
16
  import { codexHomeFrom, plainDirsOrMissing, readSmallJson, writeFileAtomic } from "./live-step.js";
17
17
  import { makeRedactor } from "./rewind-redact.js";
18
18
  import { listRollouts, newBudget, readRollout, TOTAL_BYTES, } from "./rewind-rollout.js";
19
+ import { readLiveness } from "./session-liveness.js";
19
20
  import { normalizeSessionId } from "./state-paths.js";
20
- import { countPlanRows, planRows, readWorkflowSignals } from "./workflow-map.js";
21
+ import { countPlanRows, planProgress, planRows, readWorkflowSignals } from "./workflow-map.js";
21
22
  import { frameLabel, frameNote, pausedSpine, readStack, STACK_DIR, stackGauge, } from "./workflow-stack.js";
22
23
  export const ADHD_DIR = ".litcodex/adhd";
23
24
  /** A session written to in the last quarter hour is still running. */
@@ -149,33 +150,45 @@ function isTemplate(rows) {
149
150
  return (rows.some((row) => /<[^<>]{1,40}>/u.test(row.label)) ||
150
151
  (rows.length > 1 && new Set(rows.map((row) => row.label.trim())).size === 1));
151
152
  }
152
- function openPlansOf(path) {
153
+ function plansOf(path) {
154
+ const scan = { open: [], finished: [], skipped: [] };
153
155
  if (!plainDirsOrMissing(path, ".litcodex/plans"))
154
- return [];
155
- const plans = [];
156
+ return scan;
156
157
  for (const file of listDir(join(path, ".litcodex/plans"), ".md", 40)) {
157
158
  try {
158
159
  const full = join(path, ".litcodex/plans", file);
159
160
  const stat = lstatSync(full);
160
- if (!stat.isFile() || stat.size > MAX_STATE_BYTES)
161
+ if (!stat.isFile())
161
162
  continue;
163
+ if (stat.size > MAX_STATE_BYTES) {
164
+ scan.skipped.push({ name: file, done: 0, total: 0, gauge: null, changedMs: stat.mtimeMs });
165
+ continue;
166
+ }
162
167
  const text = readFileSync(full, "utf8");
163
168
  const rows = countPlanRows(text);
164
- if (rows.total > 0 && rows.done < rows.total && !isTemplate(planRows(text))) {
165
- plans.push({
166
- name: file,
167
- done: rows.done,
168
- total: rows.total,
169
- gauge: stackGauge({ n: rows.done, total: rows.total }),
170
- changedMs: stat.mtimeMs,
171
- });
172
- }
169
+ if (rows.total === 0 || isTemplate(planRows(text)))
170
+ continue;
171
+ const plan = {
172
+ name: file,
173
+ done: rows.done,
174
+ total: rows.total,
175
+ gauge: stackGauge({ n: rows.done, total: rows.total }),
176
+ changedMs: stat.mtimeMs,
177
+ };
178
+ (rows.done < rows.total ? scan.open : scan.finished).push(plan);
173
179
  }
174
180
  catch {
175
181
  // An unreadable plan is left out.
176
182
  }
177
183
  }
178
- return plans;
184
+ return scan;
185
+ }
186
+ function openPlansOf(path) {
187
+ return plansOf(path).open;
188
+ }
189
+ /** The open plan `name` (a file under `.litcodex/plans`), or null when it is finished, a scaffold or missing. */
190
+ export function openPlanNamed(cwd, name) {
191
+ return openPlansOf(cwd).find((plan) => plan.name === name) ?? null;
179
192
  }
180
193
  function pausedFramesOf(path) {
181
194
  if (!plainDirsOrMissing(path, STACK_DIR))
@@ -189,7 +202,8 @@ function pausedFramesOf(path) {
189
202
  }
190
203
  return out;
191
204
  }
192
- function handoffHeading(path) {
205
+ /** The first 16 KiB of this folder's HANDOFF note, or null. */
206
+ function handoffText(path) {
193
207
  for (const name of listDir(path, ".md", 200)
194
208
  .filter((file) => /^HANDOFF/iu.test(file))
195
209
  .slice(0, 1)) {
@@ -198,8 +212,7 @@ function handoffHeading(path) {
198
212
  const stat = lstatSync(full);
199
213
  if (!stat.isFile())
200
214
  continue;
201
- const text = readFileSync(full, "utf8").slice(0, MAX_HANDOFF_BYTES);
202
- return /^#{1,3}\s+(.+)$/mu.exec(text)?.[1]?.trim() ?? null;
215
+ return readFileSync(full, "utf8").slice(0, MAX_HANDOFF_BYTES);
203
216
  }
204
217
  catch {
205
218
  return null;
@@ -207,6 +220,36 @@ function handoffHeading(path) {
207
220
  }
208
221
  return null;
209
222
  }
223
+ function handoffHeading(path) {
224
+ const text = handoffText(path);
225
+ return text === null ? null : (/^#{1,3}\s+(.+)$/mu.exec(text)?.[1]?.trim() ?? null);
226
+ }
227
+ /** The first item under the HANDOFF note's `## Next` that is not ticked off, or null. */
228
+ function handoffNext(path) {
229
+ const text = handoffText(path);
230
+ const body = text === null ? undefined : /^##\s+Next\b[^\n]*\n([\s\S]*?)(?=^#{1,2}\s|(?![\s\S]))/imu.exec(text)?.[1];
231
+ for (const line of (body ?? "").split("\n")) {
232
+ if (/^\s*[-*+]\s+\[[xX]\]/u.test(line))
233
+ continue;
234
+ const item = line
235
+ .replace(/^\s*(?:[-*+]|\d+[.)])\s+(?:\[ \]\s+)?/u, "")
236
+ .replace(/\s+/gu, " ")
237
+ .trim();
238
+ if (item !== "")
239
+ return fit(item, 160);
240
+ }
241
+ return null;
242
+ }
243
+ /** The session finished what it ran: its top frame is a closed start-work, or the plan it carries is all ticked. */
244
+ function sessionFinished(cwd, sessionId) {
245
+ const top = readStack(cwd, sessionId).frames.at(-1);
246
+ if (top === undefined)
247
+ return false;
248
+ if (top.done === true && (top.skill === "start-work" || top.skill === "litwork"))
249
+ return true;
250
+ const plan = top.ref === undefined ? null : planProgress(cwd, top.ref.plan);
251
+ return plan !== null && plan.done >= plan.total;
252
+ }
210
253
  // ── Session and timeline words ───────────────────────────────────────────────
211
254
  /** `6m`, `2h 5m`, `3d` for a length of time. */
212
255
  function spanWords(ms) {
@@ -232,6 +275,10 @@ function sessionFacts(facts, redact) {
232
275
  function needsOf(status, doing) {
233
276
  if (status === "waiting-on-user")
234
277
  return "answer its question";
278
+ if (status === "done")
279
+ return "review what it finished";
280
+ if (status === "idle")
281
+ return "its turn is over; it waits for your next message";
235
282
  if (status === "active")
236
283
  return doing === null ? "nothing yet; it is still working" : `now: ${doing}`;
237
284
  if (status === "ended")
@@ -350,6 +397,9 @@ function chooseNextRaw(cwd, sessionId) {
350
397
  plan: only.name,
351
398
  };
352
399
  }
400
+ const handoff = open.length === 0 ? handoffNext(cwd) : null;
401
+ if (handoff !== null)
402
+ return { kind: "handoff", text: `from the handoff: ${handoff}` };
353
403
  return { kind: "none", text: "no single next step stands out; say what to work on" };
354
404
  }
355
405
  function nextPath(cwd, sessionId) {
@@ -364,7 +414,7 @@ export function writeNext(cwd, sessionId, next, now) {
364
414
  try {
365
415
  if (!plainDirsOrMissing(cwd, ADHD_DIR))
366
416
  return;
367
- if (next.kind === "none") {
417
+ if (next.kind === "none" || next.kind === "handoff") {
368
418
  rmSync(path, { force: true });
369
419
  return;
370
420
  }
@@ -407,7 +457,15 @@ export function collectRewind(options) {
407
457
  if (options.here === true && (facts.cwd === null || !insideDir(facts.cwd, options.cwd)))
408
458
  continue;
409
459
  const top = facts.cwd === null ? undefined : readStack(facts.cwd, facts.id).frames.at(-1);
410
- const status = statusOf(facts, file.mtimeMs, now);
460
+ const seen = statusOf(facts, file.mtimeMs, now);
461
+ // What the workspace recorded outranks a guess from the record's age: finished work, then a closed turn.
462
+ const status = facts.cwd !== null && sessionFinished(facts.cwd, facts.id)
463
+ ? "done"
464
+ : seen !== "waiting-on-user" &&
465
+ facts.cwd !== null &&
466
+ readLiveness(facts.cwd, facts.id, now)?.state === "idle"
467
+ ? "idle"
468
+ : seen;
411
469
  const lastAgent = snippet(redact, facts.lastAgent, 160);
412
470
  const gauge = stackGauge(top ?? {});
413
471
  const noted = top === undefined ? "" : frameNote(top);
@@ -465,11 +523,10 @@ export function collectRewind(options) {
465
523
  total: signals.goals.total,
466
524
  gauge: stackGauge({ n: signals.goals.done, total: signals.goals.total }),
467
525
  };
468
- // This worktree's open plans stay; another worktree's count only if changed inside the window.
469
- const local = insideDir(options.cwd, tree.path);
470
- const openPlans = openPlansOf(tree.path)
471
- .filter((plan) => local || (plan.changedMs !== null && now - plan.changedMs <= sinceMs))
472
- .slice(0, 4);
526
+ // Every plan, this worktree's too, counts only if it changed inside the window.
527
+ const inWindow = (plan) => plan.changedMs !== null && now - plan.changedMs <= sinceMs;
528
+ const scan = plansOf(tree.path);
529
+ const openPlans = scan.open.filter(inWindow).slice(0, 4);
473
530
  const pausedHere = pausedFramesOf(tree.path);
474
531
  return {
475
532
  path: redact(tree.path),
@@ -479,6 +536,11 @@ export function collectRewind(options) {
479
536
  work,
480
537
  goals,
481
538
  openPlans,
539
+ finishedPlans: scan.finished
540
+ .filter(inWindow)
541
+ .map((plan) => plan.name)
542
+ .slice(0, 4),
543
+ skippedPlans: scan.skipped.filter(inWindow).length,
482
544
  milestones: milestonesOf(tree.path, git, pausedHere.map(({ frame }) => redact(frameLabel(frame))), openPlans, now).map((milestone) => ({ ...milestone, label: snippet(redact, milestone.label, 80) ?? "" })),
483
545
  paused: pausedHere.map(({ session, frame }) => ({
484
546
  session: session.slice(0, 8),
@@ -536,12 +598,18 @@ export function suggestionOf(sessions, worktrees) {
536
598
  const question = lastQuestion(waiting.lastAgent);
537
599
  return `answer ${waiting.shortId} in ${placeOf(waiting)}${question === null ? "" : `: “${question}”`}`;
538
600
  }
601
+ // Finished work is reviewed, never picked up again as if it were still to do.
602
+ const finished = others.find((session) => session.status === "done");
603
+ if (finished !== undefined)
604
+ return `review what ${finished.shortId} finished in ${placeOf(finished)}: ${fit(finished.title ?? "no first request", 50)}`;
539
605
  for (const tree of worktrees) {
540
606
  const paused = tree.paused[0];
541
607
  if (paused !== undefined)
542
608
  return `resume ${paused.label} in ${paused.session} (${homeless(tree.path)})`;
543
609
  }
544
- const liveTrees = new Set(sessions.filter((session) => session.status !== "ended").map((session) => session.tree));
610
+ const liveTrees = new Set(sessions
611
+ .filter((session) => session.status !== "ended" && session.status !== "done")
612
+ .map((session) => session.tree));
545
613
  const withItem = worktrees
546
614
  .filter((tree) => tree.openPlans.length > 0 && tree.milestones.some((item) => item.state === "now"))
547
615
  .sort((a, b) => Number(liveTrees.has(b.path)) - Number(liveTrees.has(a.path)));
@@ -549,7 +617,7 @@ export function suggestionOf(sessions, worktrees) {
549
617
  const item = tree?.milestones.find((milestone) => milestone.state === "now");
550
618
  if (tree !== undefined && item !== undefined)
551
619
  return `next in ${tree.openPlans[0]?.name ?? "the open plan"} (${homeless(tree.path)}): ${item.label}`;
552
- const active = others.find((session) => session.status === "active");
620
+ const active = others.find((session) => session.status === "active" || session.status === "idle");
553
621
  if (active !== undefined)
554
622
  return `check on ${active.shortId} in ${placeOf(active)} (${fit(active.title ?? "no first request", 50)})${active.doing === null ? "" : `, now ${active.doing}`}`;
555
623
  const ended = others.find((session) => session.status === "ended");
@@ -588,6 +656,8 @@ function agoShort(from, now) {
588
656
  const BADGE = {
589
657
  "waiting-on-user": "🟡 **WAITS ON YOU**",
590
658
  active: "🟢 **RUNNING**",
659
+ idle: "💤 **IDLE**",
660
+ done: "✅ **DONE**",
591
661
  ended: "⚪ **ENDED**",
592
662
  unknown: "⚫ **NO RECORD**",
593
663
  };
@@ -599,21 +669,34 @@ function plural(count, one, many = `${one}s`) {
599
669
  function stepOf(result) {
600
670
  return result.next.kind === "none" ? result.suggestion : result.next.text;
601
671
  }
602
- /** The one-line headline: how many sessions, what waits on the person, and the one next step. */
603
- export function briefHeadline(result) {
604
- const waiting = result.sessions.filter((session) => session.status === "waiting-on-user").length;
605
- const running = result.sessions.filter((session) => session.status === "active").length;
672
+ /** The opener's three parts: what is finished, what is under way, and the one next step. */
673
+ function openerOf(result) {
674
+ const count = (status) => result.sessions.filter((session) => session.status === status).length;
675
+ const plans = result.worktrees.reduce((sum, tree) => sum + tree.finishedPlans.length, 0);
676
+ const finished = [
677
+ plans > 0 ? `${plural(plans, "plan")} finished` : "",
678
+ count("done") > 0 ? `${plural(count("done"), "session")} done` : "",
679
+ ].filter((part) => part !== "");
680
+ const waiting = count("waiting-on-user");
606
681
  const paused = result.worktrees.reduce((sum, tree) => sum + tree.paused.length, 0);
607
- const parts = [
608
- plural(result.sessions.length, "session"),
609
- waiting === 0 ? "nothing waits on you" : `${waiting} ${waiting === 1 ? "waits" : "wait"} on you`,
610
- ];
611
- if (running > 0)
612
- parts.push(`${running} running`);
613
- if (paused > 0)
614
- parts.push(`${paused} paused`);
615
- parts.push(`next: ${stepOf(result)}`);
616
- return parts.join(" · ");
682
+ const doing = [
683
+ count("active") > 0 ? `${count("active")} running` : "",
684
+ count("idle") > 0 ? `${count("idle")} idle` : "",
685
+ paused > 0 ? `${paused} paused` : "",
686
+ ].filter((part) => part !== "");
687
+ if (doing.length === 0)
688
+ doing.push("nothing running");
689
+ doing.push(waiting === 0 ? "nothing waits on you" : `${waiting} ${waiting === 1 ? "waits" : "wait"} on you`);
690
+ return {
691
+ done: finished.length === 0 ? "nothing finished in this window" : finished.join(" · "),
692
+ doing: doing.join(" · "),
693
+ next: stepOf(result),
694
+ };
695
+ }
696
+ /** The three-line opener in plain words: done so far, doing now, next. */
697
+ export function briefHeadline(result) {
698
+ const opener = openerOf(result);
699
+ return [`done so far: ${opener.done}`, `doing now: ${opener.doing}`, `next: ${opener.next}`].join("\n");
617
700
  }
618
701
  // Markdown words: record text is inert data, so every character that would turn it into markup is neutralised.
619
702
  const GAUGE = /\[[▉░]{1,10}\] \d+\/\d+/gu;
@@ -655,6 +738,7 @@ function roadmapBlock(tree, live) {
655
738
  : `start-work ${rich(tree.work.status)}${tree.work.gauge === null ? "" : ` ${code(tree.work.gauge)}`}`,
656
739
  tree.goals === null ? null : `goals${tree.goals.gauge === null ? "" : ` ${code(tree.goals.gauge)}`}`,
657
740
  ...tree.openPlans.map((plan) => `plan ${code(plan.name)}${plan.gauge === null ? "" : ` ${code(plan.gauge)}`}`),
741
+ ...tree.finishedPlans.map((name) => `plan ${code(name)} finished`),
658
742
  ].filter((part) => part !== null);
659
743
  const open = parts.length > 0 || tree.milestones.some((item) => item.state !== "done");
660
744
  if (!open && !(live && (tree.milestones.length > 0 || tree.handoff !== null)))
@@ -704,10 +788,12 @@ function nextBox(result, width) {
704
788
  ? "nothing runs on its own here: open that session, or say what to do"
705
789
  : result.next.kind === "approve-boundary"
706
790
  ? "answer `lit approve` or `lit deny` yourself"
707
- : "say `go` to run it";
791
+ : result.next.kind === "handoff"
792
+ ? "a step from the handoff note; `go` does not run it, so say what to do"
793
+ : "say `go` to run it";
708
794
  const box = (text) => `│ ${pad(text, inner)} │`;
709
795
  return [
710
- "```text",
796
+ "```",
711
797
  `╭─ Recommended next step ${"─".repeat(Math.max(1, inner - 22))}╮`,
712
798
  ...wrap(stepOf(result), inner).map(box),
713
799
  ...wrap(say, inner, 2).map(box),
@@ -725,15 +811,20 @@ function windowWords(ms) {
725
811
  }
726
812
  /**
727
813
  * The brief as Markdown limited to what the Codex terminal draws: bold, emoji, lists, a table and a fenced box.
728
- * Never `#` headings or `>` quotes, which it prints as raw marks. A headline, live session cards (waiting or
729
- * running) grouped by worktree with each worktree's roadmap (done ✓ with its date, now ▶, later ○), one table
814
+ * Never `#` headings or `>` quotes, which it prints as raw marks. A three-line opener, a card for every session
815
+ * that has not ended, grouped by worktree with each worktree's roadmap (done ✓ with its date, now ▶, later ○), one table
730
816
  * row for every ended session, and the one recommended next step in a box. A progress gauge appears only when
731
817
  * both counts are real; otherwise the known facts are written out in words.
732
818
  */
733
819
  export function renderBrief(result, width = 96) {
734
820
  const now = Date.parse(result.generatedAt);
735
- const lines = [`**🧭 ${rich(briefHeadline(result))}**`];
736
- lines.push(`*last ${windowWords(result.scope.sinceMs)} · ${plural(Math.max(1, result.scope.worktrees), "worktree")}*`);
821
+ const opener = openerOf(result);
822
+ const lines = [
823
+ `**✅ Done so far:** ${rich(opener.done)} `,
824
+ `**▶ Doing now:** ${rich(opener.doing)} `,
825
+ `**⏭ Next:** ${rich(opener.next)}`,
826
+ ];
827
+ lines.push(`*last ${windowWords(result.scope.sinceMs)} · ${plural(result.sessions.length, "session")} · ${plural(Math.max(1, result.scope.worktrees), "worktree")}*`);
737
828
  if (result.sessions.length === 0)
738
829
  lines.push("", "No Codex session records in range.");
739
830
  const live = result.sessions.filter((session) => session.status !== "ended");
@@ -767,6 +858,9 @@ export function renderBrief(result, width = 96) {
767
858
  .map(([name]) => name);
768
859
  if (unknown.length > 0)
769
860
  lines.push("", `*not readable: ${unknown.join(", ")}*`);
861
+ const skipped = result.worktrees.reduce((sum, tree) => sum + tree.skippedPlans, 0);
862
+ if (skipped > 0)
863
+ lines.push("", `*${skipped === 1 ? "1 plan" : `${skipped} plans`} too large to read, left out*`);
770
864
  if (result.budget.exhausted)
771
865
  lines.push("", "*older sessions were not read (read budget spent)*");
772
866
  return cleanLines(lines.join("\n"));
@@ -74,7 +74,7 @@ const LIT_PLAN = [
74
74
  "- Explore before asking: ground yourself with read-only tools first and ask only what exploration cannot resolve.",
75
75
  "- Surface, then ask: present what you found, the genuine ambiguities (each with a recommended option) and the approach you intend to plan.",
76
76
  "- Wait for the user's explicit okay before generating the plan. Never auto-transition from interview to plan generation: no plan file, gap analysis or execution before approval.",
77
- '- Drafts go under `.litcodex/drafts/*.md`. Never edit source or lifecycle authority state. Asked to "just do it", decline; after approval, hand the published plan to `lit start work <plan-name>`.',
77
+ '- Drafts go under `.litcodex/drafts/*.md`. Never edit source or lifecycle authority state. Asked to "just do it", decline; after approval, hand the published plan to `lit start work <plan-name>`, and close by telling the user to type `go` within 30 minutes to start it.',
78
78
  "",
79
79
  "Required first steps: in the skill's `references/full-workflow.md`, read Phase 0 - Classify, Phase 1 - Ground, Phase 2 - Interview and the Approval gate; then open exactly one of `references/intent-clear.md` or `references/intent-unclear.md`.",
80
80
  "Native Codex Plan Mode is a host UI mode, not a hook-controlled setting. Inside it, stay read-only and return `<proposed_plan>...</proposed_plan>`; LitCodex cannot switch modes for the user (Shift+Tab can).",
@@ -0,0 +1,16 @@
1
+ export declare const LIVENESS_DIR = ".litcodex/liveness";
2
+ export declare const LIVENESS_THROTTLE_MS = 30000;
3
+ export declare const LIVENESS_ENDED_MS: number;
4
+ export type LivenessState = "alive" | "idle" | "ended";
5
+ export interface LivenessRecord {
6
+ readonly sessionId: string;
7
+ readonly state: LivenessState;
8
+ readonly at: number;
9
+ readonly herdrPane: string | null;
10
+ }
11
+ /** Note that `sessionId` is `alive` or `idle` now. Never throws; a failed write only leaves the old record. */
12
+ export declare function recordLiveness(repoRoot: string, sessionId: string, state: "alive" | "idle", env: NodeJS.ProcessEnv, now?: number): void;
13
+ /** This session's record with `ended` derived from its age, or null when there is none. */
14
+ export declare function readLiveness(repoRoot: string, sessionId: string, now?: number): LivenessRecord | null;
15
+ /** Every session's record in this workspace (at most 64), `ended` derived from age. */
16
+ export declare function readSessionsLiveness(repoRoot: string, now?: number): LivenessRecord[];
@@ -0,0 +1,90 @@
1
+ // src/session-liveness.ts — whether each LIT session in a workspace is working, waiting or gone.
2
+ //
3
+ // One small record per session, `.litcodex/liveness/<session>.json`: `alive` from the PostToolUse live hook,
4
+ // `idle` from Stop once the turn has closed. Codex fires no hook when a session ends, so `ended` is never
5
+ // written; a reader derives it from a record left untouched for 15 minutes. A repeat of the same state within
6
+ // 30 seconds writes nothing, so a busy turn costs one write per half minute. The herdr pane id is kept only when
7
+ // `HERDR_PANE_ID` is a short plain token. Writes are atomic, refuse a symlinked folder and never throw.
8
+ import { lstatSync, mkdirSync, readdirSync } from "node:fs";
9
+ import { isAbsolute, join } from "node:path";
10
+ import { plainDirs, plainDirsOrMissing, readSmallJson, writeFileAtomic } from "./live-step.js";
11
+ import { normalizeSessionId } from "./state-paths.js";
12
+ export const LIVENESS_DIR = ".litcodex/liveness";
13
+ export const LIVENESS_THROTTLE_MS = 30_000;
14
+ export const LIVENESS_ENDED_MS = 15 * 60_000;
15
+ const PANE_ID = /^[A-Za-z0-9:_-]{1,32}$/u;
16
+ const MAX_RECORDS = 64;
17
+ function recordPath(repoRoot, sessionId) {
18
+ const id = normalizeSessionId(sessionId);
19
+ if (id === null || typeof repoRoot !== "string" || !isAbsolute(repoRoot))
20
+ return null;
21
+ return join(repoRoot, LIVENESS_DIR, `${id}.json`);
22
+ }
23
+ function parse(value, now) {
24
+ if (typeof value !== "object" || value === null || Array.isArray(value))
25
+ return null;
26
+ const record = value;
27
+ const { sessionId, state, at, herdrPane } = record;
28
+ if (record["version"] !== 1 || typeof sessionId !== "string" || typeof at !== "number" || !Number.isFinite(at))
29
+ return null;
30
+ if (state !== "alive" && state !== "idle")
31
+ return null;
32
+ return {
33
+ sessionId,
34
+ state: now - at > LIVENESS_ENDED_MS ? "ended" : state,
35
+ at,
36
+ herdrPane: typeof herdrPane === "string" && PANE_ID.test(herdrPane) ? herdrPane : null,
37
+ };
38
+ }
39
+ /** Note that `sessionId` is `alive` or `idle` now. Never throws; a failed write only leaves the old record. */
40
+ export function recordLiveness(repoRoot, sessionId, state, env, now = Date.now()) {
41
+ const path = recordPath(repoRoot, sessionId);
42
+ if (path === null)
43
+ return;
44
+ try {
45
+ if (!plainDirsOrMissing(repoRoot, LIVENESS_DIR))
46
+ return;
47
+ const last = parse(readSmallJson(path), now);
48
+ if (last !== null && last.state === state && now - last.at >= 0 && now - last.at < LIVENESS_THROTTLE_MS)
49
+ return;
50
+ const pane = env["HERDR_PANE_ID"];
51
+ mkdirSync(join(repoRoot, LIVENESS_DIR), { recursive: true });
52
+ const herdrPane = typeof pane === "string" && PANE_ID.test(pane) ? pane : null;
53
+ writeFileAtomic(path, `${JSON.stringify({ version: 1, sessionId, state, at: now, herdrPane })}\n`);
54
+ }
55
+ catch {
56
+ // Liveness is a hint for other sessions' views; the hook's own answer never depends on it.
57
+ }
58
+ }
59
+ /** This session's record with `ended` derived from its age, or null when there is none. */
60
+ export function readLiveness(repoRoot, sessionId, now = Date.now()) {
61
+ const path = recordPath(repoRoot, sessionId);
62
+ if (path === null || !plainDirs(repoRoot, LIVENESS_DIR))
63
+ return null;
64
+ return parse(readSmallJson(path), now);
65
+ }
66
+ /** Every session's record in this workspace (at most 64), `ended` derived from age. */
67
+ export function readSessionsLiveness(repoRoot, now = Date.now()) {
68
+ if (typeof repoRoot !== "string" || !isAbsolute(repoRoot) || !plainDirs(repoRoot, LIVENESS_DIR))
69
+ return [];
70
+ const dir = join(repoRoot, LIVENESS_DIR);
71
+ let names;
72
+ try {
73
+ if (!lstatSync(dir).isDirectory())
74
+ return [];
75
+ names = readdirSync(dir)
76
+ .filter((name) => name.endsWith(".json"))
77
+ .sort()
78
+ .slice(0, MAX_RECORDS);
79
+ }
80
+ catch {
81
+ return [];
82
+ }
83
+ const out = [];
84
+ for (const name of names) {
85
+ const record = parse(readSmallJson(join(dir, name)), now);
86
+ if (record !== null)
87
+ out.push(record);
88
+ }
89
+ return out;
90
+ }
@@ -1,7 +1,8 @@
1
1
  // src/threads.ts — the threads of a session as the card and the text HUD draw them.
2
2
  //
3
3
  // A thread is a frame of the session's workflow stack, a child agent (lane) running under its top frame, or
4
- // the top frame of another session of the same project that moved lately. Each takes its `k/n` from the
4
+ // the top frame of another session of the same project that moved lately or whose liveness record is fresh
5
+ // (running first, then idle; named `<skill> · <pane>` when herdr gave a pane). Each takes its `k/n` from the
5
6
  // first source that really knows it: the count the frame recorded, the start-work run it drives, the
6
7
  // checkboxes of the plan it works from, the open goal's criteria, the main thread's own `update_plan` list
7
8
  // (top frame only), and for a lane its own `update_plan`. A gauge is drawn only when both numbers are real;
@@ -95,8 +96,12 @@ export function readThreads(cwd, sessionId, now, signals) {
95
96
  const laneRows = lanes.map((lane) => laneRow(lane, now));
96
97
  const otherRows = others.map((other) => {
97
98
  const top = other.frames.at(-1);
99
+ const row = frameRow(top, `session-${other.id.slice(0, SHORT_SESSION)}`, frameCounts(top, cwd, null, null), false, false);
98
100
  return {
99
- ...frameRow(top, `session-${other.id.slice(0, SHORT_SESSION)}`, frameCounts(top, cwd, null, null), false, false),
101
+ ...row,
102
+ // A session whose turn has closed waits for its person, so it reads idle rather than running.
103
+ ...(other.liveness === "idle" && row.state === "running" ? { state: "idle" } : {}),
104
+ ...(other.pane === null ? {} : { name: `${row.name} · ${other.pane}` }),
100
105
  kind: "session",
101
106
  session: other.id.slice(0, SHORT_SESSION),
102
107
  };
@@ -98,15 +98,22 @@ export declare function recordStackEvent(cwd: string, sessionId: string, event:
98
98
  };
99
99
  /** Another session of the project counts as live while its stack was written this recently. */
100
100
  export declare const OTHER_SESSION_MS: number;
101
+ /** A finished start-work run stays on other sessions' views this long, then leaves. */
102
+ export declare const FINISHED_WORK_MS = 60000;
101
103
  export interface OtherStack {
102
104
  readonly id: string;
103
105
  readonly frames: readonly StackFrame[];
104
106
  /** The newest time any of its frames moved. */
105
107
  readonly at: number;
108
+ /** What the session's liveness record says now (`ended` records are left out), or null without one. */
109
+ readonly liveness: "alive" | "idle" | null;
110
+ readonly pane: string | null;
106
111
  }
107
112
  /**
108
- * The stacks of the project's other sessions that moved within OTHER_SESSION_MS, newest first. It only
109
- * reads: a link, an oversized or malformed file reads as empty, and an older session is simply dropped.
113
+ * The stacks of the project's other sessions that moved within OTHER_SESSION_MS, or whose liveness record is
114
+ * still fresh, running first, then idle, then the rest, newest first within each. A start-work run that
115
+ * finished leaves after FINISHED_WORK_MS. It only reads: a link, an oversized or malformed file reads as
116
+ * empty, and an older session is simply dropped.
110
117
  */
111
118
  export declare function readOtherStacks(cwd: string, selfId: string, now?: number): OtherStack[];
112
119
  /** The frame a bare `lit continue` should resume: the nearest spine below a side frame, else null. */