@jjanczur/tyran 0.1.9 → 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.
- package/.claude-plugin/marketplace.json +1 -1
- package/.claude-plugin/plugin.json +1 -1
- package/CHANGELOG.md +34 -0
- package/README.md +4 -1
- package/bin/tyran.mjs +8 -0
- package/hooks/HOOK-CONTRACT-MEASURED.md +50 -3
- package/hooks/hooks.json +10 -0
- package/hooks/scripts/policy-gate.mjs +3 -4
- package/hooks/scripts/session-start.mjs +43 -4
- package/hooks/scripts/usage-gate.mjs +465 -0
- package/package.json +1 -1
- package/scripts/doctor.mjs +140 -2
- package/scripts/hooks-check.mjs +41 -4
- package/scripts/overnight.mjs +599 -0
- package/scripts/scan-repo.mjs +59 -16
- package/scripts/schema.mjs +62 -1
- package/scripts/statusline.mjs +161 -0
- package/skills/run/SKILL.md +9 -0
- package/skills/setup/SKILL.md +20 -0
- package/skills/status/SKILL.md +9 -5
- package/templates/config.yaml +20 -0
|
@@ -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.
|
|
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.
|
|
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,39 @@
|
|
|
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
|
+
|
|
3
37
|
## 0.1.9 — 2026-08-13
|
|
4
38
|
|
|
5
39
|
### 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
|
-
- [
|
|
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
|
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
|
-
|
|
5
|
-
guess about the platform is a gate of
|
|
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
|
@@ -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
|
}
|