@jjanczur/tyran 0.1.9 → 0.1.11

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.
@@ -11,7 +11,7 @@
11
11
  {
12
12
  "name": "tyran",
13
13
  "description": "A task conductor for Claude Code: multi-agent orchestration with an enforced evidence contract, repo-specific learning, and update-safe local evolution.",
14
- "version": "0.1.9",
14
+ "version": "0.1.11",
15
15
  "source": "./",
16
16
  "author": {
17
17
  "name": "Jacek Janczura",
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "tyran",
3
- "version": "0.1.9",
3
+ "version": "0.1.11",
4
4
  "description": "A task conductor for Claude Code: multi-agent orchestration with an enforced evidence contract, repo-specific learning, and update-safe local evolution.",
5
5
  "author": {
6
6
  "name": "Jacek Janczura",
package/CHANGELOG.md CHANGED
@@ -1,5 +1,63 @@
1
1
  # Changelog
2
2
 
3
+ ## 0.1.11 — 2026-08-13
4
+
5
+ ### The journal learns what agents are doing, finding, and waiting on
6
+
7
+ The closed event set grows 14 → 17 — the reviewed core change the journal
8
+ page names. `progress` is the agent's own mid-run signal (`started` ·
9
+ `working` · `blocked` · `unblocked`, a closed list emitted at four named
10
+ points, never part of spawn↔report pairing); `finding` is a claim about a named
11
+ area plus the proof for it, queryable by other agents (`F-<n>` ids issued
12
+ by `append`);
13
+ `ticket.status` is the conductor's lane override for exactly the three
14
+ states no lifecycle event can derive (`blocked` · `waiting-operator` ·
15
+ `parked`), cleared automatically by the next report, review or merge and
16
+ never counted as progress. Both new value sets are closed and rejected at
17
+ append naming the whole set; the free-text keys `detail`/`claim`/`proof`
18
+ cap at 2 000 codepoints — rejected, never truncated.
19
+
20
+ STATE.md gains `Open blockages` and `Findings` sections and a per-agent
21
+ `Last signal` column; doctor gains `spawn-blocked` (an agent whose own last
22
+ signal says blocked, past a threshold); the agent contracts gain the
23
+ emission points, the anti-duplication grep, and the implementer's "what you
24
+ did NOT do" report section; operator questions and mid-run ticket intake
25
+ now land as journal events, so the coming board can render them.
26
+
27
+ ## 0.1.10 — 2026-08-13
28
+
29
+ ### Overnight mode: the usage cliff becomes a wind-down
30
+
31
+ Both subscription windows were hit live while this was being built — a
32
+ five-hour wall at 12:15 and the weekly wall at 15:30, each killing a
33
+ four-agent review fleet mid-flight — which is the exact failure this
34
+ feature removes. A new `PreToolUse` usage gate reads the telemetry sidecar
35
+ that an operator-installed statusline helper (`scripts/statusline.mjs`)
36
+ maintains, and near the threshold refuses everything except a closed
37
+ wind-down set; the refusal text is the checkpoint checklist itself.
38
+ Measured on 2.1.197 and recorded in the hook contract: the hook payload
39
+ carries NO rate-limit data, so the statusline is the only telemetry source,
40
+ and every unknown fails open — no telemetry, stale telemetry, a malformed
41
+ config or a supervised operator can never produce a false pause.
42
+
43
+ Time-until-reset decides what happens next (`limits.wait_max_hours`,
44
+ default 5). Within it, `scripts/overnight.mjs` spawns a detached watcher
45
+ that sleeps to the reset and resumes the paused session with
46
+ `claude -p --resume`, then babysits it — a resumed headless session has no
47
+ statusline, so success is judged by journal movement, never exit codes.
48
+ Beyond it — the weekly shape — the pause is LONG: the operator is notified
49
+ (desktop notification, session-start banner, doctor) and by default nothing
50
+ resumes without them (`limits.long_wait: hold`). The `.tyran/STOP` brake
51
+ outranks the watcher; four new doctor codes surface active, stale, dead-
52
+ watcher and telemetry-missing states; the overnight runtime files are
53
+ name-exempt from the stray-file check and seeded into `.tyran/.gitignore` —
54
+ on an install whose gitignore predates them, re-running `scan-repo.mjs`
55
+ (`--write` or `--ensure-policy`) appends the missing lines.
56
+
57
+ The gate registers `node`-dispatched because the policy gate (correctly)
58
+ refuses agent-run `chmod` on hook paths; `hooks-check` learned to model
59
+ interpreter dispatch.
60
+
3
61
  ## 0.1.9 — 2026-08-13
4
62
 
5
63
  ### One layout for an initiative's files
package/README.md CHANGED
@@ -436,7 +436,10 @@ underlying script does.
436
436
  published as numbers rather than as a table of intentions)
437
437
  - [ ] Update delta-review: reconcile a new core version with what your repo
438
438
  has learned locally
439
- - [ ] Overnight mode (ralph-tui integration)
439
+ - [x] Overnight mode: usage-limit pause + scheduled resume — the statusline
440
+ telemetry sidecar, a wind-down gate near the subscription window, and a
441
+ watcher that resumes (or, on a days-away weekly reset, notifies and
442
+ holds) — see [docs/overnight.md](docs/overnight.md)
440
443
  - [ ] Read-only dashboard (phase C)
441
444
 
442
445
  ## Where this came from
@@ -15,6 +15,21 @@ commits and anything written to disk are in English.**
15
15
  lease file as the handoff describes. Another agent's unexpired lease
16
16
  means you do NOT start — you report back. Release it when you finish,
17
17
  including when you finish by failing.
18
+ - **Signal at four points, no more** — `progress` events appended to the
19
+ MAIN checkout's journal (the handoff carries its absolute path):
20
+ `started` right after the lease (it is also the proof the lease protocol
21
+ was honoured) · `blocked` at the FIRST blockage, BEFORE attempting any
22
+ workaround · `unblocked` when it clears · `working` before the final
23
+ full validation run, the longest silent stretch you have. Shape:
24
+ `node ${CLAUDE_PLUGIN_ROOT}/scripts/journal.mjs append <abs-journal>
25
+ progress <init> --actor <you> --data
26
+ '{"agent":"<you>","state":"blocked","ticket":"T-n","detail":"..."}'`.
27
+ Four emissions per story; this is a closed list, not a diary.
28
+ - **Grep before you build.** Search for an existing implementation of the
29
+ thing you are about to write; if it exists, report it as a corrected
30
+ premise instead of duplicating it. Durable discoveries worth another
31
+ agent's time go into the journal as `finding` events (`area` + `claim`
32
+ are required, plus its `proof`) — not only into prose.
18
33
  - **Verify the handoff's premises in the code.** A stale path, a wrong
19
34
  assignment, a function that no longer exists — correct it and report the
20
35
  correction EXPLICITLY instead of executing blindly. Premises about DATA
@@ -54,9 +69,11 @@ commits and anything written to disk are in English.**
54
69
  and showing it still fails — not by asserting it. Take that baseline
55
70
  after a `git fetch` run immediately beforehand; a stale remote once
56
71
  turned a correct proof into a false accusation.
57
- 7. **Final report:** what was done · test and validation output · what the
58
- optimization pass changed · branch or PR · premises you corrected · a
59
- verdict on every knowledge-brief entry id in your handoff (helped, wrong,
60
- or unused — the retrospective folds these into the store's counters) ·
61
- open doubts. The open doubts are worth more than the summary; do not tidy
62
- them away.
72
+ 7. **Final report:** what was done · **what you did NOT do** (scope cut,
73
+ tests skipped, the input class you never exercised — name the worst case
74
+ for each, this section is a merge gate) · test and validation output ·
75
+ what the optimization pass changed · branch or PR · premises you
76
+ corrected · a verdict on every knowledge-brief entry id in your handoff
77
+ (helped, wrong, or unused — the retrospective folds these into the
78
+ store's counters) · open doubts. The open doubts are worth more than the
79
+ summary; do not tidy them away.
package/agents/retro.md CHANGED
@@ -17,6 +17,10 @@ to disk is in English.**
17
17
  the process itself).
18
18
  2. The agents' reports from this initiative: corrected premises, escalations,
19
19
  open doubts. This is the densest source of signal you have.
20
+ Alongside them, the journal's `finding` events (`journal.mjs query <file>
21
+ --ev finding`) — the claims agents recorded WITH proof, mid-run. Promote
22
+ the recurring ones into `.tyran/knowledge/` through the filter below; the
23
+ rest die with the initiative, which is correct.
20
24
  3. `git log` for the initiative: reverts, fixes of your own regressions,
21
25
  repeated phases.
22
26
  4. The current state of `skills/`, `agents/`, `scripts/` and the docs — **so
@@ -25,6 +25,10 @@ that keeps you.
25
25
  author's report with no raw command output you reject on sight, without
26
26
  reading further. Run the tests yourself; for UI, drive the browser yourself
27
27
  through `browser-check`. Paste what you got, with counts.
28
+ - **Signal `started` after taking your lease, `blocked`/`unblocked` when a
29
+ blockage genuinely stops the review** — `progress` events to the main
30
+ checkout's journal, path from the handoff. No `working` signal: your
31
+ `review` event is your completion, and it closes your spawn.
28
32
  - Settle disputed measurements (font size, padding, colour) by dumping
29
33
  computed styles to JSON, never by eye. An "it looks off" audit produces
30
34
  wrong findings at roughly the rate it produces right ones.
package/agents/scout.md CHANGED
@@ -17,7 +17,10 @@ disk is in English.**
17
17
  2. **A finding is a claim plus its proof.** Every line you return is
18
18
  `finding -> path:line, quoted fragment, or URL`. The conductor reads dozens
19
19
  of these; there is no budget for warm-up paragraphs, and an unsourced
20
- finding costs more than no finding because someone will act on it.
20
+ finding costs more than no finding because someone will act on it. Prefix
21
+ the ones that will outlive this task with `DURABLE:` — the conductor
22
+ journals those as `finding` events (rule 1 stands: you write nothing, not
23
+ even to the journal; the prefix is how a durable fact reaches it anyway).
21
24
  3. **When you did not find something, say "I did not find it"** and list
22
25
  where you looked. Never fill the gap with a guess. Anchor every grep over
23
26
  env or config files (`grep -nE '^VARIABLE='`) — an unanchored grep matches
package/bin/tyran.mjs CHANGED
@@ -72,6 +72,14 @@ export const COMMANDS = {
72
72
  'knowledge.mjs',
73
73
  'Select the knowledge entries that apply to a set of paths and print a paste-ready brief for a handoff.',
74
74
  ],
75
+ overnight: [
76
+ 'overnight.mjs',
77
+ 'Schedule and run the usage-limit resume watcher: wait for the window reset, then resume the paused session.',
78
+ ],
79
+ statusline: [
80
+ 'statusline.mjs',
81
+ 'Statusline helper that tees platform rate-limit telemetry into .tyran/state/usage.json for the usage gate.',
82
+ ],
75
83
  'stop-check': [
76
84
  'stop-check.mjs',
77
85
  'Check the .tyran/STOP operator brake that halts a running initiative before its next spawn or merge.',
@@ -1,8 +1,9 @@
1
1
  # Hook I/O contract — measured, not assumed
2
2
 
3
- Every statement here was read out of the shipped Claude Code binary
4
- (**v2.1.116**), not out of documentation. It exists because a gate built on a
5
- guess about the platform is a gate of unknown strength (ADR-22), and because
3
+ Every statement here was read out of the shipped Claude Code binary — §1–§16
4
+ on **v2.1.116**, §17–§18 on **v2.1.197** — not out of documentation. It
5
+ exists because a gate built on a guess about the platform is a gate of
6
+ unknown strength (ADR-22), and because
6
7
  four of the facts below **contradict** the documented contract in ways that
7
8
  would each have produced a control that looks installed and cannot refuse.
8
9
 
@@ -375,3 +376,49 @@ Two consequences worth carrying into every later gate:
375
376
  `Bash` input is reading a program, and a program's output cannot be known
376
377
  without running it. Escape decoding closes the obvious spelling; the class
377
378
  stays open by construction and must be declared, not implied.
379
+
380
+ ## 17. The PreToolUse payload carries NO usage telemetry (measured 2.1.197)
381
+
382
+ Measured 2026-08-13 with a dump hook (`cat > file`) registered in a scratch
383
+ repository, one live tool call. The complete PreToolUse stdin payload:
384
+
385
+ ```
386
+ session_id · transcript_path · cwd · prompt_id · permission_mode ·
387
+ effort.level · hook_event_name · tool_name · tool_input · tool_use_id
388
+ ```
389
+
390
+ **No `rate_limits` field, in any shape.** The statusline JSON is therefore
391
+ the only programmatic source of subscription-window telemetry, and a plugin
392
+ cannot register a statusline — the operator does. Every consumer of usage
393
+ data in this plugin (the usage gate, doctor, the overnight scheduler) reads
394
+ the sidecar `scripts/statusline.mjs` writes, and treats its absence as
395
+ UNKNOWN, which fails open. If a later platform version adds `rate_limits`
396
+ to hook stdin, re-measure and prefer it — stdin beats a sidecar on
397
+ freshness by construction.
398
+
399
+ Two adjacent facts measured the same day, same version:
400
+
401
+ - `claude -p --resume <session-id> "<prompt>"` was measured resuming a
402
+ session **created by a previous `-p` run**, context intact, session id
403
+ unchanged. The direction the overnight watcher actually relies on —
404
+ resuming an INTERACTIVE session headlessly — is assumed to behave the
405
+ same and has **not** been measured. The compensating control is that the
406
+ watcher never trusts the resume: it judges success by journal movement
407
+ (`resumeTook` in `scripts/overnight.mjs` — events after minus events
408
+ before), retries on a finite backoff ladder, and reports a resume that
409
+ exited cleanly having appended nothing as failed, loudly. A resume that
410
+ silently does nothing is therefore detected, never trusted.
411
+ - Statuslines do not run under `claude -p`, so a RESUMED headless session
412
+ has no fresh telemetry and its usage gate fails open by design. The
413
+ overnight watcher compensates by babysitting the resumed process and
414
+ judging success by journal movement, never by exit code.
415
+
416
+ ## 18. Both windows, hit live, while this section was being written
417
+
418
+ The five-hour window (12:15) and then the weekly window (15:30) killed two
419
+ four-agent review fleets on 2026-08-13. Observed behaviour, confirming the
420
+ docs: the parent session SURVIVES — only new subagent work fails, with the
421
+ platform's own message naming the window and its reset time. The main loop
422
+ retained enough headroom to wind down in order: commit, checkpoint, notify
423
+ the operator, schedule the resume. That ordering is exactly the wind-down
424
+ checklist the usage gate prints, rehearsed by hand before it was shipped.
package/hooks/hooks.json CHANGED
@@ -42,6 +42,16 @@
42
42
  "timeout": 8
43
43
  }
44
44
  ]
45
+ },
46
+ {
47
+ "matcher": ".+|^$",
48
+ "hooks": [
49
+ {
50
+ "type": "command",
51
+ "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/scripts/usage-gate.mjs\"",
52
+ "timeout": 8
53
+ }
54
+ ]
45
55
  }
46
56
  ],
47
57
  "Stop": [
@@ -1278,11 +1278,10 @@ const MESSAGE_FLAGS = Object.freeze(['-m', '--message', '-F', '--file', '-t', '-
1278
1278
  * Deliberately NOT a general quote-aware lexer — this repository has one lexer
1279
1279
  * and is not getting a second. What is skipped is a bounded, named shape.
1280
1280
  */
1281
+ export const MESSAGE_ARGUMENT_RE = /(^|\s)(-m|--message|-F|--file|-t|--template|-am|-ma|--data)(=|\s+)("[^"]*"|'[^']*'|\S+)/g;
1282
+
1281
1283
  export function stripMessageArguments(command) {
1282
- return String(command).replace(
1283
- /(^|\s)(-m|--message|-F|--file|-t|--template|-am|-ma|--data)(=|\s+)("[^"]*"|'[^']*'|\S+)/g,
1284
- '$1',
1285
- );
1284
+ return String(command).replace(MESSAGE_ARGUMENT_RE, '$1');
1286
1285
  }
1287
1286
 
1288
1287
  /**
@@ -17,7 +17,7 @@
17
17
  * worse bug than the missing summary.
18
18
  */
19
19
  import { execFileSync } from 'node:child_process';
20
- import { existsSync, readdirSync, realpathSync, statSync } from 'node:fs';
20
+ import { existsSync, readFileSync, readdirSync, realpathSync, statSync } from 'node:fs';
21
21
  import { cpus, totalmem } from 'node:os';
22
22
  import { dirname, isAbsolute, join, resolve } from 'node:path';
23
23
  import { fileURLToPath } from 'node:url';
@@ -168,15 +168,19 @@ function rows(list, render) {
168
168
  * 120 characters under the platform's hard ceiling. Escaping first means the
169
169
  * length fitBudget sees is the length that ships.
170
170
  */
171
- export function renderContext({ repoRoot, initiatives, doctor, hardware, nowIso }) {
172
- if (initiatives.length === 0) return '';
171
+ export function renderContext({ repoRoot, initiatives, doctor, hardware, nowIso, pause = null }) {
172
+ if (initiatives.length === 0 && pause === null) return '';
173
173
  const lines = [
174
174
  '## Tyran state (injected by the session-start probe)',
175
175
  '',
176
176
  `Repo: ${inlinePlain(repoRoot)} · as of ${inlinePlain(nowIso)}`,
177
177
  `Machine: ${inlinePlain(hardware)}`,
178
- '',
179
178
  ];
179
+ // The pause notice lives in the HEADER, before any `### ` section, because
180
+ // fitBudget always keeps the preamble and drops sections from the end — a
181
+ // paused session must never lose the one line that says why it is paused.
182
+ if (pause !== null) lines.push(renderPauseNotice(pause, nowIso));
183
+ lines.push('');
180
184
 
181
185
  for (const { name, state, error } of initiatives) {
182
186
  lines.push(`### Initiative \`${inlinePlain(name)}\``);
@@ -309,6 +313,40 @@ export function fitBudget(text, budget = CONTEXT_BUDGET) {
309
313
  return `${out}\n\n[tyran session-start: ${dropped} further section(s) omitted to stay inside the ${budget}-character working budget; read .tyran/state/ for the rest]`;
310
314
  }
311
315
 
316
+ /**
317
+ * One line about an active usage-limit pause — or a stale one, which is the
318
+ * variant that actually needs a human. Everything through inlinePlain; only
319
+ * marker fields the overnight tooling itself wrote are shown.
320
+ */
321
+ export function renderPauseNotice(marker, nowIso) {
322
+ const resumeAtMs = Date.parse(typeof marker.resume_at === 'string' ? marker.resume_at : '');
323
+ const nowMs = Date.parse(nowIso);
324
+ if (Number.isFinite(resumeAtMs) && Number.isFinite(nowMs) && resumeAtMs < nowMs) {
325
+ return (
326
+ `PAUSED-STALE: the usage-limit pause marker's resume time (${inlinePlain(marker.resume_at)}) has ` +
327
+ 'PASSED — run `node scripts/overnight.mjs status` and reschedule or clear it.'
328
+ );
329
+ }
330
+ const window = marker.window === 'seven_day' ? 'weekly' : 'five-hour';
331
+ return (
332
+ `PAUSED on the ${window} usage limit until ${inlinePlain(marker.resume_at ?? 'the window resets')}` +
333
+ (marker.long_wait === true ? ' — a LONG pause; the scheduler holds unless told otherwise' : '') +
334
+ '. Operator takeover: `node scripts/overnight.mjs cancel --clear`.'
335
+ );
336
+ }
337
+
338
+ /** The pause marker, if one is active. Garbage reads as absent. */
339
+ export function readPauseMarker(stateDir) {
340
+ try {
341
+ const path = join(stateDir, 'state', 'paused-until.json');
342
+ if (!existsSync(path)) return null;
343
+ const doc = JSON.parse(readFileSync(path, 'utf8'));
344
+ return doc !== null && typeof doc === 'object' && !Array.isArray(doc) ? doc : null;
345
+ } catch {
346
+ return null;
347
+ }
348
+ }
349
+
312
350
  export async function buildContext({ input, now = new Date(), env = process.env, health = hookHealth } = {}) {
313
351
  // Said even in a repository that has nothing to do with Tyran: the claim
314
352
  // being corrected is about the PLUGIN the user installed, not about this
@@ -328,6 +366,7 @@ export async function buildContext({ input, now = new Date(), env = process.env,
328
366
  doctor: runDoctor(stateDir, nowIso),
329
367
  hardware: hardwareLine(),
330
368
  nowIso,
369
+ pause: readPauseMarker(stateDir),
331
370
  }),
332
371
  );
333
372
  }