@jjanczur/tyran 0.1.8 → 0.1.10

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.8",
14
+ "version": "0.1.10",
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.8",
3
+ "version": "0.1.10",
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,74 @@
1
1
  # Changelog
2
2
 
3
+ ## 0.1.10 — 2026-08-13
4
+
5
+ ### Overnight mode: the usage cliff becomes a wind-down
6
+
7
+ Both subscription windows were hit live while this was being built — a
8
+ five-hour wall at 12:15 and the weekly wall at 15:30, each killing a
9
+ four-agent review fleet mid-flight — which is the exact failure this
10
+ feature removes. A new `PreToolUse` usage gate reads the telemetry sidecar
11
+ that an operator-installed statusline helper (`scripts/statusline.mjs`)
12
+ maintains, and near the threshold refuses everything except a closed
13
+ wind-down set; the refusal text is the checkpoint checklist itself.
14
+ Measured on 2.1.197 and recorded in the hook contract: the hook payload
15
+ carries NO rate-limit data, so the statusline is the only telemetry source,
16
+ and every unknown fails open — no telemetry, stale telemetry, a malformed
17
+ config or a supervised operator can never produce a false pause.
18
+
19
+ Time-until-reset decides what happens next (`limits.wait_max_hours`,
20
+ default 5). Within it, `scripts/overnight.mjs` spawns a detached watcher
21
+ that sleeps to the reset and resumes the paused session with
22
+ `claude -p --resume`, then babysits it — a resumed headless session has no
23
+ statusline, so success is judged by journal movement, never exit codes.
24
+ Beyond it — the weekly shape — the pause is LONG: the operator is notified
25
+ (desktop notification, session-start banner, doctor) and by default nothing
26
+ resumes without them (`limits.long_wait: hold`). The `.tyran/STOP` brake
27
+ outranks the watcher; four new doctor codes surface active, stale, dead-
28
+ watcher and telemetry-missing states; the overnight runtime files are
29
+ name-exempt from the stray-file check and seeded into `.tyran/.gitignore` —
30
+ on an install whose gitignore predates them, re-running `scan-repo.mjs`
31
+ (`--write` or `--ensure-policy`) appends the missing lines.
32
+
33
+ The gate registers `node`-dispatched because the policy gate (correctly)
34
+ refuses agent-run `chmod` on hook paths; `hooks-check` learned to model
35
+ interpreter dispatch.
36
+
37
+ ## 0.1.9 — 2026-08-13
38
+
39
+ ### One layout for an initiative's files
40
+
41
+ The core disagreed with itself about where an initiative's files live:
42
+ `agents/retro.md` read `PLAN.md`/`NOTES.md` and wrote `RETRO.md` under
43
+ `.tyran/initiatives/<slug>/`, and iron rule 7 put leases there too — while
44
+ every mechanical consumer (journal, projections, doctor, the hooks) reads
45
+ `.tyran/state/<slug>/`, which is also where real installs put those files.
46
+ Everything now names `state/`; leases move to `.tyran/state/<slug>/locks/`,
47
+ already covered by the `.tyran/state/**` AUTO rule. The template keeps the
48
+ `.tyran/initiatives/*/locks/**` rule as a dated legacy alias for installs
49
+ adopted at ≤ 0.1.8, and `doctor --state` reports a leftover legacy directory
50
+ (`state-legacy-initiatives-dir`).
51
+
52
+ Because `state/` is committed and leases must not be, `scan-repo` (and so
53
+ `/tyran:setup`) now seeds a create-only `.tyran/.gitignore` excluding
54
+ `state/*/locks/`, and doctor warns when lease files are tracked anyway
55
+ (`lease-file-tracked`).
56
+
57
+ ### The knowledge store gets its missing reader
58
+
59
+ `.tyran/knowledge/` had a writer (the retrospective), a schema, and no
60
+ reader — the loop was write-only, and the measured cost was a 137 KB store
61
+ nothing consumed. `scripts/knowledge.mjs brief` (also `npx @jjanczur/tyran
62
+ knowledge brief`) selects entries whose `applies_to` globs intersect a
63
+ story's predicted files, ranks by confidence, cuts to a character budget
64
+ with an explicit omission line, and prints a block the conductor pastes
65
+ verbatim into a handoff — item (8) of the handoff contract. Reports owe a
66
+ verdict on the entry ids they received; the retrospective folds the verdicts
67
+ into the `used`/`helpful`/`outdated_reports` counters at close. Oversized
68
+ entries (over 4 000 characters) now draw a `knowledge-entry-oversized`
69
+ doctor warning, because one document-sized entry crowds out every other
70
+ entry a budgeted brief would have carried.
71
+
3
72
  ## 0.1.8 — 2026-08-08
4
73
 
5
74
  ### The secrets gate scanned everything except what the command published
package/README.md CHANGED
@@ -253,7 +253,11 @@ echo "wrong branch — hold everything" > .tyran/STOP
253
253
  tunes Tyran's own playbook, through an anti-bloat filter with four
254
254
  questions, a hard cap of three edits per retrospective, and a stated
255
255
  preference for deleting rules over adding them — so *"I changed nothing"*
256
- is a correct outcome, and so is declining the retro entirely. **You are
256
+ is a correct outcome, and so is declining the retro entirely. What was
257
+ learned reaches the agent that needs it: every handoff carries a budgeted
258
+ **knowledge brief** of the entries that apply to the files at hand, and
259
+ each agent's report grades the entries it received, so the store is
260
+ pruned on evidence. **You are
257
261
  never blocked twice**, whichever you choose. This is a gate rather than a
258
262
  sentence in a skill because the retro is the step most easily skipped: it
259
263
  happens after the merge, when the interesting part is over.
@@ -355,9 +359,9 @@ Published on npm as [`@jjanczur/tyran`](https://www.npmjs.com/package/@jjanczur/
355
359
  command stays `tyran` either way; only the registry name is scoped, the same
356
360
  pattern as `@angular/cli` giving you `ng`. `bin/tyran.mjs` exposes the same
357
361
  scripts the plugin's hooks and skills already call — `doctor`, `scan-repo`,
358
- `tiers`, `journal`, `schema`, `stop-check`, `scan-control-chars`,
359
- `desc-budget` — for a shell or a CI job with no Claude Code session. Zero
360
- dependencies; `--help` lists them.
362
+ `tiers`, `journal`, `schema`, `knowledge`, `stop-check`,
363
+ `scan-control-chars`, `desc-budget` — for a shell or a CI job with no Claude
364
+ Code session. Zero dependencies; `--help` lists them.
361
365
 
362
366
  ```bash
363
367
  npx @jjanczur/tyran doctor --hooks # is any gate installed but unable to fire?
@@ -432,7 +436,10 @@ underlying script does.
432
436
  published as numbers rather than as a table of intentions)
433
437
  - [ ] Update delta-review: reconcile a new core version with what your repo
434
438
  has learned locally
435
- - [ ] 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)
436
443
  - [ ] Read-only dashboard (phase C)
437
444
 
438
445
  ## Where this came from
@@ -55,6 +55,8 @@ commits and anything written to disk are in English.**
55
55
  after a `git fetch` run immediately beforehand; a stale remote once
56
56
  turned a correct proof into a false accusation.
57
57
  7. **Final report:** what was done · test and validation output · what the
58
- optimization pass changed · branch or PR · premises you corrected · open
59
- doubts. The open doubts are worth more than the summary; do not tidy them
60
- away.
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.
package/agents/retro.md CHANGED
@@ -12,7 +12,7 @@ to disk is in English.**
12
12
 
13
13
  ## Inputs, in this order
14
14
 
15
- 1. `.tyran/initiatives/<slug>/PLAN.md` (the ledger — what went smoothly, what
15
+ 1. `.tyran/state/<slug>/PLAN.md` (the ledger — what went smoothly, what
16
16
  came back) and `NOTES.md` (decisions, deviations, the agents' signals about
17
17
  the process itself).
18
18
  2. The agents' reports from this initiative: corrected premises, escalations,
@@ -64,6 +64,12 @@ next retro relitigating the same idea.
64
64
  - **Scripts and harnesses** worth reusing — gates, comparators, probes,
65
65
  report generators. A one-off harness from an initiative either becomes a
66
66
  general tool or gets deleted; do not leave dead files behind.
67
+ - **Knowledge upkeep:** fold the reports' knowledge-brief verdicts into the
68
+ entries' counters (the fold procedure lives in `skills/retro/SKILL.md`,
69
+ step 3 — one home, not two), and retire or split entries
70
+ `doctor --state` flags as `knowledge-entry-oversized`. An entry whose
71
+ counters say it stopped earning its keep is a deletion candidate, which
72
+ satisfies the deletion preference.
67
73
  - **Documentation that pays forward:** the repo's detected configuration,
68
74
  protocols, runbooks. **Every initiative should leave the repo better
69
75
  described than it found it** — that is the part that makes each next
@@ -78,7 +84,7 @@ behaviour visible to users of the product.
78
84
  ## Product
79
85
 
80
86
  1. The implemented changes — surgical, each with its reason.
81
- 2. `.tyran/initiatives/<slug>/RETRO.md`: what worked (keep it) · what failed
87
+ 2. `.tyran/state/<slug>/RETRO.md`: what worked (keep it) · what failed
82
88
  (with the cost) · **implemented** · **rejected and why** · candidates for
83
89
  later.
84
90
  3. A five-line report for the conductor: candidates, implemented, rejected,
package/bin/tyran.mjs CHANGED
@@ -68,6 +68,18 @@ export const COMMANDS = {
68
68
  'schema.mjs',
69
69
  'Validate .tyran/ config, knowledge, and policy files against their schemas.',
70
70
  ],
71
+ knowledge: [
72
+ 'knowledge.mjs',
73
+ 'Select the knowledge entries that apply to a set of paths and print a paste-ready brief for a handoff.',
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
+ ],
71
83
  'stop-check': [
72
84
  'stop-check.mjs',
73
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
  }