@litfamily/litcodex 1.0.31 → 1.0.33

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
@@ -15,6 +15,7 @@
15
15
  import { closeSync, fstatSync, lstatSync, mkdirSync, readdirSync, readSync } from "node:fs";
16
16
  import { isAbsolute, join } from "node:path";
17
17
  import { openRegularFile, plainDirs, plainDirsOrMissing, writeFileAtomic } from "./live-step.js";
18
+ import { readSessionsLiveness } from "./session-liveness.js";
18
19
  import { normalizeSessionId } from "./state-paths.js";
19
20
  export const STACK_DIR = ".litcodex/workflow-stack";
20
21
  export const MAX_FRAMES = 3;
@@ -400,15 +401,31 @@ export function recordStackEvent(cwd, sessionId, event, now = new Date()) {
400
401
  export const OTHER_SESSION_MS = 15 * 60 * 1000;
401
402
  const MAX_OTHER_SESSIONS = 6;
402
403
  const MAX_OTHER_FILES = 24;
404
+ /** A finished start-work run stays on other sessions' views this long, then leaves. */
405
+ export const FINISHED_WORK_MS = 60_000;
406
+ /** Running first, then idle, then the rest (paused, done, or silent). */
407
+ function otherRank(other) {
408
+ const top = other.frames.at(-1);
409
+ if (other.liveness === "idle")
410
+ return 1;
411
+ if (top?.done === true || top?.status === "paused")
412
+ return 2;
413
+ return other.liveness === "alive" || other.liveness === null ? 0 : 2;
414
+ }
403
415
  /**
404
- * The stacks of the project's other sessions that moved within OTHER_SESSION_MS, newest first. It only
405
- * reads: a link, an oversized or malformed file reads as empty, and an older session is simply dropped.
416
+ * The stacks of the project's other sessions that moved within OTHER_SESSION_MS, or whose liveness record is
417
+ * still fresh, running first, then idle, then the rest, newest first within each. A start-work run that
418
+ * finished leaves after FINISHED_WORK_MS. It only reads: a link, an oversized or malformed file reads as
419
+ * empty, and an older session is simply dropped.
406
420
  */
407
421
  export function readOtherStacks(cwd, selfId, now = Date.now()) {
408
422
  try {
409
423
  const own = normalizeSessionId(selfId);
410
424
  if (!isAbsolute(cwd) || !plainDirs(cwd, STACK_DIR))
411
425
  return [];
426
+ const lives = new Map(readSessionsLiveness(cwd, now)
427
+ .filter((record) => record.state !== "ended")
428
+ .map((record) => [normalizeSessionId(record.sessionId), record]));
412
429
  const found = [];
413
430
  const names = readdirSync(join(cwd, STACK_DIR))
414
431
  .filter((name) => name.endsWith(".json"))
@@ -420,10 +437,23 @@ export function readOtherStacks(cwd, selfId, now = Date.now()) {
420
437
  continue;
421
438
  const frames = readStack(cwd, id).frames;
422
439
  const at = Math.max(0, ...frames.map((frame) => Date.parse(frame.at)));
423
- if (frames.length > 0 && now - at <= OTHER_SESSION_MS)
424
- found.push({ id, frames, at });
440
+ const live = lives.get(id);
441
+ const top = frames.at(-1);
442
+ if (top === undefined || (now - at > OTHER_SESSION_MS && live === undefined))
443
+ continue;
444
+ if (top.skill === "start-work" && top.done === true && now - at > FINISHED_WORK_MS)
445
+ continue;
446
+ found.push({
447
+ id,
448
+ frames,
449
+ at: Math.max(at, live?.at ?? 0),
450
+ liveness: live === undefined ? null : live.state,
451
+ pane: live?.herdrPane ?? null,
452
+ });
425
453
  }
426
- return found.sort((a, b) => b.at - a.at || a.id.localeCompare(b.id)).slice(0, MAX_OTHER_SESSIONS);
454
+ return found
455
+ .sort((a, b) => otherRank(a) - otherRank(b) || b.at - a.at || a.id.localeCompare(b.id))
456
+ .slice(0, MAX_OTHER_SESSIONS);
427
457
  }
428
458
  catch {
429
459
  return [];
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@litcodex/lit-loop",
3
- "version": "1.0.31",
3
+ "version": "1.0.33",
4
4
  "description": "LitCodex Lit-Loop runtime: durable repo-native multi-goal orchestration with embedded success criteria and observable evidence audit.",
5
5
  "type": "module",
6
6
  "private": true,
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@litcodex/lsp",
3
- "version": "1.0.31",
3
+ "version": "1.0.33",
4
4
  "description": "LitCodex LSP hook (inert placeholder): post-edit diagnostics + cache reset, no-op until an LSP daemon is provided.",
5
5
  "type": "module",
6
6
  "private": true,
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@litcodex/rules",
3
- "version": "1.0.31",
3
+ "version": "1.0.33",
4
4
  "description": "LitCodex rules: injects project rule files (AGENTS.md etc.) into model context through lifecycle hooks.",
5
5
  "type": "module",
6
6
  "private": true,
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@litcodex/start-work-continuation",
3
- "version": "1.0.31",
3
+ "version": "1.0.33",
4
4
  "description": "LitCodex Start-Work continuation hook: resumes in-flight start-work state on root Stop.",
5
5
  "type": "module",
6
6
  "private": true,
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@litcodex/telemetry",
3
- "version": "1.0.31",
3
+ "version": "1.0.33",
4
4
  "description": "LitCodex telemetry: a deliberately inert, local-only SessionStart hook (NO network, NO data collection).",
5
5
  "type": "module",
6
6
  "private": true,
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@litcodex/wikify-knowledge",
3
- "version": "1.0.31",
3
+ "version": "1.0.33",
4
4
  "description": "Local review-gated knowledge records for the LitCodex Wikify surface.",
5
5
  "type": "module",
6
6
  "private": true,
@@ -80,19 +80,19 @@ verdicts: [PASS, FAIL, BLOCKED]
80
80
  "collector": "components/lit-loop/dist/cli.js rewind --json",
81
81
  "next_note": ".litcodex/adhd/next-<session>.json",
82
82
  "go_window_minutes": 30,
83
- "statuses": ["waiting-on-user", "active", "ended", "unknown"],
84
- "next_kinds": ["resume-frame", "approve-boundary", "continue-work", "start-plan", "none"],
83
+ "statuses": ["waiting-on-user", "active", "idle", "done", "ended", "unknown"],
84
+ "next_kinds": ["resume-frame", "approve-boundary", "continue-work", "start-plan", "handoff", "none"],
85
85
  "verdicts": ["PASS", "FAIL", "BLOCKED"]
86
86
  }
87
87
  ```
88
88
 
89
- The brief is read in ten seconds, so it has this shape, in this order. The collector's `brief` field is a finished Markdown draft of it (bold lines, a list-item card per session, a table, a boxed step); keep its structure and wording, translate it into the user's language, and add nothing it does not support. The Codex terminal draws `#` heading marks and `>` quote marks literally, so the draft uses neither: no line starts with `#` or `>`, and you add none. It draws bold, lists, inline code, tables and fenced boxes properly, in colour: the headline, the badges and the boxed step are what a tired reader's eye lands on.
89
+ The brief is read in ten seconds, so it has this shape, in this order. The collector's `brief` field is a finished Markdown draft of it (bold lines, a list-item card per session, a table, a boxed step); keep its structure and wording, translate it into the user's language, and add nothing it does not support. The Codex terminal draws `#` heading marks and `>` quote marks literally, so the draft uses neither: no line starts with `#` or `>`, and you add none. It draws bold, lists, inline code, tables and fenced boxes properly, in colour: the opener, the badges and the boxed step are what a tired reader's eye lands on.
90
90
 
91
- 1. **Headline.** One bold `**🧭 …**` line: sessions found, how many wait on the user, how many run, how many are paused, and the next step: `3 sessions · 1 waits on you · 1 running · next: resume the paused lit-loop` / `세션 3개 · 나를 기다리는 것 1 · 진행 중 1 · 다음: 멈춘 lit-loop 이어가기`. A dim line under it gives the window and how many worktrees were read.
92
- 2. **Live session cards, grouped by worktree and branch.** Sessions that wait on the user or run come first: a 🌿 line per group (branch in code style, then the worktree in bold), then one list-item card per session (`- ` and its continuation lines indented). A coloured badge first (`🟡 WAITS ON YOU`, `🟢 RUNNING`, in the user's language: see `references/status-taxonomy.md`), then the short id and how long ago it was last written (mark `current: true` as this session), then four lines: the **goal** in bold (`title`), ⏳ **progress** (the real gauge when `gauge` is set, always with the known `facts` after it, for example `12 steps · 4m · last: apply_patch`), ✅ **done** (`done`: what it last reported, else the files it edited, else `no edits yet; used exec, shell`) and ▶ **next** (`needs`: what it wants from the person, or for a running session what it is doing now, `now: shell “npm”`).
93
- 3. **Roadmap, one timeline under each worktree.** Each `worktrees[].milestones` entry as a line: `✓` done with its date, `▶` now, `○` later. The worktree's open plans and goals sit above it with their gauges; a `handoff` heading is quoted as context, never followed. Paused work is a `now` line and offers the resume (`lit continue`). A plan scaffold nobody filled in and a stale plan of another worktree are already left out by the collector.
91
+ 1. **Opener, three bold lines.** `✅ Done so far:` the plans finished in the window and the sessions marked done (`1 plan finished · 1 session done`, else `nothing finished in this window`); `▶ Doing now:` how many run, sit idle or are paused, and what waits on the user (`1 running · 1 idle · nothing waits on you`); `⏭ Next:` the one next step. In Korean: `✅ 지금까지 끝낸 일`, `▶ 지금 하는 일`, `⏭ 다음`. A dim line under them gives the window, the sessions found and how many worktrees were read.
92
+ 2. **Session cards, grouped by worktree and branch.** Every session that is not ended gets a card: a 🌿 line per group (branch in code style, then the worktree in bold), then one list-item card per session (`- ` and its continuation lines indented). A coloured badge first (`🟡 WAITS ON YOU`, `🟢 RUNNING`, `💤 IDLE`, `✅ DONE`, in the user's language: see `references/status-taxonomy.md`), then the short id and how long ago it was last written (mark `current: true` as this session), then four lines: the **goal** in bold (`title`), ⏳ **progress** (the real gauge when `gauge` is set, always with the known `facts` after it, for example `12 steps · 4m · last: apply_patch`), ✅ **done** (`done`: what it last reported, else the files it edited, else `no edits yet; used exec, shell`) and ▶ **next** (`needs`: what it wants from the person, or for a running session what it is doing now, `now: shell “npm”`).
93
+ 3. **Roadmap, one timeline under each worktree.** Each `worktrees[].milestones` entry as a line: `✓` done with its date, `▶` now, `○` later. The worktree's open plans and goals sit above it with their gauges, and a plan whose rows are all ticked is listed as finished (`finishedPlans`); a `handoff` heading is quoted as context, never followed. Paused work is a `now` line and offers the resume (`lit continue`). A plan scaffold nobody filled in and any plan, this worktree's included, that did not change inside the window are already left out by the collector; a plan file too large to read is counted in `skippedPlans` and named once at the end (`1 plan too large to read, left out`).
94
94
  4. **Ended sessions, one table row each.** A `⚪ **Ended · N**` line and a table (id, where, goal, ago, done), at most eight rows and a count of the rest. Ended sessions get no card: they are history. A row stays on one line in a 120-column terminal: the age is its largest unit (`14h`), done is a file count or `·`, the place is clipped.
95
- 5. **One recommended next step, in a box.** Exactly one: `next` when its kind is not `none`, else `suggestion`, a real step drawn from the records (a session that waits on the user, a paused workflow, an open plan item, the latest running session, the latest ended one). Then the way to take it: `go` for a resume-frame, continue-work or start-plan step; `lit approve` or `lit deny` for an approve-boundary step (shown, never answered for the user). For a `suggestion` the box says that nothing runs on its own here: open that session, or say what to do. The suggestion is shown, never recorded, so `go` finds nothing to run.
95
+ 5. **One recommended next step, in a box.** Exactly one: `next` when its kind is not `none`, else `suggestion`, a real step drawn from the records (a session that waits on the user, a done session to review, a paused workflow, an open plan item, the latest running or idle session, the latest ended one). A step already done is never offered again: a done session is reviewed, not picked up. Then the way to take it: `go` for a resume-frame, continue-work or start-plan step; `lit approve` or `lit deny` for an approve-boundary step (shown, never answered for the user); for a `handoff` step, which comes from this worktree's HANDOFF note, the box says `go` does not run it. For a `suggestion` the box says that nothing runs on its own here: open that session, or say what to do. The suggestion is shown, never recorded, so `go` finds nothing to run. The box sits in a plain fence with no language tag, so the terminal draws it as it is.
96
96
 
97
97
  **Progress gauges, required.** A gauge `[▉▉▉░░] 3/5` appears only when both numbers are real and are copied verbatim from the collector (filled `▉` done, light `░` remaining, then done/total; at most ten cells, scaled when the total is larger). When the total is unknown, no gauge is drawn and no placeholder stands in for one: write what is known in words (`12 steps · 4m · last: apply_patch`, `step 2`, `running 4m`). Never a guess, never an estimate, never a gauge of your own, and never a run of question marks in place of a number.
98
98
 
@@ -130,11 +130,12 @@ The collector (`dist/cli.js rewind` in the lit-loop component) reads, for the cu
130
130
  | Source | What it gives | Missing reads |
131
131
  | --- | --- | --- |
132
132
  | Codex session records, the rollout `.jsonl` files under the `sessions` folder of the Codex home | per session: id, folder, first ask (`title`), last ask, last assistant text, status, the tools it used most, the files it patched and what its last call was about (a program or file base name, never a command line) | `sessions: unknown` |
133
- | `.litcodex/plans/*.md` checkbox rows | open plans and done/total | none; absent means no open plan |
133
+ | `.litcodex/plans/*.md` checkbox rows | open and finished plans with done/total, held to the window; oversized files counted | none; absent means no plan |
134
+ | `.litcodex/liveness/*.json` | whether a session's turn has closed (`idle`), written by the PostToolUse and Stop hooks | none; absent means the age alone decides |
134
135
  | `.litcodex/start-work/state.json` | the active or paused start-work, its plan progress, a boundary waiting for an answer | none |
135
136
  | `.litcodex/lit-loop/goals.json` | lit-loop goals, done/total | none |
136
137
  | `.litcodex/workflow-stack/*.json` | running and paused disciplines with stage and k/n | none |
137
- | `HANDOFF*.md` | the first heading only | none |
138
+ | `HANDOFF*.md` | the first heading, and the first unticked item under `## Next` as the last-resort next step | none |
138
139
  | `git worktree list`, `git log -1` | worktrees, branches, the last commit subject | `git: unknown` |
139
140
 
140
141
  Session records are read head (256 KiB, enough for the meta line and the first ask) and tail (256 KiB, the latest turn) only, under one 8 MiB budget for the whole run, through descriptors opened without following links; a linked file or folder, a named pipe and a subagent's records are skipped. The format is private to Codex, so every field is read tolerantly and a record that does not parse becomes `unknown`. Every string is redacted before it leaves the collector: credential shapes, `NAME=value` with a secret-like name, URI userinfo, any current environment value of eight or more characters, and the home directory (shown as `~`).
@@ -142,6 +143,8 @@ Session records are read head (256 KiB, enough for the meta line and the first a
142
143
  ## Status taxonomy
143
144
 
144
145
  - `waiting-on-user`: the session's last word was the assistant finishing a turn that asks the person something (a closing question, or a request to approve, confirm or deny), and it has been quiet for more than 15 minutes.
146
+ - `done`: the session finished what it ran: its top workflow frame is a closed start-work, or the plan it carries has every row ticked. This outranks every other status.
147
+ - `idle`: its liveness record says the turn closed and it asks nothing; it waits for the person's next message. This outranks the age-based `active`.
145
148
  - `active`: written to within the last 15 minutes.
146
149
  - `ended`: quiet for longer than that and asking nothing: a finished turn without a question, or an interrupted or closed session. Ended sessions are folded into one table.
147
150
  - `unknown`: the record held no timestamp or event the collector understands.
@@ -154,11 +157,12 @@ Session records are read head (256 KiB, enough for the meta line and the first a
154
157
  2. A start-work paused at a boundary: show what it wants. Say `lit approve` or `lit deny`. This is never automatic and `go` does not answer it.
155
158
  3. This session's active start-work or open lit-loop goals: keep going. Say `go`.
156
159
  4. Exactly one open plan in this folder and no work running: start it. Say `go`, which runs `start-work <plan>` for that plan.
157
- 5. Otherwise `none`: the brief still recommends a `suggestion` drawn from the records, and says nothing runs on its own.
160
+ 5. No open plan, and this folder's HANDOFF note has an unticked item under `## Next`: show it as a `handoff` step. It is never written for `go`.
161
+ 6. Otherwise `none`: the brief still recommends a `suggestion` drawn from the records, and says nothing runs on its own.
158
162
 
159
163
  ## Continuing with go
160
164
 
161
- After a brief, the user's `go` (also `lit go`, `ㄱㄱ`, `고`, `진행`, as the whole prompt) continues the step the brief offered, in the same session, within 30 minutes. The hook reads the next-step note the collector wrote for this session, deletes it, checks the step against the saved state once more, and then routes the matching ordinary prompt: a paused frame resumes (`lit continue`), active work continues, a single open plan starts through `start-work <plan>`. A boundary still needs `lit approve`. After 30 minutes, or if the state moved on, nothing starts and the reply says so. Anything else typed after the brief is an ordinary prompt.
165
+ After a brief, the user's `go` (also `lit go`, `ㄱㄱ`, `고`, `진행`, as the whole prompt) continues the step the brief offered, in the same session, within 30 minutes. The hook reads the next-step note the collector wrote for this session, deletes it, checks the step against the saved state once more, and then routes the matching ordinary prompt: a paused frame resumes (`lit continue`), active work continues, a single open plan starts through `start-work <plan>`, and a note that names its plan (a brief's, or the one a saved lit-plan leaves) starts that plan while it is still open, even beside a second open plan. A boundary still needs `lit approve`. After 30 minutes, or if the state moved on, nothing starts and the reply says so. Anything else typed after the brief is an ordinary prompt.
162
166
 
163
167
  ## Relation to lit-recap
164
168
 
@@ -41,8 +41,10 @@ A session with no edit yet shows the tools it used, and a running one shows what
41
41
  ## English
42
42
 
43
43
  ````markdown
44
- **🧭 4 sessions · 1 waits on you · 1 running · 1 paused · next: start work on sync.md, 3 of 5 tasks done**
45
- *last 7d · 1 worktree*
44
+ **✅ Done so far:** nothing finished in this window
45
+ **▶ Doing now:** 1 running · 1 paused · 1 waits on you
46
+ **⏭ Next:** start work on sync.md, 3 of 5 tasks done
47
+ *last 7d · 4 sessions · 1 worktree*
46
48
 
47
49
  🌿 `feat/retry` · **sync-service**
48
50
 
@@ -74,7 +76,7 @@ A session with no edit yet shows the tools it used, and a running one shows what
74
76
  | `40a1c3e5` | sync-service | Split the sync client | 29h | 3 files |
75
77
  | `50a1c3e5` | sync-service | 카드 레이아웃 정리 | 30h | · |
76
78
 
77
- ```text
79
+ ```
78
80
  ╭─ Recommended next step ───────────────────────────────────╮
79
81
  │ start work on sync.md, 3 of 5 tasks done │
80
82
  │ say `go` to run it │
@@ -85,8 +87,10 @@ A session with no edit yet shows the tools it used, and a running one shows what
85
87
  ## 한국어
86
88
 
87
89
  ````markdown
88
- **🧭 세션 4개 · 나를 기다리는 것 1 · 진행 중 1 · 멈춘 작업 1 · 다음: sync.md 작업 시작, 5개 중 3개 완료**
89
- *최근 7d · 작업 트리 1개*
90
+ **✅ 지금까지 끝낸 일:** 이 기간에 끝낸 것 없음
91
+ **▶ 지금 하는 일:** 진행 중 1 · 멈춘 작업 1 · 나를 기다리는 것 1
92
+ **⏭ 다음:** sync.md 작업 시작, 5개 중 3개 완료
93
+ *최근 7d · 세션 4개 · 작업 트리 1개*
90
94
 
91
95
  🌿 `feat/retry` · **sync-service**
92
96
 
@@ -118,7 +122,7 @@ A session with no edit yet shows the tools it used, and a running one shows what
118
122
  | `40a1c3e5` | sync-service | Split the sync client | 29h | 파일 3개 |
119
123
  | `50a1c3e5` | sync-service | 카드 레이아웃 정리 | 30h | · |
120
124
 
121
- ```text
125
+ ```
122
126
  ╭─ 추천하는 다음 단계 ──────────────────────────────────────╮
123
127
  │ sync.md 작업 시작, 5개 중 3개 완료 │
124
128
  │ `go`라고 입력하세요 │
@@ -131,7 +135,7 @@ A session with no edit yet shows the tools it used, and a running one shows what
131
135
  With `next.kind` of `none` the box still recommends a step, the collector's `suggestion`, and says
132
136
  that nothing runs on its own here:
133
137
 
134
- ```text
138
+ ```
135
139
  ╭─ Recommended next step ───────────────────────────────────────╮
136
140
  │ answer 10a1c3e5 in sync-service: “Should the cap be 30s or │
137
141
  │ 60s?” │
@@ -140,6 +144,18 @@ that nothing runs on its own here:
140
144
  ╰───────────────────────────────────────────────────────────────╯
141
145
  ```
142
146
 
147
+ ## After a session finished its plan
148
+
149
+ One session ran `sync.md` to its last row and this session is the one asking. The finished session
150
+ gets a `✅ DONE` card, its plan is counted under "Done so far", and the step is to review it rather
151
+ than to pick it up again:
152
+
153
+ ````markdown
154
+ **✅ Done so far:** 1 plan finished · 1 session done
155
+ **▶ Doing now:** 1 running · nothing waits on you
156
+ **⏭ Next:** review what 10a1c3e5 finished in sync-service: Add retry with backoff to the sync job
157
+ ````
158
+
143
159
  ## What the examples do not do
144
160
 
145
161
  - They do not estimate the sessions' progress: the records hold no total, so each card shows the known facts in words.
@@ -1,19 +1,23 @@
1
1
  # lit-adhd status taxonomy
2
2
 
3
3
  The collector assigns every session exactly one status. The brief renders it in the user's language
4
- with the words below and never invents a fifth.
4
+ with the words below and never invents a seventh.
5
5
 
6
6
  | Status | Set when | English | 한국어 |
7
7
  | --- | --- | --- | --- |
8
+ | `done` | The session finished what it ran: its top workflow frame is a closed start-work, or the plan that frame carries has every row ticked. Outranks every other status | done | 끝냄 |
8
9
  | `waiting-on-user` | The last record is the assistant finishing a turn that asks the person something (a closing question, or a request to approve, confirm or deny), and the session has been quiet for more than 15 minutes | waiting on you | 나를 기다림 |
10
+ | `idle` | Its liveness record (`.litcodex/liveness/<session>.json`, under 15 minutes old) says the turn closed, and it asks nothing | idle | 쉬는 중 |
9
11
  | `active` | A record was written within the last 15 minutes | active | 진행 중 |
10
12
  | `ended` | Quiet for longer than 15 minutes and asking nothing: a finished turn without a question, or an interrupted or closed session | ended | 끝남 |
11
13
  | `unknown` | The record held no timestamp or event the collector understands | unknown | 모름 |
12
14
 
13
15
  A session that holds a paused workflow frame shows it under "Paused work" in the brief; the status
14
- itself stays one of the four above.
16
+ itself stays one of the six above.
15
17
 
16
- Order in the brief: waiting sessions first, then active, newest first inside each group, as list-item cards. Ended sessions are one table row each (eight at most), and unknown ones keep a card.
18
+ Order in the brief: every session that is not ended gets a list-item card, grouped by worktree. Ended
19
+ sessions are one table row each (eight at most), and unknown ones keep a card. The opener counts done
20
+ sessions and finished plans under "Done so far", and running, idle and paused work under "Doing now".
17
21
 
18
22
  ## Sources
19
23
 
@@ -24,7 +28,7 @@ line and never filled in from memory.
24
28
  | --- | --- |
25
29
  | `sessions` | Codex session records under `<codex home>/sessions` |
26
30
  | `git` | `git worktree list` and `git log -1` |
27
- | `state` | `.litcodex/` stack, start-work, plans and goals of each worktree |
31
+ | `state` | `.litcodex/` stack, start-work, plans, goals and liveness records of each worktree |
28
32
 
29
33
  ## Next-step kinds
30
34
 
@@ -34,4 +38,8 @@ line and never filled in from memory.
34
38
  | `approve-boundary` | `lit approve` | start-work waits at a boundary; the user answers it | start-work가 경계 승인을 기다림, 직접 답하기 |
35
39
  | `continue-work` | `go` | keep running the active work | 진행 중인 작업 계속 |
36
40
  | `start-plan` | `go` | start <plan> with start-work | <plan>을 start-work로 시작 |
41
+ | `handoff` | — | the first unticked item under `## Next` in this worktree's HANDOFF note; `go` does not run it | 이 worktree HANDOFF의 `## Next`에서 아직 체크하지 않은 첫 항목, `go`로는 실행되지 않음 |
37
42
  | `none` | — | the brief recommends its `suggestion` instead and says nothing runs on its own | 대신 `suggestion`을 추천하고, 저절로 실행되는 단계는 없다고 말함 |
43
+
44
+ A suggestion never repeats a step already done: a done session is offered for review
45
+ (`review what <id> finished in <place>`), never picked up as if it still had work.
@@ -91,7 +91,7 @@ Treat this SKILL.md as an LLM contract artifact, not a casual help page. Load it
91
91
  ## #contract.procedure
92
92
 
93
93
  1. **Acknowledge activation deterministically.** Print the exact banner required above before any explanation when the skill is truly active.
94
- 2. **Bind scope.** Name the requested outcome, in-scope files or surfaces, and any explicit non-goals. Keep sibling repositories outside scope unless the user names them.
94
+ 2. **Bind scope.** Name the requested outcome, in-scope files or surfaces, and any explicit non-goals. Keep sibling repositories outside scope unless the user names them. When a todo names an absolute path outside the project, declare it on its own column-zero line, `Scope roots: <path> (<actions>)`, so start-work can grant it at init instead of pausing at the first touch. The Stop hook names any such path left undeclared, once per plan, with the exact line to paste; `/` and the bare home folder never count as a root.
95
95
  3. **Ground in Codex reality.** Prefer repo-local files, package scripts, component directives, marketplace metadata, and hook behavior over memory or generic agent habits.
96
96
  4. **Select the smallest complete path.** Reuse existing tests, scripts, components, directives, and docs before inventing new abstractions.
97
97
  5. **Execute with evidence gates.** For behavior changes, obtain a failing-first proof when a seam exists; for docs/contracts, add a guard that fails before the rewrite and passes after it.
@@ -195,7 +195,8 @@ they can press Shift+Tab and continue, or proceed with file-backed lit-plan.
195
195
  - **Planner scope only.** Prepare one Markdown plan and publish it only through the bundled
196
196
  `publish-plan` route. Write drafts under `.litcodex/drafts/*.md`. Never edit source or lifecycle
197
197
  authority state. If asked to "just do it", decline: you plan; after approval, hand the published plan
198
- to execution with `lit start work <plan-name>`.
198
+ to execution with `lit start work <plan-name>`. Saving the plan arms a one-word `go` for this session,
199
+ so close by telling the user to type `go` within 30 minutes to start it.
199
200
 
200
201
  ## Objective-achievable plan contract
201
202
 
@@ -99,7 +99,8 @@ node <plugin-root>/components/start-work-continuation/dist/cli.js publish-plan -
99
99
 
100
100
  The route validates through `analyzePlanProgress`, creates the plan without overwriting an existing
101
101
  target, and writes no lifecycle authority state. Finish by naming the collision-safe execution handoff:
102
- `lit start work <plan-name>`.
102
+ `lit start work <plan-name>`. The Stop hook that sees the saved plan arms a one-word `go` for this session
103
+ only, so close by telling the user to type `go` within 30 minutes to start it.
103
104
 
104
105
  ## Objective-achievable checklist contract
105
106
 
@@ -267,7 +267,7 @@ node <plugin-root>/components/start-work-continuation/dist/cli.js init
267
267
  {"cwd":"<canonical repo>","init_id":"<stable id>","expected_revision":0,"work_id":"<work id>","plan":".litcodex/plans/<plan>.md","plan_name":"<display name>","session_id":"<raw Codex id>","worktree_path":"<canonical cwd or separate worktree>","authority":{"authority_id":"<approval id>","allowed_roots":["<canonical approved root>"],"allowed_actions":["edit","test"],"forbidden_actions":["publish"]}}
268
268
  ```
269
269
 
270
- Its JSON stdin must include `cwd`, a stable `init_id`, global-CAS `expected_revision`, `work_id`, canonical repo-relative `plan`, bounded display-only `plan_name`, raw Codex `session_id`, a live canonical absolute `worktree_path`, and an `authority` object with `authority_id`, canonical absolute `allowed_roots`, `allowed_actions`, and `forbidden_actions`. Derive that envelope only from the user's approved plan and scope. `init` atomically creates schema 3 and emits `start_work_initialized`; exact retained replay is idempotent. A terminal completed/abandoned state permits a new distinct init at the current revision while preserving bounded replay history; any nonterminal work rejects it.
270
+ Its JSON stdin must include `cwd`, a stable `init_id`, global-CAS `expected_revision`, `work_id`, canonical repo-relative `plan`, bounded display-only `plan_name`, raw Codex `session_id`, a live canonical absolute `worktree_path`, and an `authority` object with `authority_id`, canonical absolute `allowed_roots`, `allowed_actions`, and `forbidden_actions`. Derive that envelope only from the user's approved plan and scope: the project root, plus the path of every column-zero `Scope roots: <path> (<actions>)` line in the plan, made canonical and absolute, with its actions added to `allowed_actions`. Skip a declared `/` or bare home folder. `init` atomically creates schema 3 and emits `start_work_initialized`; exact retained replay is idempotent. A terminal completed/abandoned state permits a new distinct init at the current revision while preserving bounded replay history; any nonterminal work rejects it.
271
271
 
272
272
  Schema 3 has one global monotonic `revision`; `active_work_id` selects the same-keyed sole nonterminal `works[id]` or is `null` after terminal cancel/complete. Every work owns `worktree_path`; a nonterminal path must exist, be canonical, and lie within effective authority, while a terminal historical record may retain its normalized absolute path after cleanup removes the directory. Paused work must own one pending boundary matching its last canonical pause event. Every load sorts retained events by revision rather than object-key enumeration and validates unique contiguous revisions, last-transition consistency, authority, and worktree containment. Replay history is compacted to a bounded newest window with an explicit floor; terminal work records whose final events fall below that floor are compacted too, and pruned replay fails as `REPLAY_EXPIRED`. A valid schema-2 state is migrated lazily only when the first code-owned mutation supplies a valid authority envelope and the fully constructed schema-3 result validates; ambiguous nonterminal state is rejected without mutation. A historical absolute plan is normalized only when its no-follow canonical realpath proves it is directly inside `cwd/.litcodex/plans`; unsupported or unsafe state stays silent and is reported by `doctor --cwd <path> --json`.
273
273
 
@@ -156,19 +156,21 @@ the Codex home yourself.
156
156
  Use the user's language. Start from the JSON's `brief` field, a finished Markdown draft; keep its structure,
157
157
  translate it, and add no `#` heading or `>` quote mark (the Codex terminal prints them literally), and copy ids, gauges, titles, dates and names from the JSON verbatim.
158
158
 
159
- 1. Headline: one bold `**🧭 …**` line with the session count, how many wait on the user, how many run, how many are paused,
160
- and the next step, then a dim line with the window.
161
- 2. One list-item card (`- ` first line, indented continuation lines) per live session (waiting or running), grouped by worktree and branch: a coloured badge
162
- (`🟡 WAITS ON YOU`, `🟢 RUNNING`), then the goal in bold (`title`), ⏳ progress, ✅ done (`done`) and ▶ next (`needs`;
159
+ 1. Opener, three bold lines: `✅ Done so far:` (finished plans, done sessions), `▶ Doing now:` (running, idle,
160
+ paused, what waits on the user) and `⏭ Next:` (the one next step), then a dim line with the window and session count.
161
+ 2. One list-item card (`- ` first line, indented continuation lines) per session that is not ended, grouped by worktree and branch: a coloured badge
162
+ (`🟡 WAITS ON YOU`, `🟢 RUNNING`, `💤 IDLE`, `✅ DONE`), then the goal in bold (`title`), ⏳ progress, ✅ done (`done`) and ▶ next (`needs`;
163
163
  for a running session what it is doing now, `now: shell “npm”`). Sessions with status `ended` get no card.
164
164
  3. Roadmap under each worktree: `worktrees[].milestones` as `✓` done with its date, `▶` now, `○` later; open plans and
165
- goals with their gauges; paused frames from `worktrees[].paused` as a `now` line with the way back (`lit continue`).
165
+ goals with their gauges, finished plans (`finishedPlans`) as finished; paused frames from `worktrees[].paused` as a `now` line with the way back (`lit continue`).
166
166
  4. One table under a `⚪ **Ended · N**` line: id, where, goal, ago, done, one row per ended session, eight at most, then the count
167
167
  of the rest. Keep each row on one line.
168
168
  5. One recommended next step in a box: `next` when its kind is not `none`, else `suggestion`, a real step from the
169
169
  records. Say `go` for a resume-frame, continue-work or start-plan step, `lit approve` or `lit deny` for an
170
- approve-boundary step (shown only; never answer it for the user). A `suggestion` says nothing runs on its own here:
171
- open that session, or say what to do. Never write "no next step".
170
+ approve-boundary step (shown only; never answer it for the user). A `handoff` step comes from this worktree's
171
+ HANDOFF note and `go` does not run it. A `suggestion` says nothing runs on its own here: open that session, or say
172
+ what to do; a done session is offered for review, never picked up again. Never write "no next step". The box
173
+ sits in a plain fence with no language tag.
172
174
 
173
175
  A gauge `[▉▉▉░░] 3/5` is drawn only when both numbers are real, copied as given. An unknown total gets no gauge and no
174
176
  placeholder: write the known facts in words (`12 steps · 4m · last: apply_patch`). Never show a run of question marks
@@ -176,10 +178,11 @@ where a number would go, and never estimate a total.
176
178
 
177
179
  Finish with one `unknown:` line naming each source whose status is not `ok`
178
180
  (`sources.sessions`, `sources.git`, `sources.state`) and whether the byte budget
179
- ran out. Never fill an unknown from memory.
181
+ ran out, and say once how many plan files were too large to read (`skippedPlans`). Never fill an unknown from memory.
180
182
 
181
183
  # Status words
182
- `waiting-on-user`, `active` (a record in the last 15 minutes), `ended`, `unknown`.
184
+ `done` (its work or plan finished), `waiting-on-user`, `idle` (its turn closed, per its liveness record), `active` (a
185
+ record in the last 15 minutes), `ended`, `unknown`.
183
186
  The skill's `references/status-taxonomy.md` has the English and Korean words;
184
187
  `references/card-examples.md` shows a finished brief.
185
188
 
@@ -458,7 +458,8 @@ approval, until independently verified.
458
458
  approach), then stop and wait.
459
459
  - After approval: announce the plan path `.litcodex/plans/<slug>.md`, a
460
460
  one-paragraph summary of scope, waves, and verification, and the collision-safe next action
461
- `lit start work <plan-name>`.
461
+ `lit start work <plan-name>`. Close by telling the user to type `go` within 30 minutes to start it:
462
+ saving the plan arms a one-word `go` for this session only.
462
463
 
463
464
  # Stop rules
464
465
  - Plan file exists, template filled, every todo has action + output + verification +
@@ -37,6 +37,8 @@ export interface CardStatus {
37
37
  readonly workspace: string | null;
38
38
  /** When the newest card of this thread opened; an older card that sees a later time folds itself. */
39
39
  readonly cardOpenedAt: number | null;
40
+ /** `restart to <v>` while a newer LitCodex is installed than the one this process loaded, else null. */
41
+ readonly restart?: string | null;
40
42
  readonly now: number;
41
43
  }
42
44
  /**
@@ -70,6 +72,7 @@ export declare function toolDisplayName(tool: string): string;
70
72
  /** The card for one thread. `rollout: false` keeps every Codex rollout file unread; the usage row then stays empty. */
71
73
  export declare function readCardStatus(threadId: string | null, env: NodeJS.ProcessEnv, now?: number, options?: {
72
74
  readonly rollout?: boolean;
75
+ readonly loadedVersion?: string | null;
73
76
  }): CardStatus;
74
77
  /** Minutes and seconds, `m:ss`. */
75
78
  export declare function clock(ms: number): string;
@@ -12,6 +12,7 @@ import { basename, isAbsolute, join } from "node:path";
12
12
  import { lookOf, REVIEW_LANE_IDS } from "./card-looks.js";
13
13
  import { cleanDeep, cleanLines } from "./control-chars.js";
14
14
  import { codexHomeFrom, openRegularFile, plainDirs, readLiveStep, readThreadPointer, } from "./live-step.js";
15
+ import { installedPluginVersion, loadedPluginVersion, restartChip } from "./restart-chip.js";
15
16
  import { normalizeSessionId } from "./state-paths.js";
16
17
  import { readThreads, threadLines } from "./threads.js";
17
18
  import { readWorkflowSignals, workflowMapCells, workflowMapText, workflowTurn, } from "./workflow-map.js";
@@ -422,6 +423,7 @@ export function readCardStatus(threadId, env, now = Date.now(), options = {}) {
422
423
  branch: readBranch(cwd),
423
424
  workspace,
424
425
  cardOpenedAt,
426
+ restart: restartChip(options.loadedVersion === undefined ? loadedPluginVersion() : options.loadedVersion, installedPluginVersion(env)),
425
427
  now,
426
428
  });
427
429
  }
@@ -441,8 +443,9 @@ export function cardStatusText(status) {
441
443
  : status.look === "review"
442
444
  ? " REVIEW"
443
445
  : "";
446
+ const chip = status.restart ? ` ↻ ${status.restart}` : "";
444
447
  const lines = [
445
- `🔥 LIT ${status.state === "complete" ? "COMPLETE ✓" : "IGNITED"} · ${status.mode ?? "lit"}${lookLabel}`,
448
+ `🔥 LIT ${status.state === "complete" ? "COMPLETE ✓" : "IGNITED"} · ${status.mode ?? "lit"}${lookLabel}${chip}`,
446
449
  ];
447
450
  if (status.map !== null) {
448
451
  lines.push(workflowMapText(status.map));
@@ -21,6 +21,7 @@ import { clearActiveRoute, isBareLit, isLitContinue, readActiveRoute, readResume
21
21
  import { isBoundaryAnswer, isGoPrompt, takeGo } from "./rewind-go.js";
22
22
  import { workflowCard } from "./screen-card.js";
23
23
  import { screenColor } from "./screen-status.js";
24
+ import { recordLiveness } from "./session-liveness.js";
24
25
  import { applyPromptToStack, frameToResume } from "./stack-hook.js";
25
26
  import { recordWorkflowTurn, workflowStopLine, workflowTurn } from "./workflow-map.js";
26
27
  /** Hard cap on stdin to bound memory / ReDoS exposure inside the 5 s Codex hook budget. 8 MB. */
@@ -362,7 +363,7 @@ export async function runStopPlanPersistenceHookCli(stdin, stdout, stderr, repoR
362
363
  // No tool runs once Stop fires: one whose PostToolUse never came (interrupted, or denied by another hook) is over.
363
364
  // The turn itself closes only below, after the guards that can send the model back to work.
364
365
  endLiveStep(scope.cwd, scope.sessionId, auto.now, false);
365
- const persistence = evaluatePlanPersistence(scope.cwd, scope.sessionId);
366
+ const persistence = evaluatePlanPersistence(scope.cwd, scope.sessionId, auto.now);
366
367
  if (persistence.decision === "block") {
367
368
  stdout.write(formatStopBlockOutput(persistence.reason));
368
369
  return 0;
@@ -396,6 +397,8 @@ export async function runStopPlanPersistenceHookCli(stdin, stdout, stderr, repoR
396
397
  const lastMsg = typeof record["last_assistant_message"] === "string" ? record["last_assistant_message"] : null;
397
398
  endLiveStep(scope.cwd, scope.sessionId, auto.now, true, detectWaitReason(lastMsg));
398
399
  const env = auto.env ?? process.env;
400
+ if (workflowTurn(scope.cwd, scope.sessionId) !== null)
401
+ recordLiveness(scope.cwd, scope.sessionId, "idle", env, auto.now);
399
402
  const line = typeof record["turn_id"] === "string"
400
403
  ? workflowStopLine(scope.cwd, scope.sessionId, record["turn_id"], {
401
404
  stopHookActive: record["stop_hook_active"] === true,
@@ -538,8 +541,11 @@ export async function runPostToolUseLiveHookCli(stdin, _stdout, _stderr, options
538
541
  return 0;
539
542
  const scope = toolEventScope(event.parsed);
540
543
  const now = options.now ?? Date.now();
541
- if (scope !== null && !OWN_CARD_TOOL.test(scope.tool))
544
+ if (scope !== null && !OWN_CARD_TOOL.test(scope.tool)) {
542
545
  recordLiveStepEnd(scope.cwd, scope.sessionId, scope, now);
546
+ if (workflowTurn(scope.cwd, scope.sessionId) !== null)
547
+ recordLiveness(scope.cwd, scope.sessionId, "alive", options.env ?? process.env, now);
548
+ }
543
549
  recordLanes(event.parsed, toolLaneEvents, now);
544
550
  // A shell call that ran the film renderer is noted for the completion gate (motion-gate.ts).
545
551
  recordMotionTool(event.parsed, now);
@@ -17,6 +17,6 @@ export declare function rearmLitPlanIfSatisfied(repoRoot: string, sessionId: str
17
17
  * already satisfied, or when the block cap is spent; otherwise block until a checkbox plan newer than
18
18
  * the activation exists. Fail-open on any fs error.
19
19
  */
20
- export declare function evaluatePlanPersistence(repoRoot: string, sessionId: string): PlanPersistenceDecision;
20
+ export declare function evaluatePlanPersistence(repoRoot: string, sessionId: string, now?: number): PlanPersistenceDecision;
21
21
  /** Codex Stop hook output for a block decision (single line + newline). */
22
22
  export declare function formatStopBlockOutput(reason: string): string;
@@ -8,7 +8,10 @@
8
8
  // PLAN_PERSISTENCE_MAX_BLOCKS blocks are issued per session so a model that keeps interviewing (or a
9
9
  // user who abandons the plan) can never be trapped in a Stop loop. Every fs failure is FAIL-OPEN.
10
10
  import { mkdirSync, readdirSync, readFileSync, renameSync, statSync, writeFileSync } from "node:fs";
11
+ import { homedir } from "node:os";
11
12
  import { isAbsolute, join } from "node:path";
13
+ import { scopeRootGaps, scopeRootLine } from "./plan-scope-roots.js";
14
+ import { writeNext } from "./rewind.js";
12
15
  import { normalizeSessionId } from "./state-paths.js";
13
16
  import { recordStackEvent } from "./workflow-stack.js";
14
17
  export const PLAN_PERSISTENCE_DIR = ".litcodex/lit-plan";
@@ -38,12 +41,14 @@ function readState(path) {
38
41
  typeof record["satisfied"] !== "boolean") {
39
42
  return null;
40
43
  }
44
+ const warned = record["scopeWarned"];
41
45
  return {
42
46
  version: STATE_VERSION,
43
47
  sessionId: record["sessionId"],
44
48
  activatedAt: record["activatedAt"],
45
49
  blocks: record["blocks"],
46
50
  satisfied: record["satisfied"],
51
+ ...(Array.isArray(warned) ? { scopeWarned: warned.filter((name) => typeof name === "string") } : {}),
47
52
  };
48
53
  }
49
54
  catch {
@@ -103,7 +108,7 @@ function newestPlanSince(repoRoot, since) {
103
108
  return null;
104
109
  try {
105
110
  const body = readFileSync(join(dir, newest.file), "utf8");
106
- return { file: newest.file, taskRows: body.split(/\r?\n/).filter((line) => TASK_ROW.test(line)).length };
111
+ return { file: newest.file, taskRows: body.split(/\r?\n/).filter((line) => TASK_ROW.test(line)).length, body };
107
112
  }
108
113
  catch {
109
114
  return null;
@@ -115,12 +120,18 @@ function blockReason(detail) {
115
120
  "(plan Markdown on stdin; `## Todos` rows as `- [ ] N. <title>` at column zero). " +
116
121
  `If approval is still pending, ask for it explicitly and end the turn; this guard blocks at most ${PLAN_PERSISTENCE_MAX_BLOCKS} turns per session.`);
117
122
  }
123
+ function scopeReason(file, gaps) {
124
+ return (`The saved plan ${PLAN_PERSISTENCE_PLANS_DIR}/${file} names paths outside this project that no \`Scope roots:\` line covers, ` +
125
+ "so start-work would pause at the first touch of each. Add these lines at column zero near the top of the plan " +
126
+ `(widen \`read\` to the actions each todo needs), then end the turn:\n${gaps.map(scopeRootLine).join("\n")}\n` +
127
+ "This is advisory and shown once for this plan; leave the plan as it is if the run should ask instead.");
128
+ }
118
129
  /**
119
130
  * Decide whether the Stop for `sessionId` may end. Pass when no activation exists, when the guard is
120
131
  * already satisfied, or when the block cap is spent; otherwise block until a checkbox plan newer than
121
132
  * the activation exists. Fail-open on any fs error.
122
133
  */
123
- export function evaluatePlanPersistence(repoRoot, sessionId) {
134
+ export function evaluatePlanPersistence(repoRoot, sessionId, now = Date.now()) {
124
135
  const path = statePath(repoRoot, sessionId);
125
136
  if (path === null)
126
137
  return PASS;
@@ -129,6 +140,19 @@ export function evaluatePlanPersistence(repoRoot, sessionId) {
129
140
  return PASS;
130
141
  const newest = newestPlanSince(repoRoot, state.activatedAt);
131
142
  if (newest !== null && newest.taskRows > 0) {
143
+ const warned = state.scopeWarned ?? [];
144
+ const gaps = warned.includes(newest.file)
145
+ ? []
146
+ : scopeRootGaps(newest.body, repoRoot, process.env["HOME"] ?? homedir());
147
+ if (gaps.length > 0) {
148
+ try {
149
+ writeState(path, { ...state, scopeWarned: [...warned, newest.file] });
150
+ }
151
+ catch {
152
+ return PASS;
153
+ }
154
+ return { decision: "block", reason: scopeReason(newest.file, gaps) };
155
+ }
132
156
  try {
133
157
  writeState(path, { ...state, satisfied: true });
134
158
  }
@@ -144,6 +168,8 @@ export function evaluatePlanPersistence(repoRoot, sessionId) {
144
168
  done: true,
145
169
  ref: { plan: `${PLAN_PERSISTENCE_PLANS_DIR}/${newest.file}` },
146
170
  }, new Date());
171
+ // One `go` in this session within the go window starts the plan just saved.
172
+ writeNext(repoRoot, sessionId, { kind: "start-plan", text: `start work on ${newest.file}`, plan: newest.file }, now);
147
173
  return PASS;
148
174
  }
149
175
  if (state.blocks >= PLAN_PERSISTENCE_MAX_BLOCKS)
@@ -0,0 +1,7 @@
1
+ /**
2
+ * Absolute paths the plan's todos name outside `projectRoot` that no `Scope roots:` line covers, in order of
3
+ * first mention. Empty when the plan is covered.
4
+ */
5
+ export declare function scopeRootGaps(text: string, projectRoot: string, home: string): string[];
6
+ /** The line a planner pastes to declare `path`; read access is the default to widen deliberately. */
7
+ export declare function scopeRootLine(path: string): string;