@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
@@ -0,0 +1,76 @@
1
+ // src/plan-scope-roots.ts — the advisory `Scope roots:` check for a saved lit-plan.
2
+ //
3
+ // start-work later grants only the project and the roots a plan declares on its own column-zero lines,
4
+ // `Scope roots: <path> (<actions>)`. A todo that names an absolute path outside the project without such a
5
+ // line pauses the run at its first touch of that path, so the Stop gate points it out once while the planner
6
+ // can still add the line. Only todo rows and their indented continuation count; fenced code and inline code
7
+ // that holds a command are examples, not targets. `/` and the bare home folder never cover anything.
8
+ import { posix } from "node:path";
9
+ const FENCE = /^\s*(?:```|~~~)/u;
10
+ const TODO_ROW = /^- \[[ xX]\] /u;
11
+ const SCOPE_LINE = /^Scope roots:\s+(\S+)\s+\([^)]*\)\s*$/u;
12
+ const PATH = /(?<![\w:/.~-])(~?\/[A-Za-z0-9._~@%+/-]+)/gu;
13
+ const TRAILING = /[.,;:]+$/u;
14
+ function expand(path, home) {
15
+ return posix.normalize(path.startsWith("~/") ? `${home}${path.slice(1)}` : path).replace(/(.)\/$/u, "$1");
16
+ }
17
+ /** Plan text names POSIX paths whatever the host, so the comparison stays POSIX too. */
18
+ function inside(path, dir) {
19
+ const rel = posix.relative(dir, path);
20
+ return rel === "" || (!rel.startsWith("..") && !posix.isAbsolute(rel));
21
+ }
22
+ /** Inline code that is a bare path stays as the path; one that holds a command is dropped. */
23
+ function withoutCommands(line) {
24
+ return line.replace(/`([^`]*)`/gu, (_whole, body) => (/\s/u.test(body.trim()) ? " " : ` ${body} `));
25
+ }
26
+ /** Lines outside fenced code, each tagged with whether it belongs to a todo row. */
27
+ function proseLines(text) {
28
+ const out = [];
29
+ let fenced = false;
30
+ let todo = false;
31
+ for (const line of text.split(/\r?\n/u)) {
32
+ if (FENCE.test(line)) {
33
+ fenced = !fenced;
34
+ continue;
35
+ }
36
+ if (fenced)
37
+ continue;
38
+ if (TODO_ROW.test(line))
39
+ todo = true;
40
+ else if (line.trim() !== "" && !/^\s/u.test(line))
41
+ todo = false;
42
+ out.push({ line, todo });
43
+ }
44
+ return out;
45
+ }
46
+ /**
47
+ * Absolute paths the plan's todos name outside `projectRoot` that no `Scope roots:` line covers, in order of
48
+ * first mention. Empty when the plan is covered.
49
+ */
50
+ export function scopeRootGaps(text, projectRoot, home) {
51
+ const lines = proseLines(text);
52
+ const homeDir = expand(home, home);
53
+ const roots = lines
54
+ .map(({ line }) => SCOPE_LINE.exec(line)?.[1])
55
+ .filter((root) => root !== undefined)
56
+ .map((root) => expand(root, home))
57
+ .filter((root) => root !== "/" && root !== homeDir);
58
+ const gaps = [];
59
+ for (const { line, todo } of lines) {
60
+ if (!todo)
61
+ continue;
62
+ for (const match of withoutCommands(line).matchAll(PATH)) {
63
+ const path = expand((match[1] ?? "").replace(TRAILING, ""), home);
64
+ if (path.length < 2 || inside(path, projectRoot))
65
+ continue;
66
+ if (roots.some((root) => inside(path, root)) || gaps.includes(path))
67
+ continue;
68
+ gaps.push(path);
69
+ }
70
+ }
71
+ return gaps;
72
+ }
73
+ /** The line a planner pastes to declare `path`; read access is the default to widen deliberately. */
74
+ export function scopeRootLine(path) {
75
+ return `Scope roots: ${path} (read)`;
76
+ }
@@ -0,0 +1,6 @@
1
+ /** The version this process loaded, or null when its manifest cannot be read. */
2
+ export declare function loadedPluginVersion(): string | null;
3
+ /** The version the installer last put in place for the Codex home in `env`, or null. */
4
+ export declare function installedPluginVersion(env: NodeJS.ProcessEnv): string | null;
5
+ /** `restart to <installed>` when `installed` is a newer plain version than `loaded`; null otherwise. */
6
+ export declare function restartChip(loaded: string | null, installed: string | null): string | null;
@@ -0,0 +1,59 @@
1
+ // src/restart-chip.ts — `restart to <v>` when a newer LitCodex is installed than the one running.
2
+ //
3
+ // The running version is this plugin's own `.codex-plugin/plugin.json`, read once when the module loads, so a
4
+ // long-lived card server keeps the version it started with. The installed version is the managed marketplace
5
+ // payload the installer and the auto-updater rewrite (`<CODEX_HOME>/marketplaces/litcodex/...`), the same
6
+ // file `litcodex doctor` reads; the plugin cache is not used because it keeps every past version as history.
7
+ // Versions compare as plain `x.y.z` the way the auto-updater compares them; anything else shows no chip.
8
+ import { readFileSync } from "node:fs";
9
+ import { join } from "node:path";
10
+ import { codexHomeFrom, readSmallJson } from "./live-step.js";
11
+ const MAX_MANIFEST_BYTES = 64 * 1024;
12
+ const STABLE = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)$/u;
13
+ const MANAGED_MANIFEST = "marketplaces/litcodex/plugins/litcodex/.codex-plugin/plugin.json";
14
+ function versionOf(manifest) {
15
+ if (typeof manifest !== "object" || manifest === null || Array.isArray(manifest))
16
+ return null;
17
+ const { name, version } = manifest;
18
+ return name === "litcodex" && typeof version === "string" ? version : null;
19
+ }
20
+ const LOADED = (() => {
21
+ try {
22
+ const text = readFileSync(new URL("../../../.codex-plugin/plugin.json", import.meta.url), "utf8");
23
+ return text.length > MAX_MANIFEST_BYTES ? null : versionOf(JSON.parse(text));
24
+ }
25
+ catch {
26
+ return null;
27
+ }
28
+ })();
29
+ /** The version this process loaded, or null when its manifest cannot be read. */
30
+ export function loadedPluginVersion() {
31
+ return LOADED;
32
+ }
33
+ /** The version the installer last put in place for the Codex home in `env`, or null. */
34
+ export function installedPluginVersion(env) {
35
+ const home = codexHomeFrom(env);
36
+ return home === null ? null : versionOf(readSmallJson(join(home, MANAGED_MANIFEST), MAX_MANIFEST_BYTES));
37
+ }
38
+ function parts(version) {
39
+ const match = version === null ? null : STABLE.exec(version);
40
+ if (match?.[1] === undefined || match[2] === undefined || match[3] === undefined)
41
+ return null;
42
+ return [BigInt(match[1]), BigInt(match[2]), BigInt(match[3])];
43
+ }
44
+ /** `restart to <installed>` when `installed` is a newer plain version than `loaded`; null otherwise. */
45
+ export function restartChip(loaded, installed) {
46
+ const a = parts(loaded);
47
+ const b = parts(installed);
48
+ if (a === null || b === null)
49
+ return null;
50
+ for (let index = 0; index < 3; index += 1) {
51
+ const left = a[index];
52
+ const right = b[index];
53
+ if (right > left)
54
+ return `restart to ${installed}`;
55
+ if (right < left)
56
+ return null;
57
+ }
58
+ return null;
59
+ }
@@ -10,7 +10,7 @@ import { rmSync } from "node:fs";
10
10
  import { isAbsolute, join } from "node:path";
11
11
  import { clean } from "./control-chars.js";
12
12
  import { plainDirsOrMissing, readSmallJson } from "./live-step.js";
13
- import { ADHD_DIR, chooseNext, GO_WINDOW_MS } from "./rewind.js";
13
+ import { ADHD_DIR, chooseNext, GO_WINDOW_MS, openPlanNamed } from "./rewind.js";
14
14
  import { normalizeSessionId } from "./state-paths.js";
15
15
  const GO_PROMPT = /^\s*(?:(?:lit\s+)?go|ㄱㄱ|고|진행)[\s.!?]*$/iu;
16
16
  const MAX_NOTE_BYTES = 8 * 1024;
@@ -66,6 +66,16 @@ export function takeGo(cwd, sessionId, now) {
66
66
  if (note.kind === "approve-boundary")
67
67
  return { kind: "hint", text: BOUNDARY };
68
68
  const fresh = chooseNext(cwd, sessionId);
69
+ // A note naming its plan (a saved lit-plan, or a brief) holds while that plan is open and nothing outranks it,
70
+ // even when a second open plan means the brief alone would name none.
71
+ const named = note.kind === "start-plan" && note.plan !== null ? openPlanNamed(cwd, note.plan) : null;
72
+ if (named !== null && (fresh.kind === "none" || fresh.kind === "handoff" || fresh.kind === "start-plan")) {
73
+ return {
74
+ kind: "run",
75
+ prompt: `start-work ${named.name.replace(/\.md$/u, "")}`,
76
+ note: `go: start work on ${named.name}, ${named.done} of ${named.total} tasks done`,
77
+ };
78
+ }
69
79
  if (fresh.kind !== note.kind || (note.kind === "start-plan" && fresh.plan !== note.plan)) {
70
80
  return { kind: "hint", text: STALE };
71
81
  }
@@ -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[];