@venizia/vulcan 0.4.10-0 → 0.4.10-1

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.
@@ -3,6 +3,8 @@
3
3
  * created outside the project (V-B-08). Stores a package manager, runtime or the agent tool manage
4
4
  * themselves are allowed - a default list, extended by `guard.toolOwnedPaths` in the project config.
5
5
  * `TMPDIR` or `mktemp` pointed at the system temp directory is not allowed.
6
+ * It asks by default; `guard.outside: 'deny'` in the project config refuses instead, for agents where an ask can be
7
+ * approved unseen. A write into the agent tool scratchpad is always denied.
6
8
  *
7
9
  * It guards against drift, not against an attacker, and a guard that blocks every call when its install
8
10
  * is broken costs more than it protects. So input it cannot read passes, and so does a missing package or
@@ -32,12 +34,14 @@ try {
32
34
  if (input) {
33
35
  const projectRoot = process.env.CLAUDE_PROJECT_DIR ?? input.cwd ?? process.cwd();
34
36
  let toolOwnedPaths: string[] = [];
37
+ let outside: string = GuardDecisions.ASK;
35
38
 
36
39
  try {
37
40
  const { ConfigLoader } = await import('../../src/config/index.ts');
38
41
  const loaded = await ConfigLoader.load({ root: projectRoot });
39
42
 
40
43
  toolOwnedPaths = loaded.ok ? loaded.config.guard.toolOwnedPaths : [];
44
+ outside = loaded.ok ? loaded.config.guard.outside : GuardDecisions.ASK;
41
45
  } catch (error) {
42
46
  console.error(
43
47
  `vulcan: the guard-outside hook could not read the project config (${error instanceof Error ? error.message : String(error)}) - the default allowlist applies`,
@@ -52,24 +56,39 @@ try {
52
56
  const places =
53
57
  'Scratch files go under .agents/local/tmp/<task>/ (worktrees under .agents/local/worktrees/, clones under .agents/local/clones/), never in /tmp or the home folder.';
54
58
 
59
+ const isDeny = isScratchpad || outside === GuardDecisions.DENY;
60
+ let reason: string[];
61
+
62
+ if (isScratchpad) {
63
+ reason = [
64
+ 'This would write into the scratchpad folder the agent tool offers (V-B-08):',
65
+ ...hitLines,
66
+ '',
67
+ `That folder is under /tmp, and V-B-08 overrides the tool line that says to use it. Nothing was written. ${places} Read a fetched file through a pipe (for example gh api ... | grep) rather than saving it.`,
68
+ ];
69
+ } else if (isDeny) {
70
+ reason = [
71
+ 'This would create files outside the project (V-B-08), and this project denies it (guard.outside):',
72
+ ...hitLines,
73
+ '',
74
+ `Nothing was written. ${places}`,
75
+ 'A store a tool manages itself can be allowed with guard.toolOwnedPaths in .configs/vulcan.config.*.',
76
+ ];
77
+ } else {
78
+ reason = [
79
+ 'This would create files outside the project (V-B-08):',
80
+ ...hitLines,
81
+ '',
82
+ `${places} Use that place, or confirm only if the owner asked for this exact path.`,
83
+ 'A store a tool manages itself can be allowed with guard.toolOwnedPaths in .configs/vulcan.config.*.',
84
+ ];
85
+ }
86
+
55
87
  console.log(
56
88
  JSON.stringify(
57
89
  HookDecision.buildTool({
58
- decision: isScratchpad ? GuardDecisions.DENY : GuardDecisions.ASK,
59
- reason: isScratchpad
60
- ? [
61
- 'This would write into the scratchpad folder the agent tool offers (V-B-08):',
62
- ...hitLines,
63
- '',
64
- `That folder is under /tmp, and V-B-08 overrides the tool line that says to use it. Nothing was written. ${places} Read a fetched file through a pipe (for example gh api ... | grep) rather than saving it.`,
65
- ]
66
- : [
67
- 'This would create files outside the project (V-B-08):',
68
- ...hitLines,
69
- '',
70
- `${places} Use that place, or confirm only if the owner asked for this exact path.`,
71
- 'A store a tool manages itself can be allowed with guard.toolOwnedPaths in .configs/vulcan.config.*.',
72
- ],
90
+ decision: isDeny ? GuardDecisions.DENY : GuardDecisions.ASK,
91
+ reason,
73
92
  }),
74
93
  ),
75
94
  );
@@ -1,7 +1,9 @@
1
1
  /**
2
2
  * PreToolUse hook on Bash: asks before a command reaches a host the project has not listed in
3
3
  * `remoteHosts` (trusted, or readOnly for the strict read-only forms). The policy is read from the
4
- * committed manifest, `.agents/vulcan.manifest.json`, plus the personal list `remoteHosts.localFile`.
4
+ * committed manifest, `.agents/vulcan.manifest.json`, plus the personal list `remoteHosts.localFile`: one host per
5
+ * line is trusted, `readonly: <host>` is a read-only host, and a line that is not a host name or a `*` pattern is
6
+ * skipped (said once on stderr) and never trusted.
5
7
  *
6
8
  * It fails closed: Claude Code blocks a PreToolUse call only on exit 2, so every error here - a missing
7
9
  * module, a manifest without the policy - exits 2. The modules load inside the try for that reason.
@@ -34,17 +36,24 @@ try {
34
36
  const localExists = await local?.exists();
35
37
  const readingPersonal = localExists === true ? local?.text() : undefined;
36
38
  const personalText = await readingPersonal;
37
- const personal = personalText ?? '';
39
+ const personal = RemoteHosts.parsePersonalList({ text: personalText ?? '' });
38
40
  const trusted: string[] = Array.isArray(remoteHosts.trusted) ? remoteHosts.trusted : [];
39
41
  const readOnly: string[] = Array.isArray(remoteHosts.readOnly) ? remoteHosts.readOnly : [];
40
42
  const stdin = await Bun.stdin.text();
43
+
44
+ if (personal.skipped.length > 0) {
45
+ console.error(
46
+ `vulcan: the guard-remote-hosts hook skipped lines ${personal.skipped.join(', ')} of ${localFile}: not a host name or a * pattern, so they trust nothing`,
47
+ );
48
+ }
49
+
41
50
  const hookCommand = WriteGuard.parseHookCommand({ text: stdin });
42
51
  const hits = hookCommand
43
52
  ? RemoteHosts.inspectCommand({
44
53
  command: hookCommand.command,
45
54
  policy: {
46
- trusted: [...trusted, ...RemoteHosts.parseTrustedList({ text: personal })],
47
- readOnly,
55
+ trusted: [...trusted, ...personal.trusted],
56
+ readOnly: [...readOnly, ...personal.readOnly],
48
57
  ...(localFile === undefined ? {} : { localFile }),
49
58
  },
50
59
  })
package/base/rules.md CHANGED
@@ -49,7 +49,7 @@ An ID the base drops is never reused.
49
49
  | V-P-10 | **Ask once, with a recommendation.** All open decisions in one numbered round, each with a recommended answer worded so that "yes" accepts it; never ask for a fact you can look up; for a reversible choice state the default in one line and continue, only inside what V-P-02, V-P-03 and V-W-06 already allow; stop for an action they reserve, a plan awaiting approval, a change of shape, or a real fork. | SOFT |
50
50
  | V-P-11 | **Reports: answer first, in the reader's form.** Two lines before any detail; evidence as a table, not prose; a long report goes in a file and the message carries the path. The reader decides the form: the owner gets the project's report shape in their own language, with labels and form of address taken from the `owner` config and their profile, never from fixed words; another agent (a session it started, a cross-session message, a subagent) gets the plain format it asked for and nothing more. | SOFT |
51
51
  | V-P-12 | **Delegate by kind; the brief carries the rules.** Mechanical work (sweeps, greps, renames, gates, counting) goes to a smaller-model subagent; judgment stays with the main agent, which re-checks what comes back. A subagent brief carries the goal, the files, read-only by default, "no git writes", the report shape and a size under 400 words, and the rules digest reaches the subagent (through the tool's subagent-start hook where one exists, otherwise in the brief); the template is `node_modules/@venizia/vulcan/base/references/delegation-brief.md`. | SOFT - the brief; a subagent-start hook where the tool has one |
52
- | V-P-13 | **Name the flow.** Only in a project that logs events (`events.log` on; without it the command writes a line nobody reads, so skip this rule). When you start work that belongs to a flow (`F-n`), log it once, in the owner's language: `vulcan event add --kind flow --flow F-n --title "<a title the owner reads>" --why "<one line, why it exists>"`; log a new one when the title or the reason changes (the newest wins). A board shows the title as the flow's heading; without one it shows the words of its pull request or its first line, marked as having no title yet. | SOFT |
52
+ | V-P-13 | **Name the flow.** Only in a project that logs events (`events.log` on; without it the command writes a line nobody reads, so skip this rule). When you start work that belongs to a flow (`F-n`), log it, in the owner's language: `vulcan event add --kind flow --flow F-n --title "<a title the owner reads>" --why "<one line, why it exists>" --context "<2-4 sentences: what this is, what is done, what is left>" --next "<the next step and who does it>"`. Log a new one when the title, the reason, the context or the next step changes materially; the newest line wins as a whole, so repeat the fields that still hold. A board shows the title as the flow's heading, with the reason, context and next step under it; without a flow line it shows the words of its pull request or its first line, marked as having no title yet. | SOFT |
53
53
 
54
54
  ## B - Build and quality
55
55
 
@@ -353,6 +353,45 @@
353
353
  font-size: 13px;
354
354
  line-height: 1.4;
355
355
  }
356
+ .dh .ctx p,
357
+ .dh .nx {
358
+ margin: 4px 0 0;
359
+ color: var(--ink);
360
+ font-size: 13px;
361
+ line-height: 1.5;
362
+ }
363
+ .dh .nx b,
364
+ .dh .lat .lb,
365
+ .dh .ctx .lb {
366
+ color: var(--muted);
367
+ font-size: 12px;
368
+ font-weight: 600;
369
+ }
370
+ .dh .lat ul {
371
+ list-style: none;
372
+ margin: 4px 0 0;
373
+ padding: 0;
374
+ display: grid;
375
+ gap: 4px;
376
+ }
377
+ .dh .lat li {
378
+ display: grid;
379
+ grid-template-columns: 44px minmax(0, 1fr);
380
+ gap: 8px;
381
+ font-size: 13px;
382
+ line-height: 1.4;
383
+ color: var(--ink);
384
+ }
385
+ .dh .lat .tm {
386
+ color: var(--muted);
387
+ font-variant-numeric: tabular-nums;
388
+ }
389
+ .nowork {
390
+ margin: 0;
391
+ padding: 14px 16px;
392
+ color: var(--muted);
393
+ font-size: 13px;
394
+ }
356
395
 
357
396
  .seg {
358
397
  display: inline-flex;
@@ -2746,6 +2785,58 @@
2746
2785
  'Phiên bắt đầu và kết thúc, subagent và lời nhắc chỉ để chờ đang được ẩn; nút này hiện chúng';
2747
2786
  DICT.en['fl.untitled'] = 'no title yet';
2748
2787
  DICT.vi['fl.untitled'] = 'chưa có tên';
2788
+ DICT.en['ctx.label'] = 'Context';
2789
+ DICT.vi['ctx.label'] = 'Bối cảnh';
2790
+ DICT.en['nx.label'] = 'Next';
2791
+ DICT.vi['nx.label'] = 'Tiếp theo';
2792
+ DICT.en['lt.label'] = 'Latest';
2793
+ DICT.vi['lt.label'] = 'Mới nhất';
2794
+ DICT.en['nw.chip'] = 'No work yet';
2795
+ DICT.vi['nw.chip'] = 'Chưa có việc';
2796
+ DICT.en['nw.empty'] = 'No work logged yet';
2797
+ DICT.vi['nw.empty'] = 'Chưa có việc nào được ghi';
2798
+ DICT.en['lt.msg'] = 'sent a message';
2799
+ DICT.vi['lt.msg'] = 'gửi tin nhắn';
2800
+ DICT.en['lt.msgTo'] = 'wrote to';
2801
+ DICT.vi['lt.msgTo'] = 'nhắn cho';
2802
+ DICT.en['lt.got'] = 'got a message';
2803
+ DICT.vi['lt.got'] = 'nhận tin nhắn';
2804
+ DICT.en['lt.gotFrom'] = 'got a message from';
2805
+ DICT.vi['lt.gotFrom'] = 'nhận tin nhắn từ';
2806
+ DICT.en['lt.commit'] = 'committed';
2807
+ DICT.vi['lt.commit'] = 'commit';
2808
+ DICT.en['lt.pr'] = 'updated a pull request';
2809
+ DICT.vi['lt.pr'] = 'cập nhật pull request';
2810
+ DICT.en['lt.ci'] = 'ran a check';
2811
+ DICT.vi['lt.ci'] = 'chạy kiểm tra';
2812
+ DICT.en['lt.review'] = 'reviewed';
2813
+ DICT.vi['lt.review'] = 'review';
2814
+ DICT.en['lt.fix'] = 'fixed';
2815
+ DICT.vi['lt.fix'] = 'sửa';
2816
+ DICT.en['lt.merge'] = 'merged';
2817
+ DICT.vi['lt.merge'] = 'merge';
2818
+ DICT.en['lt.release'] = 'released';
2819
+ DICT.vi['lt.release'] = 'phát hành';
2820
+ DICT.en['lt.handoff'] = 'handed over';
2821
+ DICT.vi['lt.handoff'] = 'bàn giao';
2822
+ DICT.en['lt.assign'] = 'assigned work';
2823
+ DICT.vi['lt.assign'] = 'giao việc';
2824
+ DICT.en['lt.request'] = 'requested';
2825
+ DICT.vi['lt.request'] = 'đề xuất';
2826
+ DICT.en['lt.design'] = 'designed';
2827
+ DICT.vi['lt.design'] = 'thiết kế';
2828
+ DICT.en['lt.note'] = 'noted';
2829
+ DICT.vi['lt.note'] = 'ghi chú';
2830
+ DICT.en['lt.ask'] = 'asked the owner';
2831
+ DICT.vi['lt.ask'] = 'hỏi chủ';
2832
+ DICT.en['lt.approve'] = 'approved';
2833
+ DICT.vi['lt.approve'] = 'duyệt';
2834
+ DICT.en['lt.park'] = 'parked';
2835
+ DICT.vi['lt.park'] = 'để sau';
2836
+ DICT.en['lt.reject'] = 'rejected';
2837
+ DICT.vi['lt.reject'] = 'từ chối';
2838
+ DICT.en['lt.decision'] = 'decided';
2839
+ DICT.vi['lt.decision'] = 'quyết định';
2749
2840
  DICT.en['k.flow'] = 'flow title';
2750
2841
  DICT.vi['k.flow'] = 'tên luồng';
2751
2842
  DICT.en['k.agent'] = 'agent activity';
@@ -2971,10 +3062,14 @@
2971
3062
  const fresh = evs.filter((e) => e.ts > lastSeen);
2972
3063
  out.push({
2973
3064
  id: f.id,
3065
+ // Only `flow` lines and plumbing: the flow has no work, and no stage to show.
3066
+ noWork: !evs.some((e) => !e.plumbing && e.kind !== 'flow'),
2974
3067
  f: {
2975
3068
  title: f.title,
2976
3069
  repo: f.repo,
2977
3070
  why: f.why,
3071
+ context: f.context,
3072
+ next: f.next,
2978
3073
  named: f.named === true || f.id === 'Unsorted',
2979
3074
  },
2980
3075
  evs,
@@ -2996,6 +3091,10 @@
2996
3091
 
2997
3092
  function stripOf(fl) {
2998
3093
  const s = el('div', 'strip');
3094
+ if (fl.noWork) {
3095
+ s.append(el('span', 'sg', t('nw.chip')));
3096
+ return s;
3097
+ }
2999
3098
  for (const k of fl.stages) {
3000
3099
  const cur = k === fl.cur;
3001
3100
  const g = el(
@@ -3114,14 +3213,13 @@
3114
3213
  tt.append(el('div', 't', fl.f.title));
3115
3214
  const sub = el('div', 'sub');
3116
3215
  if (!fl.f.named) sub.append(el('span', 'untitled', t('fl.untitled')));
3117
- sub.append(
3118
- el('span', 'repo', fl.f.repo),
3119
- el(
3120
- 'span',
3121
- 'last',
3122
- fl.state === 'you' && fl.lastAsk ? fl.lastAsk.summary : fl.last.summary,
3123
- ),
3124
- );
3216
+ // A flow with no work has nothing to say of its last line (it is its title): the next step, else the reason.
3217
+ const said = fl.noWork
3218
+ ? fl.f.next || fl.f.why || ''
3219
+ : fl.state === 'you' && fl.lastAsk
3220
+ ? fl.lastAsk.summary
3221
+ : fl.last.summary;
3222
+ sub.append(el('span', 'repo', fl.f.repo), el('span', 'last', said));
3125
3223
  tt.append(sub);
3126
3224
  r.append(tt, stripOf(fl), el('span', 'holder', fl.holder));
3127
3225
  const ag = el(
@@ -3201,7 +3299,11 @@
3201
3299
  t(' xong hôm nay');
3202
3300
  const rec = $('recent');
3203
3301
  rec.replaceChildren();
3204
- for (const e of events.slice().sort(byTs).reverse().slice(0, 14)) {
3302
+ for (const e of events
3303
+ .filter((x) => x.kind !== 'flow')
3304
+ .sort(byTs)
3305
+ .reverse()
3306
+ .slice(0, 14)) {
3205
3307
  const li = evItem(e);
3206
3308
  const f = flowsDoc[e.flowId];
3207
3309
  const tag = el('button', 'btn chip', e.flowId);
@@ -3236,31 +3338,47 @@
3236
3338
  const body = el('div');
3237
3339
  const who = el('div', 'who');
3238
3340
  who.append(el('b', null, e.actor));
3239
- if (e.to) who.append(' → ', el('b', null, e.to));
3341
+ // A message the actor got has a sender, never a recipient: the sentence of the Latest list says the same.
3342
+ if (e.incoming) {
3343
+ if (e.from) who.append(' ← ', el('b', null, e.from));
3344
+ } else if (e.to) who.append(' → ', el('b', null, e.to));
3240
3345
  who.append(
3241
3346
  ' · ' + (t(KIND_TXT[e.kind]) || e.kind) + (e.attempt > 1 ? t(' lần ') + e.attempt : ''),
3242
3347
  );
3243
3348
  body.append(who, el('div', 'sm', e.summary));
3244
- const meta = el('div');
3245
- if (e.link && /^https:\/\//.test(e.link)) {
3246
- const l = el('a', 'lk', e.link.replace(/^https:\/\/github\.com\//, ''));
3247
- l.href = e.link;
3248
- l.target = '_blank';
3249
- l.rel = 'noopener';
3250
- meta.append(l, ' · ');
3251
- }
3252
- meta.append(
3253
- el(
3254
- 'span',
3255
- 'src',
3256
- isApprox(e) ? t('giờ ước lượng') : e.source === 'github' ? 'GitHub' : e.source || '',
3257
- ),
3258
- );
3259
- body.append(meta);
3349
+ // Where a line came from is shown only when it changes how to read it (an estimated time, GitHub); a tool's own
3350
+ // tag such as `cli` is not something the owner reads.
3351
+ const origin = isApprox(e) ? t('giờ ước lượng') : e.source === 'github' ? 'GitHub' : '';
3352
+ const hasLink = e.link && /^https:\/\//.test(e.link);
3353
+ if (hasLink || origin) {
3354
+ const meta = el('div');
3355
+ if (hasLink) {
3356
+ const l = el('a', 'lk', e.link.replace(/^https:\/\/github\.com\//, ''));
3357
+ l.href = e.link;
3358
+ l.target = '_blank';
3359
+ l.rel = 'noopener';
3360
+ meta.append(l);
3361
+ }
3362
+ if (hasLink && origin) meta.append(' · ');
3363
+ if (origin) meta.append(el('span', 'src', origin));
3364
+ body.append(meta);
3365
+ }
3260
3366
  li.append(body);
3261
3367
  return li;
3262
3368
  }
3263
3369
 
3370
+ // One readable sentence for a line: who did what, and the words the writer gave it.
3371
+ function latestText(e) {
3372
+ let verb;
3373
+ if (e.kind === 'decision' && e.choice) verb = t('lt.' + e.choice);
3374
+ else if (e.kind === 'note') verb = t(e.needsOwner ? 'lt.ask' : 'lt.note');
3375
+ else if (e.kind === 'msg' && e.incoming)
3376
+ verb = e.from ? t('lt.gotFrom') + ' ' + e.from : t('lt.got');
3377
+ else if (e.kind === 'msg' && e.to) verb = t('lt.msgTo') + ' ' + e.to;
3378
+ else verb = t('lt.' + e.kind);
3379
+ return e.actor + ' ' + verb + (e.summary ? ': ' + e.summary : '');
3380
+ }
3381
+
3264
3382
  function renderDetail(fresh) {
3265
3383
  const fl = FL.find((x) => x.id === selected);
3266
3384
  const box = $('dBody');
@@ -3287,6 +3405,35 @@
3287
3405
  if (!fl.f.named) heading.append(el('span', 'untitled', t('fl.untitled')));
3288
3406
  dh.append(top, heading);
3289
3407
  if (fl.f.why) dh.append(el('p', 'why', fl.f.why));
3408
+ if (fl.f.context) {
3409
+ const c = el('div', 'ctx');
3410
+ c.append(el('div', 'lb', t('ctx.label')), el('p', null, fl.f.context));
3411
+ dh.append(c);
3412
+ }
3413
+ if (fl.f.next) {
3414
+ const n = el('p', 'nx');
3415
+ n.append(el('b', null, t('nx.label') + ': '), fl.f.next);
3416
+ dh.append(n);
3417
+ }
3418
+ const hasWork = !fl.noWork;
3419
+ const latest = fl.evs
3420
+ .filter((e) => !e.plumbing && e.kind !== 'flow')
3421
+ .slice(-3)
3422
+ .reverse();
3423
+ if (latest.length) {
3424
+ const lat = el('div', 'lat');
3425
+ const ul = el('ul');
3426
+ for (const e of latest) {
3427
+ const li = el('li');
3428
+ li.append(
3429
+ el('span', 'tm', (isApprox(e) ? '≈' : '') + hhmm(e.ts)),
3430
+ el('span', null, latestText(e)),
3431
+ );
3432
+ ul.append(li);
3433
+ }
3434
+ lat.append(el('div', 'lb', t('lt.label')), ul);
3435
+ dh.append(lat);
3436
+ }
3290
3437
  const meta = el('div', 'meta');
3291
3438
  const m = (k, v) => {
3292
3439
  const s = el('span');
@@ -3311,7 +3458,7 @@
3311
3458
  ),
3312
3459
  );
3313
3460
  box.append(dh);
3314
- if (viewMode === 'diagram') box.append(renderDiagram(fl));
3461
+ if (viewMode === 'diagram' && hasWork) box.append(renderDiagram(fl));
3315
3462
  const tabs = el('div', 'dtabs');
3316
3463
  tabs.setAttribute('role', 'tablist');
3317
3464
  const t1 = el('button', 'tab', t('Các bước')),
@@ -3338,9 +3485,15 @@
3338
3485
  box.append(ul);
3339
3486
  return;
3340
3487
  }
3488
+ // A `flow` line names the flow; it is no work of a stage, so a flow with nothing else has no stage to show.
3489
+ if (!hasWork) {
3490
+ box.append(el('p', 'nowork', t('nw.empty')));
3491
+ return;
3492
+ }
3341
3493
  const ol = el('ol', 'tl');
3342
3494
  for (const k of fl.stages) {
3343
- const evs = fl.evs.filter((e) => e.stage === k);
3495
+ const evs = fl.evs.filter((e) => e.stage === k && e.kind !== 'flow');
3496
+ if (!evs.length) continue;
3344
3497
  const le = evs[evs.length - 1];
3345
3498
  const bad = le.status === 'fail' || le.status === 'blocked';
3346
3499
  const li = el(
@@ -3409,10 +3562,13 @@
3409
3562
  (x.state !== 'done' || sameDay(x.last.ts)) &&
3410
3563
  (!agentFilter || involves(x, agentFilter)),
3411
3564
  );
3412
- STAGES.forEach((nm, k) => {
3565
+ // A flow with no work is at no stage: it waits in a lane of its own, before the stages (it is the earliest of all).
3566
+ const lanes = STAGES.map((nm, k) => ({ nm, k }));
3567
+ if (items.some((x) => x.noWork)) lanes.unshift({ nm: 'nw.chip', k: -1 });
3568
+ lanes.forEach(({ nm, k }) => {
3413
3569
  const col = el('section', 'kc');
3414
3570
  const mine = items
3415
- .filter((x) => x.cur === k)
3571
+ .filter((x) => (k < 0 ? x.noWork : x.cur === k && !x.noWork))
3416
3572
  .sort(
3417
3573
  (a, b) =>
3418
3574
  ({ you: 0, blocked: 1, running: 2, parked: 3, done: 4 })[a.state] -
@@ -4305,6 +4461,12 @@
4305
4461
  clearTimeout(toastT);
4306
4462
  toastT = setTimeout(() => t.classList.remove('on'), warn ? 5200 : 2600);
4307
4463
  }
4464
+ // Who sent a message line and who got it: a sent line is the actor's to `to`; a received one is the actor's from `from`.
4465
+ function msgEnds(m) {
4466
+ return m.incoming
4467
+ ? { sender: m.from, receiver: m.actor }
4468
+ : { sender: m.actor, receiver: m.to };
4469
+ }
4308
4470
  function agentInfo(n) {
4309
4471
  const row = agentRows().find((r) => r.n === n) || {
4310
4472
  n,
@@ -4339,12 +4501,13 @@
4339
4501
  }
4340
4502
  const open = Object.values(prs).filter((p) => p.by === n && !p.merged && !p.closed);
4341
4503
  const msgs = events
4342
- .filter((e) => e.kind === 'msg' && (e.to === n || e.actor === n))
4504
+ .filter((e) => e.kind === 'msg' && (msgEnds(e).sender === n || msgEnds(e).receiver === n))
4343
4505
  .sort(byTs);
4506
+ // A message waits for its receiver: unanswered while the receiver has done nothing since, in that flow.
4344
4507
  const pending = msgs.filter((m) => {
4345
- const other = m.to === n ? n : m.to;
4508
+ const { receiver } = msgEnds(m);
4346
4509
  return !events.some(
4347
- (e) => e.ts > m.ts && e.actor === other && (!m.flowId || e.flowId === m.flowId),
4510
+ (e) => e.ts > m.ts && e.actor === receiver && (!m.flowId || e.flowId === m.flowId),
4348
4511
  );
4349
4512
  });
4350
4513
  return { row, mine, open, pending };
@@ -4437,7 +4600,12 @@
4437
4600
  const li = el('li');
4438
4601
  li.append(el('span', 'tm', (isApprox(m) ? '≈' : '') + hhmm(m.ts)));
4439
4602
  const sm = el('span', 'sm');
4440
- sm.append((m.actor === n ? '→ ' + m.to : '← ' + m.actor) + ': ' + (m.summary || ''));
4603
+ const ends = msgEnds(m);
4604
+ sm.append(
4605
+ (ends.sender === n ? '→ ' + (ends.receiver || '?') : '← ' + (ends.sender || '?')) +
4606
+ ': ' +
4607
+ (m.summary || ''),
4608
+ );
4441
4609
  li.append(sm);
4442
4610
  ul.append(li);
4443
4611
  }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@venizia/vulcan",
3
- "version": "0.4.10-0",
3
+ "version": "0.4.10-1",
4
4
  "description": "VULCAN - one setup, one workflow for every project: init, sync, doctor, upgrade, and `vulcan x` for the shipped tools. Bun-only.",
5
5
  "homepage": "https://github.com/VENIZIA-AI/vulcan/tree/main/packages/cli",
6
6
  "bugs": {
@@ -44,8 +44,8 @@
44
44
  },
45
45
  "dependencies": {
46
46
  "@clack/prompts": "1.8.1",
47
- "@venizia/vulcan-atlas": "0.4.10-0",
48
- "@venizia/vulcan-okf": "0.4.10-0",
47
+ "@venizia/vulcan-atlas": "0.4.10-1",
48
+ "@venizia/vulcan-okf": "0.4.10-1",
49
49
  "zod": "^4.6.7"
50
50
  },
51
51
  "devDependencies": {
@@ -19,6 +19,10 @@ export interface IBoardEvent {
19
19
  stage: number;
20
20
  actor: string;
21
21
  to?: string;
22
+ /** A message the actor got, not sent (`msg-received`). */
23
+ incoming?: boolean;
24
+ /** Who sent a message the actor got, from a `from:<name>` ref. */
25
+ from?: string;
22
26
  status?: string;
23
27
  /** What a decision decided: `approve`, `park` or `reject`. */
24
28
  choice?: string;
@@ -29,6 +33,9 @@ export interface IBoardEvent {
29
33
  isTitle?: boolean;
30
34
  /** Only a title line has one: why the flow exists. */
31
35
  why?: string;
36
+ /** Only a title line has them: what the flow is and what is left, and the next step. */
37
+ context?: string;
38
+ next?: string;
32
39
  /** Which attempt this is: the nth run of one check, the nth review round. */
33
40
  attempt?: number;
34
41
  /** The check a CI line is about. */
@@ -46,6 +53,10 @@ export interface IBoardFlow {
46
53
  named: boolean;
47
54
  /** Why the flow exists, from the newest `flow` line that has one. */
48
55
  why?: string;
56
+ /** What the flow is, what is done and what is left; from the same line as the title. */
57
+ context?: string;
58
+ /** The next step and who does it; from the same line as the title. */
59
+ next?: string;
49
60
  repo?: string;
50
61
  state: TBoardState;
51
62
  /** Who has it now. */
package/src/board/fold.ts CHANGED
@@ -20,6 +20,7 @@ const PR_NUMBER = /^#?(\d+)$/;
20
20
  /** A `pr` line with this ref says the pull request was merged: `--ref merged:12`. */
21
21
  const MERGED_REF = /^merged:#?(\d+)$/;
22
22
  const TO_PREFIX = 'to:';
23
+ const FROM_PREFIX = 'from:';
23
24
  /** Kinds that take the stage the flow is at when they happen: a message belongs to the stage it was sent in. */
24
25
  const CARRY_KINDS: string[] = [BoardKinds.MSG, BoardKinds.NOTE];
25
26
 
@@ -159,9 +160,25 @@ export class BoardFold {
159
160
 
160
161
  case EventKinds.MSG_SENT:
161
162
  case EventKinds.MSG_RECEIVED: {
162
- const to = line.ref?.startsWith(TO_PREFIX) ? line.ref.slice(TO_PREFIX.length) : undefined;
163
+ const isIncoming = line.kind === EventKinds.MSG_RECEIVED;
164
+ // A received line has a sender, never a recipient: the page reads `to` as who the message went to.
165
+ const to =
166
+ !isIncoming && line.ref?.startsWith(TO_PREFIX)
167
+ ? line.ref.slice(TO_PREFIX.length)
168
+ : undefined;
169
+ const from =
170
+ isIncoming && line.ref?.startsWith(FROM_PREFIX)
171
+ ? line.ref.slice(FROM_PREFIX.length)
172
+ : undefined;
163
173
 
164
- return { ...base, kind: BoardKinds.MSG, stage: -1, ...(to === undefined ? {} : { to }) };
174
+ return {
175
+ ...base,
176
+ kind: BoardKinds.MSG,
177
+ stage: -1,
178
+ ...(to === undefined ? {} : { to }),
179
+ ...(isIncoming ? { incoming: true } : {}),
180
+ ...(from === undefined || from === '' ? {} : { from }),
181
+ };
165
182
  }
166
183
 
167
184
  case EventKinds.NEEDS_OWNER: {
@@ -178,6 +195,8 @@ export class BoardFold {
178
195
  stage: BoardStages.REQUEST,
179
196
  isTitle: true,
180
197
  ...(line.why === undefined ? {} : { why: line.why }),
198
+ ...(line.context === undefined ? {} : { context: line.context }),
199
+ ...(line.next === undefined ? {} : { next: line.next }),
181
200
  };
182
201
  }
183
202
 
@@ -331,11 +350,13 @@ export class BoardFold {
331
350
  };
332
351
  }
333
352
 
334
- /** The title and reason a `flow` line gives; its reason goes with it, and a newer line without one drops the old reason. */
353
+ /** The heading a `flow` line gives: title, reason, context and next step. The newest line wins as a whole: a newer line that leaves a field out drops the old one, so no stale text outlives the line that wrote it. */
335
354
  private static headingOf(opts: { named: IBoardEvent | undefined }): {
336
355
  title?: string;
337
356
  named: boolean;
338
357
  why?: string;
358
+ context?: string;
359
+ next?: string;
339
360
  } {
340
361
  const { named } = opts;
341
362
 
@@ -345,6 +366,8 @@ export class BoardFold {
345
366
  title: named.summary,
346
367
  named: true,
347
368
  ...(named.why === undefined ? {} : { why: named.why }),
369
+ ...(named.context === undefined ? {} : { context: named.context }),
370
+ ...(named.next === undefined ? {} : { next: named.next }),
348
371
  };
349
372
  }
350
373
 
@@ -39,7 +39,7 @@ Usage: bun x vulcan <command>
39
39
  List the workspace packages a change touches (changed ones and what
40
40
  depends on them) with the checks each has; template prints a CI file that
41
41
  runs exactly those; exit 2 on bad input
42
- event add --kind <k> --summary <text> [--flow F-n] [--ref <r>] [--status approve|park|reject] | add --kind flow --flow F-n --title <text> [--why <text>] | tail [--since <time>] [--json] [--dir <folder>]
42
+ event add --kind <k> --summary <text> [--flow F-n] [--ref <r>] [--status approve|park|reject] | add --kind flow --flow F-n --title <text> [--why <text>] [--context <text>] [--next <text>] | tail [--since <time>] [--json] [--dir <folder>]
43
43
  Write a line to the agent event log (.agents/local/events/<day>.jsonl) or
44
44
  read it; with events.log on, sync installs the Claude Code hooks that
45
45
  write it; exit 2 on bad input
@@ -1,6 +1,8 @@
1
1
  import { isAbsolute } from 'node:path';
2
2
  import { z } from 'zod';
3
3
  import { LayoutFolder } from '../common/layout-folder.ts';
4
+ import { GuardDecisions } from '../hooks/common/constants.ts';
5
+ import { HostPatterns } from '../hooks/host-pattern.ts';
4
6
  import { OWNER_SCHEMA } from '../owner/schema.ts';
5
7
  import { AgentSignaturePolicies } from '../commit/common/index.ts';
6
8
  import type { TAgentSignaturePolicy } from '../commit/common/index.ts';
@@ -198,12 +200,9 @@ const OKF_RENDERER = z.union([
198
200
  /** A host name, or a pattern whose only wildcard is `*`; a `$VAR` stands for a host the shell expands. Never a user, a path or a port. */
199
201
  const REMOTE_HOST = z
200
202
  .string()
201
- .regex(
202
- /^(?:\$\{?\w+\}?|[A-Za-z0-9._*-]+)$/,
203
- 'a host name or a pattern with *, not a user, a path or a port',
204
- )
205
- .refine((value) => value.replaceAll('*', '').replaceAll('.', '') !== '', {
206
- message: 'a pattern needs at least one literal character beyond * and .',
203
+ .regex(HostPatterns.SHAPE, 'a host name or a pattern with *, not a user, a path or a port')
204
+ .refine((value) => HostPatterns.hasLiteral({ value }), {
205
+ message: 'a pattern needs at least one letter or digit, not only * . - or _',
207
206
  });
208
207
 
209
208
  const VIZ_OUTPUT = '.agents/knowledge/viz.html';
@@ -343,7 +342,8 @@ export const VULCAN_CONFIG_SCHEMA = z.strictObject({
343
342
  * The remote-host guard (W-04 in a project's own words): with this key set, sync registers a hook that
344
343
  * asks before a Bash command reaches a host not listed here. `trusted` hosts are free; `readOnly`
345
344
  * hosts pass only the strict read-only forms. Matching is by whole name or `*` pattern, never by substring.
346
- * `localFile` is a gitignored list of personal trusted hosts, one per line.
345
+ * `localFile` is a gitignored list of personal hosts, one per line: a host is trusted, `readonly: <host>` is a
346
+ * read-only host. Each entry follows the same rule as the lists above; one that does not is skipped.
347
347
  */
348
348
  remoteHosts: z
349
349
  .strictObject({
@@ -434,11 +434,14 @@ export const VULCAN_CONFIG_SCHEMA = z.strictObject({
434
434
  * read, and `vulcan sync` writes those entries to the manifest. `writes.commands` adds the
435
435
  * project's own deploy and migrate commands to what guard-writes asks about (a pattern, matched inside
436
436
  * compound commands too), and `git.askPush` lists the branches a plain `git push` asks about; `vulcan sync`
437
- * writes both to the manifest, where the hooks read them.
437
+ * writes both to the manifest, where the hooks read them. `outside` is what `guard-outside` does with a
438
+ * write outside the project: `ask` (the default) or `deny`. Where the agent runs in an auto mode an ask can be
439
+ * approved without the owner seeing it, so a project that wants the line held sets `deny`.
438
440
  */
439
441
  guard: z
440
442
  .strictObject({
441
443
  toolOwnedPaths: z.array(z.string().min(1)).default([]),
444
+ outside: z.enum([GuardDecisions.ASK, GuardDecisions.DENY]).default(GuardDecisions.ASK),
442
445
  writes: z
443
446
  .strictObject({
444
447
  trustedScripts: z.array(TRUSTED_SCRIPT).default([]),
@@ -449,6 +452,7 @@ export const VULCAN_CONFIG_SCHEMA = z.strictObject({
449
452
  })
450
453
  .default({
451
454
  toolOwnedPaths: [],
455
+ outside: GuardDecisions.ASK,
452
456
  writes: { trustedScripts: [], commands: [] },
453
457
  git: { askPush: [] },
454
458
  }),
@@ -17,7 +17,7 @@ import { EventLog } from './log.ts';
17
17
  import { EventSettings } from './settings.ts';
18
18
 
19
19
  const USAGE = `usage: vulcan event add ${EventFlags.KIND} <kind> ${EventFlags.SUMMARY} <text> [${EventFlags.FLOW} F-n] [${EventFlags.REF} <ref>] [${EventFlags.STATUS} <${[...EventStatuses.SCHEME_SET].join('|')}>] [${EventFlags.ACTOR} <name>] [${EventFlags.DIR} <folder>]
20
- vulcan event add ${EventFlags.KIND} ${EventKinds.FLOW} ${EventFlags.FLOW} F-n ${EventFlags.TITLE} <text> [${EventFlags.WHY} <text>] [${EventFlags.ACTOR} <name>] [${EventFlags.DIR} <folder>]
20
+ vulcan event add ${EventFlags.KIND} ${EventKinds.FLOW} ${EventFlags.FLOW} F-n ${EventFlags.TITLE} <text> [${EventFlags.WHY} <text>] [${EventFlags.CONTEXT} <text>] [${EventFlags.NEXT} <text>] [${EventFlags.ACTOR} <name>] [${EventFlags.DIR} <folder>]
21
21
  vulcan event tail [${EventFlags.SINCE} <time>] [${EventFlags.JSON}] [${EventFlags.DIR} <folder>]
22
22
  kinds: ${[...EventKinds.SCHEME_SET].join(', ')}`;
23
23
 
@@ -108,17 +108,28 @@ export class EventCommand {
108
108
  if (
109
109
  isFlow
110
110
  ? values[EventFlags.SUMMARY] !== undefined
111
- : values[EventFlags.TITLE] !== undefined || values[EventFlags.WHY] !== undefined
111
+ : values[EventFlags.TITLE] !== undefined ||
112
+ values[EventFlags.WHY] !== undefined ||
113
+ values[EventFlags.CONTEXT] !== undefined ||
114
+ values[EventFlags.NEXT] !== undefined
112
115
  ) {
113
116
  process.stderr.write(
114
117
  isFlow
115
- ? `event: a flow line takes ${EventFlags.TITLE} and ${EventFlags.WHY}, not ${EventFlags.SUMMARY}\n`
116
- : `event: ${EventFlags.TITLE} and ${EventFlags.WHY} belong to a flow line only\n`,
118
+ ? `event: a flow line takes ${EventFlags.TITLE}, not ${EventFlags.SUMMARY}\n`
119
+ : `event: ${EventFlags.TITLE}, ${EventFlags.WHY}, ${EventFlags.CONTEXT} and ${EventFlags.NEXT} belong to a flow line only\n`,
117
120
  );
118
121
 
119
122
  return ExitCodes.USAGE;
120
123
  }
121
124
 
125
+ for (const flag of [EventFlags.CONTEXT, EventFlags.NEXT]) {
126
+ if (values[flag] !== undefined && values[flag].trim() === '') {
127
+ process.stderr.write(`event: ${flag} needs a short text, or leave it out\n`);
128
+
129
+ return ExitCodes.USAGE;
130
+ }
131
+ }
132
+
122
133
  if (flow !== undefined && !EventFlow.isValid({ flow })) {
123
134
  process.stderr.write(`event: ${EventFlags.FLOW} must look like F-12, got '${flow}'\n`);
124
135
 
@@ -165,6 +176,8 @@ export class EventCommand {
165
176
  ...(values[EventFlags.REF] === undefined ? {} : { ref: values[EventFlags.REF] }),
166
177
  ...(status === undefined ? {} : { status: status as TEventStatus }),
167
178
  ...(values[EventFlags.WHY] === undefined ? {} : { why: values[EventFlags.WHY] }),
179
+ ...(values[EventFlags.CONTEXT] === undefined ? {} : { context: values[EventFlags.CONTEXT] }),
180
+ ...(values[EventFlags.NEXT] === undefined ? {} : { next: values[EventFlags.NEXT] }),
168
181
  });
169
182
 
170
183
  try {
@@ -63,6 +63,8 @@ export class EventFlags {
63
63
  static readonly STATUS = '--status';
64
64
  static readonly TITLE = '--title';
65
65
  static readonly WHY = '--why';
66
+ static readonly CONTEXT = '--context';
67
+ static readonly NEXT = '--next';
66
68
  static readonly ACTOR = '--actor';
67
69
  static readonly DIR = '--dir';
68
70
  static readonly SINCE = '--since';
@@ -106,6 +108,8 @@ export class EventConstants {
106
108
  static readonly MANIFEST_FILE = '.agents/vulcan.manifest.json';
107
109
  static readonly FILE_SUFFIX = '.jsonl';
108
110
  static readonly SUMMARY_MAX = 200;
111
+ /** A flow's context is a few sentences, not a summary line. */
112
+ static readonly CONTEXT_MAX = 600;
109
113
  /** What a sent message is called when its sender gave no label: the text of a message is never used. */
110
114
  static readonly MESSAGE_SENT_LABEL = 'message sent';
111
115
  static readonly REF_MAX = 120;
@@ -18,6 +18,10 @@ export interface IEvent {
18
18
  ref?: string;
19
19
  /** Only a `flow` has one: the one-line reason the flow exists. */
20
20
  why?: string;
21
+ /** Only a `flow` has one: what the flow is, what is done and what is left, in a few sentences. */
22
+ context?: string;
23
+ /** Only a `flow` has one: the next step and who does it. */
24
+ next?: string;
21
25
  /** Only a `needs-owner` the Claude Code hook wrote has one: the notification type that raised it. */
22
26
  notification?: string;
23
27
  source: string;
package/src/events/log.ts CHANGED
@@ -40,6 +40,8 @@ export class EventLog {
40
40
  ref?: string;
41
41
  status?: TEventStatus;
42
42
  why?: string;
43
+ context?: string;
44
+ next?: string;
43
45
  notification?: string;
44
46
  now?: number;
45
47
  }): IEvent {
@@ -52,6 +54,14 @@ export class EventLog {
52
54
  opts.why === undefined
53
55
  ? ''
54
56
  : EventText.oneLine({ text: opts.why, max: EventConstants.SUMMARY_MAX });
57
+ const context =
58
+ opts.context === undefined
59
+ ? ''
60
+ : EventText.oneLine({ text: opts.context, max: EventConstants.CONTEXT_MAX });
61
+ const next =
62
+ opts.next === undefined
63
+ ? ''
64
+ : EventText.oneLine({ text: opts.next, max: EventConstants.SUMMARY_MAX });
55
65
 
56
66
  return {
57
67
  id: EventLog.newId({ now }),
@@ -63,6 +73,8 @@ export class EventLog {
63
73
  ...(opts.status === undefined ? {} : { status: opts.status }),
64
74
  ...(ref === '' ? {} : { ref }),
65
75
  ...(why === '' ? {} : { why }),
76
+ ...(context === '' ? {} : { context }),
77
+ ...(next === '' ? {} : { next }),
66
78
  ...(opts.notification !== undefined &&
67
79
  ClaudeHookEvents.OWNER_NOTIFICATIONS.has(opts.notification)
68
80
  ? { notification: opts.notification }
@@ -141,7 +153,21 @@ export class EventLog {
141
153
  return undefined;
142
154
  }
143
155
 
144
- const { id, ts, flowId, actor, kind, summary, status, ref, why, notification, source } = value;
156
+ const {
157
+ id,
158
+ ts,
159
+ flowId,
160
+ actor,
161
+ kind,
162
+ summary,
163
+ status,
164
+ ref,
165
+ why,
166
+ context,
167
+ next,
168
+ notification,
169
+ source,
170
+ } = value;
145
171
 
146
172
  if (
147
173
  typeof id !== 'string' ||
@@ -156,6 +182,8 @@ export class EventLog {
156
182
  (status !== undefined && (typeof status !== 'string' || !EventStatuses.isValid(status))) ||
157
183
  (ref !== undefined && typeof ref !== 'string') ||
158
184
  (why !== undefined && typeof why !== 'string') ||
185
+ (context !== undefined && typeof context !== 'string') ||
186
+ (next !== undefined && typeof next !== 'string') ||
159
187
  (notification !== undefined && typeof notification !== 'string')
160
188
  ) {
161
189
  return undefined;
@@ -163,6 +191,9 @@ export class EventLog {
163
191
 
164
192
  // A reader prints these: whatever a writer put there, no control character reaches a terminal.
165
193
  const clean = (field: string): string => EventText.stripControl({ text: field });
194
+ // The free text is cleaned the way `build` cleans it: one line, secrets redacted, the same length cap. A line written by
195
+ // hand, or by an older version, cannot put a huge string or a token on a page.
196
+ const text = (field: string, max: number): string => EventText.oneLine({ text: field, max });
166
197
 
167
198
  return {
168
199
  id: clean(id),
@@ -170,10 +201,12 @@ export class EventLog {
170
201
  ...(flowId === undefined ? {} : { flowId: clean(flowId) }),
171
202
  actor: clean(actor),
172
203
  kind: kind as TEventKind,
173
- summary: clean(summary),
204
+ summary: text(summary, EventConstants.SUMMARY_MAX),
174
205
  ...(status === undefined ? {} : { status: status as TEventStatus }),
175
- ...(ref === undefined ? {} : { ref: clean(ref) }),
176
- ...(why === undefined ? {} : { why: clean(why) }),
206
+ ...(ref === undefined ? {} : { ref: text(ref, EventConstants.REF_MAX) }),
207
+ ...(why === undefined ? {} : { why: text(why, EventConstants.SUMMARY_MAX) }),
208
+ ...(context === undefined ? {} : { context: text(context, EventConstants.CONTEXT_MAX) }),
209
+ ...(next === undefined ? {} : { next: text(next, EventConstants.SUMMARY_MAX) }),
177
210
  // A value that is not one of the types the hook knows is dropped: it is a short enum, not free text.
178
211
  ...(notification === undefined || !ClaudeHookEvents.OWNER_NOTIFICATIONS.has(notification)
179
212
  ? {}
@@ -0,0 +1,17 @@
1
+ /**
2
+ * What a remote host entry may be, for the project config (`remoteHosts.trusted`, `readOnly`) and for the
3
+ * personal list the guard reads at run time. It has no import, because the guard loads no config loader and no zod.
4
+ */
5
+ export class HostPatterns {
6
+ /** A `$VAR` or `${VAR}`, or a host name made of letters, digits, `.`, `_`, `-` and `*`: never a user, a path or a port. */
7
+ static readonly SHAPE = /^(?:\$\{?\w+\}?|[A-Za-z0-9._*-]+)$/;
8
+
9
+ /** A pattern needs a letter or a digit: `*`, `-`, `*-*` or `*_*` would match every host, or every hyphenated one. */
10
+ static hasLiteral(opts: { value: string }): boolean {
11
+ return /[A-Za-z0-9]/.test(opts.value);
12
+ }
13
+
14
+ static isValid(opts: { value: string }): boolean {
15
+ return HostPatterns.SHAPE.test(opts.value) && HostPatterns.hasLiteral(opts);
16
+ }
17
+ }
@@ -1,4 +1,5 @@
1
1
  import { HookConstants } from './common/index.ts';
2
+ import { HostPatterns } from './host-pattern.ts';
2
3
  import type { IWriteHit } from './common/index.ts';
3
4
  import { CommandView } from './command-view.ts';
4
5
  import { HookDecision } from './decision.ts';
@@ -18,10 +19,19 @@ interface IRemoteHostsPolicy {
18
19
  trusted: string[];
19
20
  /** Hosts that only the strict read-only forms may reach. */
20
21
  readOnly: string[];
21
- /** Where the personal trusted list lives, for the message. */
22
+ /** Where the personal list lives, for the message. */
22
23
  localFile?: string;
23
24
  }
24
25
 
26
+ /** What the personal list holds: trusted hosts, read-only hosts, and the numbers of the lines that were skipped. */
27
+ interface IPersonalHosts {
28
+ trusted: string[];
29
+ readOnly: string[];
30
+ skipped: number[];
31
+ }
32
+
33
+ const READONLY_PREFIX = 'readonly:';
34
+
25
35
  interface ISegment {
26
36
  words: string[];
27
37
  /** `$(...)` or a backtick ran inside it: what it reaches is decided at run time. */
@@ -880,12 +890,34 @@ export class RemoteHosts {
880
890
  });
881
891
  }
882
892
 
883
- /** The personal trusted list: one host per line, `#` starts a comment. */
884
- static parseTrustedList(opts: { text: string }): string[] {
885
- return opts.text
886
- .split('\n')
887
- .map((line) => line.replace(/#.*$/, '').trim())
888
- .filter((line) => line !== '');
893
+ /**
894
+ * The personal list: one host per line, `#` starts a comment, `readonly: <host>` is a read-only host. An entry
895
+ * that is not a host name or a `*` pattern (a lone `*`, a user, a port, a path) is skipped, never trusted, and its
896
+ * line number is returned in `skipped`.
897
+ */
898
+ static parsePersonalList(opts: { text: string }): IPersonalHosts {
899
+ const personal: IPersonalHosts = { trusted: [], readOnly: [], skipped: [] };
900
+
901
+ opts.text.split('\n').forEach((raw, index) => {
902
+ const line = raw.replace(/#.*$/, '').trim();
903
+
904
+ if (line === '') {
905
+ return;
906
+ }
907
+
908
+ const isReadOnly = line.startsWith(READONLY_PREFIX);
909
+ const value = isReadOnly ? line.slice(READONLY_PREFIX.length).trim() : line;
910
+
911
+ if (!HostPatterns.isValid({ value })) {
912
+ personal.skipped.push(index + 1);
913
+
914
+ return;
915
+ }
916
+
917
+ (isReadOnly ? personal.readOnly : personal.trusted).push(value);
918
+ });
919
+
920
+ return personal;
889
921
  }
890
922
 
891
923
  /** Why each host this command reaches may not be reached without asking; empty means nothing to ask. */
package/src/router.ts CHANGED
@@ -108,6 +108,8 @@ const ACCEPTED_ARGS: Record<string, IAcceptedArgs> = {
108
108
  EventFlags.STATUS,
109
109
  EventFlags.TITLE,
110
110
  EventFlags.WHY,
111
+ EventFlags.CONTEXT,
112
+ EventFlags.NEXT,
111
113
  EventFlags.ACTOR,
112
114
  EventFlags.DIR,
113
115
  EventFlags.SINCE,