@jjanczur/tyran 0.1.35 → 0.1.36
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 +114 -0
- package/README.md +21 -12
- package/agents/implementer.md +17 -8
- package/hooks/scripts/session-start.mjs +25 -1
- package/package.json +1 -1
- package/scripts/answer.mjs +5 -0
- package/scripts/board-daemon.mjs +46 -4
- package/scripts/board-html.mjs +22 -10
- package/scripts/board.mjs +35 -11
- package/scripts/cli-args.mjs +82 -0
- package/scripts/cost.mjs +15 -4
- package/scripts/desc-budget.mjs +6 -0
- package/scripts/doctor.mjs +16 -10
- package/scripts/migrate.mjs +5 -0
- package/scripts/project.mjs +21 -2
- package/scripts/scan-repo.mjs +11 -0
- package/scripts/stop-check.mjs +6 -0
- package/scripts/tiers.mjs +21 -0
- package/skills/run/SKILL.md +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.36",
|
|
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.36",
|
|
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,119 @@
|
|
|
1
1
|
# Changelog
|
|
2
2
|
|
|
3
|
+
## 0.1.36 — 2026-08-17
|
|
4
|
+
|
|
5
|
+
Four fixes, three of them found by installing Tyran into a clean repo and
|
|
6
|
+
walking through what a new user actually gets, rather than by reading the code.
|
|
7
|
+
|
|
8
|
+
### The first sentence a new install reads was wrong
|
|
9
|
+
|
|
10
|
+
A brand-new user's opening message ended *"Run `/tyran` to resume, or read
|
|
11
|
+
`.tyran/state/<init>/STATE.md` in full."* There is nothing to resume, and
|
|
12
|
+
`.tyran/state/<init>/` is not a directory — at that point `.tyran/state/` holds
|
|
13
|
+
only `board-server.json`.
|
|
14
|
+
|
|
15
|
+
A regression from 0.1.34. `renderContext` returned `''` when there was no
|
|
16
|
+
initiative and no pause, so that line was unreachable from an empty repo;
|
|
17
|
+
autostart added `board` to the guard, `board` is non-null in every adopted
|
|
18
|
+
repo, and the whole scaffold began rendering for repos with no state at all.
|
|
19
|
+
Checked: a repo that never adopted Tyran still injects `{}`.
|
|
20
|
+
|
|
21
|
+
The closing line now branches, and names the initiative when there is exactly
|
|
22
|
+
one instead of sending the reader to look up `<init>`. The README's dashboard
|
|
23
|
+
section was stale the same way — it opened with `--serve`, a command setup made
|
|
24
|
+
unnecessary, and taught `--write` as an opt-in flag that setup now writes by
|
|
25
|
+
default.
|
|
26
|
+
|
|
27
|
+
### A board that failed to start deleted the record of the one running
|
|
28
|
+
|
|
29
|
+
With a board already up, a second `--serve` loses the bind, prints *"port 4173
|
|
30
|
+
is already in use"*, and exits — running the `clear` handler `board.mjs`
|
|
31
|
+
registers on `process.exit` unconditionally. That deleted the RUNNING board's
|
|
32
|
+
record. Measured after: `curl` still answering on 4173, `.tyran/state/` empty,
|
|
33
|
+
`--stop` reporting *"no board server is recorded"*. A server serving with
|
|
34
|
+
nothing naming it — invisible to `--status`, unreachable by `--stop`, killable
|
|
35
|
+
only with `lsof`.
|
|
36
|
+
|
|
37
|
+
`removeServerRecord` now refuses to unlink a record naming another pid. The
|
|
38
|
+
guard is in the module, not at the call site: ownership enforced by whoever
|
|
39
|
+
remembers to check is caller discipline, which `journal.mjs` and `doctor.mjs`
|
|
40
|
+
both reject by name. `stopServer` passes `owner: null` and has earned it.
|
|
41
|
+
|
|
42
|
+
Same session, same cause: `--detach --write --transcripts <dir>` against a
|
|
43
|
+
running board printed *"already serving"*, exit 0, and applied nothing.
|
|
44
|
+
`--transcripts` is the remedy the Spend tab itself prints, so the product
|
|
45
|
+
recommended a command that reported success and fixed nothing. The inert flags
|
|
46
|
+
are now named, with how to apply them. A plain re-run stays silent — autostart
|
|
47
|
+
runs it every session.
|
|
48
|
+
|
|
49
|
+
### The chip printed spawn time under the words "last signal"
|
|
50
|
+
|
|
51
|
+
`NOTES-REQUESTS` §11 recorded that four shipped features rest on a `progress`
|
|
52
|
+
event that fires once in 388 journals, and that the measurement to decide what
|
|
53
|
+
to do had not been made. It has now. Folding **420 real journals**: 72 running
|
|
54
|
+
agents on boards, `last_signal === since` for **72 of 72**, never once an actual
|
|
55
|
+
signal, with `detail`, `next` and `state: "blocked"` at zero.
|
|
56
|
+
|
|
57
|
+
`last_signal` fell back to the spawn time, so this was not an empty field — it
|
|
58
|
+
was spawn time published under a label saying *"when it last spoke"*, in the
|
|
59
|
+
chip, the `BOARD.md` column and the cross-repo line. A blank reads as an
|
|
60
|
+
absence; a number reads as a measurement.
|
|
61
|
+
|
|
62
|
+
The age was worth keeping, so this is a relabelling: the chip measures from
|
|
63
|
+
`since` and says *"since it started"*, `BOARD.md` gains a **Started** column,
|
|
64
|
+
and a real signal gets its own line when there is one. The golden fixture
|
|
65
|
+
missed it because its one agent does signal — the case that is universal in the
|
|
66
|
+
wild was the one no fixture covered.
|
|
67
|
+
|
|
68
|
+
`agents/implementer.md` now asks for **one** `progress` emission, at the first
|
|
69
|
+
blockage, instead of four. Three of the four were reconstructable from events
|
|
70
|
+
another party writes; a blockage is the exception, because nothing else says an
|
|
71
|
+
agent is stuck or why. Deleting `progress` outright was rejected for that
|
|
72
|
+
reason — `spawn-blocked` and the `blocked` lane stay.
|
|
73
|
+
|
|
74
|
+
### Four commands silently ignored a flag they did not understand
|
|
75
|
+
|
|
76
|
+
Swept every command `bin/tyran.mjs` dispatches, against a repo where setup had
|
|
77
|
+
just run:
|
|
78
|
+
|
|
79
|
+
| | |
|
|
80
|
+
|---|---:|
|
|
81
|
+
| `--help` answered as help | **0 of 14** |
|
|
82
|
+
| silently ignored an unknown flag | **4** |
|
|
83
|
+
|
|
84
|
+
`tiers`, `scan-repo`, `stop-check` and `desc-budget` parse by looking up the
|
|
85
|
+
flags they know, so a flag they do not know is never rejected — it is never
|
|
86
|
+
seen. `tiers --rol reviewer` exited **0** and printed the entire routing table:
|
|
87
|
+
a different answer to a different question, given without a word about the
|
|
88
|
+
typo. One character later, `tiers --role revieweer` was refused by name with
|
|
89
|
+
the list of valid roles — the value was checked and the flag was not. Worse,
|
|
90
|
+
`scan-repo --wrte .tyran/config.yaml` scanned, printed JSON and exited 0, a
|
|
91
|
+
swallowed typo in the one flag that decides whether the command writes.
|
|
92
|
+
|
|
93
|
+
`scripts/cli-args.mjs` is now the single implementation of both rules, and it
|
|
94
|
+
is not a new convention: `board`, `doctor`, `answer`, `cost` and `migrate`
|
|
95
|
+
already refused unknown flags, so this is the majority one made importable so
|
|
96
|
+
the count of spellings stops rising (ADR-21).
|
|
97
|
+
|
|
98
|
+
**`--help` is now answered, on stdout, exit 0, by all nine flag-taking
|
|
99
|
+
commands.** `cost` needed a second fix on the way: its `main` is handed an
|
|
100
|
+
already-sliced argv, so an added `argv.slice(2)` dropped the first two
|
|
101
|
+
arguments and `--help` fell through to the parser. The four subcommand-style
|
|
102
|
+
commands (`journal`, `schema`, `knowledge`, `mistakes`) still print usage with
|
|
103
|
+
exit 2; recorded in `NOTES-REQUESTS.md` rather than fixed here.
|
|
104
|
+
|
|
105
|
+
### Exercise cloud access, and never ask for a secret's value
|
|
106
|
+
|
|
107
|
+
Both from `NOTES-REQUESTS` §12.4. STEP 0 already spawns a throwaway teammate
|
|
108
|
+
rather than infer that Agent Teams work; cloud access had no such rule, and a
|
|
109
|
+
missing permission surfaces at deploy — after the work. It is now exercised
|
|
110
|
+
with a read-only call per service the plan names.
|
|
111
|
+
|
|
112
|
+
And a gate must never ask for a credential's VALUE: `journal.mjs ask` writes
|
|
113
|
+
the question into the journal and `answer.mjs apply` folds the reply back as a
|
|
114
|
+
`decision`, both into a committed file. Ask where it lives — the SSM parameter
|
|
115
|
+
name, the secrets-manager key, the vault path.
|
|
116
|
+
|
|
3
117
|
## 0.1.35 — 2026-08-17
|
|
4
118
|
|
|
5
119
|
### Three surfaces promised a consolidation step that nobody implements
|
package/README.md
CHANGED
|
@@ -229,20 +229,29 @@ echo "wrong branch — hold everything" > .tyran/STOP
|
|
|
229
229
|
|
|
230
230
|
## The dashboard
|
|
231
231
|
|
|
232
|
+
**It is already running.** `/tyran:setup` writes `board: autostart: true`, so
|
|
233
|
+
every session after it starts the dashboard if it is not up and prints the URL —
|
|
234
|
+
**open that.** The board is bound to loopback, re-rendered on every request, and
|
|
235
|
+
it reloads itself every 30 seconds.
|
|
236
|
+
|
|
237
|
+
The **Settings** tab is an editor for `.tyran/config.yaml` and the autonomy
|
|
238
|
+
policy — every knob with a sentence explaining it, your comments kept, and
|
|
239
|
+
loosening a boundary behind a second deliberate press. Setup turns it on;
|
|
240
|
+
`board: write: false` makes the board read-only, `autostart: false` stops it
|
|
241
|
+
starting at all.
|
|
242
|
+
|
|
243
|
+
From a plain shell — outside Claude Code, or in a script:
|
|
244
|
+
|
|
232
245
|
```bash
|
|
233
|
-
npx @jjanczur/tyran board --dir .tyran --
|
|
246
|
+
npx @jjanczur/tyran board --dir .tyran --detach # starts it, prints the URL, returns
|
|
247
|
+
npx @jjanczur/tyran board --dir .tyran --status # where is it, if anywhere
|
|
248
|
+
npx @jjanczur/tyran board --dir .tyran --stop # ends it
|
|
234
249
|
```
|
|
235
250
|
|
|
236
|
-
|
|
237
|
-
|
|
238
|
-
|
|
239
|
-
|
|
240
|
-
Claude Code and they need **Node ≥ 22**.
|
|
241
|
-
|
|
242
|
-
Add `--write` and the **Settings** tab becomes an editor for `.tyran/config.yaml`
|
|
243
|
-
and the autonomy policy — every knob with a sentence explaining it, your
|
|
244
|
-
comments kept, and loosening a boundary behind a second deliberate press. It is
|
|
245
|
-
read-only without that flag.
|
|
251
|
+
`--serve` instead of `--detach` holds the terminal until `Ctrl-C`, which is what
|
|
252
|
+
you want only if you are a person at a prompt. `--port <n>` if 4173 is taken.
|
|
253
|
+
These are the one place a Node version matters, because `npx` runs the scripts
|
|
254
|
+
outside Claude Code and they need **Node ≥ 22**.
|
|
246
255
|
|
|
247
256
|
No terminal, no server: the same page is written to **`.tyran/state/board.html`**
|
|
248
257
|
after every agent, so you can just open the file —
|
|
@@ -309,7 +318,7 @@ enforces the cap (4352 of 5000 characters). What each one assumes, when it
|
|
|
309
318
|
fires and who invokes it, is in
|
|
310
319
|
[skills and agents](https://jjanczur.github.io/tyran/skills/); the prompts
|
|
311
320
|
themselves are in [`skills/`](skills/) and [`agents/`](agents/). Behind all of
|
|
312
|
-
it:
|
|
321
|
+
it: 1586 unit tests, run with `node --test "tests/**/*.test.mjs"`.
|
|
313
322
|
|
|
314
323
|
## Documentation
|
|
315
324
|
|
package/agents/implementer.md
CHANGED
|
@@ -15,16 +15,25 @@ 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
|
|
19
|
-
MAIN checkout's journal (the handoff
|
|
20
|
-
|
|
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:
|
|
18
|
+
- **Signal ONCE: at the first blockage, before any workaround.** A
|
|
19
|
+
`progress` event appended to the MAIN checkout's journal (the handoff
|
|
20
|
+
carries its absolute path):
|
|
24
21
|
`node ${CLAUDE_PLUGIN_ROOT}/scripts/journal.mjs append <abs-journal>
|
|
25
22
|
progress <init> --actor <you> --data
|
|
26
|
-
'{"agent":"<you>","state":"blocked","ticket":"T-n","detail":"..."}'
|
|
27
|
-
|
|
23
|
+
'{"agent":"<you>","state":"blocked","ticket":"T-n","detail":"..."}'`,
|
|
24
|
+
and `state: "unblocked"` when it clears.
|
|
25
|
+
|
|
26
|
+
This asked for four emissions until 2026-08-17 — `started`, `blocked`,
|
|
27
|
+
`unblocked`, `working` — and measurement ended the argument: **one**
|
|
28
|
+
`progress` event across 388 real journals, against roughly six thousand
|
|
29
|
+
the instruction predicted. The lease bullet immediately above produced
|
|
30
|
+
434 in the same set, so this is not an agent that ignores the journal or
|
|
31
|
+
ignores this file. Three of the four asks were also reconstructable from
|
|
32
|
+
events someone else writes — your lease IS `started`, your report IS the
|
|
33
|
+
end of `working` — and a signal only you can contradict is worth less
|
|
34
|
+
than one another party produces. A blockage is the exception: nothing
|
|
35
|
+
else in the journal says you are stuck, or why. So the list is one item
|
|
36
|
+
long, and it is the item that carries information nothing else can.
|
|
28
37
|
- **Grep before you build.** Search for an existing implementation of the
|
|
29
38
|
thing you are about to write; if it exists, report it as a corrected
|
|
30
39
|
premise instead of duplicating it. Durable discoveries worth another
|
|
@@ -256,10 +256,34 @@ export function renderContext({ repoRoot, initiatives, doctor, hardware, nowIso,
|
|
|
256
256
|
lines.push('- run `node scripts/doctor.mjs --state --now "$(date -u +%FT%TZ)"` by hand');
|
|
257
257
|
}
|
|
258
258
|
lines.push('');
|
|
259
|
-
lines.push(
|
|
259
|
+
lines.push(closingLine(initiatives));
|
|
260
260
|
return lines.join('\n');
|
|
261
261
|
}
|
|
262
262
|
|
|
263
|
+
/**
|
|
264
|
+
* The last line — which, on a fresh install, is the FIRST sentence Tyran says.
|
|
265
|
+
*
|
|
266
|
+
* Until the board began starting itself this line was unreachable from an
|
|
267
|
+
* empty repo: the guard above returned '' when there was no initiative and no
|
|
268
|
+
* pause, so only someone with state to resume ever read it. Autostart made
|
|
269
|
+
* `board` non-null in every adopted repo, the guard stopped tripping, and a
|
|
270
|
+
* first-time user's opening message became an instruction to *resume* work
|
|
271
|
+
* that does not exist and to open a `STATE.md` under a literal `<init>`
|
|
272
|
+
* directory that is not on disk. A wrong first sentence, not a missing one.
|
|
273
|
+
*
|
|
274
|
+
* Naming the initiative when there is exactly one is the same defect a size
|
|
275
|
+
* down: `<init>` is a placeholder standing in a sentence whose writer already
|
|
276
|
+
* knows the answer. The name is a directory read off disk, so it is journal-
|
|
277
|
+
* adjacent input and goes through `inlinePlain` like everything else here.
|
|
278
|
+
*/
|
|
279
|
+
export function closingLine(initiatives) {
|
|
280
|
+
if (initiatives.length === 0) {
|
|
281
|
+
return 'No initiative here yet — run `/tyran` and describe what you want done.';
|
|
282
|
+
}
|
|
283
|
+
const where = initiatives.length === 1 ? inlinePlain(initiatives[0].name) : '<init>';
|
|
284
|
+
return `Run \`/tyran\` to resume, or read \`.tyran/state/${where}/STATE.md\` in full.`;
|
|
285
|
+
}
|
|
286
|
+
|
|
263
287
|
/**
|
|
264
288
|
* The plugin's own gates, checked at session start — the ONE thing this probe
|
|
265
289
|
* says even in a repository that has no Tyran state at all.
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@jjanczur/tyran",
|
|
3
|
-
"version": "0.1.
|
|
3
|
+
"version": "0.1.36",
|
|
4
4
|
"description": "Command-line scripts for the Tyran task conductor (doctor, journal, schema, and repo tooling) for CI and terminals outside Claude Code. Installing this package does NOT install the Claude Code plugin — add that separately with `/plugin marketplace add jjanczur/tyran` inside Claude Code.",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"engines": {
|
package/scripts/answer.mjs
CHANGED
|
@@ -54,6 +54,7 @@ import { append, ASK_KIND_RE, CAPPED_DATA_KEYS, readJournal } from './journal.mj
|
|
|
54
54
|
import { formatCodePoint, invisibleProblem } from './invisible.mjs';
|
|
55
55
|
import { resumeArgv, SESSION_ID_RE } from './overnight.mjs';
|
|
56
56
|
import { inlinePlain, naturalCompare, projectFile, WAITING_RE, writeAllAtomic, writeAtomic } from './project.mjs';
|
|
57
|
+
import { wantsHelp } from './cli-args.mjs';
|
|
57
58
|
|
|
58
59
|
/** The sheet, and the session record `apply --resume` reads. Both under
|
|
59
60
|
* `state/`, which is already the AUTO policy class on every install. */
|
|
@@ -871,6 +872,10 @@ function doApply(tyranDir, sheetPath, flags) {
|
|
|
871
872
|
}
|
|
872
873
|
|
|
873
874
|
function main() {
|
|
875
|
+
if (wantsHelp(process.argv.slice(2))) {
|
|
876
|
+
console.log(USAGE);
|
|
877
|
+
return;
|
|
878
|
+
}
|
|
874
879
|
let parsed;
|
|
875
880
|
try {
|
|
876
881
|
parsed = parseArgs(process.argv.slice(2));
|
package/scripts/board-daemon.mjs
CHANGED
|
@@ -112,8 +112,34 @@ export function writeServerRecord(dir, record) {
|
|
|
112
112
|
}
|
|
113
113
|
}
|
|
114
114
|
|
|
115
|
-
|
|
115
|
+
/**
|
|
116
|
+
* Remove the record — but only if it is THIS process's to remove.
|
|
117
|
+
*
|
|
118
|
+
* `owner` is the pid the caller claims. It defaults to this process because
|
|
119
|
+
* the ordinary caller is a server tidying up after itself, and the defect this
|
|
120
|
+
* guards is precisely a caller tidying up after somebody else: `board.mjs`
|
|
121
|
+
* registers its `clear` handler on `process.exit` unconditionally, so a
|
|
122
|
+
* `--serve` that lost the port to EADDRINUSE still ran it on the way out and
|
|
123
|
+
* deleted the record belonging to the healthy board that HELD the port. That
|
|
124
|
+
* board went on serving with no record naming it — invisible to `--status`,
|
|
125
|
+
* unreachable by `--stop`, and stoppable only with `lsof` and a kill. A leaked
|
|
126
|
+
* server is the exact failure this module was written to end, so it may not be
|
|
127
|
+
* reintroduced by the cleanup path.
|
|
128
|
+
*
|
|
129
|
+
* The guard lives here rather than at the call site on purpose. Ownership
|
|
130
|
+
* enforced by whoever remembers to check is caller discipline, which this
|
|
131
|
+
* repository rejects by name in `journal.mjs` and `doctor.mjs`.
|
|
132
|
+
*
|
|
133
|
+
* `owner: null` means "any", and `stopServer` is the one caller that has
|
|
134
|
+
* earned it: it health-probes the port and confirms the board answering there
|
|
135
|
+
* belongs to this directory before it signals or unlinks anything.
|
|
136
|
+
*/
|
|
137
|
+
export function removeServerRecord(dir, { owner = process.pid } = {}) {
|
|
116
138
|
try {
|
|
139
|
+
if (owner !== null) {
|
|
140
|
+
const record = readServerRecord(dir);
|
|
141
|
+
if (record !== null && record.pid !== owner) return false;
|
|
142
|
+
}
|
|
117
143
|
rmSync(serverRecordPath(dir), { force: true });
|
|
118
144
|
return true;
|
|
119
145
|
} catch {
|
|
@@ -290,7 +316,20 @@ export async function startDetached(
|
|
|
290
316
|
) {
|
|
291
317
|
const existing = await findLiveServer(dir, port, { probe });
|
|
292
318
|
if (existing !== null) {
|
|
293
|
-
|
|
319
|
+
// `write` comes back with the reuse so the caller can tell the operator
|
|
320
|
+
// when the flags on THIS command line did not apply. Start-time flags are
|
|
321
|
+
// silently inert against a server that is already up, and autostart has
|
|
322
|
+
// made "already up" the ordinary case rather than the unlucky one — so the
|
|
323
|
+
// remedy printed on the Spend tab (`--transcripts <dir>`) reported success
|
|
324
|
+
// and changed nothing for anyone whose board was already running.
|
|
325
|
+
return {
|
|
326
|
+
started: false,
|
|
327
|
+
reused: true,
|
|
328
|
+
port: existing.port,
|
|
329
|
+
url: urlFor(existing.port),
|
|
330
|
+
pid: existing.health.pid ?? null,
|
|
331
|
+
write: existing.health.write === true,
|
|
332
|
+
};
|
|
294
333
|
}
|
|
295
334
|
const chosen = await pickPort(dir, port, { probe });
|
|
296
335
|
if (chosen === null) {
|
|
@@ -381,7 +420,10 @@ export async function stopServer(dir, { probe = probeHealth, kill = process.kill
|
|
|
381
420
|
if (record === null) return { stopped: false, reason: 'no board server is recorded for this directory' };
|
|
382
421
|
const health = await probe(record.port);
|
|
383
422
|
if (health === null || !sameDir(health.dir, dir)) {
|
|
384
|
-
removeServerRecord
|
|
423
|
+
// `owner: null` — see removeServerRecord. Clearing a record that names
|
|
424
|
+
// another pid is this function's JOB, and it has proved the right to it:
|
|
425
|
+
// either nothing answers, or what answers is not this directory's board.
|
|
426
|
+
removeServerRecord(dir, { owner: null });
|
|
385
427
|
return { stopped: false, reason: `nothing is answering on port ${record.port} — cleared the stale record` };
|
|
386
428
|
}
|
|
387
429
|
const pid = health.pid ?? record.pid;
|
|
@@ -391,7 +433,7 @@ export async function stopServer(dir, { probe = probeHealth, kill = process.kill
|
|
|
391
433
|
} catch (err) {
|
|
392
434
|
return { stopped: false, reason: `could not signal pid ${pid}: ${String(err?.message ?? err)}` };
|
|
393
435
|
}
|
|
394
|
-
removeServerRecord(dir);
|
|
436
|
+
removeServerRecord(dir, { owner: null });
|
|
395
437
|
return { stopped: true, pid, port: record.port };
|
|
396
438
|
}
|
|
397
439
|
|
package/scripts/board-html.mjs
CHANGED
|
@@ -501,11 +501,21 @@ if (data.schema !== 1) {
|
|
|
501
501
|
// Four buckets, not three. The old top bucket was "30 minutes or six
|
|
502
502
|
// hours", which are not the same event: one is a long test run, the
|
|
503
503
|
// other is an agent that is not coming back.
|
|
504
|
-
|
|
505
|
-
|
|
506
|
-
|
|
507
|
-
|
|
504
|
+
// Measured from SPAWN, and it says so. This line read "N min since last
|
|
505
|
+
// signal" off a field that held spawn time for 72 of 72 agents across
|
|
506
|
+
// 420 journals — a real number under a label describing a different
|
|
507
|
+
// event. The number was worth keeping; the label was not.
|
|
508
|
+
var ageMs = ageMsOf(a.since);
|
|
509
|
+
var ageText = ageMs === null ? 'start time unknown'
|
|
510
|
+
: ageMs >= 10800000 ? Math.round(ageMs / 3600000) + ' HOURS since it started — likely dead'
|
|
511
|
+
: Math.round(ageMs / 60000) + ' min since it started';
|
|
508
512
|
chip.appendChild(el('div', ageClass(ageMs), ageText));
|
|
513
|
+
// Shown only when there IS one. An agent that has signalled is rare
|
|
514
|
+
// enough that it deserves its own line rather than a slot that reads the
|
|
515
|
+
// same whether it spoke or not.
|
|
516
|
+
if (a.last_signal) {
|
|
517
|
+
chip.appendChild(el('div', ageClass(ageMsOf(a.last_signal)), 'said so ' + ago(a.last_signal)));
|
|
518
|
+
}
|
|
509
519
|
// Signal is what the agent SAID; evidence is what it SHOWED. An agent
|
|
510
520
|
// emitting progress every few minutes while achieving nothing is the
|
|
511
521
|
// healthiest-looking chip on the board, and the strip is sorted by the
|
|
@@ -1004,7 +1014,7 @@ if (data.schema !== 1) {
|
|
|
1004
1014
|
var sp = panels.spend;
|
|
1005
1015
|
var spBody = el('div');
|
|
1006
1016
|
sp.appendChild(spBody);
|
|
1007
|
-
spBody.appendChild(el('div', 'hint', 'Spend is read from the transcripts Claude Code already writes, and it is served rather than embedded
|
|
1017
|
+
spBody.appendChild(el('div', 'hint', 'Spend is read from the transcripts Claude Code already writes, and it is served rather than embedded. You are reading the file on disk, so this tab stays empty. Setup starts a dashboard with every session — open the URL it printed, or run "board.mjs --dir .tyran --detach" to start one and print it.'));
|
|
1008
1018
|
|
|
1009
1019
|
// Mirrors compositionLabel in cost.mjs. Restated rather than imported
|
|
1010
1020
|
// because this file is a browser bundle with no module graph — the two are
|
|
@@ -1073,8 +1083,9 @@ if (data.schema !== 1) {
|
|
|
1073
1083
|
if (payload && payload.transcripts_found === false) {
|
|
1074
1084
|
hints.push(
|
|
1075
1085
|
'No transcripts found for this repo. If the conductor ran from another working directory, ' +
|
|
1076
|
-
'
|
|
1077
|
-
'
|
|
1086
|
+
'set spend.transcript_dirs in .tyran/config.yaml \\u2014 that survives a restart and is read ' +
|
|
1087
|
+
'on the next request. The --transcripts <dir> flag does the same, but only as a server STARTS: ' +
|
|
1088
|
+
'against a board that is already up it has no effect, so stop that one first.'
|
|
1078
1089
|
);
|
|
1079
1090
|
}
|
|
1080
1091
|
return hints;
|
|
@@ -1242,8 +1253,9 @@ if (data.schema !== 1) {
|
|
|
1242
1253
|
if ((cov.agent_transcripts || 0) === 0 && agents.length > 0) {
|
|
1243
1254
|
into.appendChild(el('div', 'hint',
|
|
1244
1255
|
'No agent transcripts found where this repo\\u2019s transcripts are expected. If the conductor ' +
|
|
1245
|
-
'ran from another working directory,
|
|
1246
|
-
'--transcripts <dir>
|
|
1256
|
+
'ran from another working directory, set spend.transcript_dirs in .tyran/config.yaml. The ' +
|
|
1257
|
+
'--transcripts <dir> flag does the same, but only as a server STARTS: against a board that is ' +
|
|
1258
|
+
'already up it has no effect, so stop that one first.'));
|
|
1247
1259
|
}
|
|
1248
1260
|
// cost.transcripts_found is true whenever this function runs at all, so
|
|
1249
1261
|
// spendResolutionHints only ever contributes the missing-dirs line here
|
|
@@ -1351,7 +1363,7 @@ if (data.schema !== 1) {
|
|
|
1351
1363
|
var st = panels.settings;
|
|
1352
1364
|
var stBody = el('div');
|
|
1353
1365
|
st.appendChild(stBody);
|
|
1354
|
-
stBody.appendChild(el('div', 'setnote', 'Settings are read from .tyran/config.yaml and .tyran/policies/autonomy.yaml, and they are served rather than embedded — open
|
|
1366
|
+
stBody.appendChild(el('div', 'setnote', 'Settings are read from .tyran/config.yaml and .tyran/policies/autonomy.yaml, and they are served rather than embedded. You are reading the file on disk. Setup starts a dashboard with every session — open the URL it printed, or run "board.mjs --dir .tyran --detach" to start one and print it.'));
|
|
1355
1367
|
|
|
1356
1368
|
// Auto-refresh, and the reason it is a timer rather than a meta tag.
|
|
1357
1369
|
//
|
package/scripts/board.mjs
CHANGED
|
@@ -55,6 +55,7 @@ import { SettingsError, applyPolicyClass, applySetting, readSettings } from './s
|
|
|
55
55
|
import { checkStopAt } from './stop-check.mjs';
|
|
56
56
|
import { runState } from './overnight.mjs';
|
|
57
57
|
import { answerOne, answerProblem, classify, openAsks, partitionAsks, reRender, sortAsks } from './answer.mjs';
|
|
58
|
+
import { wantsHelp } from './cli-args.mjs';
|
|
58
59
|
import {
|
|
59
60
|
HEALTH_ROUTE,
|
|
60
61
|
PORT_SEARCH_SPAN,
|
|
@@ -453,7 +454,8 @@ export function renderCrossMd(payload) {
|
|
|
453
454
|
parts.push(
|
|
454
455
|
`- \`${inline(a.agent)}\` (${inline(a.role)}) — ${inline(a.init)}` +
|
|
455
456
|
`${a.ticket != null ? ` · \`${inline(a.ticket)}\`` : ''} · ${inline(a.state)}` +
|
|
456
|
-
`${a.detail != null ? ` — ${inline(a.detail)}` : ''} ·
|
|
457
|
+
`${a.detail != null ? ` — ${inline(a.detail)}` : ''} · started ${inline(a.since)}` +
|
|
458
|
+
`${a.last_signal != null ? ` · last signal ${inline(a.last_signal)}` : ''}` +
|
|
457
459
|
`${a.next != null ? ` · next: ${inline(a.next)}` : ''}\n`,
|
|
458
460
|
);
|
|
459
461
|
}
|
|
@@ -697,18 +699,25 @@ function parseArgs(argv) {
|
|
|
697
699
|
return flags;
|
|
698
700
|
}
|
|
699
701
|
|
|
702
|
+
export const BOARD_USAGE =
|
|
703
|
+
'usage: board.mjs [--dir <.tyran>] [--check]\n' +
|
|
704
|
+
' [--serve|--detach [--port <n>] [--write] [--open] [--transcripts <dir>]...]\n' +
|
|
705
|
+
' [--status] [--stop]';
|
|
706
|
+
|
|
700
707
|
function main() {
|
|
708
|
+
// Answered before parsing, because the parser's job is to refuse what it
|
|
709
|
+
// does not know and `--help` is exactly that to every parser here.
|
|
710
|
+
if (wantsHelp(process.argv.slice(2))) {
|
|
711
|
+
console.log(BOARD_USAGE);
|
|
712
|
+
return;
|
|
713
|
+
}
|
|
701
714
|
let flags;
|
|
702
715
|
try {
|
|
703
716
|
flags = parseArgs(process.argv.slice(2));
|
|
704
717
|
} catch (err) {
|
|
705
718
|
if (!(err instanceof UsageError)) throw err;
|
|
706
719
|
console.error(`board: ${err.message}`);
|
|
707
|
-
console.error(
|
|
708
|
-
'usage: board.mjs [--dir <.tyran>] [--check]\n' +
|
|
709
|
-
' [--serve|--detach [--port <n>] [--write] [--open] [--transcripts <dir>]...]\n' +
|
|
710
|
-
' [--status] [--stop]'
|
|
711
|
-
);
|
|
720
|
+
console.error(BOARD_USAGE);
|
|
712
721
|
process.exit(2);
|
|
713
722
|
}
|
|
714
723
|
// `--detach` is `--serve` that returns. Every flag describing HOW to serve
|
|
@@ -805,12 +814,27 @@ function main() {
|
|
|
805
814
|
// "Already running" is a SUCCESS, and saying which one it is matters:
|
|
806
815
|
// this command is meant to be safe to run on every session start, so
|
|
807
816
|
// its ordinary outcome is that there was nothing to do.
|
|
817
|
+
if (result.reused) {
|
|
818
|
+
console.log(`board: already serving ${result.url} (pid ${result.pid ?? '?'})`);
|
|
819
|
+
// Start-time flags do not reach a server that is already up. Saying
|
|
820
|
+
// so is the whole fix: the command reported success, the operator
|
|
821
|
+
// reloaded the tab, and nothing had changed — with `--transcripts`
|
|
822
|
+
// that is the remedy the Spend tab itself recommends.
|
|
823
|
+
const inert = [];
|
|
824
|
+
if (flags.transcripts.length > 0) inert.push('--transcripts');
|
|
825
|
+
if (flags.write && !result.write) inert.push('--write');
|
|
826
|
+
if (inert.length > 0) {
|
|
827
|
+
console.log(
|
|
828
|
+
`board: ${inert.join(' and ')} had NO effect — that server was started separately. ` +
|
|
829
|
+
`To change how it runs: node scripts/board.mjs --dir ${dir} --stop, then start it again.`,
|
|
830
|
+
);
|
|
831
|
+
}
|
|
832
|
+
return;
|
|
833
|
+
}
|
|
808
834
|
console.log(
|
|
809
|
-
result.
|
|
810
|
-
?
|
|
811
|
-
|
|
812
|
-
`${flags.write ? 'Settings can edit config.yaml and autonomy.yaml' : 'read-only'}; ` +
|
|
813
|
-
`stop it with: node scripts/board.mjs --dir ${dir} --stop)`,
|
|
835
|
+
`board: serving ${result.url} (pid ${result.pid ?? '?'}; ` +
|
|
836
|
+
`${flags.write ? 'Settings can edit config.yaml and autonomy.yaml' : 'read-only'}; ` +
|
|
837
|
+
`stop it with: node scripts/board.mjs --dir ${dir} --stop)`,
|
|
814
838
|
);
|
|
815
839
|
});
|
|
816
840
|
return;
|
|
@@ -0,0 +1,82 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* cli-args — the two things every command-line entry point owes its caller:
|
|
3
|
+
* answer `--help`, and refuse a flag it does not understand.
|
|
4
|
+
*
|
|
5
|
+
* Measured across the 14 commands `bin/tyran.mjs` dispatches, on a repo where
|
|
6
|
+
* setup had just run:
|
|
7
|
+
*
|
|
8
|
+
* --help answered as help ............ 0 of 14
|
|
9
|
+
* silently IGNORED an unknown flag ... 4 (tiers, scan-repo, stop-check,
|
|
10
|
+
* desc-budget)
|
|
11
|
+
*
|
|
12
|
+
* The second is the defect; the first is the symptom that found it. Those four
|
|
13
|
+
* parse by scanning for the flags they know (`args.indexOf('--role')`), so a
|
|
14
|
+
* flag they do not know is not rejected — it is never looked at. `tiers --rol
|
|
15
|
+
* reviewer` therefore exits 0 and prints the whole routing table, which is a
|
|
16
|
+
* different answer to a different question, given without a word about the
|
|
17
|
+
* typo. The same line one character later, `tiers --role revieweer`, is
|
|
18
|
+
* refused with the list of valid roles: the VALUE was validated and the flag
|
|
19
|
+
* NAME was not.
|
|
20
|
+
*
|
|
21
|
+
* board.mjs, doctor.mjs, answer.mjs, cost.mjs and migrate.mjs already refuse
|
|
22
|
+
* unknown flags. This module is not a new convention — it is the one already
|
|
23
|
+
* in the majority, made importable so the count of spellings stops going up
|
|
24
|
+
* (ADR-21).
|
|
25
|
+
*/
|
|
26
|
+
|
|
27
|
+
/** What a caller types when they want to be told, rather than obeyed. */
|
|
28
|
+
export const HELP_FLAGS = Object.freeze(['--help', '-h', 'help']);
|
|
29
|
+
|
|
30
|
+
export function wantsHelp(args) {
|
|
31
|
+
return args.some((arg) => HELP_FLAGS.includes(arg));
|
|
32
|
+
}
|
|
33
|
+
|
|
34
|
+
/**
|
|
35
|
+
* Every `--flag` in `args` that is not in `known`.
|
|
36
|
+
*
|
|
37
|
+
* Returns the offending tokens rather than throwing, so each caller keeps its
|
|
38
|
+
* own exit code and its own `name: message` prefix — the scripts disagree
|
|
39
|
+
* about those on purpose and this module has no business unifying them.
|
|
40
|
+
*
|
|
41
|
+
* A bare `--` ends flag parsing by convention and is not a flag; anything
|
|
42
|
+
* after it is a positional and is not inspected. Negative numbers (`-3`) are
|
|
43
|
+
* not flags either, which is why only `--` prefixes are considered.
|
|
44
|
+
*/
|
|
45
|
+
export function unknownFlags(args, known) {
|
|
46
|
+
const allow = new Set(known.map((k) => (k.startsWith('--') ? k : `--${k}`)));
|
|
47
|
+
const found = [];
|
|
48
|
+
for (const arg of args) {
|
|
49
|
+
if (arg === '--') break;
|
|
50
|
+
if (!arg.startsWith('--')) continue;
|
|
51
|
+
// `--flag=value` is the same flag as `--flag`.
|
|
52
|
+
const name = arg.includes('=') ? arg.slice(0, arg.indexOf('=')) : arg;
|
|
53
|
+
if (!allow.has(name)) found.push(name);
|
|
54
|
+
}
|
|
55
|
+
return found;
|
|
56
|
+
}
|
|
57
|
+
|
|
58
|
+
/**
|
|
59
|
+
* The whole contract in one call, for a script whose usage is a plain string.
|
|
60
|
+
*
|
|
61
|
+
* `print`/`fail` are injected so a test can drive this without a process, and
|
|
62
|
+
* `exit` is called rather than returned so a caller cannot forget to stop.
|
|
63
|
+
*/
|
|
64
|
+
export function handleArgs(
|
|
65
|
+
args,
|
|
66
|
+
{ name, usage, known },
|
|
67
|
+
{ print = console.log, fail = console.error, exit = process.exit } = {},
|
|
68
|
+
) {
|
|
69
|
+
if (wantsHelp(args)) {
|
|
70
|
+
print(usage);
|
|
71
|
+
exit(0);
|
|
72
|
+
return false;
|
|
73
|
+
}
|
|
74
|
+
const bad = unknownFlags(args, known);
|
|
75
|
+
if (bad.length > 0) {
|
|
76
|
+
fail(`${name}: unknown flag ${bad.join(', ')}`);
|
|
77
|
+
fail(usage);
|
|
78
|
+
exit(2);
|
|
79
|
+
return false;
|
|
80
|
+
}
|
|
81
|
+
return true;
|
|
82
|
+
}
|
package/scripts/cost.mjs
CHANGED
|
@@ -47,6 +47,7 @@ import { parse } from './yaml-lite.mjs';
|
|
|
47
47
|
import { pricingOf, PRICING_RATE_KEYS } from './schema.mjs';
|
|
48
48
|
import { defaultRateCard, RATE_CARD_ID, planOfTier, PLAN_LABELS, SUBSCRIPTION_USD, periodStart } from './pricing.mjs';
|
|
49
49
|
import { jsonEscapeInvisible } from './invisible.mjs';
|
|
50
|
+
import { wantsHelp } from './cli-args.mjs';
|
|
50
51
|
|
|
51
52
|
export const COST_FILE = 'cost.json';
|
|
52
53
|
|
|
@@ -1265,16 +1266,26 @@ function parseArgs(argv) {
|
|
|
1265
1266
|
return flags;
|
|
1266
1267
|
}
|
|
1267
1268
|
|
|
1269
|
+
export const COST_USAGE =
|
|
1270
|
+
'usage: cost.mjs [--dir <.tyran>] [--session <id>] [--projects <dir>] ' +
|
|
1271
|
+
'[--transcripts <dir>]... [--window 30d|period|all] [--json]';
|
|
1272
|
+
|
|
1268
1273
|
function main(argv) {
|
|
1274
|
+
// `argv` reaches here ALREADY sliced — `main(process.argv.slice(2))` at the
|
|
1275
|
+
// bottom of this file — unlike migrate.mjs next door, which is handed the
|
|
1276
|
+
// whole of process.argv. Slicing again here silently dropped the first two
|
|
1277
|
+
// arguments, so `cost --help` fell through to the parser and was reported as
|
|
1278
|
+
// an unknown argument.
|
|
1279
|
+
if (wantsHelp(argv)) {
|
|
1280
|
+
console.log(COST_USAGE);
|
|
1281
|
+
return 0;
|
|
1282
|
+
}
|
|
1269
1283
|
let flags;
|
|
1270
1284
|
try {
|
|
1271
1285
|
flags = parseArgs(argv);
|
|
1272
1286
|
} catch (err) {
|
|
1273
1287
|
console.error(String(err.message ?? err));
|
|
1274
|
-
console.error(
|
|
1275
|
-
'usage: cost.mjs [--dir <.tyran>] [--session <id>] [--projects <dir>] ' +
|
|
1276
|
-
'[--transcripts <dir>]... [--window 30d|period|all] [--json]'
|
|
1277
|
-
);
|
|
1288
|
+
console.error(COST_USAGE);
|
|
1278
1289
|
return 2;
|
|
1279
1290
|
}
|
|
1280
1291
|
const tyranDir = resolve(flags.dir);
|
package/scripts/desc-budget.mjs
CHANGED
|
@@ -14,6 +14,7 @@ import { readFileSync, readdirSync, statSync, existsSync, realpathSync } from 'n
|
|
|
14
14
|
import { escapeInvisible } from './invisible.mjs';
|
|
15
15
|
import { join, dirname, resolve } from 'node:path';
|
|
16
16
|
import { fileURLToPath } from 'node:url';
|
|
17
|
+
import { handleArgs } from './cli-args.mjs';
|
|
17
18
|
|
|
18
19
|
/**
|
|
19
20
|
* The ceiling, and the ONLY place it is written.
|
|
@@ -68,8 +69,13 @@ export function collectSkillDescriptions(pluginRoot) {
|
|
|
68
69
|
return out.sort((a, b) => b.length - a.length);
|
|
69
70
|
}
|
|
70
71
|
|
|
72
|
+
export const DESC_BUDGET_USAGE =
|
|
73
|
+
'usage: desc-budget.mjs [--budget <chars>] [pluginRoot]\n' +
|
|
74
|
+
'Exit: 0 within budget · 1 over budget · 2 usage/IO error';
|
|
75
|
+
|
|
71
76
|
function main() {
|
|
72
77
|
const args = process.argv.slice(2);
|
|
78
|
+
if (!handleArgs(args, { name: 'desc-budget', usage: DESC_BUDGET_USAGE, known: ['budget'] })) return;
|
|
73
79
|
let budget = DEFAULT_BUDGET;
|
|
74
80
|
const bi = args.indexOf('--budget');
|
|
75
81
|
if (bi !== -1) {
|
package/scripts/doctor.mjs
CHANGED
|
@@ -67,6 +67,7 @@ import { readPlatformUsage } from './usage-source.mjs';
|
|
|
67
67
|
import { gitRunner } from './scan-repo.mjs';
|
|
68
68
|
import { SERVER_RECORD_FILE } from './board-daemon.mjs';
|
|
69
69
|
import { parseMistakes, countSignatures, fenceState, KNOWLEDGE_THRESHOLD, MISTAKES_FILE, CLAUDE_MD_FILE } from './mistakes.mjs';
|
|
70
|
+
import { wantsHelp } from './cli-args.mjs';
|
|
70
71
|
|
|
71
72
|
/** Severity order is also the report order. `info` never fails the check. */
|
|
72
73
|
export const SEVERITIES = Object.freeze(['error', 'warning', 'info']);
|
|
@@ -2099,7 +2100,21 @@ export function parseArgs(argv) {
|
|
|
2099
2100
|
};
|
|
2100
2101
|
}
|
|
2101
2102
|
|
|
2103
|
+
export const DOCTOR_USAGE =
|
|
2104
|
+
'usage: doctor.mjs --state [--dir <.tyran>] [--json] [--now <iso>] [--stale-hours <n>]\n' +
|
|
2105
|
+
' doctor.mjs --hooks [--plugin-root <dir>] [--json]\n' +
|
|
2106
|
+
'\n' +
|
|
2107
|
+
' A mode is REQUIRED: `--state` asks whether the record of the work is\n' +
|
|
2108
|
+
' consistent, `--hooks` whether the gates can fire at all. They answer\n' +
|
|
2109
|
+
' different questions, and a bare invocation would have to pick one\n' +
|
|
2110
|
+
' silently. This text said `--state is the only mode today` long after\n' +
|
|
2111
|
+
' `--hooks` shipped, which sent readers looking for a flag they had.';
|
|
2112
|
+
|
|
2102
2113
|
function main() {
|
|
2114
|
+
if (wantsHelp(process.argv.slice(2))) {
|
|
2115
|
+
console.log(DOCTOR_USAGE);
|
|
2116
|
+
return;
|
|
2117
|
+
}
|
|
2103
2118
|
try {
|
|
2104
2119
|
const args = parseArgs(process.argv.slice(2));
|
|
2105
2120
|
const { dir, json, now, staleHours, dirGiven } = args;
|
|
@@ -2126,16 +2141,7 @@ function main() {
|
|
|
2126
2141
|
if (!allOk) process.exit(1);
|
|
2127
2142
|
} catch (err) {
|
|
2128
2143
|
if (err instanceof UsageError) {
|
|
2129
|
-
console.error(
|
|
2130
|
-
'usage: doctor.mjs --state [--dir <.tyran>] [--json] [--now <iso>] [--stale-hours <n>]\n' +
|
|
2131
|
-
' doctor.mjs --hooks [--plugin-root <dir>] [--json]\n' +
|
|
2132
|
-
'\n' +
|
|
2133
|
-
' A mode is REQUIRED: `--state` asks whether the record of the work is\n' +
|
|
2134
|
-
' consistent, `--hooks` whether the gates can fire at all. They answer\n' +
|
|
2135
|
-
' different questions, and a bare invocation would have to pick one\n' +
|
|
2136
|
-
' silently. This text said `--state is the only mode today` long after\n' +
|
|
2137
|
-
' `--hooks` shipped, which sent readers looking for a flag they had.',
|
|
2138
|
-
);
|
|
2144
|
+
console.error(DOCTOR_USAGE);
|
|
2139
2145
|
process.exit(2);
|
|
2140
2146
|
}
|
|
2141
2147
|
console.error(`doctor: ${err.message}`);
|
package/scripts/migrate.mjs
CHANGED
|
@@ -41,6 +41,7 @@ import { existsSync, mkdirSync, readdirSync, renameSync, rmdirSync, statSync } f
|
|
|
41
41
|
import { join, resolve } from 'node:path';
|
|
42
42
|
|
|
43
43
|
import { escapeInvisible } from './invisible.mjs';
|
|
44
|
+
import { wantsHelp } from './cli-args.mjs';
|
|
44
45
|
|
|
45
46
|
/** The pre-0.1.9 home of the initiative directories. */
|
|
46
47
|
export const LEGACY_DIR = 'initiatives';
|
|
@@ -154,6 +155,10 @@ function usage(message) {
|
|
|
154
155
|
|
|
155
156
|
function main(argv) {
|
|
156
157
|
const args = argv.slice(2);
|
|
158
|
+
if (wantsHelp(args)) {
|
|
159
|
+
console.log('usage: node scripts/migrate.mjs [--dir <.tyran>] [--apply]');
|
|
160
|
+
return;
|
|
161
|
+
}
|
|
157
162
|
for (const arg of args) {
|
|
158
163
|
if (!['--dir', '--apply'].includes(arg) && arg.startsWith('--')) usage(`unknown flag ${arg}`);
|
|
159
164
|
}
|
package/scripts/project.mjs
CHANGED
|
@@ -978,7 +978,22 @@ export function boardOf(state, { staleHours = DEFAULT_STALE_HOURS } = {}) {
|
|
|
978
978
|
open_hours: ageHours === null ? null : Math.round(ageHours * 10) / 10,
|
|
979
979
|
detail: signal?.detail ?? null,
|
|
980
980
|
next: signal?.next ?? null,
|
|
981
|
-
|
|
981
|
+
// NULL when the agent has never signalled, and it almost never has.
|
|
982
|
+
//
|
|
983
|
+
// This used to fall back to `a.spawnTs`, which made every consumer
|
|
984
|
+
// print spawn time under a label that says "when it last spoke".
|
|
985
|
+
// Measured over 420 real journals: 72 running agents on boards, and
|
|
986
|
+
// `last_signal === since` for 72 of 72. Not once a signal. `detail`,
|
|
987
|
+
// `next` and `state: 'blocked'` were zero across the same set, because
|
|
988
|
+
// all four come from a `progress` event that fires once in 388
|
|
989
|
+
// journals against an instruction asking for four per story.
|
|
990
|
+
//
|
|
991
|
+
// The fallback made that invisible: the board looked like it was
|
|
992
|
+
// reporting agent chatter and was reporting process ages. A wrong
|
|
993
|
+
// number reads as a measurement, which is worse than a blank — so the
|
|
994
|
+
// blank is the honest value, and `since` (right below) is where spawn
|
|
995
|
+
// time has always actually lived.
|
|
996
|
+
last_signal: signal?.ts ?? null,
|
|
982
997
|
// What it has SHOWN. Null until it shows something, which is the
|
|
983
998
|
// ordinary state of an agent that has just started — the strip says
|
|
984
999
|
// "nothing yet" rather than implying silence.
|
|
@@ -1029,13 +1044,17 @@ export function renderBoard(state, board = boardOf(state)) {
|
|
|
1029
1044
|
parts.push('\n## Agents\n\n');
|
|
1030
1045
|
parts.push(
|
|
1031
1046
|
table(
|
|
1032
|
-
|
|
1047
|
+
// "Started" is the column that always has a value; "Last signal" is the
|
|
1048
|
+
// one that almost never does, and printing spawn time in it made the
|
|
1049
|
+
// table look fuller than the journal was.
|
|
1050
|
+
['Agent', 'Role', 'Ticket', 'State', 'Detail', 'Started', 'Last signal'],
|
|
1033
1051
|
sortByKey(board.agents, (a) => a.agent).map((a) => [
|
|
1034
1052
|
inline(a.agent),
|
|
1035
1053
|
inline(a.role),
|
|
1036
1054
|
inline(a.ticket),
|
|
1037
1055
|
inline(a.state),
|
|
1038
1056
|
inline(a.detail),
|
|
1057
|
+
inline(a.since),
|
|
1039
1058
|
inline(a.last_signal),
|
|
1040
1059
|
]),
|
|
1041
1060
|
),
|
package/scripts/scan-repo.mjs
CHANGED
|
@@ -35,6 +35,7 @@ import { fileURLToPath } from 'node:url';
|
|
|
35
35
|
import { parse, stringify } from './yaml-lite.mjs';
|
|
36
36
|
import { validatePolicy } from './schema.mjs';
|
|
37
37
|
import { escapeInvisible } from './invisible.mjs';
|
|
38
|
+
import { handleArgs } from './cli-args.mjs';
|
|
38
39
|
|
|
39
40
|
/** Lockfile -> package manager. Order matters only for reporting stability. */
|
|
40
41
|
export const LOCKFILES = Object.freeze({
|
|
@@ -820,8 +821,18 @@ export function ensureStateGitignore(repoRoot) {
|
|
|
820
821
|
return { path, status: 'created' };
|
|
821
822
|
}
|
|
822
823
|
|
|
824
|
+
export const SCAN_REPO_USAGE =
|
|
825
|
+
'usage: scan-repo.mjs [--dir <repo-root>] [--write <.tyran/config.yaml>]\n' +
|
|
826
|
+
' [--ensure-policy]\n' +
|
|
827
|
+
'With no --write, prints the scan as JSON and changes nothing.\n' +
|
|
828
|
+
'--write also installs .tyran/policies/autonomy.yaml first, create-only.\n' +
|
|
829
|
+
'--ensure-policy is the repair path: seed the policy and do nothing else.';
|
|
830
|
+
|
|
823
831
|
function main() {
|
|
824
832
|
const args = process.argv.slice(2);
|
|
833
|
+
// `--wrte .tyran/config.yaml` used to scan, print JSON and exit 0 — a typo
|
|
834
|
+
// in the one flag that decides whether this command WRITES, swallowed.
|
|
835
|
+
if (!handleArgs(args, { name: 'scan-repo', usage: SCAN_REPO_USAGE, known: ['dir', 'write', 'ensure-policy'] })) return;
|
|
825
836
|
const flag = (name, fallback) => {
|
|
826
837
|
const i = args.indexOf(`--${name}`);
|
|
827
838
|
return i === -1 ? fallback : args[i + 1];
|
package/scripts/stop-check.mjs
CHANGED
|
@@ -26,6 +26,7 @@ import { readFileSync, existsSync, statSync, realpathSync } from 'node:fs';
|
|
|
26
26
|
import { join, resolve } from 'node:path';
|
|
27
27
|
import { fileURLToPath } from 'node:url';
|
|
28
28
|
import { escapeInvisible } from './invisible.mjs';
|
|
29
|
+
import { handleArgs } from './cli-args.mjs';
|
|
29
30
|
|
|
30
31
|
export const STOP_PATH = join('.tyran', 'STOP');
|
|
31
32
|
|
|
@@ -66,8 +67,13 @@ export function checkStopAt(path) {
|
|
|
66
67
|
}
|
|
67
68
|
}
|
|
68
69
|
|
|
70
|
+
export const STOP_CHECK_USAGE =
|
|
71
|
+
'usage: stop-check.mjs [--dir <repo-root>]\n' +
|
|
72
|
+
'Exit: 0 clear · 1 stopped by .tyran/STOP · 2 usage';
|
|
73
|
+
|
|
69
74
|
function main() {
|
|
70
75
|
const args = process.argv.slice(2);
|
|
76
|
+
if (!handleArgs(args, { name: 'stop-check', usage: STOP_CHECK_USAGE, known: ['dir'] })) return;
|
|
71
77
|
const di = args.indexOf('--dir');
|
|
72
78
|
const dir = resolve(di === -1 ? process.cwd() : (args[di + 1] ?? process.cwd()));
|
|
73
79
|
|
package/scripts/tiers.mjs
CHANGED
|
@@ -38,6 +38,7 @@ import { validateConfig, PROFILES, TIER_KEYS } from './schema.mjs';
|
|
|
38
38
|
import { escapeInvisible } from './invisible.mjs';
|
|
39
39
|
import { APPROVING_RE } from './project.mjs';
|
|
40
40
|
import { readJournal } from './journal.mjs';
|
|
41
|
+
import { handleArgs } from './cli-args.mjs';
|
|
41
42
|
|
|
42
43
|
/** Capability tiers, cheapest first. Index order is the escalation ladder. */
|
|
43
44
|
export const TIER_ORDER = TIER_KEYS;
|
|
@@ -412,8 +413,28 @@ export function readProfile(doc) {
|
|
|
412
413
|
return raw && typeof raw === 'object' && !Array.isArray(raw) ? raw.value : raw;
|
|
413
414
|
}
|
|
414
415
|
|
|
416
|
+
/**
|
|
417
|
+
* Every flag `main` reads. It is a LIST rather than a comment because the
|
|
418
|
+
* parser below cannot derive it: `flag()` looks up the names it wants, so a
|
|
419
|
+
* name it does not want is not rejected, it is unseen. `--rol reviewer` used
|
|
420
|
+
* to print the entire routing table and exit 0 — a different answer to a
|
|
421
|
+
* different question, with nothing said about the typo — while `--role
|
|
422
|
+
* revieweer` one character later was refused by name. The value was checked
|
|
423
|
+
* and the flag was not.
|
|
424
|
+
*/
|
|
425
|
+
export const TIERS_FLAGS = Object.freeze([
|
|
426
|
+
'config', 'profile', 'risk', 'role', 'field', 'tier', 'effort', 'unavailable', 'journal', 'ticket',
|
|
427
|
+
]);
|
|
428
|
+
|
|
429
|
+
export const TIERS_USAGE =
|
|
430
|
+
'usage: tiers.mjs [--config <config.yaml>] [--profile <p>] [--risk <normal|high>]\n' +
|
|
431
|
+
' [--role <role>] [--field <model|effort|tier>] [--tier <t>] [--effort <e>]\n' +
|
|
432
|
+
' [--unavailable <model>]... [--journal <path> --ticket <T-n>]\n' +
|
|
433
|
+
'With no --role, prints the whole resolved routing table as JSON.';
|
|
434
|
+
|
|
415
435
|
function main() {
|
|
416
436
|
const args = process.argv.slice(2);
|
|
437
|
+
if (!handleArgs(args, { name: 'tiers', usage: TIERS_USAGE, known: TIERS_FLAGS })) return;
|
|
417
438
|
const flag = (name, fallback) => {
|
|
418
439
|
const i = args.indexOf(`--${name}`);
|
|
419
440
|
return i === -1 ? fallback : args[i + 1];
|
package/skills/run/SKILL.md
CHANGED
|
@@ -80,6 +80,16 @@ English regardless.
|
|
|
80
80
|
- **dry-run every automaton** for one no-op iteration before you trust it
|
|
81
81
|
with unattended work. Trust dialogs and missing dependencies surface
|
|
82
82
|
then, not at 3am.
|
|
83
|
+
- **exercise cloud access, never infer it.** A profile in `~/.aws/config`, a
|
|
84
|
+
key in the environment and a role named in a template are three claims
|
|
85
|
+
that the call you actually need will succeed — none of them is the call.
|
|
86
|
+
Make one cheap read-only request per service the plan names, starting with
|
|
87
|
+
an identity check (`aws sts get-caller-identity` and its equivalents) and
|
|
88
|
+
then a `list`/`describe` on the one resource you will touch, and record
|
|
89
|
+
the account, region and profile as a `decision`. This is the teammate
|
|
90
|
+
probe two bullets up, one layer out: availability that was inferred rather
|
|
91
|
+
than exercised has already been wrong here, and the cloud version of that
|
|
92
|
+
mistake surfaces at deploy time — after the work, in front of the operator.
|
|
83
93
|
5. **Project configuration — detect it yourself.**
|
|
84
94
|
- If `.tyran/config.yaml` exists, read it and treat it as binding.
|
|
85
95
|
- Otherwise send `tyran:scout` to establish: (a) the **stack** — languages,
|
|
@@ -295,6 +305,16 @@ open one.
|
|
|
295
305
|
your scope without the domain owner's consent — proposals go to `NOTES.md`.
|
|
296
306
|
Secrets never enter the repo. Production data only through the accounts the
|
|
297
307
|
configuration names.
|
|
308
|
+
- **The gate below is a way in, so it has its own rule.** `journal.mjs ask`
|
|
309
|
+
writes the question into the journal, and `answer.mjs apply` folds the
|
|
310
|
+
operator's reply back as a `decision` — both in a file you commit. **Never
|
|
311
|
+
ask for a credential's VALUE. Ask where it lives**: the SSM parameter
|
|
312
|
+
NAME, the secrets-manager key, the vault path — something whose disclosure
|
|
313
|
+
costs nothing and which the machine doing the work can already resolve.
|
|
314
|
+
*"Which SSM parameter holds the staging database password?"* is a question
|
|
315
|
+
whose answer is safe in a committed file. *"What is the staging database
|
|
316
|
+
password?"* is a leak with a ticket number on it, and the operator who
|
|
317
|
+
pasted it now has a credential to rotate.
|
|
298
318
|
6. **Gates are the only stops:** plan acceptance (L) or concept acceptance
|
|
299
319
|
(XL); product, visual and irreversible decisions, put in plain language
|
|
300
320
|
with your recommendation; anything hard to undo or visible outside the
|