@jjanczur/tyran 0.1.32 → 0.1.34
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 +149 -0
- package/README.md +1 -1
- package/hooks/scripts/session-start.mjs +89 -3
- package/package.json +1 -1
- package/scripts/board-daemon.mjs +412 -0
- package/scripts/board-html.mjs +123 -0
- package/scripts/board.mjs +180 -13
- package/scripts/doctor.mjs +12 -1
- package/scripts/overnight.mjs +24 -2
- package/scripts/project.mjs +35 -1
- package/scripts/scan-repo.mjs +14 -0
- package/scripts/schema.mjs +51 -1
- package/skills/run/SKILL.md +26 -0
- package/skills/setup/SKILL.md +14 -3
- package/templates/config.yaml +18 -0
package/scripts/board.mjs
CHANGED
|
@@ -21,8 +21,13 @@
|
|
|
21
21
|
*
|
|
22
22
|
* CLI:
|
|
23
23
|
* node board.mjs [--dir <.tyran>] [--check]
|
|
24
|
-
* [--serve [--port <n>] [--write] [--open] [--transcripts <dir>]...]
|
|
25
|
-
*
|
|
24
|
+
* [--serve|--detach [--port <n>] [--write] [--open] [--transcripts <dir>]...]
|
|
25
|
+
* [--status] [--stop]
|
|
26
|
+
* Exit: 0 ok · 1 drift (--check), or no server (--status/--stop) · 2 usage/IO
|
|
27
|
+
*
|
|
28
|
+
* `--serve` holds the terminal; `--detach` starts the same server, waits only
|
|
29
|
+
* until it answers, and returns. Anything that is not a human with a spare
|
|
30
|
+
* terminal wants the second one — see board-daemon.mjs.
|
|
26
31
|
*/
|
|
27
32
|
import { existsSync, readdirSync, statSync, readFileSync } from 'node:fs';
|
|
28
33
|
import { createServer } from 'node:http';
|
|
@@ -50,9 +55,22 @@ import { SettingsError, applyPolicyClass, applySetting, readSettings } from './s
|
|
|
50
55
|
import { checkStopAt } from './stop-check.mjs';
|
|
51
56
|
import { runState } from './overnight.mjs';
|
|
52
57
|
import { answerOne, answerProblem, classify, openAsks, partitionAsks, reRender, sortAsks } from './answer.mjs';
|
|
58
|
+
import {
|
|
59
|
+
HEALTH_ROUTE,
|
|
60
|
+
PORT_SEARCH_SPAN,
|
|
61
|
+
findLiveServer,
|
|
62
|
+
removeServerRecord,
|
|
63
|
+
startDetached,
|
|
64
|
+
stopServer,
|
|
65
|
+
urlFor,
|
|
66
|
+
writeServerRecord,
|
|
67
|
+
} from './board-daemon.mjs';
|
|
53
68
|
|
|
54
69
|
export const BOARD_HTML_FILE = 'board.html';
|
|
55
70
|
|
|
71
|
+
/** How often a served board checks that it still has a directory to serve. */
|
|
72
|
+
export const DIR_WATCHDOG_MS = 60_000;
|
|
73
|
+
|
|
56
74
|
/**
|
|
57
75
|
* Open the served board in the operator's browser.
|
|
58
76
|
*
|
|
@@ -234,6 +252,7 @@ export const MAX_LOGGED_ERRORS = 20;
|
|
|
234
252
|
|
|
235
253
|
export function crossBoard({ initiatives, errors, warned = [], stop = null }) {
|
|
236
254
|
const asks = [];
|
|
255
|
+
const summaries = [];
|
|
237
256
|
const agents = [];
|
|
238
257
|
const paused = [];
|
|
239
258
|
const logged = [];
|
|
@@ -246,6 +265,39 @@ export function crossBoard({ initiatives, errors, warned = [], stop = null }) {
|
|
|
246
265
|
for (const { name, state, board, files: docs } of initiatives) {
|
|
247
266
|
merged += state.merged;
|
|
248
267
|
tickets += state.ticketList.length;
|
|
268
|
+
// Per-initiative, because one blended percentage over every initiative is
|
|
269
|
+
// not a fact about any of them: an operator reading "50%" across four
|
|
270
|
+
// slugs cannot tell which is nearly done from which has not started.
|
|
271
|
+
//
|
|
272
|
+
// The TITLE is the point of the row. `init.created` has carried a written
|
|
273
|
+
// sentence all along — "Settings on the board: edit config and the
|
|
274
|
+
// autonomy policy from the page" — and the board showed the directory
|
|
275
|
+
// slug. `waiting` and `last_ts` are here rather than a computed idle time
|
|
276
|
+
// because this payload is byte-compared under `--check` and reads no
|
|
277
|
+
// clock; the page ages them, exactly as it already ages agents.
|
|
278
|
+
summaries.push({
|
|
279
|
+
name,
|
|
280
|
+
title: typeof state.created?.data?.title === 'string' ? state.created.data.title : null,
|
|
281
|
+
tickets: state.ticketList.length,
|
|
282
|
+
merged: state.merged,
|
|
283
|
+
percent: state.percent,
|
|
284
|
+
waiting: board.asks.length,
|
|
285
|
+
// A COUNT, and deliberately not the findings themselves. Measured across
|
|
286
|
+
// 63 distinct real journals: 3 carry any finding at all, 49 in total,
|
|
287
|
+
// and NOT ONE names a ticket — so they cannot enrich a card, which is
|
|
288
|
+
// where a richer board would have put them. Their median claim is 429
|
|
289
|
+
// characters, a paragraph rather than a label, and STATE.md already
|
|
290
|
+
// renders the full seven-column table.
|
|
291
|
+
//
|
|
292
|
+
// So this is a pointer, not a copy: the research exists and the reader
|
|
293
|
+
// is told where. Duplicating the prose here would be ADR-21's defect
|
|
294
|
+
// and would cost ~600 B per finding in a byte-compared payload.
|
|
295
|
+
// Guarded: `crossBoard` is exported and takes any folded state, and a
|
|
296
|
+
// caller assembling one by hand need not have every collection. A
|
|
297
|
+
// missing array must read as "none", never take the board down.
|
|
298
|
+
findings: (state.findings ?? []).length,
|
|
299
|
+
last_ts: state.lastTs,
|
|
300
|
+
});
|
|
249
301
|
if (state.lastTs !== null && (asOf === null || state.lastTs > asOf)) asOf = state.lastTs;
|
|
250
302
|
for (const a of board.asks) asks.push({ ...a, init: name });
|
|
251
303
|
for (const a of board.agents) agents.push({ ...a, init: name });
|
|
@@ -329,6 +381,10 @@ export function crossBoard({ initiatives, errors, warned = [], stop = null }) {
|
|
|
329
381
|
stop: stop === null ? null : { stopped: stop.stopped, reason: stop.reason },
|
|
330
382
|
paused,
|
|
331
383
|
asks,
|
|
384
|
+
// Ordered by directory name, like everything else here, so two renders of
|
|
385
|
+
// one journal set are byte-identical. `totals.percent` blends these; the
|
|
386
|
+
// rows are what let a reader see WHICH initiative it blends.
|
|
387
|
+
initiatives: summaries,
|
|
332
388
|
agents,
|
|
333
389
|
files,
|
|
334
390
|
lanes,
|
|
@@ -607,14 +663,17 @@ function handleSettingsWrite(dir, route, body) {
|
|
|
607
663
|
|
|
608
664
|
// ------------------------------------------------------------------- CLI
|
|
609
665
|
|
|
610
|
-
const BOOLEAN_FLAGS = ['check', 'serve', 'write', 'open'];
|
|
666
|
+
const BOOLEAN_FLAGS = ['check', 'serve', 'write', 'open', 'detach', 'stop', 'status'];
|
|
611
667
|
const VALUE_FLAGS = ['dir', 'port'];
|
|
612
668
|
// Repeatable, unlike VALUE_FLAGS: sources are the union over every directory
|
|
613
669
|
// given, exactly like cost.mjs's own `--transcripts`.
|
|
614
670
|
const REPEATABLE_FLAGS = ['transcripts'];
|
|
615
671
|
|
|
616
672
|
function parseArgs(argv) {
|
|
617
|
-
const flags = {
|
|
673
|
+
const flags = {
|
|
674
|
+
dir: '.tyran', port: 4173, check: false, serve: false, write: false, open: false,
|
|
675
|
+
detach: false, stop: false, status: false, transcripts: [],
|
|
676
|
+
};
|
|
618
677
|
for (let i = 0; i < argv.length; i += 1) {
|
|
619
678
|
const arg = argv[i];
|
|
620
679
|
if (!arg.startsWith('--')) throw new UsageError(`unexpected argument "${arg}"`);
|
|
@@ -646,25 +705,34 @@ function main() {
|
|
|
646
705
|
if (!(err instanceof UsageError)) throw err;
|
|
647
706
|
console.error(`board: ${err.message}`);
|
|
648
707
|
console.error(
|
|
649
|
-
'usage: board.mjs [--dir <.tyran>] [--check]
|
|
650
|
-
'[--serve [--port <n>] [--write] [--transcripts <dir>]...]'
|
|
708
|
+
'usage: board.mjs [--dir <.tyran>] [--check]\n' +
|
|
709
|
+
' [--serve|--detach [--port <n>] [--write] [--open] [--transcripts <dir>]...]\n' +
|
|
710
|
+
' [--status] [--stop]'
|
|
651
711
|
);
|
|
652
712
|
process.exit(2);
|
|
653
713
|
}
|
|
654
|
-
|
|
655
|
-
|
|
714
|
+
// `--detach` is `--serve` that returns. Every flag describing HOW to serve
|
|
715
|
+
// therefore has to accept either, or the detached form would refuse exactly
|
|
716
|
+
// the arguments it exists to be given.
|
|
717
|
+
const serving = flags.serve || flags.detach;
|
|
718
|
+
if (flags.serve && flags.detach) {
|
|
719
|
+
console.error('board: --serve and --detach are the same server, one holding the terminal and one not — pass one');
|
|
720
|
+
process.exit(2);
|
|
721
|
+
}
|
|
722
|
+
if (flags.write && !serving) {
|
|
723
|
+
console.error('board: --write only means anything with --serve or --detach (it is what the served page may edit)');
|
|
656
724
|
process.exit(2);
|
|
657
725
|
}
|
|
658
|
-
if (flags.open && !
|
|
726
|
+
if (flags.open && !serving) {
|
|
659
727
|
// Same refusal as --write and --transcripts, for the same reason: there is
|
|
660
728
|
// no URL to open without a server, and a flag that silently does nothing
|
|
661
729
|
// reads as configuration.
|
|
662
|
-
console.error('board: --open only means anything with --serve (there is no URL to open without it)');
|
|
730
|
+
console.error('board: --open only means anything with --serve or --detach (there is no URL to open without it)');
|
|
663
731
|
process.exit(2);
|
|
664
732
|
}
|
|
665
|
-
if (flags.transcripts.length > 0 && !
|
|
733
|
+
if (flags.transcripts.length > 0 && !serving) {
|
|
666
734
|
console.error(
|
|
667
|
-
'board: --transcripts only means anything with --serve (it is what /cost.json reads instead of ' +
|
|
735
|
+
'board: --transcripts only means anything with --serve or --detach (it is what /cost.json reads instead of ' +
|
|
668
736
|
'the derived transcript directory)'
|
|
669
737
|
);
|
|
670
738
|
process.exit(2);
|
|
@@ -691,6 +759,63 @@ function main() {
|
|
|
691
759
|
}
|
|
692
760
|
const outDir = join(dir, 'state');
|
|
693
761
|
|
|
762
|
+
// ---- the three routes that talk ABOUT a server rather than being one ----
|
|
763
|
+
//
|
|
764
|
+
// All three are async, and `main` stays sync for everything else on
|
|
765
|
+
// purpose: the rendering path is the one every test and every hook drives,
|
|
766
|
+
// and making it return a promise would change the shape of a contract that
|
|
767
|
+
// has nothing to do with servers.
|
|
768
|
+
if (flags.status) {
|
|
769
|
+
findLiveServer(dir, flags.port).then((live) => {
|
|
770
|
+
if (live === null) {
|
|
771
|
+
console.log(
|
|
772
|
+
`board: no server is answering for ${dir} ` +
|
|
773
|
+
`(tried the recorded port, if any, then ${flags.port}-${flags.port + PORT_SEARCH_SPAN - 1}) — ` +
|
|
774
|
+
`start one with: node scripts/board.mjs --dir ${dir} --detach --write`,
|
|
775
|
+
);
|
|
776
|
+
process.exitCode = 1;
|
|
777
|
+
return;
|
|
778
|
+
}
|
|
779
|
+
console.log(
|
|
780
|
+
`board: serving ${urlFor(live.port)} (pid ${live.health.pid ?? '?'}; ` +
|
|
781
|
+
`${live.health.write ? 'Settings can edit config.yaml and autonomy.yaml' : 'read-only'})`,
|
|
782
|
+
);
|
|
783
|
+
});
|
|
784
|
+
return;
|
|
785
|
+
}
|
|
786
|
+
if (flags.stop) {
|
|
787
|
+
stopServer(dir).then((result) => {
|
|
788
|
+
if (result.stopped) {
|
|
789
|
+
console.log(`board: stopped the server on port ${result.port} (pid ${result.pid})`);
|
|
790
|
+
return;
|
|
791
|
+
}
|
|
792
|
+
console.error(`board: ${result.reason}`);
|
|
793
|
+
process.exitCode = 1;
|
|
794
|
+
});
|
|
795
|
+
return;
|
|
796
|
+
}
|
|
797
|
+
if (flags.detach) {
|
|
798
|
+
startDetached(dir, { port: flags.port, write: flags.write, open: flags.open, transcripts: flags.transcripts })
|
|
799
|
+
.then((result) => {
|
|
800
|
+
if (result.error) {
|
|
801
|
+
console.error(`board: ${result.error}`);
|
|
802
|
+
process.exitCode = 2;
|
|
803
|
+
return;
|
|
804
|
+
}
|
|
805
|
+
// "Already running" is a SUCCESS, and saying which one it is matters:
|
|
806
|
+
// this command is meant to be safe to run on every session start, so
|
|
807
|
+
// its ordinary outcome is that there was nothing to do.
|
|
808
|
+
console.log(
|
|
809
|
+
result.reused
|
|
810
|
+
? `board: already serving ${result.url} (pid ${result.pid ?? '?'})`
|
|
811
|
+
: `board: serving ${result.url} (pid ${result.pid ?? '?'}; ` +
|
|
812
|
+
`${flags.write ? 'Settings can edit config.yaml and autonomy.yaml' : 'read-only'}; ` +
|
|
813
|
+
`stop it with: node scripts/board.mjs --dir ${dir} --stop)`,
|
|
814
|
+
);
|
|
815
|
+
});
|
|
816
|
+
return;
|
|
817
|
+
}
|
|
818
|
+
|
|
694
819
|
if (flags.serve) {
|
|
695
820
|
// Loopback-only, re-rendered per request so it is always fresh. No
|
|
696
821
|
// filesystem path is ever derived from the URL.
|
|
@@ -726,6 +851,15 @@ function main() {
|
|
|
726
851
|
// marker, the resume watcher and the usage sidecar are gitignored and
|
|
727
852
|
// different on every machine, so they are served — the same split, and
|
|
728
853
|
// the same argument, spend already makes.
|
|
854
|
+
// The liveness answer, and the ONLY reliable one. A caller asking
|
|
855
|
+
// "is a board already up for this repo" cannot use the recorded pid —
|
|
856
|
+
// see board-daemon.mjs for why — so it asks the server itself, and
|
|
857
|
+
// `dir` is what stops ANOTHER repository's board (same program, same
|
|
858
|
+
// route) from answering yes on this one's behalf.
|
|
859
|
+
if (req.url === HEALTH_ROUTE) {
|
|
860
|
+
sendJson(res, 200, { tyran_board: true, schema: 1, dir, pid: process.pid, port: flags.port, write: flags.write });
|
|
861
|
+
return;
|
|
862
|
+
}
|
|
729
863
|
if (req.url === '/run.json') {
|
|
730
864
|
try {
|
|
731
865
|
sendJson(res, 200, { schema: 1, ...runState(resolve(dir, '..')) });
|
|
@@ -846,13 +980,46 @@ function main() {
|
|
|
846
980
|
process.exitCode = 2;
|
|
847
981
|
});
|
|
848
982
|
server.listen(flags.port, '127.0.0.1', () => {
|
|
849
|
-
const url =
|
|
983
|
+
const url = urlFor(flags.port);
|
|
984
|
+
// Written from INSIDE the listen callback, so the record only ever
|
|
985
|
+
// describes a server that actually bound a port — a record written
|
|
986
|
+
// before this point would be an intention, and `--stop` would signal
|
|
987
|
+
// whatever inherited the pid of a board that never started.
|
|
988
|
+
writeServerRecord(dir, { pid: process.pid, port: flags.port, url, write: flags.write, started_at: new Date().toISOString() });
|
|
850
989
|
console.log(
|
|
851
990
|
`board: serving ${url} ` +
|
|
852
991
|
`(${flags.write ? 'Settings can edit config.yaml and autonomy.yaml' : 'read-only'}; Ctrl-C to stop)`,
|
|
853
992
|
);
|
|
854
993
|
if (flags.open) openInBrowser(url);
|
|
855
994
|
});
|
|
995
|
+
// Clear the record on the way out, so the next caller does not have to
|
|
996
|
+
// probe a port to learn that this one is gone. Best-effort: a killed
|
|
997
|
+
// process runs none of this, which is exactly why the reader treats the
|
|
998
|
+
// record as a hint and the health probe as the answer.
|
|
999
|
+
const clear = () => { removeServerRecord(dir); };
|
|
1000
|
+
process.on('exit', clear);
|
|
1001
|
+
for (const signal of ['SIGINT', 'SIGTERM', 'SIGHUP']) {
|
|
1002
|
+
process.on(signal, () => {
|
|
1003
|
+
clear();
|
|
1004
|
+
process.exit(0);
|
|
1005
|
+
});
|
|
1006
|
+
}
|
|
1007
|
+
// A board whose directory is gone is serving nothing, and nothing will
|
|
1008
|
+
// ever ask it to stop: `--stop` needs a `.tyran` to find the record in,
|
|
1009
|
+
// and the operator who deleted the checkout is not going to hunt a pid.
|
|
1010
|
+
// Detached servers are started automatically now, so "nobody ever stops
|
|
1011
|
+
// it" is the DEFAULT case rather than an unlucky one — a deleted worktree
|
|
1012
|
+
// otherwise leaves a process holding a port until the machine reboots.
|
|
1013
|
+
const watchdog = setInterval(() => {
|
|
1014
|
+
if (!existsSync(dir)) {
|
|
1015
|
+
clear();
|
|
1016
|
+
process.exit(0);
|
|
1017
|
+
}
|
|
1018
|
+
}, DIR_WATCHDOG_MS);
|
|
1019
|
+
// Unref'd so it is the SERVER that keeps this process alive, never the
|
|
1020
|
+
// timer: a watchdog that held the loop open would turn every exit path
|
|
1021
|
+
// above into a hang.
|
|
1022
|
+
watchdog.unref?.();
|
|
856
1023
|
return;
|
|
857
1024
|
}
|
|
858
1025
|
|
package/scripts/doctor.mjs
CHANGED
|
@@ -65,6 +65,7 @@ import { classifyPath, normalizePath, validateFile, knowledgeWarnings, MANDATORY
|
|
|
65
65
|
import { auditEntries, loadEntries as loadKnowledgeEntries } from './knowledge.mjs';
|
|
66
66
|
import { readPlatformUsage } from './usage-source.mjs';
|
|
67
67
|
import { gitRunner } from './scan-repo.mjs';
|
|
68
|
+
import { SERVER_RECORD_FILE } from './board-daemon.mjs';
|
|
68
69
|
import { parseMistakes, countSignatures, fenceState, KNOWLEDGE_THRESHOLD, MISTAKES_FILE, CLAUDE_MD_FILE } from './mistakes.mjs';
|
|
69
70
|
|
|
70
71
|
/** Severity order is also the report order. `info` never fails the check. */
|
|
@@ -1613,7 +1614,17 @@ export function mistakesFindings(repoRoot, run = null) {
|
|
|
1613
1614
|
|
|
1614
1615
|
/** The repo-global overnight runtime files that legally live at state/ level. */
|
|
1615
1616
|
/** The cross-initiative board artefacts board.mjs writes at state/ level. */
|
|
1616
|
-
export const CROSS_BOARD_FILES = Object.freeze([
|
|
1617
|
+
export const CROSS_BOARD_FILES = Object.freeze([
|
|
1618
|
+
'BOARD.md',
|
|
1619
|
+
'board.json',
|
|
1620
|
+
'board.html',
|
|
1621
|
+
// Not a projection like the three above — the running server's own record,
|
|
1622
|
+
// written from inside its listen callback and removed on the way out. It
|
|
1623
|
+
// sits at this level because the server serves the whole directory, and it
|
|
1624
|
+
// is machine-local for the same reason the overnight files are: another
|
|
1625
|
+
// clone has a different pid on a different port.
|
|
1626
|
+
SERVER_RECORD_FILE,
|
|
1627
|
+
]);
|
|
1617
1628
|
|
|
1618
1629
|
export const OVERNIGHT_RUNTIME_FILES = Object.freeze([
|
|
1619
1630
|
'paused-until.json',
|
package/scripts/overnight.mjs
CHANGED
|
@@ -228,15 +228,37 @@ export function runState(repo, nowMs = Date.now()) {
|
|
|
228
228
|
five_hour: pickWindow(sidecar.five_hour),
|
|
229
229
|
seven_day: pickWindow(sidecar.seven_day),
|
|
230
230
|
},
|
|
231
|
+
// Which mode the gate is IN, not only what it can see. Without this a page
|
|
232
|
+
// cannot tell "the gate cannot see" from "the feature was never switched
|
|
233
|
+
// on", and off is the default (templates/config.yaml) — so a telemetry
|
|
234
|
+
// warning built on the `usage` field alone would fire on every repository
|
|
235
|
+
// that has never enabled overnight mode.
|
|
236
|
+
limits_mode: readLimitsFile(repo)?.mode ?? 'off',
|
|
231
237
|
};
|
|
232
238
|
}
|
|
233
239
|
|
|
234
|
-
/**
|
|
240
|
+
/**
|
|
241
|
+
* Numbers and an ISO string only — never a free payload string from a hook.
|
|
242
|
+
*
|
|
243
|
+
* `resets_at` arrives as epoch SECONDS: `statusline.mjs`'s `windowOf` keeps
|
|
244
|
+
* only `finiteNumber` values, and `usage-source.mjs` normalises the platform's
|
|
245
|
+
* ISO string to the same. This function tested `typeof === 'string'` and so
|
|
246
|
+
* returned null for every real payload it has ever been given — `/run.json`
|
|
247
|
+
* has never once carried a reset time, and the board's run panel could say a
|
|
248
|
+
* pause was in force but never when it would end.
|
|
249
|
+
*
|
|
250
|
+
* The string half of the guard was not wrong about the OUTPUT: this is the
|
|
251
|
+
* page's shape, and an ISO string is what a reader wants. It was wrong about
|
|
252
|
+
* the input. So convert, rather than widening the test and emitting seconds
|
|
253
|
+
* the page would have to know to multiply.
|
|
254
|
+
*/
|
|
235
255
|
function pickWindow(w) {
|
|
236
256
|
if (w === null || typeof w !== 'object') return null;
|
|
257
|
+
const seconds = typeof w.resets_at === 'number' && Number.isFinite(w.resets_at) ? w.resets_at : null;
|
|
258
|
+
const iso = seconds === null ? null : new Date(seconds * 1000);
|
|
237
259
|
return {
|
|
238
260
|
used_percentage: typeof w.used_percentage === 'number' ? w.used_percentage : null,
|
|
239
|
-
resets_at:
|
|
261
|
+
resets_at: iso !== null && Number.isFinite(iso.getTime()) ? iso.toISOString() : null,
|
|
240
262
|
};
|
|
241
263
|
}
|
|
242
264
|
|
package/scripts/project.mjs
CHANGED
|
@@ -400,6 +400,17 @@ export function fold({ events = [], truncatedTail = false, badLines = [] } = {})
|
|
|
400
400
|
title: null,
|
|
401
401
|
deps: null,
|
|
402
402
|
agents: [],
|
|
403
|
+
// The same spawns as `agents`, by REFERENCE rather than by name, so a
|
|
404
|
+
// ticket can answer "what actually ran here" — which model, from when
|
|
405
|
+
// to when, ending in what verdict. `agents` stays a list of names
|
|
406
|
+
// because BOARD.md and the lane cards both read it as one.
|
|
407
|
+
//
|
|
408
|
+
// References, not copies, on purpose: the `report` fold mutates a
|
|
409
|
+
// spawn's status, verdict and reportTs after this push, and a copy
|
|
410
|
+
// taken at spawn time would freeze every run as `running` with no
|
|
411
|
+
// verdict — which is exactly the row an operator opens a finished
|
|
412
|
+
// ticket to read.
|
|
413
|
+
runs: [],
|
|
403
414
|
report: null,
|
|
404
415
|
review: null,
|
|
405
416
|
merge: null,
|
|
@@ -482,7 +493,11 @@ export function fold({ events = [], truncatedTail = false, badLines = [] } = {})
|
|
|
482
493
|
}
|
|
483
494
|
}
|
|
484
495
|
state.agents.push(agent);
|
|
485
|
-
if (data.ticket != null)
|
|
496
|
+
if (data.ticket != null) {
|
|
497
|
+
const onTicket = ticketOf(data.ticket, ts);
|
|
498
|
+
onTicket.agents.push(agent.agent);
|
|
499
|
+
onTicket.runs.push(agent);
|
|
500
|
+
}
|
|
486
501
|
break;
|
|
487
502
|
}
|
|
488
503
|
case 'report': {
|
|
@@ -909,6 +924,25 @@ export function boardOf(state, { staleHours = DEFAULT_STALE_HOURS } = {}) {
|
|
|
909
924
|
// discarded at fold time, so the board could say a ticket had come back
|
|
910
925
|
// and never why — the one thing the reader opens the card for.
|
|
911
926
|
report_text: t.report?.text ?? null,
|
|
927
|
+
// The two lifecycle facts the LANE could only imply. `done` said a
|
|
928
|
+
// ticket was merged and never which commit; `changes-requested` said a
|
|
929
|
+
// review had come back and never who wrote it. Both are in the journal
|
|
930
|
+
// — `review` carries ticket/verdict/by and `merge` carries ticket/sha —
|
|
931
|
+
// and neither reached the one surface people open to ask.
|
|
932
|
+
review: t.review === null ? null : { verdict: t.review.verdict, by: t.review.by, ts: t.review.ts },
|
|
933
|
+
merge: t.merge === null ? null : { sha: t.merge.sha, mode: t.merge.mode, ts: t.merge.ts },
|
|
934
|
+
// What actually ran, in spawn order: which agent, on which model, from
|
|
935
|
+
// when to when, ending in what verdict. `worked_by` answers "who
|
|
936
|
+
// touched this"; this answers "what did it cost me and how did it go",
|
|
937
|
+
// which is the question a finished ticket is opened for.
|
|
938
|
+
execution: t.runs.map((a) => ({
|
|
939
|
+
agent: a.agent,
|
|
940
|
+
role: a.role,
|
|
941
|
+
model: a.model,
|
|
942
|
+
started: a.spawnTs,
|
|
943
|
+
ended: a.reportTs,
|
|
944
|
+
verdict: a.verdict,
|
|
945
|
+
})),
|
|
912
946
|
annotation: annotations.length > 0 ? annotations.join(' · ') : null,
|
|
913
947
|
});
|
|
914
948
|
}
|
package/scripts/scan-repo.mjs
CHANGED
|
@@ -375,6 +375,17 @@ export function scanRepo(dir, { run = gitRunner(dir) } = {}) {
|
|
|
375
375
|
resume_margin_minutes: 5,
|
|
376
376
|
keep_awake: false,
|
|
377
377
|
},
|
|
378
|
+
// The dashboard, ON. Written in full for the same reason `limits:` is —
|
|
379
|
+
// the Settings tab patches keys that exist and will not invent them — but
|
|
380
|
+
// with the opposite default, because the argument for OFF does not apply.
|
|
381
|
+
// `limits:` off is inert; a board that does not start means every
|
|
382
|
+
// projection Tyran writes is generated and never read by anyone.
|
|
383
|
+
board: {
|
|
384
|
+
autostart: true,
|
|
385
|
+
port: 4173,
|
|
386
|
+
write: true,
|
|
387
|
+
open: false,
|
|
388
|
+
},
|
|
378
389
|
};
|
|
379
390
|
|
|
380
391
|
const questions = [];
|
|
@@ -745,6 +756,9 @@ export const STATE_GITIGNORE_LINES = Object.freeze([
|
|
|
745
756
|
// that was stale the moment it was written.
|
|
746
757
|
'state/conductor.json',
|
|
747
758
|
'state/ANSWERS.md',
|
|
759
|
+
// The running board's own record: a pid and a port, which name a process on
|
|
760
|
+
// THIS machine and a stranger anywhere else.
|
|
761
|
+
'state/board-server.json',
|
|
748
762
|
]);
|
|
749
763
|
const STATE_GITIGNORE_BODY =
|
|
750
764
|
'# Runtime files, never history. Leases record who holds a worktree or a\n' +
|
package/scripts/schema.mjs
CHANGED
|
@@ -68,7 +68,7 @@ export function validateConfig(doc) {
|
|
|
68
68
|
const errors = [];
|
|
69
69
|
if (!isPlainObject(doc)) return ['config must be a mapping'];
|
|
70
70
|
|
|
71
|
-
const known = ['profile', 'autonomy', 'tiers', 'validation', 'shared_zones', 'budget', 'main_writable_paths', 'limits', 'pricing', 'spend'];
|
|
71
|
+
const known = ['profile', 'autonomy', 'tiers', 'validation', 'shared_zones', 'budget', 'main_writable_paths', 'limits', 'pricing', 'spend', 'board'];
|
|
72
72
|
for (const key of Object.keys(doc)) {
|
|
73
73
|
if (!known.includes(key)) errors.push(`${key}: unknown top-level key`);
|
|
74
74
|
}
|
|
@@ -259,9 +259,59 @@ export function validateConfig(doc) {
|
|
|
259
259
|
}
|
|
260
260
|
}
|
|
261
261
|
|
|
262
|
+
// The dashboard's own switches. Absent means the DEFAULTS below apply, and
|
|
263
|
+
// those defaults are ON — the board is where everything Tyran does becomes
|
|
264
|
+
// legible, and an install that leaves it off is an install where none of it
|
|
265
|
+
// is. This block exists to turn it DOWN, which is why every key is optional.
|
|
266
|
+
if ('board' in doc) {
|
|
267
|
+
if (!isPlainObject(doc.board)) errors.push('board: must be a mapping');
|
|
268
|
+
else {
|
|
269
|
+
const board = doc.board;
|
|
270
|
+
for (const key of ['autostart', 'write', 'open']) {
|
|
271
|
+
if (key in board && typeof board[key] !== 'boolean') {
|
|
272
|
+
errors.push(`board.${key}: must be true or false (quote 'off'/'on' if you meant a string — bare ones are YAML booleans)`);
|
|
273
|
+
}
|
|
274
|
+
}
|
|
275
|
+
if ('port' in board) {
|
|
276
|
+
const port = board.port;
|
|
277
|
+
if (!Number.isInteger(port) || port <= 0 || port > 65535) {
|
|
278
|
+
errors.push('board.port: must be an integer in (0, 65535]');
|
|
279
|
+
}
|
|
280
|
+
}
|
|
281
|
+
const knownBoard = ['autostart', 'port', 'write', 'open'];
|
|
282
|
+
for (const key of Object.keys(board)) {
|
|
283
|
+
if (!knownBoard.includes(key)) errors.push(`board.${key}: unknown key`);
|
|
284
|
+
}
|
|
285
|
+
}
|
|
286
|
+
}
|
|
287
|
+
|
|
262
288
|
return errors;
|
|
263
289
|
}
|
|
264
290
|
|
|
291
|
+
/**
|
|
292
|
+
* The board's settings, with the defaults applied.
|
|
293
|
+
*
|
|
294
|
+
* ONE function, because three callers need this answer — the session-start
|
|
295
|
+
* hook that autostarts, the setup skill's command, and doctor — and three
|
|
296
|
+
* copies of "default the port to 4173" is ADR-21 with a port number in it.
|
|
297
|
+
*
|
|
298
|
+
* `autostart` and `write` default TRUE. The board was previously reached only
|
|
299
|
+
* by a human typing a blocking command, which meant that on any install where
|
|
300
|
+
* nobody typed it, every projection Tyran writes existed and nothing read
|
|
301
|
+
* them. Defaulting off would preserve exactly that.
|
|
302
|
+
*/
|
|
303
|
+
export const BOARD_DEFAULTS = Object.freeze({ autostart: true, port: 4173, write: true, open: false });
|
|
304
|
+
|
|
305
|
+
export function boardSettings(doc) {
|
|
306
|
+
const board = isPlainObject(doc) && isPlainObject(doc.board) ? doc.board : {};
|
|
307
|
+
return {
|
|
308
|
+
autostart: typeof board.autostart === 'boolean' ? board.autostart : BOARD_DEFAULTS.autostart,
|
|
309
|
+
port: Number.isInteger(board.port) && board.port > 0 && board.port <= 65535 ? board.port : BOARD_DEFAULTS.port,
|
|
310
|
+
write: typeof board.write === 'boolean' ? board.write : BOARD_DEFAULTS.write,
|
|
311
|
+
open: typeof board.open === 'boolean' ? board.open : BOARD_DEFAULTS.open,
|
|
312
|
+
};
|
|
313
|
+
}
|
|
314
|
+
|
|
265
315
|
export const LIMITS_MODES = Object.freeze(['off', 'warn', 'pause']);
|
|
266
316
|
export const LIMITS_LONG_WAIT = Object.freeze(['hold', 'resume']);
|
|
267
317
|
|
package/skills/run/SKILL.md
CHANGED
|
@@ -452,6 +452,32 @@ open one.
|
|
|
452
452
|
a lease still held by an agent that has already reported. An orphaned lease
|
|
453
453
|
blocks the next initiative from a resource nobody is using, and the person
|
|
454
454
|
who hits it has no way to know it is stale.
|
|
455
|
+
- **Close the initiative when it is closed**, with the retrospective recorded
|
|
456
|
+
and the leases released:
|
|
457
|
+
|
|
458
|
+
```bash
|
|
459
|
+
node "${CLAUDE_PLUGIN_ROOT}/scripts/journal.mjs" append <abs-journal> checkpoint <init> \
|
|
460
|
+
--actor conductor --data '{"phase":"closed","next_steps":[]}'
|
|
461
|
+
```
|
|
462
|
+
|
|
463
|
+
`append ... checkpoint`, not a `checkpoint` subcommand — there is no such
|
|
464
|
+
subcommand, and the first draft of this line invented one. It would have
|
|
465
|
+
printed a usage block and closed nothing.
|
|
466
|
+
|
|
467
|
+
This is one line and it is load-bearing. The projection closes every still-
|
|
468
|
+
open spawn on a closing checkpoint, which is what stops an agent that
|
|
469
|
+
finished weeks ago from reading as live work, and it is the only signal any
|
|
470
|
+
reader has that an initiative is DONE rather than abandoned mid-flight.
|
|
471
|
+
|
|
472
|
+
Measured across 63 real journals: **9 ever received one**, while 43 sat
|
|
473
|
+
waiting on a question nobody answered. Nothing had ever told you to write
|
|
474
|
+
it — the fold that consumes it shipped, and the event that triggers it was
|
|
475
|
+
never emitted by anything, so the feature has been inert since it landed.
|
|
476
|
+
|
|
477
|
+
A closing checkpoint is not the same as "every ticket merged". Say it when
|
|
478
|
+
the work is over, including when it is over because it was abandoned — an
|
|
479
|
+
initiative someone walked away from is finished too, and saying so is what
|
|
480
|
+
keeps the board honest about which of them are still waiting on you.
|
|
455
481
|
- **A usage-gate refusal is a wind-down order, not an obstacle.** Near the
|
|
456
482
|
subscription window the gate refuses everything except checkpointing;
|
|
457
483
|
its refusal text IS the checklist — follow it verbatim, in order, then
|
package/skills/setup/SKILL.md
CHANGED
|
@@ -168,9 +168,16 @@ files on disk; the board is where any of it becomes legible, and it was the
|
|
|
168
168
|
one thing installation never actually reached.
|
|
169
169
|
|
|
170
170
|
```bash
|
|
171
|
-
node "${CLAUDE_PLUGIN_ROOT}/scripts/board.mjs" --dir .tyran --
|
|
171
|
+
node "${CLAUDE_PLUGIN_ROOT}/scripts/board.mjs" --dir .tyran --detach --write --open
|
|
172
172
|
```
|
|
173
173
|
|
|
174
|
+
**`--detach`, never `--serve`.** They are the same server; `--serve` holds the
|
|
175
|
+
terminal until Ctrl-C, which is right for a human who typed it and fatal here
|
|
176
|
+
— an agent that runs it sits on the call until the platform's timeout, and
|
|
177
|
+
every step below this one silently never happens. That is what this step used
|
|
178
|
+
to do. `--detach` waits only until the board answers, prints the URL, and
|
|
179
|
+
returns; `--stop` ends it.
|
|
180
|
+
|
|
174
181
|
`--open` launches their browser; `--write` is what makes the **Settings** tab
|
|
175
182
|
able to edit `config.yaml` and the autonomy policy from the page. Tell them
|
|
176
183
|
that tab exists and what it covers — profile, autonomy class, tiers,
|
|
@@ -178,8 +185,12 @@ validation commands, shared zones, overnight limits — because for someone who
|
|
|
178
185
|
would rather not hand-edit YAML in their own repository, that tab is the
|
|
179
186
|
entire configuration story and they will not guess it is there.
|
|
180
187
|
|
|
181
|
-
|
|
182
|
-
|
|
188
|
+
Say that they do not have to run this again: the scan wrote a `board:` block
|
|
189
|
+
with `autostart: true`, so every later session starts the board if it is not
|
|
190
|
+
already up, and prints the URL in its opening summary. Several repositories at
|
|
191
|
+
once each get their own — the port walks forward from 4173 when one is taken.
|
|
192
|
+
`node scripts/board.mjs --dir .tyran --status` says where it is; `--stop` ends
|
|
193
|
+
it; `autostart: false` in the config turns the whole thing off.
|
|
183
194
|
|
|
184
195
|
## 5. Validate and report
|
|
185
196
|
|
package/templates/config.yaml
CHANGED
|
@@ -68,6 +68,24 @@ limits:
|
|
|
68
68
|
resume_margin_minutes: 5
|
|
69
69
|
keep_awake: false # a real boolean, so the bare-off trap above cannot apply
|
|
70
70
|
|
|
71
|
+
# The dashboard. Unlike everything above, this defaults ON: the board is where
|
|
72
|
+
# a journal, a projection and a spend report become something a person can
|
|
73
|
+
# read, and an install where nobody starts it is an install where none of that
|
|
74
|
+
# is ever seen. Set autostart: false to turn it down.
|
|
75
|
+
#
|
|
76
|
+
# autostart: true start it with the session, if it is not already up
|
|
77
|
+
# port: 4173 the first port tried; the next 9 are used if it is taken,
|
|
78
|
+
# so several repositories can each have their own board
|
|
79
|
+
# write: true lets the Settings tab edit config.yaml and the autonomy
|
|
80
|
+
# policy. false serves the same page read-only.
|
|
81
|
+
# open: false true also launches your browser on every session, which
|
|
82
|
+
# is a tab per session — the URL is printed either way.
|
|
83
|
+
board:
|
|
84
|
+
autostart: true
|
|
85
|
+
port: 4173
|
|
86
|
+
write: true
|
|
87
|
+
open: false
|
|
88
|
+
|
|
71
89
|
# What a model costs, per MILLION tokens. Optional; absent means the spend
|
|
72
90
|
# report counts tokens and shows no money, which is the honest default —
|
|
73
91
|
# Tyran does not know what you pay. Operator-written from a vendor's price
|