@litfamily/litgravity 0.1.2 → 0.1.3

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.
package/CHANGELOG.md CHANGED
@@ -1,5 +1,24 @@
1
1
  # Changelog
2
2
 
3
+ ## 0.1.3 — 2026-10-28
4
+
5
+ Plans:
6
+
7
+ - After `lit plan` saves a plan, type `go` in the same conversation within 30 minutes and start-work picks it up.
8
+ - If a plan's tasks touch a folder outside the project, the plan asks for a `Scope roots: <path> (<actions>)` line before it is saved, and the plan checker points at any path that line does not cover. The line is a reminder, not a lock.
9
+
10
+ Status line:
11
+
12
+ - Each conversation keeps a small record of whether it is running, idle or ended. The status line uses it to show the other conversations in the same workspace as one count, such as `+2 running · 1 idle`, and shows a start-work that just finished as done for a minute.
13
+
14
+ lit-adhd:
15
+
16
+ - The brief now opens with three lines: what is done, what is happening now, and what comes next. It also lists idle and finished conversations, reads plans before transcripts, says how many plan files it skipped, and, when nothing else suggests a next step, uses the `## Next` item of this folder's HANDOFF file. The box is a plain code fence.
17
+
18
+ Project:
19
+
20
+ - `TRADEMARK.md` explains how the LitGravity and LitFamily names and logos may be used. The code stays MIT.
21
+
3
22
  ## 0.1.2 — 2026-10-27
4
23
 
5
24
  New skills (42 in all):
package/README.md CHANGED
@@ -109,7 +109,7 @@ When the terminal narrows, the extras give way first and the route and the conte
109
109
  [LIT] | GF3.8 | ctx [#--] 42%/1049k | [LIT] . lit-loop 2:20 | [PIN] = RED . - GREEN . - VERIFY . - REVIEW . - RECORD .
110
110
  ```
111
111
 
112
- Some moments change the look of the row. While `lit adhd` (or `lit-rewind`, the skill typed whole or after `/`, or the skill the model loads by itself) is the route, every cell turns its own colour of a slow rainbow. When the turn ends on a question, a typed approval, a BLOCKED report or a goal that needs a decision, the row turns amber and reads `⚠ YOUR TURN · <why>` until you type. During `lit review work` the five lanes (goal, qa, quality, security, context) appear as each reports, in its own colour with its verdict mark and a count such as `2/5`. A plan or goal finished during the route shows `✦ DONE ✦` for twenty seconds. agy repaints the line when it chooses, so every look is static, and `NO_COLOR` keeps the labels in plain text.
112
+ Some moments change the look of the row. While `lit adhd` (or `lit-rewind`, the skill typed whole or after `/`, or the skill the model loads by itself) is the route, every cell turns its own colour of a slow rainbow. When the turn ends on a question, a typed approval, a BLOCKED report or a goal that needs a decision, the row turns amber and reads `⚠ YOUR TURN · <why>` until you type. During `lit review work` the five lanes (goal, qa, quality, security, context) appear as each reports, in its own colour with its verdict mark and a count such as `2/5`. A plan or goal finished during the route shows `✦ DONE ✦` for twenty seconds. Other conversations in the same workspace appear as one count, `+2 running · 1 idle` (shortened to `+3 others` when the row is tight), read from the small liveness record each conversation's hooks keep; a start-work that just finished counts as done for a minute. agy repaints the line when it chooses, so every look is static, and `NO_COLOR` keeps the labels in plain text.
113
113
 
114
114
  ## What you get
115
115
 
@@ -200,3 +200,5 @@ The seven armored machines on the cover are those seven packages, and LitGravity
200
200
  ## License
201
201
 
202
202
  MIT. See [LICENSE](./LICENSE).
203
+
204
+ The LitGravity and LitFamily names and logos are covered by the [trademark policy](./TRADEMARK.md).
package/README_ko-KR.md CHANGED
@@ -200,3 +200,5 @@ LitGravity는 LitFamily 패키지 일곱 개 중 하나입니다. 각 패키지
200
200
  ## 라이선스
201
201
 
202
202
  MIT. [LICENSE](./LICENSE)를 보세요.
203
+
204
+ LitGravity와 LitFamily 이름과 로고는 [상표 정책](./TRADEMARK.md)을 따릅니다.
package/TRADEMARK.md ADDED
@@ -0,0 +1,12 @@
1
+ # Trademark policy
2
+
3
+ The code in this repository is free to use under the MIT License (see `LICENSE`). The names **LitGravity**
4
+ and **LitFamily**, and the logos and mascot art, are not part of that license.
5
+
6
+ - You can fork, change and share the code under MIT.
7
+ - If you publish a changed version, give it a different name and logo, and do not suggest that the
8
+ LitGravity maintainers made or endorse it.
9
+ - You can say in plain text that your project is "based on LitGravity" or "a fork of LitGravity".
10
+ - Unchanged copies, such as mirrors and package caches, may keep the name.
11
+
12
+ Questions: open an issue at https://github.com/wjgoarxiv/litgravity/issues.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@litfamily/litgravity",
3
- "version": "0.1.2",
3
+ "version": "0.1.3",
4
4
  "description": "Installer for LitGravity: skills, hooks and agents that help Google's Antigravity CLI (agy) plan, build, check and hand off work.",
5
5
  "keywords": [
6
6
  "antigravity",
@@ -35,7 +35,8 @@
35
35
  "README.md",
36
36
  "README_ko-KR.md",
37
37
  "CHANGELOG.md",
38
- "LICENSE"
38
+ "LICENSE",
39
+ "TRADEMARK.md"
39
40
  ],
40
41
  "publishConfig": {
41
42
  "access": "public"
@@ -0,0 +1,81 @@
1
+ // Liveness: one small record per conversation beside its route state, `<id>.live.json`, read by the status line's
2
+ // other-session chip and the lit-adhd collector. PostToolUse writes `alive` and an unheld Stop writes `idle`, for every
3
+ // conversation, lit route or not. agy fires no session-end event, so `ended` is never written: a record left alone past
4
+ // its staleness limit reads as ended. The same state is rewritten at most once per throttle window; a change of state is
5
+ // written at once.
6
+
7
+ import { closeSync, constants, fstatSync, lstatSync, mkdirSync, openSync, readSync, readdirSync, renameSync, writeFileSync } from 'node:fs';
8
+ import { dirname, join } from 'node:path';
9
+ import { sessionPath } from './common.mjs';
10
+
11
+ export const LIVE_THROTTLE_MS = 30_000;
12
+ // An alive record that goes quiet this long belongs to a session that stopped without a Stop event.
13
+ export const ALIVE_STALE_MS = 10 * 60_000;
14
+ // An idle session waits on its user; after this long it is taken as closed.
15
+ export const IDLE_STALE_MS = 2 * 60 * 60_000;
16
+ const MAX_FILE_BYTES = 4096;
17
+ const PANE = /^[A-Za-z0-9._:-]{1,64}$/;
18
+ const LIVE_FILE = /^([A-Za-z0-9_-]{1,128})\.live\.json$/;
19
+
20
+ export const livePath = (cwd, conversationId, env = process.env) => {
21
+ const base = sessionPath(cwd, conversationId, env);
22
+ return base ? base.replace(/\.json$/, '.live.json') : null;
23
+ };
24
+
25
+ const readRaw = (path) => {
26
+ let fd;
27
+ try {
28
+ if (!lstatSync(path).isFile()) return null;
29
+ fd = openSync(path, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0));
30
+ const { size } = fstatSync(fd);
31
+ if (size > MAX_FILE_BYTES) return null;
32
+ const buffer = Buffer.alloc(size);
33
+ readSync(fd, buffer, 0, size, 0);
34
+ const record = JSON.parse(buffer.toString('utf8'));
35
+ return record && ['alive', 'idle'].includes(record.state) && Number.isFinite(Date.parse(record.at)) ? record : null;
36
+ } catch {
37
+ return null;
38
+ } finally {
39
+ if (fd !== undefined) closeSync(fd);
40
+ }
41
+ };
42
+
43
+ // The record with its effective state: `alive`, `idle`, or `ended` once stale. Null when absent or damaged.
44
+ export const readLive = (path, now = Date.now()) => {
45
+ const record = readRaw(path);
46
+ if (!record) return null;
47
+ const age = now - Date.parse(record.at);
48
+ const stale = age > (record.state === 'alive' ? ALIVE_STALE_MS : IDLE_STALE_MS);
49
+ return { ...record, state: stale ? 'ended' : record.state };
50
+ };
51
+
52
+ // Every conversation's record in one route-state folder (one workspace), newest first.
53
+ export const listLive = (dir, now = Date.now()) => {
54
+ let names;
55
+ try { names = readdirSync(dir); } catch { return []; }
56
+ return names
57
+ .map((name) => LIVE_FILE.exec(name))
58
+ .filter(Boolean)
59
+ .map((m) => ({ id: m[1], ...readLive(join(dir, m[0]), now) }))
60
+ .filter((r) => r.state)
61
+ .sort((a, b) => Date.parse(b.at) - Date.parse(a.at));
62
+ };
63
+
64
+ export const markLive = (cwd, conversationId, state, { env = process.env, now = Date.now() } = {}) => {
65
+ const path = livePath(cwd, conversationId, env);
66
+ if (!path) return false;
67
+ const previous = readRaw(path);
68
+ if (previous?.state === state && now - Date.parse(previous.at) < LIVE_THROTTLE_MS) return false;
69
+ const record = { state, at: new Date(now).toISOString() };
70
+ if (typeof env.HERDR_PANE_ID === 'string' && PANE.test(env.HERDR_PANE_ID)) record.pane = env.HERDR_PANE_ID;
71
+ try {
72
+ if (lstatSync(path).isSymbolicLink()) return false;
73
+ } catch {
74
+ // absent is fine
75
+ }
76
+ mkdirSync(dirname(path), { recursive: true });
77
+ const staging = `${path}.${process.pid}.tmp`;
78
+ writeFileSync(staging, `${JSON.stringify(record)}\n`);
79
+ renameSync(staging, path);
80
+ return true;
81
+ };
@@ -14,9 +14,15 @@ const WORDS = {
14
14
  sessions: (n) => `${n} ${n === 1 ? 'session' : 'sessions'}`,
15
15
  waiting: (n) => `${n} ${n === 1 ? 'waits' : 'wait'} on you`,
16
16
  active: (n) => `${n} active`,
17
- next: 'next',
18
17
  window: (since, trees) => `last ${since} · ${trees} ${trees === 1 ? 'folder' : 'folders'} read`,
19
- badge: { 'waiting-on-user': '🟠 **WAITING ON YOU**', active: '🟢 **ACTIVE**', ended: '⚪ ended', unknown: '⚫ unknown' },
18
+ badge: { 'waiting-on-user': '🟠 **WAITING ON YOU**', active: '🟢 **ACTIVE**', idle: '💤 idle', done: '✅ **DONE**', ended: '⚪ ended', unknown: '⚫ unknown' },
19
+ doneSoFar: 'Done so far',
20
+ doingNow: 'Doing now',
21
+ plansFinished: (n) => `${n} ${n === 1 ? 'plan' : 'plans'} finished`,
22
+ sessionsDone: (n) => `${n} ${n === 1 ? 'session' : 'sessions'} done`,
23
+ nothingDone: 'nothing finished in this window',
24
+ nothingRunning: 'nothing running',
25
+ plansSkipped: (n) => `${n} plan ${n === 1 ? 'file' : 'files'} skipped (no task rows or an unfilled scaffold).`,
20
26
  reason: { 'asked the user': 'it asked you something', 'paused workflow': 'a paused route' },
21
27
  ago: (text) => `${text} ago`,
22
28
  justNow: 'just now',
@@ -55,6 +61,7 @@ const WORDS = {
55
61
  plan: ({ plan, item }) => `Next in ${plan}: ${item}`,
56
62
  check: ({ id8, goal, where, doing }) => `Check on ${id8} in ${where} (${goal})${doing ? `, now ${doing}` : ''}`,
57
63
  pickUp: ({ id8, goal, where }) => `Pick up ${id8} in ${where}: ${goal}`,
64
+ handoff: ({ file, next }) => `From ${file}: ${next}`,
58
65
  start: () => 'No conversation or plan in this window: say what to start',
59
66
  },
60
67
  goLine: (say) => `Type **\`${say}\`** to continue.`,
@@ -68,9 +75,15 @@ const WORDS = {
68
75
  sessions: (n) => `세션 ${n}개`,
69
76
  waiting: (n) => `나를 기다리는 것 ${n}`,
70
77
  active: (n) => `진행 중 ${n}`,
71
- next: '다음',
72
78
  window: (since, trees) => `최근 ${since} · 폴더 ${trees}곳 읽음`,
73
- badge: { 'waiting-on-user': '🟠 **나를 기다림**', active: '🟢 **진행 중**', ended: '⚪ 끝남', unknown: '⚫ 알 수 없음' },
79
+ badge: { 'waiting-on-user': '🟠 **나를 기다림**', active: '🟢 **진행 중**', idle: '💤 쉬는 중', done: '✅ **완료**', ended: '⚪ 끝남', unknown: '⚫ 알 수 없음' },
80
+ doneSoFar: '지금까지 한 일',
81
+ doingNow: '지금 하는 일',
82
+ plansFinished: (n) => `끝난 계획 ${n}개`,
83
+ sessionsDone: (n) => `끝난 세션 ${n}개`,
84
+ nothingDone: '이 기간에 끝난 일 없음',
85
+ nothingRunning: '진행 중인 일 없음',
86
+ plansSkipped: (n) => `계획 파일 ${n}개는 건너뜀(작업 행이 없거나 채우지 않은 틀).`,
74
87
  reason: { 'asked the user': '질문하고 기다림', 'paused workflow': '멈춘 라우트' },
75
88
  ago: (text) => `${text} 전`,
76
89
  justNow: '방금',
@@ -109,6 +122,7 @@ const WORDS = {
109
122
  plan: ({ plan, item }) => `${plan} 다음 항목: ${item}`,
110
123
  check: ({ id8, goal, where, doing }) => `${where}의 ${id8} 확인 (${goal})${doing ? `, 지금 ${doing}` : ''}`,
111
124
  pickUp: ({ id8, goal, where }) => `${where}의 ${id8} 이어받기: ${goal}`,
125
+ handoff: ({ file, next }) => `${file}에서: ${next}`,
112
126
  start: () => '이 기간에 대화·계획이 없습니다. 시작할 일을 말해 주세요',
113
127
  },
114
128
  goLine: (say) => `**\`${say}\`** 라고 입력하면 이어갑니다.`,
@@ -249,6 +263,8 @@ const suggestion = (data, w) => {
249
263
  if (active) return w.suggest.check({ id8: active.id8, goal: goal(active), where: where(active), doing: actionOf(active, bare) });
250
264
  const ended = sessions.find((s) => s.status === 'ended' && !s.self);
251
265
  if (ended) return w.suggest.pickUp({ id8: ended.id8, goal: goal(ended), where: where(ended) });
266
+ const handoff = (data.handoffs ?? []).find((h) => h.local && h.next);
267
+ if (handoff) return w.suggest.handoff({ file: bare(handoff.file), next: bare(handoff.next) });
252
268
  return w.suggest.start();
253
269
  };
254
270
 
@@ -289,7 +305,22 @@ const wrap = (text, width, max = 3) => {
289
305
  // Open on the right: agy's chat font draws Hangul narrower than two cells, so a right edge would wander.
290
306
  const box = (title, body) => {
291
307
  const inner = Math.max(displayWidth(title) + 4, ...body.map(displayWidth)) + 2;
292
- return ['```text', `╭─ ${title} ${'─'.repeat(Math.max(1, inner - displayWidth(title) - 3))}`, ...body.map((line) => `│ ${line}`), `╰${'─'.repeat(inner)}`, '```'].join('\n');
308
+ return ['```', `╭─ ${title} ${'─'.repeat(Math.max(1, inner - displayWidth(title) - 3))}`, ...body.map((line) => `│ ${line}`), `╰${'─'.repeat(inner)}`, '```'].join('\n');
309
+ };
310
+
311
+ // Three lines under the headline, for a reader who reads nothing else: what is finished, what runs now, the step.
312
+ const opener = (data, step, w) => {
313
+ const sessions = data.sessions ?? [];
314
+ const finished = (data.roadmap?.plans ?? []).filter((p) => p.finished).length;
315
+ const doneSessions = sessions.filter((s) => s.status === 'done').length;
316
+ const commits = (data.commits ?? []).length;
317
+ const done = [finished ? w.plansFinished(finished) : null, doneSessions ? w.sessionsDone(doneSessions) : null, commits ? w.commits(commits) : null].filter(Boolean);
318
+ const running = sessions.filter((s) => s.status === 'active').slice(0, 2).map((s) => `${code(s.id8)} ${plain(clipToWidth(goalOf(s), 50))}`);
319
+ return [
320
+ `**${w.doneSoFar}:** ${done.length ? done.join(' · ') : w.nothingDone}`,
321
+ `**${w.doingNow}:** ${running.length ? running.join(' · ') : w.nothingRunning}`,
322
+ `**${w.nextLabel}:** ${plain(step)}`,
323
+ ];
293
324
  };
294
325
 
295
326
  export const renderBrief = (data, { lang = 'en', width = 72, now = Date.parse(data.generatedAt) || Date.now() } = {}) => {
@@ -298,7 +329,8 @@ export const renderBrief = (data, { lang = 'en', width = 72, now = Date.parse(da
298
329
  const summary = data.summary ?? { sessions: sessions.length, waitingOnUser: 0, active: 0 };
299
330
  const runs = data.next?.kind && data.next.kind !== 'none';
300
331
  const step = runs ? w.step[data.next.kind](Object.fromEntries(Object.entries(data.next.target ?? {}).map(([k, v]) => [k, bare(v)]))) : bare(suggestion(data, w));
301
- const out = [`## 🧭 ${[w.sessions(summary.sessions), w.waiting(summary.waitingOnUser), w.active(summary.active)].join(' · ')} · ${w.next}: ${plain(step)}`];
332
+ const out = [`## 🧭 ${[w.sessions(summary.sessions), w.waiting(summary.waitingOnUser), w.active(summary.active)].join(' · ')}`];
333
+ out.push(...opener(data, step, w));
302
334
  out.push(`*${w.window(data.scope?.since ?? '7d', (data.scope?.worktrees ?? []).length || 1)}*`);
303
335
  if (!sessions.length) out.push('', w.noSessions);
304
336
 
@@ -326,7 +358,7 @@ export const renderBrief = (data, { lang = 'en', width = 72, now = Date.parse(da
326
358
  out.push('', runs && data.next.say ? w.goLine(data.next.say) : w.noGo);
327
359
 
328
360
  const unread = Object.entries(data.sources ?? {}).filter(([, v]) => v === 'unknown').map(([k]) => k);
329
- const tail = [unread.length ? w.unknownSources(unread.join(', ')) : null, data.budget?.exhausted ? w.older : null].filter(Boolean);
361
+ const tail = [unread.length ? w.unknownSources(unread.join(', ')) : null, data.roadmap?.plansSkipped ? w.plansSkipped(data.roadmap.plansSkipped) : null, data.budget?.exhausted ? w.older : null].filter(Boolean);
330
362
  if (tail.length) out.push('', `*${tail.join(' ')}*`);
331
363
  return `${out.join('\n')}\n`;
332
364
  };
@@ -14,6 +14,7 @@ import { renderBrief } from './brief.mjs';
14
14
  import { chooseNextStep, writeNextStep } from './next-step.mjs';
15
15
  import { makeRedactor } from './redact.mjs';
16
16
  import { findTranscripts, makeBudget, readTranscriptLines, sessionRecord } from './transcripts.mjs';
17
+ import { listLive } from '../liveness.mjs';
17
18
 
18
19
  const SMALL_FILE_BYTES = 1024 * 1024;
19
20
  const GIT_TIMEOUT_MS = 5000;
@@ -72,15 +73,22 @@ const worktreesOf = (cwd, exec) => {
72
73
  // A plan scaffold nobody filled in: a row still holding a `<placeholder>`, or every row the same.
73
74
  const isTemplate = (rows) => rows.some((r) => /<[^<>]{1,40}>/u.test(r.title)) || (rows.length > 1 && new Set(rows.map((r) => r.title.trim())).size === 1);
74
75
 
75
- const plansIn = (root, budget, redact, local) => {
76
+ // `skipped.count` grows by one per Markdown file under plans/ that is no plan: unreadable, without task rows, an
77
+ // unfilled scaffold, or a name with a control character.
78
+ const plansIn = (root, budget, redact, local, skipped) => {
76
79
  const list = entries(join(root, 'plans'));
77
80
  if (!list) return null;
81
+ const markdown = list.filter((e) => e.isFile() && e.name.endsWith('.md'));
78
82
  // A name with a control character could carry its own lines into the brief or the `go` note; skip it.
79
- return list.filter((e) => e.isFile() && e.name.endsWith('.md') && !/[\p{Cc}\p{Cf}]/u.test(e.name)).sort((a, b) => a.name.localeCompare(b.name)).flatMap((e) => {
83
+ const named = markdown.filter((e) => !/[\p{Cc}\p{Cf}]/u.test(e.name));
84
+ skipped.count += markdown.length - named.length;
85
+ return named.sort((a, b) => a.name.localeCompare(b.name)).flatMap((e) => {
80
86
  const text = readSmallFile(join(root, 'plans', e.name), budget);
81
- if (text === null) return [];
82
- const rows = planRows(text);
83
- if (!rows.length || isTemplate(rows)) return [];
87
+ const rows = text === null ? [] : planRows(text);
88
+ if (!rows.length || isTemplate(rows)) {
89
+ skipped.count += 1;
90
+ return [];
91
+ }
84
92
  const open = rows.filter((r) => !r.done);
85
93
  const done = rows.length - open.length;
86
94
  let mtime = null;
@@ -108,12 +116,26 @@ const litgoalOf = (root, budget, redact) => {
108
116
  };
109
117
  };
110
118
 
111
- const handoffsOf = (root, budget, redact) => (entries(root) ?? [])
119
+ // The first item under a handoff's `## Next` heading, without its list marker, or null.
120
+ const nextOfHandoff = (text) => {
121
+ const lines = text.split('\n');
122
+ const at = lines.findIndex((l) => /^#{2,3}\s+Next\b/iu.test(l));
123
+ if (at === -1) return null;
124
+ for (const line of lines.slice(at + 1)) {
125
+ if (/^#{1,6} /u.test(line)) return null;
126
+ const item = line.replace(/^\s*(?:[-*+]|\d+[.)])\s+/u, '').replace(/^\s*-\s*\[[ xX]\]\s*/u, '').trim();
127
+ if (item) return item;
128
+ }
129
+ return null;
130
+ };
131
+
132
+ const handoffsOf = (root, budget, redact, local) => (entries(root) ?? [])
112
133
  .filter((e) => e.isFile() && /^HANDOFF.*\.md$/u.test(e.name))
113
134
  .map((e) => {
114
135
  const text = readSmallFile(join(root, e.name), budget) ?? '';
115
136
  const headings = text.split('\n').slice(0, 40).filter((l) => /^#{1,3} /u.test(l)).map((l) => clipToWidth(redact(l), 100));
116
- return { worktree: redact(root), file: e.name, headings };
137
+ const next = nextOfHandoff(text);
138
+ return { worktree: redact(root), file: e.name, headings, local, next: next ? clipToWidth(redact(next), 100) : null };
117
139
  });
118
140
 
119
141
  const branchOf = (root, exec) => {
@@ -160,7 +182,7 @@ const stacksOf = (stateDir, budget, redact) => {
160
182
  };
161
183
 
162
184
  const known = (list) => (list === null ? 'unknown' : 'ok');
163
- const statusRank = { 'waiting-on-user': 0, active: 1, ended: 2, unknown: 3 };
185
+ const statusRank = { 'waiting-on-user': 0, active: 1, idle: 2, done: 3, ended: 4, unknown: 5 };
164
186
 
165
187
  export const collectRewind = ({
166
188
  cwd = process.cwd(),
@@ -188,16 +210,36 @@ export const collectRewind = ({
188
210
  for (const { root: r, dir } of stateDirs) {
189
211
  for (const e of entries(dir) ?? []) {
190
212
  const m = /^([A-Za-z0-9._:-]{1,160})\.json$/.exec(e.name);
191
- if (e.isFile() && m && !/\.(?:snapshot|stack|motion)$/.test(m[1]) && !owner.has(m[1])) owner.set(m[1], r);
213
+ if (e.isFile() && m && !/\.(?:snapshot|stack|motion|live)$/.test(m[1]) && !owner.has(m[1])) owner.set(m[1], r);
192
214
  }
193
215
  }
216
+ // Plans, goals, handoffs and stacks are small and come first, so long transcripts cannot use up the read budget
217
+ // before them.
218
+ const collectEach = (read) => {
219
+ const results = roots.map(read);
220
+ return results.every((v) => v === null) ? null : results.flatMap((v) => v ?? []);
221
+ };
222
+ const skipped = { count: 0 };
223
+ const plans = collectEach((r) => plansIn(r, budget, redact, resolve(r) === start, skipped));
224
+ const litgoal = collectEach((r) => {
225
+ const goal = litgoalOf(r, budget, redact);
226
+ return goal ? [{ ...goal, local: resolve(r) === start }] : null;
227
+ });
228
+ const handoffs = roots.flatMap((r) => handoffsOf(r, budget, redact, resolve(r) === start));
229
+ const stackLists = stateDirs.map(({ dir }) => stacksOf(dir, budget, redact));
230
+ const workflows = stackLists.every((v) => v === null) ? null : stackLists.flatMap((v) => v ?? []);
231
+ const liveness = new Map(stateDirs.flatMap(({ dir }) => listLive(dir, now).map((r) => [r.id, r.state])));
232
+ // A conversation whose start-work frame names a plan with every row ticked is done.
233
+ const finishedPlans = new Set((plans ?? []).filter((p) => p.finished).map((p) => `${p.worktree}\u0000${p.plan}`));
234
+ const finishedIn = (id, root) => (workflows ?? []).some((f) => f.sessionId === id && f.ref?.plan && finishedPlans.has(`${redact(root)}\u0000${f.ref.plan}`));
235
+
194
236
  const geminiDir = join(home, '.gemini', 'antigravity-cli');
195
237
  const transcripts = owner.size ? findTranscripts(geminiDir, [...owner.keys()]) : { status: 'unknown', files: [] };
196
238
  const sessions = [];
197
239
  for (const { id, path } of transcripts.files) {
198
240
  if (sessions.length >= limit || budget.exhausted) break;
199
241
  const lines = readTranscriptLines(path, budget);
200
- const session = lines ? sessionRecord(lines, { redact, now, cwd: owner.get(id) }) : null;
242
+ const session = lines ? sessionRecord(lines, { redact, now, cwd: owner.get(id), live: liveness.get(id) ?? null, finished: finishedIn(id, owner.get(id)) }) : null;
201
243
  if (!session || (session.lastMs !== null && now - session.lastMs > sinceMs)) continue;
202
244
  session.sessionId = id;
203
245
  session.id8 = id.slice(0, 8);
@@ -206,20 +248,8 @@ export const collectRewind = ({
206
248
  sessions.push(session);
207
249
  }
208
250
 
209
- const collectEach = (read) => {
210
- const results = roots.map(read);
211
- return results.every((v) => v === null) ? null : results.flatMap((v) => v ?? []);
212
- };
213
- const plans = collectEach((r) => plansIn(r, budget, redact, resolve(r) === start));
214
- const litgoal = collectEach((r) => {
215
- const goal = litgoalOf(r, budget, redact);
216
- return goal ? [{ ...goal, local: resolve(r) === start }] : null;
217
- });
218
- const handoffs = roots.flatMap((r) => handoffsOf(r, budget, redact));
219
251
  const commits = collectEach((r) => commitsOf(r, sinceMs, now, exec, redact));
220
- const stackLists = stateDirs.map(({ dir }) => stacksOf(dir, budget, redact));
221
252
  const branches = new Map(roots.map((r) => [r, branchOf(r, exec)]));
222
- const workflows = stackLists.every((v) => v === null) ? null : stackLists.flatMap((v) => v ?? []);
223
253
 
224
254
  for (const session of sessions) {
225
255
  const frames = (workflows ?? []).filter((f) => f.sessionId === session.sessionId);
@@ -238,9 +268,9 @@ export const collectRewind = ({
238
268
  }
239
269
  sessions.sort((a, b) => statusRank[a.status] - statusRank[b.status] || (b.lastMs ?? 0) - (a.lastMs ?? 0));
240
270
 
241
- // This folder's open plans, then another folder's plans changed inside the window, newest first; a
242
- // finished plan elsewhere or one nobody touched lately is history, not roadmap.
243
- const recent = (p) => p.local || (!p.finished && p.mtime !== null && now - p.mtime <= sinceMs);
271
+ // Plans changed inside the window, this folder's first, newest first; a plan nobody touched lately is history,
272
+ // and so is a finished plan of another folder. This folder's finished plans count as done.
273
+ const recent = (p) => p.mtime !== null && now - p.mtime <= sinceMs && (p.local || !p.finished);
244
274
  const orderedPlans = (plans ?? []).filter(recent).sort((a, b) => Number(b.local) - Number(a.local) || (b.mtime ?? 0) - (a.mtime ?? 0));
245
275
  const shownPlans = orderedPlans.slice(0, PLAN_LIMIT);
246
276
  const localGoals = (litgoal ?? []).filter((g) => g.local);
@@ -267,6 +297,7 @@ export const collectRewind = ({
267
297
  roadmap: {
268
298
  plans: shownPlans,
269
299
  plansOmitted: orderedPlans.length - shownPlans.length,
300
+ plansSkipped: skipped.count,
270
301
  // Another folder's finished objective is history.
271
302
  litgoal: (litgoal ?? []).filter((g) => g.local || g.status !== 'complete'),
272
303
  progress: roadmapItems.length ? aggregateProgress(roadmapItems) : progressOf(null, null),
@@ -140,7 +140,7 @@ export const waitingReason = (lines) => {
140
140
  };
141
141
 
142
142
  // One session's record from its agy transcript lines.
143
- export const sessionRecord = (lines, { redact = (t) => t, now = Date.now(), cwd: workspace = null } = {}) => {
143
+ export const sessionRecord = (lines, { redact = (t) => t, now = Date.now(), cwd: workspace = null, live = null, finished = false } = {}) => {
144
144
  if (!lines || !lines.length) return null;
145
145
  let cwd = workspace;
146
146
  let started = null;
@@ -189,7 +189,10 @@ export const sessionRecord = (lines, { redact = (t) => t, now = Date.now(), cwd:
189
189
  const changed = [...new Set(files.reverse())].slice(0, 5).map((p) => redact(relativeFile(p)));
190
190
  const asked = [...new Set([prompts[0], prompts.at(-1)].filter(Boolean))].slice(0, 2).map((t) => clip(redact(t), 160));
191
191
  const waiting = lastEntry?.role === 'assistant' && WAITING_TEXT.test(lastEntry.text.slice(-400));
192
- const status = last === null ? 'unknown' : waiting ? 'waiting-on-user' : now - last < ACTIVE_MS ? 'active' : 'ended';
192
+ // A question on record wins; then a finished plan; then the hooks' liveness record (`alive`, `idle`); the
193
+ // transcript's own clock decides only when neither says more.
194
+ const clock = last === null ? 'unknown' : now - last < ACTIVE_MS ? 'active' : 'ended';
195
+ const status = waiting ? 'waiting-on-user' : finished ? 'done' : live === 'alive' ? 'active' : live === 'idle' ? 'idle' : clock;
193
196
  // agy does not carry a sessionId in the transcript; use the conversation folder name if available.
194
197
  const sessionId = lines.find((l) => typeof l.conversation_id === 'string')?.conversation_id ?? null;
195
198
  return {
@@ -5,6 +5,7 @@ import { targetPaths } from './lib/policy.mjs';
5
5
  import { clip } from './lib/redact.mjs';
6
6
  import { MOTION_ROUTE, recordMotionTool } from './lib/motion.mjs';
7
7
  import { recordLane } from './lib/lanes.mjs';
8
+ import { markLive } from './lib/liveness.mjs';
8
9
  import { READ_ONLY_DISCIPLINES, applyStackEvent, readStack, writeStack } from './lib/workflow-stack.mjs';
9
10
  import { ROUTE_LOOKS } from '../hud/looks.mjs';
10
11
 
@@ -40,6 +41,7 @@ function startLoadedSkill(payload, args) {
40
41
  // While a route is active every tool call leaves one ledger line, and a call that touches a goal record binds that
41
42
  // record to this conversation, which is what lets the Stop hook hold the turn on its open criteria.
42
43
  run((payload) => {
44
+ try { markLive(workspaceOf(payload), payload.conversationId, 'alive'); } catch { /* liveness never blocks */ }
43
45
  if (toolName(payload)) startLoadedSkill(payload, toolArgs(payload));
44
46
  const state = activeRoute(payload);
45
47
  if (!state || state.corrupt) return {};
@@ -34,8 +34,10 @@ function goActivation(step, conversationId) {
34
34
  return `LitGravity: \`go\` continues the paused ${step.target?.skill ?? 'route'} at ${step.target?.stage ?? 'its current stage'}.\nBegin your reply with \`🔥 LIT CONTINUES · ${step.target?.skill ?? 'route'}\` once. Keep the criteria, plan and ledger you hold; reload no skill and start no new run.`;
35
35
  case 'continue-work':
36
36
  return `LitGravity: \`go\` continues the active start-work run${step.target?.plan ? ` on ${step.target.plan}` : ''}.\nBegin your reply with \`🔥 LIT CONTINUES · start-work\` once. Carry on from the first unticked row.`;
37
- case 'start-plan':
38
- return activation({ route: 'start-work', keyword: 'start', bare: false, resume: false, restart: false, direct: false, empty: false }, conversationId, 'ignite');
37
+ case 'start-plan': {
38
+ const text = activation({ route: 'start-work', keyword: 'start', bare: false, resume: false, restart: false, direct: false, empty: false }, conversationId, 'ignite');
39
+ return step.target?.plan ? `${text}\nThe user typed \`go\`: the plan to execute is ${step.target.plan}.` : text;
40
+ }
39
41
  default:
40
42
  return null;
41
43
  }
@@ -13,7 +13,7 @@ function hasRecentLitSessions(workspace, env) {
13
13
  try {
14
14
  const now = Date.now();
15
15
  for (const name of readdirSync(dir)) {
16
- if (!name.endsWith('.json') || name.includes('.stack') || name.includes('.snapshot') || name.includes('.lanes')) continue;
16
+ if (!name.endsWith('.json') || name.includes('.stack') || name.includes('.snapshot') || name.includes('.lanes') || name.includes('.live')) continue;
17
17
  const full = join(dir, name);
18
18
  try {
19
19
  if (now - statSync(full).mtimeMs < RECENT_SESSION_MS) return true;
@@ -1,16 +1,25 @@
1
- import { existsSync, readdirSync, statSync } from 'node:fs';
1
+ import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
2
2
  import { join } from 'node:path';
3
- import { run, holdStop, activeRoute, readSession, writeSession, workspaceOf } from './lib/common.mjs';
3
+ import { run, holdStop, activeRoute, readSession, writeSession, workspaceOf, stateRoot } from './lib/common.mjs';
4
4
  import { continuationHold } from './lib/continuation.mjs';
5
5
  import { boundaryProblem, BOUNDARY_HOLDS } from './lib/boundary.mjs';
6
6
  import { lastUserRequest } from './lib/transcript.mjs';
7
7
  import { MOTION_ROUTE, evaluateMotionStop } from './lib/motion.mjs';
8
8
  import { makeBudget, readTranscriptLines, waitingReason } from './lib/rewind/transcripts.mjs';
9
+ import { writeNextStep } from './lib/rewind/next-step.mjs';
10
+ import { uncoveredPaths } from '../skills/lit-plan/scripts/check-plan.mjs';
11
+ import { markLive } from './lib/liveness.mjs';
9
12
 
13
+ // The newest plans/*.md written since the route started, as `plans/<name>.md`, or null.
10
14
  function planWrittenSince(cwd, since) {
11
15
  const dir = join(cwd, 'plans');
12
- if (!existsSync(dir)) return false;
13
- return readdirSync(dir).some((f) => f.endsWith('.md') && statSync(join(dir, f)).mtimeMs >= since);
16
+ if (!existsSync(dir)) return null;
17
+ let best = null;
18
+ for (const f of readdirSync(dir).filter((name) => name.endsWith('.md'))) {
19
+ const mtime = statSync(join(dir, f)).mtimeMs;
20
+ if (mtime >= since && (!best || mtime > best.mtime)) best = { plan: `plans/${f}`, mtime };
21
+ }
22
+ return best?.plan ?? null;
14
23
  }
15
24
 
16
25
  const WAIT_READ_BYTES = 512 * 1024;
@@ -32,8 +41,15 @@ function settle(payload, out) {
32
41
  // holds are bounded by continuation.mjs; the motion gate holds at most twice, then asks the reply to say the render is
33
42
  // not done. Only a normal end of turn is held: errors, cancellations and limits end.
34
43
  run((payload) => {
44
+ const finish = (r) => {
45
+ // A held turn goes on; any other end leaves the conversation idle until the next tool call.
46
+ if (r?.decision !== 'continue') {
47
+ try { markLive(workspaceOf(payload), payload.conversationId, 'idle'); } catch { /* liveness never blocks */ }
48
+ }
49
+ return settle(payload, r);
50
+ };
35
51
  const out = decide(payload);
36
- return out && typeof out.then === 'function' ? out.then((r) => settle(payload, r)) : settle(payload, out);
52
+ return out && typeof out.then === 'function' ? out.then(finish) : finish(out);
37
53
  });
38
54
 
39
55
  function decide(payload) {
@@ -57,8 +73,21 @@ function decide(payload) {
57
73
  const reason = continuationHold(payload, state, request?.text, turn);
58
74
  return reason ? holdStop(reason) : {};
59
75
  }
76
+ const workspace = workspaceOf(payload);
77
+ const plan = planWrittenSince(workspace, state.activatedAt ?? 0);
78
+ if (plan && state.stopHeldFor !== turn) {
79
+ const outside = uncoveredPaths(readFileSync(join(workspace, plan), 'utf8'), workspace);
80
+ if (outside.length) {
81
+ writeSession(payload, { ...state, stopHeldFor: turn });
82
+ return holdStop(`LitGravity lit-plan gate: ${plan} names ${outside.slice(0, 3).join(', ')}${outside.length > 3 ? ` and ${outside.length - 3} more` : ''} outside the project. Ask the user which roots the work may use and with which actions, add one line "Scope roots: <path> (<actions>)" per root under ## Scope, then end the turn.`);
83
+ }
84
+ }
85
+ if (plan) {
86
+ // A saved plan arms `go`: the same conversation can start it with one word within 30 minutes.
87
+ writeNextStep(stateRoot(), payload.conversationId, { kind: 'start-plan', target: { plan } });
88
+ return {};
89
+ }
60
90
  if (state.stopHeldFor === turn) return {};
61
- if (planWrittenSince(workspaceOf(payload), state.activatedAt ?? 0)) return {};
62
91
  writeSession(payload, { ...state, stopHeldFor: turn });
63
92
  return holdStop('LitGravity lit-plan gate: this planning turn has no plan file yet. Write the plan to plans/<slug>.md (task rows as "- [ ] N. <title>"), then end the turn and point the user to `lit start`.');
64
93
  }
@@ -21,6 +21,7 @@ import { pluginVersion, sessionPath, stateRoot } from '../hooks/lib/common.mjs';
21
21
  import { activePlan, openGoal, planRows } from '../hooks/lib/continuation.mjs';
22
22
  import { readStack } from '../hooks/lib/workflow-stack.mjs';
23
23
  import { readLanes } from '../hooks/lib/lanes.mjs';
24
+ import { listLive } from '../hooks/lib/liveness.mjs';
24
25
  import { DONE_MS, REVIEW_LANES, ROUTE_LOOKS, lookOf } from './looks.mjs';
25
26
 
26
27
  const IGNITION_MS = 90_000;
@@ -523,6 +524,9 @@ function segments(input, ctx) {
523
524
  }
524
525
  if (state === 'error') segs.push({ id: 'attention', prio: 2, forms: [[sp(`${g.fail} error`, 'red', { b: true })], [sp(g.fail, 'red', { b: true })]] });
525
526
 
527
+ const others = othersSegment(input, ctx);
528
+ if (others) segs.push(others);
529
+
526
530
  const cost = costOf(input);
527
531
  if (cost !== null) segs.push({ id: 'cost', prio: 9, forms: [[sp(`$${cost < 10 ? cost.toFixed(2) : cost.toFixed(1)}`)]] });
528
532
 
@@ -662,8 +666,47 @@ function threadSegment(route, ctx) {
662
666
  return { id: 'threads', prio: 5, forms: [parts, short.length ? short : parts] };
663
667
  }
664
668
 
669
+ // A start-work in another conversation whose plan is all ticked: shown as done for this long after its last hook event.
670
+ const FINISHED_MS = 60_000;
671
+
672
+ function finishedWork(dir, id, env) {
673
+ try {
674
+ const state = JSON.parse(readFileSync(sessionPath(dir, id, env), 'utf8'));
675
+ if (state?.route !== 'start-work') return false;
676
+ const plan = activePlan({ conversationId: id, workspacePaths: [dir] }, dir);
677
+ const rows = plan ? planRows(readFileSync(join(dir, plan), 'utf8')) : [];
678
+ return rows.length > 0 && rows.every((r) => r.done);
679
+ } catch {
680
+ return false;
681
+ }
682
+ }
683
+
684
+ // The other conversations of this workspace, from their liveness records: `+N running · M idle`, and `K done` for a
685
+ // start-work that finished in the last minute. One row has room for counts only; a lone other session still shows.
686
+ function othersSegment(input, ctx) {
687
+ const { g, env, now } = ctx;
688
+ const self = input.conversation_id ?? input.conversationId;
689
+ const dir = workspaceDirs(input)[0];
690
+ const probe = dir ? sessionPath(dir, 'probe', env) : null;
691
+ if (!probe) return null;
692
+ const counts = { running: 0, idle: 0, done: 0 };
693
+ for (const rec of listLive(dirname(probe), now)) {
694
+ if (rec.id === self || rec.state === 'ended') continue;
695
+ if (finishedWork(dir, rec.id, env)) {
696
+ if (now - Date.parse(rec.at) <= FINISHED_MS) counts.done += 1;
697
+ } else {
698
+ counts[rec.state === 'alive' ? 'running' : 'idle'] += 1;
699
+ }
700
+ }
701
+ const parts = Object.entries(counts).filter(([, n]) => n > 0).map(([k, n]) => `${n} ${k}`);
702
+ if (!parts.length) return null;
703
+ const total = counts.running + counts.idle + counts.done;
704
+ const sp = (t) => ({ t, role: 'dim' });
705
+ return { id: 'others', prio: 6, forms: [[sp(`+${parts.join(` ${g.mid} `)}`)], [sp(`+${total} other${total === 1 ? '' : 's'}`)], [sp(`+${total}`)]] };
706
+ }
707
+
665
708
  // Display order: the mark, model [effort], context, quota, then the route and its map, then the extras.
666
- const ORDER = ['brand', 'model', 'ctx', 'quota', 'lit', 'attention', 'flow', 'lanes', 'threads', 'cost', 'tasks', 'git', 'title'];
709
+ const ORDER = ['brand', 'model', 'ctx', 'quota', 'lit', 'attention', 'flow', 'lanes', 'threads', 'others', 'cost', 'tasks', 'git', 'title'];
667
710
 
668
711
  function layout(segs, pick, g) {
669
712
  const shown = ORDER.flatMap((id) => segs.filter((s) => s.id === id && pick.get(s) !== null));
@@ -2,5 +2,5 @@
2
2
  "$schema": "https://antigravity.google/schemas/v1/plugin.json",
3
3
  "name": "litgravity",
4
4
  "description": "LitFamily workflows for the Antigravity CLI: bare lit activation, planning, evidence-bound execution, review, research, handoff and Korean prose care.",
5
- "version": "0.1.2"
5
+ "version": "0.1.3"
6
6
  }
@@ -49,11 +49,11 @@ verdicts: [PASS, FAIL, BLOCKED]
49
49
 
50
50
  The collector draws the brief in Markdown (`plugin/hooks/lib/rewind/brief.mjs`), because agy's chat pane renders headings, bold, quotes, tables and code blocks; the shape is the same every time, so a tired reader finds each part where it was last time. Five parts, in this order:
51
51
 
52
- 1. **Headline.** One `## 🧭` line: conversations found, how many wait on the user, how many are active, and the next step in words: `세션 5개 · 나를 기다리는 것 1 · 진행 중 1 · 다음: …` / `5 sessions · 1 waits on you · 1 active · next: …`. A dim line under it gives the window and how many folders were read.
53
- 2. **Live cards, grouped by folder and branch.** Conversations that wait on the user or are active get a `### 🌿 branch · folder` heading per group and one quoted card each: a status badge (🟠 waiting on you, 🟢 active; see `references/status-taxonomy.md`) with why it waits, its `id8`, its route, how long ago it moved and `this conversation` / `이 대화`; the goal in bold; a real gauge with the next items, or the known facts after ⏳ (how long it ran, its last ask); ✅ what was written and committed, or before any write the tools it used most; ▶ what is next for it (answer its question, resume its paused route, its route stage, or its last tool call by base name, never a command line).
52
+ 1. **Headline and opener.** One `## 🧭` line: conversations found, how many wait on the user, how many are active (`세션 5개 · 나를 기다리는 것 1 · 진행 중 1` / `5 sessions · 1 waits on you · 1 active`). Three lines follow for a reader who reads nothing else: **Done so far** (finished plans here, sessions done, commits in the window), **Doing now** (up to two active conversations by id and goal) and **Next** (the step in the box). A dim line under them gives the window and how many folders were read.
53
+ 2. **Live cards, grouped by folder and branch.** Conversations that wait on the user, are active, idle or done get a `### 🌿 branch · folder` heading per group and one quoted card each: a status badge (🟠 waiting on you, 🟢 active, 💤 idle, ✅ done; see `references/status-taxonomy.md`) with why it waits, its `id8`, its route, how long ago it moved and `this conversation` / `이 대화`; the goal in bold; a real gauge with the next items, or the known facts after ⏳ (how long it ran, its last ask); ✅ what was written and committed, or before any write the tools it used most; ▶ what is next for it (answer its question, resume its paused route, its route stage, or its last tool call by base name, never a command line).
54
54
  3. **Ended conversations, one table row each** (`### ⚪ Ended · N`: id, where, goal, ago, done), at most eight and a count of the rest. Each row fits on one line at 120 columns: the age is its largest unit and done is a commit count or a file count.
55
- 4. **Roadmap timeline** (`### 🗺️`, with this folder's gauge): ✓ commits with their dates and branch, ▶ the current item of each open plan here and of plans another folder changed inside the window (with its folder name), ○ the items after it, then litgoal objectives. Unfilled plan scaffolds, stale plans elsewhere and another folder's finished objectives are left out.
56
- 5. **One recommended next step** in a box, then one line. A step that runs on `go` shows its command and the word to type, and the line says "Type `go` to continue." When nothing runs on `go`, the box still recommends a real step from the records, in this order: a conversation waiting on the user, a paused route, an open plan item (a live conversation's folder first), the newest other active conversation, the newest ended one; the line then says nothing runs on its own.
55
+ 4. **Roadmap timeline** (`### 🗺️`, with this folder's gauge): ✓ commits with their dates and branch, ▶ the current item of each open plan changed inside the window, here or in another folder (with its folder name), ○ the items after it, then litgoal objectives. Plans are held to the window here too. Unfilled plan scaffolds and files without task rows are skipped and counted on the last line; another folder's finished plans and objectives are left out.
56
+ 5. **One recommended next step** in a box (an untagged code fence), then one line. A step that runs on `go` shows its command and the word to type, and the line says "Type `go` to continue." When nothing runs on `go`, the box still recommends a real step from the records, in this order: a conversation waiting on the user, a paused route, an open plan item (a live conversation's folder first), the newest other active conversation, the newest ended one, the first item under `## Next` in this folder's `HANDOFF*.md`; the line then says nothing runs on its own.
57
57
 
58
58
  **Progress gauges (D9).** A gauge appears only when the collector provides both done and total as real integers: `[▉▉▉░░] 3/5`. When the total is unknown, the card shows known facts in words instead (`⏳ 2h 19m of work · last ask: …`). Never show `?/?`, `[???]`, `k/?` or any question-mark placeholder. The gauge is the progress; do not compute progress from prose like "about halfway".
59
59
 
@@ -99,20 +99,23 @@ The collector (`plugin/hooks/lib/rewind/collect.mjs`, served as `node <skill-roo
99
99
  | agy transcripts, `~/.gemini/antigravity-cli/brain/<id>/.system_generated/logs/transcript.jsonl`, only for conversations this workspace's route state lists | per session: first and last ask, tools used, files changed, last model text, status | `transcripts: unknown` |
100
100
  | `plans/*.md` checkbox rows | open plans, current item, done/total, remaining names | `plans: unknown` |
101
101
  | `.litgravity/goals/active.json` | objective and passed/total criteria | `litgoal: unknown` |
102
- | `HANDOFF*.md` | headings from the first 40 lines only | `handoffs: unknown` |
102
+ | `HANDOFF*.md` | headings from the first 40 lines, and the first item under `## Next` | `handoffs: unknown` |
103
+ | Route-state `*.live.json` liveness records (written by PostToolUse and Stop) | `alive` / `idle` per conversation; `ended` once stale | status falls back to the transcript clock |
103
104
  | `git log --since` | commits in the window, matched to sessions by time and branch | `git: unknown` |
104
105
  | Route-state `*.stack.json` files | running and paused disciplines with stage and k/n | `workflowStack: unknown` |
105
106
 
106
- Transcripts are read head (64 KiB) and tail (256 KiB) only, under one 8 MiB budget for the whole run, through descriptors opened without following links. Every string is redacted before it leaves the collector: credential shapes (provider keys, bearer tokens, JWT, API keys), `NAME=value` with a secret-like name, URI userinfo, any current environment value of eight or more characters, and the home directory (shown as `~`).
107
+ Plans, goals, handoffs and stacks are read first, so a long transcript cannot use up the budget before them. Transcripts are read head (64 KiB) and tail (256 KiB) only, under one 8 MiB budget for the whole run, through descriptors opened without following links. Every string is redacted before it leaves the collector: credential shapes (provider keys, bearer tokens, JWT, API keys), `NAME=value` with a secret-like name, URI userinfo, any current environment value of eight or more characters, and the home directory (shown as `~`).
107
108
 
108
109
  ## Status taxonomy
109
110
 
110
111
  - `waiting-on-user`: the session's last word was the model asking something, or it holds a paused workflow frame.
111
- - `active`: written to within the last 15 minutes and not waiting.
112
- - `ended`: quiet for longer than that.
112
+ - `done`: its start-work frame names a plan with every row ticked.
113
+ - `active`: its liveness record says `alive`, or, without one, it was written to within the last 15 minutes.
114
+ - `idle`: its liveness record says `idle`: the last turn ended and the conversation waits for its next prompt.
115
+ - `ended`: quiet past the transcript clock, or a liveness record left alone past its limit (agy fires no session-end event).
113
116
  - `unknown`: the transcript held no timestamp.
114
117
 
115
- Sessions waiting on the user come first, then active ones, newest first.
118
+ Sessions waiting on the user come first, then active, idle, done and ended ones, newest first.
116
119
 
117
120
  ## The next step
118
121
 
@@ -5,7 +5,10 @@ The collector draws both briefs from the same records (`rewind.mjs --brief --lan
5
5
  ## English
6
6
 
7
7
  ````markdown
8
- ## 🧭 5 sessions · 1 waits on you · 1 active · next: Answer 655f39d3 in shop: “Should I also cap them at three?”
8
+ ## 🧭 5 sessions · 1 waits on you · 1 active
9
+ **Done so far:** 2 commits
10
+ **Doing now:** `f06fb727` lit pptx quarterly review deck
11
+ **Next:** Answer 655f39d3 in shop: “Should I also cap them at three?”
9
12
  *last 7d · 2 folders read*
10
13
 
11
14
  ### 🌿 `feat/checkout` · shop
@@ -38,7 +41,7 @@ The collector draws both briefs from the same records (`rewind.mjs --brief --lan
38
41
  - ○ later · Ledger entry
39
42
  - ○ later · Email receipt
40
43
 
41
- ```text
44
+ ```
42
45
  ╭─ RECOMMENDED NEXT STEP ─────────────────────────────────────
43
46
  │ Answer 655f39d3 in shop: “Should I also cap them at three?”
44
47
  ╰─────────────────────────────────────────────────────────────
@@ -52,7 +55,10 @@ Nothing runs on its own here: open that conversation, or say what to do.
52
55
  ## Korean
53
56
 
54
57
  ````markdown
55
- ## 🧭 세션 5개 · 나를 기다리는 것 1 · 진행 중 1 · 다음: shop의 655f39d3에 답하기: “Should I also cap them at three?”
58
+ ## 🧭 세션 5개 · 나를 기다리는 것 1 · 진행 중 1
59
+ **지금까지 한 일:** 커밋 2개
60
+ **지금 하는 일:** `f06fb727` lit pptx quarterly review deck
61
+ **다음:** shop의 655f39d3에 답하기: “Should I also cap them at three?”
56
62
  *최근 7d · 폴더 2곳 읽음*
57
63
 
58
64
  ### 🌿 `feat/checkout` · shop
@@ -85,7 +91,7 @@ Nothing runs on its own here: open that conversation, or say what to do.
85
91
  - ○ 나중 · Ledger entry
86
92
  - ○ 나중 · Email receipt
87
93
 
88
- ```text
94
+ ```
89
95
  ╭─ 추천 다음 단계 ─────────────────────────────────────────────
90
96
  │ shop의 655f39d3에 답하기: “Should I also cap them at three?”
91
97
  ╰──────────────────────────────────────────────────────────────
@@ -5,8 +5,10 @@ The collector assigns every session exactly one status. The brief renders it in
5
5
  | Status | Set when | English | Korean |
6
6
  | --- | --- | --- | --- |
7
7
  | `waiting-on-user` | The session's last word is the model asking something, or it holds a paused workflow frame | waiting on you | 나를 기다림 |
8
- | `active` | A transcript write within the last 15 minutes and not waiting | active | 진행 중 |
9
- | `ended` | Quiet for longer than 15 minutes | ended | 끝남 |
8
+ | `done` | Its start-work frame names a plan with every row ticked | done | 완료 |
9
+ | `active` | Its liveness record says `alive`; without one, a transcript write within the last 15 minutes | active | 진행 중 |
10
+ | `idle` | Its liveness record says `idle`: the turn ended and it waits for the next prompt | idle | 쉬는 중 |
11
+ | `ended` | Quiet for longer than 15 minutes, or a liveness record past its limit (10 minutes alive, 2 hours idle) | ended | 끝남 |
10
12
  | `unknown` | The transcript held no timestamp | unknown | 모름 |
11
13
 
12
14
  ## Sources
@@ -18,7 +20,7 @@ Each `sources` entry is `ok` or `unknown`. An unknown source is named on the bri
18
20
  | `transcripts` | `~/.gemini/antigravity-cli/brain/<id>/.system_generated/logs/transcript.jsonl` for the lit conversations of this workspace (ids from its route-state folder) |
19
21
  | `plans` | `plans/*.md` checkbox rows |
20
22
  | `litgoal` | `.litgravity/goals/active.json` |
21
- | `handoffs` | `HANDOFF*.md` headings |
23
+ | `handoffs` | `HANDOFF*.md` headings and the first item under `## Next` |
22
24
  | `git` | `git log --since` |
23
25
  | `workflowStack` | Route-state `*.stack.json` files |
24
26
 
@@ -143,6 +143,7 @@ It prints `PLAN_STRUCTURE_PASS` when the sections, row grammar, labels and numbe
143
143
  Then run the decision-complete checklist:
144
144
 
145
145
  - [ ] Every task names its files, its test and its acceptance check.
146
+ - [ ] A todo path outside the project has a `Scope roots: <path> (<actions>)` line the user agreed to.
146
147
  - [ ] Every Must have maps to at least one task's acceptance.
147
148
  - [ ] Verification names exact commands and one real-surface probe.
148
149
  - [ ] Words like "TBD", "maybe", "or alternatively", "as appropriate" are gone.
@@ -203,7 +204,7 @@ Off limits on this route: `send_command_input`, `define_subagent`, `browser_suba
203
204
 
204
205
  Stop when the plan file is written and passes the checklist, or when a missing answer blocks every useful task (then the plan carries the question as row 1 and the reply says `BLOCKED: <question>`). After two failed attempts at one section, surface what you tried and ask.
205
206
 
206
- Reply in reader form: the plan path, the TL;DR, the number of tasks, any assumption the user should confirm, and the next action: `lit start plans/<slug>.md` to execute it. Approval covers plan generation; implementation, commit, push, versioning and publishing each need their own go-ahead. Keep logs, lane verdicts and command lists in the draft and ledger unless the user asks for them.
207
+ Reply in reader form: the plan path, the TL;DR, the number of tasks, any assumption the user should confirm, and the next action: `go` in this conversation within 30 minutes, or `lit start plans/<slug>.md`, to execute it. Approval covers plan generation; implementation, commit, push, versioning and publishing each need their own go-ahead. Keep logs, lane verdicts and command lists in the draft and ledger unless the user asks for them.
207
208
 
208
209
  ## Pitfalls
209
210
 
@@ -43,7 +43,7 @@ Detail earns its place when it removes executor judgment, protects a boundary or
43
43
  ## Plan structure
44
44
 
45
45
  1. TL;DR for humans (written last) and a one-line machine summary: effort, risk, deliverables.
46
- 2. Scope: must have, must not have.
46
+ 2. Scope: must have, must not have, and one `Scope roots: <absolute path> (<actions>)` line, at column zero, for each root outside the project that a todo names.
47
47
  3. Bootstrap: facts to re-read, dirty-worktree constraints, stale-state risks, the resume ledger path, bounded cleanup rules, and which approvals are withheld (commit, push, publish, version bump).
48
48
  4. Context and current evidence, and Decisions.
49
49
  5. Verification strategy and the Goal block.
@@ -54,6 +54,17 @@ Detail earns its place when it removes executor judgment, protects a boundary or
54
54
 
55
55
  A task that builds or changes a user-facing web interface names `frontend-ui-ux` in its verification (the interface probe across the responsive matrix, no HIGH finding left) and hands the acceptance verdict to `visual-qa`. A CLI, library or backend-only task names neither.
56
56
 
57
+ ## Scope roots (advisory)
58
+
59
+ A todo that names an absolute path outside the project (a data folder, a sibling checkout, a temp folder) needs a grant the user agreed to before the plan is saved. Ask which roots the work may use and with which actions (`read`, `write`, `execute`), then write one line per root under `## Scope`:
60
+
61
+ ```text
62
+ Scope roots: /srv/data (read)
63
+ Scope roots: /tmp/build-cache (read, write)
64
+ ```
65
+
66
+ A root covers itself and every path below it; `/srv/database` is not under `/srv/data`. `check-plan.mjs --check` reads only the Todos section outside code fences, ignores URLs and one-word slash routes, and fails with one line per uncovered path. The lit-plan Stop gate runs the same check on the saved plan and holds the turn once to ask for the missing line. The grant is advisory: no hook gates a tool call on it, and `start-work` treats an uncovered outside root as a boundary to stop at.
67
+
57
68
  ## Plan-row grammar (machine-checkable)
58
69
 
59
70
  Both row forms start at column zero:
@@ -9,7 +9,7 @@
9
9
  // which is why a planning turn may run it. Exit 0 = pass, 1 = findings, 2 = usage.
10
10
 
11
11
  import { existsSync, lstatSync, readFileSync } from 'node:fs';
12
- import { dirname, join, resolve } from 'node:path';
12
+ import { basename, dirname, join, resolve } from 'node:path';
13
13
  import { fileURLToPath } from 'node:url';
14
14
 
15
15
  export const SLUG_PATTERN = /^[a-z0-9]+(?:-[a-z0-9]+)*$/u;
@@ -53,7 +53,36 @@ function rowBlock(lines, at, rows) {
53
53
  return block.join('\n');
54
54
  }
55
55
 
56
- export function checkPlan(text, { complete = false } = {}) {
56
+ const SCOPE_ROOT = /^Scope roots:\s*(\/\S*?)\/?(?:\s+\(([^)]*)\))?\s*$/u;
57
+ // An absolute path of at least two segments after a space, quote, backtick or bracket: URLs (`https://…`) and
58
+ // one-word slash routes (`/hooks`, `/litgravity:lit-plan`) are not paths.
59
+ const ABSOLUTE = /(?<=^|[\s`'"(<[])\/[A-Za-z0-9._@+~-]+(?:\/[A-Za-z0-9._@+~-]+)+\/?/gu;
60
+ const under = (path, root) => path === root || path.startsWith(`${root}/`);
61
+
62
+ // Absolute paths that a todo row names outside the project and outside every `Scope roots: <path> (<actions>)` line.
63
+ // Only the Todos section outside code fences is read. The grant is advisory: the Stop hook asks for the line once,
64
+ // and nothing gates a tool call on it.
65
+ export function uncoveredPaths(text, root) {
66
+ const lines = visibleLines(text);
67
+ const roots = [root.replace(/\/+$/u, '')];
68
+ for (const { line } of lines) {
69
+ const m = SCOPE_ROOT.exec(line);
70
+ if (m) roots.push(m[1]);
71
+ }
72
+ const found = [];
73
+ let inTodos = false;
74
+ for (const { line } of lines) {
75
+ if (/^## /u.test(line)) inTodos = line.trimEnd() === '## Todos';
76
+ if (!inTodos) continue;
77
+ for (const raw of line.match(ABSOLUTE) ?? []) {
78
+ const path = raw.replace(/\/+$/u, '');
79
+ if (!roots.some((r) => under(path, r)) && !found.includes(path)) found.push(path);
80
+ }
81
+ }
82
+ return found;
83
+ }
84
+
85
+ export function checkPlan(text, { complete = false, root = null } = {}) {
57
86
  const problems = [];
58
87
  const lines = visibleLines(text);
59
88
 
@@ -99,6 +128,11 @@ export function checkPlan(text, { complete = false } = {}) {
99
128
  }
100
129
  });
101
130
 
131
+ if (root) {
132
+ for (const path of uncoveredPaths(text, root)) {
133
+ problems.push(`a todo names ${path}, outside the project: add a line "Scope roots: <path> (<actions>)" that covers it, after asking the user`);
134
+ }
135
+ }
102
136
  if (/<fill\b/u.test(text)) problems.push('unfilled <fill ...> placeholders remain: the plan is not decision-complete');
103
137
  if (complete) {
104
138
  for (const { line } of rows) if (/^- \[ \] /u.test(line)) problems.push(`row still open: ${line.trim()}`);
@@ -121,7 +155,9 @@ function checkFile(planPath, options) {
121
155
  }
122
156
  if (stat.isSymbolicLink() || !stat.isFile()) return fail(`FAIL PLAN_UNSAFE: ${path} must be a regular file`);
123
157
  if (stat.size > MAX_BYTES) return fail(`FAIL PLAN_TOO_LARGE: ${path}`);
124
- const result = checkPlan(readFileSync(path, 'utf8'), options);
158
+ // plans/<slug>.md sits one folder below its project; any other location leaves the outside-path check off.
159
+ const root = basename(dirname(path)) === 'plans' ? dirname(dirname(path)) : null;
160
+ const result = checkPlan(readFileSync(path, 'utf8'), { ...options, root });
125
161
  if (!result.ok) {
126
162
  for (const problem of result.problems) process.stderr.write(`FAIL ${problem}\n`);
127
163
  return 1;
@@ -24,6 +24,9 @@ Your next move: <fill: approve, steer, or ask for a high-accuracy review>.
24
24
 
25
25
  ## Scope
26
26
 
27
+ <!-- When a todo names an absolute path outside this project, ask the user and add one line per root, at column zero:
28
+ Scope roots: <absolute path> (<actions: read, write, execute>) -->
29
+
27
30
  ### Must have
28
31
  - <non-negotiable property, each one checkable>
29
32
 
@@ -70,7 +70,7 @@ Each of these needs the user's explicit word in this run, so stop at the boundar
70
70
  - `git commit`, `git push`, tags, branch deletion, `git reset --hard`, `git clean`, history rewrites, a stash of someone else's changes;
71
71
  - `npm publish`, registry writes, version bumps, release notes, package uploads;
72
72
  - writes to host configuration: `~/.gemini`, other tools' home folders, credential files, and `agy plugin install`, `update` or `remove`;
73
- - a new root outside the workspace, a dependency the plan did not list, a network call that needs approval, deletion of files outside the row's scope, anything under Must NOT have;
73
+ - a root outside the workspace that no `Scope roots: <path> (<actions>)` line grants (advisory, no hook checks it), a dependency the plan did not list, a network call that needs approval, deletion of files outside the row's scope, anything under Must NOT have;
74
74
  - credentials or accounts of any kind.
75
75
 
76
76
  The Bootstrap section's "Approvals withheld" line says which of these the user already granted. A grant covers the named action on the named paths for this run.