@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.
@@ -61,7 +61,15 @@ import {
61
61
  PROGRESS_FILE,
62
62
  STATE_FILE,
63
63
  } from './project.mjs';
64
- import { classifyPath, normalizePath, validateFile, knowledgeWarnings, MANDATORY_KERNEL_PATHS } from './schema.mjs';
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) {
@@ -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' +
@@ -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
 
@@ -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
- if (id === 'autonomy') {
466
- requireConfirm('autonomy', before, next, confirm,
467
- 'A higher deployment class lets finished work travel further without you — P2 reaches staging, P3 merges to the default branch.');
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;
@@ -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
@@ -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