@jjanczur/tyran 0.1.42 → 0.1.44
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 +185 -0
- package/README.md +9 -2
- package/hooks/HOOK-CONTRACT-MEASURED.md +6 -1
- package/hooks/scripts/hook-io.mjs +66 -8
- package/hooks/scripts/policy-gate.mjs +141 -9
- package/package.json +1 -1
- package/scripts/board-html.mjs +504 -78
- package/scripts/doctor.mjs +48 -1
- package/scripts/scan-repo.mjs +17 -1
- package/scripts/schema.mjs +88 -1
- package/scripts/settings.mjs +215 -3
- package/skills/setup/SKILL.md +20 -0
- package/templates/config.yaml +28 -0
- package/templates/policies/autonomy.yaml +29 -9
package/scripts/doctor.mjs
CHANGED
|
@@ -61,7 +61,15 @@ import {
|
|
|
61
61
|
PROGRESS_FILE,
|
|
62
62
|
STATE_FILE,
|
|
63
63
|
} from './project.mjs';
|
|
64
|
-
import {
|
|
64
|
+
import {
|
|
65
|
+
boundariesOf,
|
|
66
|
+
classifyPath,
|
|
67
|
+
normalizePath,
|
|
68
|
+
relaxedBoundaries,
|
|
69
|
+
validateFile,
|
|
70
|
+
knowledgeWarnings,
|
|
71
|
+
MANDATORY_KERNEL_PATHS,
|
|
72
|
+
} from './schema.mjs';
|
|
65
73
|
import { auditEntries, loadEntries as loadKnowledgeEntries } from './knowledge.mjs';
|
|
66
74
|
import { readPlatformUsage } from './usage-source.mjs';
|
|
67
75
|
import { gitRunner } from './scan-repo.mjs';
|
|
@@ -204,6 +212,11 @@ export const SEVERITY_BY_CODE = Object.freeze(
|
|
|
204
212
|
'config-missing': 'info',
|
|
205
213
|
'config-invalid': 'error',
|
|
206
214
|
'config-unreadable': 'error',
|
|
215
|
+
// Not an error: an operator chose this. `warning` because it is the one
|
|
216
|
+
// setting whose whole effect is that refusals stop being printed, so
|
|
217
|
+
// nothing else will ever tell you it is on.
|
|
218
|
+
'boundaries-relaxed': 'warning',
|
|
219
|
+
'boundaries-absent': 'info',
|
|
207
220
|
'knowledge-invalid': 'error',
|
|
208
221
|
'knowledge-duplicate-id': 'error',
|
|
209
222
|
'knowledge-unreadable': 'error',
|
|
@@ -1915,6 +1928,40 @@ export function runStateChecks({
|
|
|
1915
1928
|
checked.push('config.yaml: absent');
|
|
1916
1929
|
}
|
|
1917
1930
|
|
|
1931
|
+
// How open this repo is, STATED rather than left to be discovered. A relaxed
|
|
1932
|
+
// boundary is not a defect — somebody chose it — but it is the one setting
|
|
1933
|
+
// whose effect is that refusals stop appearing, so nothing else in a session
|
|
1934
|
+
// will ever mention it. An operator who inherits a repo, or comes back to one
|
|
1935
|
+
// after a month, finds out here or not at all.
|
|
1936
|
+
if (configDoc !== null) {
|
|
1937
|
+
const relaxed = relaxedBoundaries(boundariesOf(configDoc));
|
|
1938
|
+
if (relaxed.length > 0) {
|
|
1939
|
+
findings.push(
|
|
1940
|
+
finding(
|
|
1941
|
+
'boundaries-relaxed',
|
|
1942
|
+
show(configPath),
|
|
1943
|
+
`boundaries: ${relaxed.join(', ')} ${relaxed.length === 1 ? 'is' : 'are'} turned down, so the policy gate ` +
|
|
1944
|
+
'no longer refuses what they cover. Secret scanning at commit and push, the enforcement hooks, ' +
|
|
1945
|
+
'.claude/settings.json and .tyran/STOP are unaffected — no setting reaches those',
|
|
1946
|
+
`node scripts/schema.mjs validate config ${sq(configPath)} # then edit boundaries: to tighten`,
|
|
1947
|
+
),
|
|
1948
|
+
);
|
|
1949
|
+
}
|
|
1950
|
+
checked.push(`boundaries: ${relaxed.length === 0 ? 'all strict' : `relaxed (${relaxed.join(', ')})`}`);
|
|
1951
|
+
if (!('boundaries' in configDoc)) {
|
|
1952
|
+
findings.push(
|
|
1953
|
+
finding(
|
|
1954
|
+
'boundaries-absent',
|
|
1955
|
+
show(configPath),
|
|
1956
|
+
'no boundaries: block — the strict default applies, which is correct, but the Settings tab patches ' +
|
|
1957
|
+
'keys that already exist and will not invent them, so that whole section of the dashboard is ' +
|
|
1958
|
+
'unusable in this repo',
|
|
1959
|
+
`node scripts/scan-repo.mjs --write ${sq(configPath)} # rewrites the config with the block in it`,
|
|
1960
|
+
),
|
|
1961
|
+
);
|
|
1962
|
+
}
|
|
1963
|
+
}
|
|
1964
|
+
|
|
1918
1965
|
const gitRun = run ?? gitRunner(repoRoot);
|
|
1919
1966
|
const untracked = untrackedTyranDir(repoRoot, gitRun, basename(root));
|
|
1920
1967
|
if (untracked === true) {
|
package/scripts/scan-repo.mjs
CHANGED
|
@@ -33,7 +33,7 @@ import { execFileSync } from 'node:child_process';
|
|
|
33
33
|
import { join, resolve, dirname, extname, relative } from 'node:path';
|
|
34
34
|
import { fileURLToPath } from 'node:url';
|
|
35
35
|
import { parse, stringify } from './yaml-lite.mjs';
|
|
36
|
-
import { validatePolicy } from './schema.mjs';
|
|
36
|
+
import { BOUNDARIES_STRICT, validatePolicy } from './schema.mjs';
|
|
37
37
|
import { escapeInvisible } from './invisible.mjs';
|
|
38
38
|
import { handleArgs } from './cli-args.mjs';
|
|
39
39
|
|
|
@@ -356,6 +356,15 @@ export function scanRepo(dir, { run = gitRunner(dir) } = {}) {
|
|
|
356
356
|
tiers: { cheap: 'haiku', work: 'sonnet', deep: 'opus', top: 'fable' },
|
|
357
357
|
validation,
|
|
358
358
|
shared_zones: [],
|
|
359
|
+
// Every boundary ON, written out in full for the same reason `limits:` is
|
|
360
|
+
// below: the Settings tab patches keys that exist and refuses to invent
|
|
361
|
+
// them, so an absent block is a section of the dashboard nobody can use.
|
|
362
|
+
//
|
|
363
|
+
// Nothing here is inferred and nothing here is ever inferred. A scanner
|
|
364
|
+
// that could conclude "this repo looks like it wants its credentials
|
|
365
|
+
// readable" is a scanner that opens a boundary on evidence, and the
|
|
366
|
+
// evidence for opening one is a person deciding to.
|
|
367
|
+
boundaries: { preset: 'strict', ...BOUNDARIES_STRICT },
|
|
359
368
|
// Written out in full, every value at its shipped default, with the
|
|
360
369
|
// feature OFF. Nothing here enables anything — `mode: 'off'` is the same
|
|
361
370
|
// inert state as omitting the block entirely.
|
|
@@ -548,6 +557,13 @@ export function renderConfig(config) {
|
|
|
548
557
|
'# autonomy class at all, which is the boundary silently missing exactly\n' +
|
|
549
558
|
'# where the most agents run.\n' +
|
|
550
559
|
'#\n' +
|
|
560
|
+
'# GIVING AGENTS MORE ROOM: `boundaries:` below is the one place the policy\n' +
|
|
561
|
+
'# gate can be turned down. `preset: open` relaxes all five at once — the\n' +
|
|
562
|
+
'# closest thing to running with permissions skipped. Secret scanning at\n' +
|
|
563
|
+
'# commit and push, the enforcement hooks, `.claude/settings.json` and\n' +
|
|
564
|
+
'# `.tyran/STOP` are NOT reachable from it, whatever it is set to.\n' +
|
|
565
|
+
'# See docs/configuration.md.\n' +
|
|
566
|
+
'#\n' +
|
|
551
567
|
'# Validate: node scripts/schema.mjs validate config .tyran/config.yaml\n' +
|
|
552
568
|
'# Resolve a role to a model: node scripts/tiers.mjs --role reviewer\n' +
|
|
553
569
|
'\n' +
|
package/scripts/schema.mjs
CHANGED
|
@@ -34,6 +34,35 @@ export const TIER_KEYS = Object.freeze(['cheap', 'work', 'deep', 'top']);
|
|
|
34
34
|
export const ARTIFACT_CLASSES = Object.freeze(['AUTO', 'GATED', 'KERNEL']);
|
|
35
35
|
export const KNOWLEDGE_KINDS = Object.freeze(['fact', 'convention', 'gotcha', 'command', 'decision']);
|
|
36
36
|
|
|
37
|
+
/**
|
|
38
|
+
* `boundaries:` — how far down the policy gate's refusals may be turned.
|
|
39
|
+
*
|
|
40
|
+
* One block, because the alternative measured badly on real installs: an
|
|
41
|
+
* operator who wants agents to read a neighbouring project's files has no
|
|
42
|
+
* business learning what `main_writable_paths` is, and the answer to "let it
|
|
43
|
+
* do everything" must not be five unrelated edits in four files.
|
|
44
|
+
*
|
|
45
|
+
* Every flag is spelled the same way — the strict value first, so a reader
|
|
46
|
+
* scanning the list knows which column is the default without consulting a
|
|
47
|
+
* table. `prompts` is the odd one because it is not a refusal knob at all: it
|
|
48
|
+
* decides whether a call this gate has NO objection to still renders the
|
|
49
|
+
* platform's own permission prompt.
|
|
50
|
+
*/
|
|
51
|
+
export const BOUNDARY_PRESETS = Object.freeze(['strict', 'open']);
|
|
52
|
+
export const BOUNDARY_VALUES = Object.freeze(['refuse', 'allow']);
|
|
53
|
+
export const BOUNDARY_PROMPTS = Object.freeze(['ask', 'skip']);
|
|
54
|
+
/** The four refusal flags, in the order they are documented. */
|
|
55
|
+
export const BOUNDARY_FLAGS = Object.freeze(['outside_repo', 'credentials', 'path_classes', 'push']);
|
|
56
|
+
/** Every key legal inside the block. */
|
|
57
|
+
export const BOUNDARY_KEYS = Object.freeze(['preset', ...BOUNDARY_FLAGS, 'prompts']);
|
|
58
|
+
/** What each preset resolves to before per-key overrides are applied. */
|
|
59
|
+
const BOUNDARY_BY_PRESET = Object.freeze({
|
|
60
|
+
strict: Object.freeze({ outside_repo: 'refuse', credentials: 'refuse', path_classes: 'refuse', push: 'refuse', prompts: 'ask' }),
|
|
61
|
+
open: Object.freeze({ outside_repo: 'allow', credentials: 'allow', path_classes: 'allow', push: 'allow', prompts: 'skip' }),
|
|
62
|
+
});
|
|
63
|
+
/** The safe answer, used for an absent block and for every value the schema rejects. */
|
|
64
|
+
export const BOUNDARIES_STRICT = BOUNDARY_BY_PRESET.strict;
|
|
65
|
+
|
|
37
66
|
const isPlainObject = (v) => typeof v === 'object' && v !== null && !Array.isArray(v);
|
|
38
67
|
const isNonEmptyString = (v) => typeof v === 'string' && v.trim() !== '';
|
|
39
68
|
|
|
@@ -69,7 +98,7 @@ export function validateConfig(doc) {
|
|
|
69
98
|
const errors = [];
|
|
70
99
|
if (!isPlainObject(doc)) return ['config must be a mapping'];
|
|
71
100
|
|
|
72
|
-
const known = ['profile', 'autonomy', 'tiers', 'validation', 'shared_zones', 'budget', 'main_writable_paths', 'limits', 'pricing', 'spend', 'board'];
|
|
101
|
+
const known = ['profile', 'autonomy', 'tiers', 'validation', 'shared_zones', 'budget', 'main_writable_paths', 'boundaries', 'limits', 'pricing', 'spend', 'board'];
|
|
73
102
|
for (const key of Object.keys(doc)) {
|
|
74
103
|
if (!known.includes(key)) errors.push(`${key}: unknown top-level key`);
|
|
75
104
|
}
|
|
@@ -146,6 +175,30 @@ export function validateConfig(doc) {
|
|
|
146
175
|
}
|
|
147
176
|
}
|
|
148
177
|
|
|
178
|
+
// How far the policy gate's refusals may be turned down. Optional; absent
|
|
179
|
+
// means strict, which is what every install had before this block existed.
|
|
180
|
+
// Operator-written policy, never scanner-inferred — no provenance wrapper.
|
|
181
|
+
if ('boundaries' in doc) {
|
|
182
|
+
if (!isPlainObject(doc.boundaries)) errors.push('boundaries: must be a mapping');
|
|
183
|
+
else {
|
|
184
|
+
const boundaries = doc.boundaries;
|
|
185
|
+
if ('preset' in boundaries && !BOUNDARY_PRESETS.includes(boundaries.preset)) {
|
|
186
|
+
errors.push(`boundaries.preset: must be one of ${BOUNDARY_PRESETS.join(' | ')}`);
|
|
187
|
+
}
|
|
188
|
+
for (const flag of BOUNDARY_FLAGS) {
|
|
189
|
+
if (flag in boundaries && !BOUNDARY_VALUES.includes(boundaries[flag])) {
|
|
190
|
+
errors.push(`boundaries.${flag}: must be one of ${BOUNDARY_VALUES.join(' | ')}`);
|
|
191
|
+
}
|
|
192
|
+
}
|
|
193
|
+
if ('prompts' in boundaries && !BOUNDARY_PROMPTS.includes(boundaries.prompts)) {
|
|
194
|
+
errors.push(`boundaries.prompts: must be one of ${BOUNDARY_PROMPTS.join(' | ')}`);
|
|
195
|
+
}
|
|
196
|
+
for (const key of Object.keys(boundaries)) {
|
|
197
|
+
if (!BOUNDARY_KEYS.includes(key)) errors.push(`boundaries.${key}: unknown key`);
|
|
198
|
+
}
|
|
199
|
+
}
|
|
200
|
+
}
|
|
201
|
+
|
|
149
202
|
// Overnight mode: usage-limit pause/resume. Optional; absent = feature off.
|
|
150
203
|
// Operator-written policy, never scanner-inferred — no provenance wrapper.
|
|
151
204
|
if ('limits' in doc) {
|
|
@@ -313,6 +366,40 @@ export function boardSettings(doc) {
|
|
|
313
366
|
};
|
|
314
367
|
}
|
|
315
368
|
|
|
369
|
+
/**
|
|
370
|
+
* The boundaries block with the preset expanded and overrides applied — the
|
|
371
|
+
* ONE place the resolution rule lives, called by the policy gate, doctor, the
|
|
372
|
+
* Settings tab and anything else that needs to know how open this repo is.
|
|
373
|
+
*
|
|
374
|
+
* Two properties, and both are the security-critical direction of `limitsOf`'s
|
|
375
|
+
* doctrine rather than a copy of it:
|
|
376
|
+
*
|
|
377
|
+
* - an absent block is STRICT, so every install written before this existed
|
|
378
|
+
* keeps exactly the behaviour it had;
|
|
379
|
+
* - a value the validator rejects is treated as absent, which for a knob
|
|
380
|
+
* whose looser setting removes a refusal means it must never RELAX on
|
|
381
|
+
* input nobody can read. `credentials: yes` is not `allow`, and guessing
|
|
382
|
+
* that it is would open the secret-read rule on a typo.
|
|
383
|
+
*
|
|
384
|
+
* An explicit key beats the preset, in both directions: `preset: open` with
|
|
385
|
+
* `credentials: refuse` is a repo that wants everything except its own keys.
|
|
386
|
+
*/
|
|
387
|
+
export function boundariesOf(doc) {
|
|
388
|
+
const raw = isPlainObject(doc) && isPlainObject(doc.boundaries) ? doc.boundaries : {};
|
|
389
|
+
const base = BOUNDARY_BY_PRESET[raw.preset] ?? BOUNDARIES_STRICT;
|
|
390
|
+
const resolved = { ...base };
|
|
391
|
+
for (const flag of BOUNDARY_FLAGS) {
|
|
392
|
+
if (BOUNDARY_VALUES.includes(raw[flag])) resolved[flag] = raw[flag];
|
|
393
|
+
}
|
|
394
|
+
if (BOUNDARY_PROMPTS.includes(raw.prompts)) resolved.prompts = raw.prompts;
|
|
395
|
+
return Object.freeze(resolved);
|
|
396
|
+
}
|
|
397
|
+
|
|
398
|
+
/** Which flags are looser than strict — what a doctor finding and the board report. */
|
|
399
|
+
export function relaxedBoundaries(resolved) {
|
|
400
|
+
return Object.keys(BOUNDARIES_STRICT).filter((key) => resolved[key] !== BOUNDARIES_STRICT[key]);
|
|
401
|
+
}
|
|
402
|
+
|
|
316
403
|
export const LIMITS_MODES = Object.freeze(['off', 'warn', 'pause']);
|
|
317
404
|
export const LIMITS_LONG_WAIT = Object.freeze(['hold', 'resume']);
|
|
318
405
|
|
package/scripts/settings.mjs
CHANGED
|
@@ -38,6 +38,9 @@ import { join } from 'node:path';
|
|
|
38
38
|
import {
|
|
39
39
|
ARTIFACT_CLASSES,
|
|
40
40
|
AUTONOMY_CLASSES,
|
|
41
|
+
BOUNDARY_PRESETS,
|
|
42
|
+
BOUNDARY_PROMPTS,
|
|
43
|
+
BOUNDARY_VALUES,
|
|
41
44
|
LIMITS_LONG_WAIT,
|
|
42
45
|
LIMITS_MODES,
|
|
43
46
|
MANDATORY_KERNEL_PATHS,
|
|
@@ -84,6 +87,11 @@ export const GROUPS = Object.freeze([
|
|
|
84
87
|
path: ['profile'],
|
|
85
88
|
label: 'Cost profile',
|
|
86
89
|
help: 'How much verification each piece of work carries. The cheaper profiles skip review passes, not tests.',
|
|
90
|
+
explain: {
|
|
91
|
+
what: 'How many independent eyes look at a piece of work before it counts as done.',
|
|
92
|
+
changes: 'The number of review passes and agents the conductor spends per ticket — never whether tests run; those always do.',
|
|
93
|
+
effect: 'Eco finishes sooner and cheaper with tests as the only guard; full adds an independent review and the strongest tier on risky work, so mistakes are caught before you see them.',
|
|
94
|
+
},
|
|
87
95
|
...choice(PROFILES, {
|
|
88
96
|
eco: 'Fewest agents and fewest review passes. Good for small, well-understood changes.',
|
|
89
97
|
balanced: 'The default. Implementation plus an independent review on anything non-trivial.',
|
|
@@ -95,6 +103,16 @@ export const GROUPS = Object.freeze([
|
|
|
95
103
|
path: ['autonomy'],
|
|
96
104
|
label: 'Deployment autonomy',
|
|
97
105
|
help: 'How far a finished piece of work may travel without you. The gate enforces this downward — it will not stop someone who edits this file from raising it, which is why the policy below decides who may.',
|
|
106
|
+
explain: {
|
|
107
|
+
what: 'The furthest a finished change may travel without a human touching it.',
|
|
108
|
+
changes: 'Which git pushes the gate allows: P1 stops at a feature branch, P2 reaches staging, P3 may land the default branch.',
|
|
109
|
+
effect: 'At P1 you merge every PR yourself; at P3 Tyran can finish a story end to end. Irreversible pushes — force, mirror, remote deletes — are refused at every level, including P3.',
|
|
110
|
+
},
|
|
111
|
+
widening: {
|
|
112
|
+
scale: 'autonomy',
|
|
113
|
+
consequence:
|
|
114
|
+
'A higher deployment class lets finished work travel further without you — P2 reaches staging, P3 merges to the default branch.',
|
|
115
|
+
},
|
|
98
116
|
...choice(AUTONOMY_CLASSES, {
|
|
99
117
|
P1: 'Branch only. Agents commit and push a branch; you open and merge the PR.',
|
|
100
118
|
P2: 'Through to staging. Agents may merge and deploy to a non-production environment.',
|
|
@@ -103,6 +121,131 @@ export const GROUPS = Object.freeze([
|
|
|
103
121
|
},
|
|
104
122
|
],
|
|
105
123
|
},
|
|
124
|
+
{
|
|
125
|
+
id: 'boundaries',
|
|
126
|
+
title: 'What agents may touch',
|
|
127
|
+
blurb:
|
|
128
|
+
'How far the policy gate turns its refusals down. Everything here starts at the strict setting, and every move toward the looser one asks you to confirm it a second time. Four things are NOT on this screen because no setting reaches them: secret scanning at commit and push, the enforcement hooks themselves, the file that registers them, and the STOP brake.',
|
|
129
|
+
settings: [
|
|
130
|
+
{
|
|
131
|
+
id: 'boundaries.preset',
|
|
132
|
+
path: ['boundaries', 'preset'],
|
|
133
|
+
label: 'Preset',
|
|
134
|
+
help: 'The one switch. "Open" turns every boundary below to its loose setting at once — the closest thing Tyran has to running Claude Code with permissions skipped. Anything you set individually below wins over the preset.',
|
|
135
|
+
explain: {
|
|
136
|
+
what: 'The master position for every boundary in this group at once.',
|
|
137
|
+
changes: 'Flips outside-repo access, credential reads, your path rules, push checks and permission prompts together; any boundary you set individually below overrides it.',
|
|
138
|
+
effect: 'On "open", agents move without friction and without asking — the four things no setting reaches (secret scanning, the hooks, their registry, the STOP brake) still hold.',
|
|
139
|
+
},
|
|
140
|
+
widening: {
|
|
141
|
+
scale: 'preset',
|
|
142
|
+
consequence:
|
|
143
|
+
'OPEN lets agents read your credentials, work outside this repository, write paths your own policy gates, push anywhere, and act without a permission prompt. Secret scanning and the gate\'s own files are unaffected.',
|
|
144
|
+
},
|
|
145
|
+
...choice(BOUNDARY_PRESETS, {
|
|
146
|
+
strict: 'Every boundary on. This is what Tyran has always done.',
|
|
147
|
+
open: 'Every boundary below turned down at once.',
|
|
148
|
+
}),
|
|
149
|
+
},
|
|
150
|
+
{
|
|
151
|
+
id: 'boundaries.outside_repo',
|
|
152
|
+
path: ['boundaries', 'outside_repo'],
|
|
153
|
+
label: 'Files outside this repository',
|
|
154
|
+
help: 'Today a path outside the repo root is refused for every agent. Allowing it lets them read and write anywhere on this machine — another project, your home directory, system files.',
|
|
155
|
+
explain: {
|
|
156
|
+
what: 'Whether an agent may touch any file that lives outside this repository’s root.',
|
|
157
|
+
changes: 'On "refuse", every read and write outside the repo is denied for every agent; on "allow", the whole machine is in reach.',
|
|
158
|
+
effect: 'The strictest boundary Tyran has: it is what makes "an agent went wrong" mean "inside this repo, revertable with git" rather than "anywhere on this computer".',
|
|
159
|
+
},
|
|
160
|
+
widening: {
|
|
161
|
+
scale: 'boundary',
|
|
162
|
+
consequence: 'Agents will be able to write files anywhere on this machine, not only inside this repository.',
|
|
163
|
+
},
|
|
164
|
+
...choice(BOUNDARY_VALUES, {
|
|
165
|
+
refuse: 'Agents stay inside this repository.',
|
|
166
|
+
allow: 'Agents may read and write anywhere on this machine.',
|
|
167
|
+
}),
|
|
168
|
+
},
|
|
169
|
+
{
|
|
170
|
+
id: 'boundaries.credentials',
|
|
171
|
+
path: ['boundaries', 'credentials'],
|
|
172
|
+
label: 'Credential files',
|
|
173
|
+
help: 'Today .env files, private keys, ~/.ssh, ~/.aws and their relatives are refused before they can reach the model — a transcript is storage. Allowing it also removes the false refusal where a word merely ENDING in .key or .pem is treated as a file.',
|
|
174
|
+
explain: {
|
|
175
|
+
what: 'Whether credential-shaped files — .env, private keys, ~/.ssh, ~/.aws — may be read into the conversation at all.',
|
|
176
|
+
changes: 'On "refuse" they are blocked before the model sees a byte; on "allow" agents can read them like any other file.',
|
|
177
|
+
effect: 'A transcript is storage, so a secret read once is a secret retained. What stops secrets being COMMITTED stays separate — the commit/push scan runs whatever this says.',
|
|
178
|
+
},
|
|
179
|
+
widening: {
|
|
180
|
+
scale: 'boundary',
|
|
181
|
+
consequence:
|
|
182
|
+
'Agents will be able to read your secrets into the conversation. What stops those bytes being COMMITTED or PUSHED is the secrets gate, which this setting does not reach.',
|
|
183
|
+
},
|
|
184
|
+
...choice(BOUNDARY_VALUES, {
|
|
185
|
+
refuse: 'Credential-shaped files never enter the conversation.',
|
|
186
|
+
allow: 'Agents may read .env files, keys and credential stores.',
|
|
187
|
+
}),
|
|
188
|
+
},
|
|
189
|
+
{
|
|
190
|
+
id: 'boundaries.path_classes',
|
|
191
|
+
path: ['boundaries', 'path_classes'],
|
|
192
|
+
label: 'Your own path rules',
|
|
193
|
+
help: 'The AUTO / GATED / KERNEL rules in the policy below. Allowing this makes them advisory: a subagent may write a path you gated. The four paths that protect the gate itself stay refused whatever this says.',
|
|
194
|
+
explain: {
|
|
195
|
+
what: 'Whether the AUTO / GATED / KERNEL classes in the autonomy policy further down this page are enforced on writes.',
|
|
196
|
+
changes: 'On "allow" they become advisory: a subagent may write a path you gated, and only the four self-protecting paths still refuse.',
|
|
197
|
+
effect: 'Turning this off removes the distinction the policy exists to draw — everything an agent can reach becomes effectively AUTO.',
|
|
198
|
+
},
|
|
199
|
+
widening: {
|
|
200
|
+
scale: 'boundary',
|
|
201
|
+
consequence: 'The GATED and KERNEL rules in your own policy stop being enforced for writes.',
|
|
202
|
+
},
|
|
203
|
+
...choice(BOUNDARY_VALUES, {
|
|
204
|
+
refuse: 'The classes in your policy are enforced.',
|
|
205
|
+
allow: 'Agents may write paths your policy gates.',
|
|
206
|
+
}),
|
|
207
|
+
},
|
|
208
|
+
{
|
|
209
|
+
id: 'boundaries.push',
|
|
210
|
+
path: ['boundaries', 'push'],
|
|
211
|
+
label: 'Where work may be pushed',
|
|
212
|
+
help: 'Turns off the deployment-class check on git push entirely, including the rules that gate the pushes nothing can undo — a force push to main, a deleted remote branch, a mirror push.',
|
|
213
|
+
explain: {
|
|
214
|
+
what: 'Whether git pushes are checked against the deployment autonomy above at all.',
|
|
215
|
+
changes: 'On "allow", the branch rules AND the irreversible-operation rules stop applying — force pushes, mirror pushes and remote branch deletes included.',
|
|
216
|
+
effect: 'This is the only setting that can permit an operation git cannot undo. The deployment-autonomy dropdown above becomes decoration while this is loose.',
|
|
217
|
+
},
|
|
218
|
+
widening: {
|
|
219
|
+
scale: 'boundary',
|
|
220
|
+
consequence:
|
|
221
|
+
'The deployment class stops being checked. Agents may force-push, delete remote branches and mirror-push, none of which can be undone.',
|
|
222
|
+
},
|
|
223
|
+
...choice(BOUNDARY_VALUES, {
|
|
224
|
+
refuse: 'Pushes are checked against the deployment autonomy above.',
|
|
225
|
+
allow: 'Any push is allowed, including the irreversible ones.',
|
|
226
|
+
}),
|
|
227
|
+
},
|
|
228
|
+
{
|
|
229
|
+
id: 'boundaries.prompts',
|
|
230
|
+
path: ['boundaries', 'prompts'],
|
|
231
|
+
label: 'Permission prompts',
|
|
232
|
+
help: 'Whether Claude Code still asks you before a tool call this gate has no objection to. "Skip" auto-approves those calls, which is what people mean by skipping permissions — a refusal from any gate still wins, so this cannot approve something another gate denied.',
|
|
233
|
+
explain: {
|
|
234
|
+
what: 'Whether Claude Code still shows its own permission dialog for calls this gate has already looked at and passed.',
|
|
235
|
+
changes: 'On "skip", those calls are auto-approved and the session flows without interruptions; refusals from any gate still refuse.',
|
|
236
|
+
effect: 'Pure convenience versus oversight: nothing becomes allowed that was not already, you just stop being the click between an allowed call and its execution.',
|
|
237
|
+
},
|
|
238
|
+
widening: {
|
|
239
|
+
scale: 'prompts',
|
|
240
|
+
consequence: 'Claude Code will stop asking before it edits files or runs commands that no gate objects to.',
|
|
241
|
+
},
|
|
242
|
+
...choice(BOUNDARY_PROMPTS, {
|
|
243
|
+
ask: 'Claude Code prompts you as it normally would.',
|
|
244
|
+
skip: 'Calls no gate objects to are approved without asking.',
|
|
245
|
+
}),
|
|
246
|
+
},
|
|
247
|
+
],
|
|
248
|
+
},
|
|
106
249
|
{
|
|
107
250
|
id: 'tiers',
|
|
108
251
|
title: 'Model tiers',
|
|
@@ -119,6 +262,16 @@ export const GROUPS = Object.freeze([
|
|
|
119
262
|
deep: 'Root-cause diagnosis, hard implementation, risky review — where a wrong answer is expensive.',
|
|
120
263
|
top: 'Security review, arbitration, final acceptance. The last word, used sparingly.',
|
|
121
264
|
}[key],
|
|
265
|
+
explain: {
|
|
266
|
+
what: `The model id every agent spawned at the "${key}" tier runs on.`,
|
|
267
|
+
changes: 'Only which model answers when a skill or agent asks for this tier — roles and routing stay as they are.',
|
|
268
|
+
effect: {
|
|
269
|
+
cheap: 'A stronger model here buys nothing but cost: this tier exists for work where any competent model gives the same answer.',
|
|
270
|
+
work: 'This is most of your spend and most of your quality — the tier to adjust first when either is wrong.',
|
|
271
|
+
deep: 'Skimping here is where wrong answers get expensive: this tier is called exactly when the work is known to be hard.',
|
|
272
|
+
top: 'The tier trusted with the final word — used rarely enough that a strong model here costs little and vetoes a lot.',
|
|
273
|
+
}[key],
|
|
274
|
+
},
|
|
122
275
|
placeholder: 'a model id or alias your CLI accepts',
|
|
123
276
|
})),
|
|
124
277
|
},
|
|
@@ -133,6 +286,11 @@ export const GROUPS = Object.freeze([
|
|
|
133
286
|
label: 'Validation commands',
|
|
134
287
|
kind: 'list',
|
|
135
288
|
help: 'Run in order before any work is reported. Each must EXIT — a watch-mode test runner here hangs every agent you ever spawn, which is a real measured incident, not a hypothetical.',
|
|
289
|
+
explain: {
|
|
290
|
+
what: 'The commands that define "done" in this repository — every agent runs them before reporting any work.',
|
|
291
|
+
changes: 'What proof each ticket must carry: add a linter and every future ticket lints; remove the tests and nothing runs them.',
|
|
292
|
+
effect: 'This list is Tyran’s definition of working code. A command that never exits (watch mode) hangs every agent; a missing one means work ships unproven.',
|
|
293
|
+
},
|
|
136
294
|
placeholder: 'npm test',
|
|
137
295
|
},
|
|
138
296
|
{
|
|
@@ -141,6 +299,11 @@ export const GROUPS = Object.freeze([
|
|
|
141
299
|
label: 'Shared zones',
|
|
142
300
|
kind: 'list',
|
|
143
301
|
help: 'Files more than one agent may touch in parallel. Writes to these are append-only and serialized by the conductor, so two agents cannot clobber each other.',
|
|
302
|
+
explain: {
|
|
303
|
+
what: 'The files that several parallel agents are expected to touch at once — registries, barrel files, route tables.',
|
|
304
|
+
changes: 'Which paths the conductor serializes: writes there become append-only and take turns instead of racing.',
|
|
305
|
+
effect: 'A hot file missing from this list is the classic parallel-agent failure: two branches both "won" and one agent’s work silently vanished in the merge.',
|
|
306
|
+
},
|
|
144
307
|
placeholder: 'src/registry.ts',
|
|
145
308
|
},
|
|
146
309
|
],
|
|
@@ -161,6 +324,11 @@ export const GROUPS = Object.freeze([
|
|
|
161
324
|
pause: 'Winds work down at the threshold, checkpoints it, and schedules the resume.',
|
|
162
325
|
}),
|
|
163
326
|
help: 'What happens as the usage window fills up.',
|
|
327
|
+
explain: {
|
|
328
|
+
what: 'Whether Tyran watches your subscription usage windows and acts before they run out.',
|
|
329
|
+
changes: 'Off ignores usage entirely; warn only reports it; pause winds running work down at the threshold, saves a checkpoint and schedules its own resume.',
|
|
330
|
+
effect: 'Pause is what makes overnight runs survivable: work stops at a clean seam instead of mid-edit when the platform cuts the session off.',
|
|
331
|
+
},
|
|
164
332
|
},
|
|
165
333
|
{
|
|
166
334
|
id: 'limits.pause_at_percent',
|
|
@@ -171,6 +339,11 @@ export const GROUPS = Object.freeze([
|
|
|
171
339
|
max: 100,
|
|
172
340
|
unit: '%',
|
|
173
341
|
help: 'How full the five-hour window must be before work winds down. The floor of 50 exists to catch 0.97 pasted where 97 belongs.',
|
|
342
|
+
explain: {
|
|
343
|
+
what: 'The fill level of the rolling five-hour usage window at which a pause begins.',
|
|
344
|
+
changes: 'Lower pauses earlier with margin to spare; higher squeezes more work out of each window at the risk of a hard platform cutoff.',
|
|
345
|
+
effect: 'The margin between this number and 100 is what the wind-down itself gets to spend — checkpointing costs tokens too.',
|
|
346
|
+
},
|
|
174
347
|
},
|
|
175
348
|
{
|
|
176
349
|
id: 'limits.weekly_pause_at_percent',
|
|
@@ -181,6 +354,11 @@ export const GROUPS = Object.freeze([
|
|
|
181
354
|
max: 100,
|
|
182
355
|
unit: '%',
|
|
183
356
|
help: 'The same threshold for the seven-day window. Hitting this one means a much longer wait.',
|
|
357
|
+
explain: {
|
|
358
|
+
what: 'The same pause threshold, for the seven-day usage window.',
|
|
359
|
+
changes: 'When the weekly window — not the five-hour one — is what stops work.',
|
|
360
|
+
effect: 'A weekly pause can mean days, not hours: this threshold decides how much of the week’s budget overnight work may consume before a human re-decides.',
|
|
361
|
+
},
|
|
184
362
|
},
|
|
185
363
|
{
|
|
186
364
|
id: 'limits.wait_max_hours',
|
|
@@ -191,6 +369,11 @@ export const GROUPS = Object.freeze([
|
|
|
191
369
|
max: 24,
|
|
192
370
|
unit: 'h',
|
|
193
371
|
help: 'A reset further away than this is a LONG pause: it gets announced rather than silently waited out. The weekly window can be days.',
|
|
372
|
+
explain: {
|
|
373
|
+
what: 'The longest gap Tyran will wait out silently before treating the pause as a long one.',
|
|
374
|
+
changes: 'Where the line between "quietly resume later" and "tell the operator" sits.',
|
|
375
|
+
effect: 'Below this, a pause is plumbing; above it, it is news — the setting decides which pauses you hear about.',
|
|
376
|
+
},
|
|
194
377
|
},
|
|
195
378
|
{
|
|
196
379
|
id: 'limits.long_wait',
|
|
@@ -201,6 +384,11 @@ export const GROUPS = Object.freeze([
|
|
|
201
384
|
resume: 'Schedule the resume anyway, however far out it is.',
|
|
202
385
|
}),
|
|
203
386
|
help: 'What the scheduler does when the reset is further away than the wait above.',
|
|
387
|
+
explain: {
|
|
388
|
+
what: 'The long-pause policy: hold for a human, or schedule the resume however far out it is.',
|
|
389
|
+
changes: 'Whether a days-away reset ends with Tyran waiting for you, or with Tyran waking itself when the window returns.',
|
|
390
|
+
effect: '"Resume" keeps an overnight programme moving across a weekly pause; "hold" guarantees a human looks at the situation before more budget is spent.',
|
|
391
|
+
},
|
|
204
392
|
},
|
|
205
393
|
{
|
|
206
394
|
id: 'limits.resume_margin_minutes',
|
|
@@ -211,6 +399,11 @@ export const GROUPS = Object.freeze([
|
|
|
211
399
|
max: 240,
|
|
212
400
|
unit: 'min',
|
|
213
401
|
help: 'How long after the window resets before work restarts. A little slack absorbs clock skew between your machine and the platform.',
|
|
402
|
+
explain: {
|
|
403
|
+
what: 'The slack between the platform’s window reset and Tyran restarting work.',
|
|
404
|
+
changes: 'How long after the reset the resume fires.',
|
|
405
|
+
effect: 'Too small and a clock-skewed resume lands before the window actually reset, burning an attempt; the cost of generous is only minutes of idleness.',
|
|
406
|
+
},
|
|
214
407
|
},
|
|
215
408
|
{
|
|
216
409
|
id: 'limits.keep_awake',
|
|
@@ -218,6 +411,11 @@ export const GROUPS = Object.freeze([
|
|
|
218
411
|
label: 'Hold the machine awake',
|
|
219
412
|
kind: 'boolean',
|
|
220
413
|
help: 'A laptop that suspends takes the resume watcher down with it. This holds the SYSTEM awake while it waits — never the display, so your screen lock is untouched.',
|
|
414
|
+
explain: {
|
|
415
|
+
what: 'Whether the machine is held awake while a scheduled resume waits.',
|
|
416
|
+
changes: 'On, the system cannot suspend while the watcher waits (the display still sleeps and locks); off, the laptop may sleep through its own resume.',
|
|
417
|
+
effect: 'The difference between an overnight run that resumed at 3 AM and one you find still paused at breakfast because the lid was closed.',
|
|
418
|
+
},
|
|
221
419
|
},
|
|
222
420
|
],
|
|
223
421
|
},
|
|
@@ -246,6 +444,11 @@ const BY_ID = new Map(GROUPS.flatMap((g) => g.settings.map((s) => [s.id, s])));
|
|
|
246
444
|
const LOOSER_FIRST = Object.freeze({
|
|
247
445
|
class: Object.freeze(['AUTO', 'GATED', 'KERNEL']),
|
|
248
446
|
autonomy: Object.freeze(['P3', 'P2', 'P1']),
|
|
447
|
+
// The `boundaries:` block. Each of these turns a REFUSAL off, so the
|
|
448
|
+
// direction that needs the second act is the one that removes a check.
|
|
449
|
+
boundary: Object.freeze([...BOUNDARY_VALUES].reverse()),
|
|
450
|
+
prompts: Object.freeze([...BOUNDARY_PROMPTS].reverse()),
|
|
451
|
+
preset: Object.freeze([...BOUNDARY_PRESETS].reverse()),
|
|
249
452
|
});
|
|
250
453
|
|
|
251
454
|
function widens(scale, before, after) {
|
|
@@ -359,6 +562,12 @@ export function readSettings(tyranDir) {
|
|
|
359
562
|
id: setting.id,
|
|
360
563
|
label: setting.label,
|
|
361
564
|
help: setting.help,
|
|
565
|
+
// The structured explanation the board folds shut under each row:
|
|
566
|
+
// what it is, what changing it does, how it lands on Tyran. The
|
|
567
|
+
// widening consequence travels beside it so the cost of loosening is
|
|
568
|
+
// readable BEFORE the confirm dialog restates it.
|
|
569
|
+
explain: setting.explain ?? null,
|
|
570
|
+
widens: setting.widening?.consequence ?? null,
|
|
362
571
|
kind: setting.kind ?? 'choice',
|
|
363
572
|
choices: setting.choices ?? null,
|
|
364
573
|
min: setting.min ?? null,
|
|
@@ -462,9 +671,12 @@ export function applySetting(tyranDir, id, value, confirm = null) {
|
|
|
462
671
|
);
|
|
463
672
|
}
|
|
464
673
|
const next = coerce(setting, value);
|
|
465
|
-
|
|
466
|
-
|
|
467
|
-
|
|
674
|
+
// Driven by the catalogue rather than by a list of ids here. The `autonomy`
|
|
675
|
+
// check used to be an `if (id === ...)`, and every knob added beside it since
|
|
676
|
+
// would have had to remember to extend that line — which is exactly how a
|
|
677
|
+
// boundary-loosening control ships with no confirmation at all.
|
|
678
|
+
if (setting.widening) {
|
|
679
|
+
requireConfirm(setting.widening.scale, before, next, confirm, setting.widening.consequence);
|
|
468
680
|
}
|
|
469
681
|
|
|
470
682
|
let text;
|
package/skills/setup/SKILL.md
CHANGED
|
@@ -248,6 +248,26 @@ agent that runs `git add -A` on a story branch sweeps the untracked `.tyran/`
|
|
|
248
248
|
into that branch, and a four-way parallel run ends with four conflicting
|
|
249
249
|
copies of the config. Stage explicit paths until this commit exists.
|
|
250
250
|
|
|
251
|
+
## 6b. Say that `boundaries:` exists, once, and do not sell it
|
|
252
|
+
|
|
253
|
+
The scan writes the block at its strict setting. Tell the operator, in one or
|
|
254
|
+
two sentences, that `.tyran/config.yaml` has a `boundaries:` block and that
|
|
255
|
+
`preset: open` relaxes all five at once — files outside the repo, credential
|
|
256
|
+
files, their own path rules, the deployment class on `git push`, and the
|
|
257
|
+
permission prompt. The Settings tab edits it, and every move toward the loose
|
|
258
|
+
value asks for a confirmation.
|
|
259
|
+
|
|
260
|
+
Say the floor in the same breath, because it is what makes the offer safe to
|
|
261
|
+
make: secret scanning at commit and push, the enforcement hooks,
|
|
262
|
+
`.claude/settings.json` and `.tyran/STOP` are unreachable from it at any
|
|
263
|
+
setting.
|
|
264
|
+
|
|
265
|
+
**Do not recommend a value, and do not ask which they want.** Strict is
|
|
266
|
+
already written and already correct; this is a pointer for the operator who
|
|
267
|
+
comes back later having hit a refusal they did not want, not a decision to
|
|
268
|
+
extract during setup. An agent that talks somebody into opening a boundary
|
|
269
|
+
during onboarding is the failure this step exists to avoid.
|
|
270
|
+
|
|
251
271
|
## 7. Offer overnight mode — and say plainly what the operator must do
|
|
252
272
|
|
|
253
273
|
Overnight mode (https://jjanczur.github.io/tyran/overnight/) pauses autonomous work near the
|
package/templates/config.yaml
CHANGED
|
@@ -43,6 +43,34 @@ validation:
|
|
|
43
43
|
# Files multiple agents may touch: append-only, serialized by the conductor.
|
|
44
44
|
shared_zones: []
|
|
45
45
|
|
|
46
|
+
# How far the policy gate turns its refusals DOWN. Every value here is the
|
|
47
|
+
# strict one, which is what Tyran did before this block existed — nothing is
|
|
48
|
+
# relaxed by having it in the file, only made editable from the Settings tab.
|
|
49
|
+
#
|
|
50
|
+
# preset: strict | open one switch. `open` sets all five below at once and
|
|
51
|
+
# is the closest thing to running with permissions
|
|
52
|
+
# skipped. Anything you set explicitly wins over it.
|
|
53
|
+
# outside_repo refuse | allow — files outside this repository
|
|
54
|
+
# credentials refuse | allow — .env, keys, ~/.ssh, ~/.aws
|
|
55
|
+
# path_classes refuse | allow — the GATED/KERNEL rules you wrote
|
|
56
|
+
# push refuse | allow — the deployment class on git push
|
|
57
|
+
# prompts ask | skip — skip Claude Code's own prompts
|
|
58
|
+
#
|
|
59
|
+
# FOUR THINGS NO SETTING HERE REACHES, whatever it says: secret scanning at
|
|
60
|
+
# commit and push, the enforcement hooks, `.claude/settings.json`, and
|
|
61
|
+
# `.tyran/STOP`. A refusal from any gate still wins over an auto-approval.
|
|
62
|
+
#
|
|
63
|
+
# This file is class AUTO, so an agent can widen these itself — the same trade
|
|
64
|
+
# `autonomy:` above already makes, and the reason the four exceptions are
|
|
65
|
+
# mechanical rather than a matter of policy. See docs/policy-gate.md.
|
|
66
|
+
boundaries:
|
|
67
|
+
preset: strict
|
|
68
|
+
outside_repo: refuse
|
|
69
|
+
credentials: refuse
|
|
70
|
+
path_classes: refuse
|
|
71
|
+
push: refuse
|
|
72
|
+
prompts: ask
|
|
73
|
+
|
|
46
74
|
# Overnight mode — pause autonomous work near the subscription usage limits
|
|
47
75
|
# and resume after the window resets (https://jjanczur.github.io/tyran/overnight/). Requires the
|
|
48
76
|
# operator-installed statusline helper (scripts/statusline.mjs), which is the
|