@jjanczur/tyran 0.1.51 → 0.1.52

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.
@@ -11,7 +11,7 @@
11
11
  {
12
12
  "name": "tyran",
13
13
  "description": "A task conductor for Claude Code: multi-agent orchestration with an enforced evidence contract, repo-specific learning, and update-safe local evolution.",
14
- "version": "0.1.51",
14
+ "version": "0.1.52",
15
15
  "source": "./",
16
16
  "author": {
17
17
  "name": "Jacek Janczura",
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "tyran",
3
- "version": "0.1.51",
3
+ "version": "0.1.52",
4
4
  "description": "A task conductor for Claude Code: multi-agent orchestration with an enforced evidence contract, repo-specific learning, and update-safe local evolution.",
5
5
  "author": {
6
6
  "name": "Jacek Janczura",
package/CHANGELOG.md CHANGED
@@ -1,5 +1,124 @@
1
1
  # Changelog
2
2
 
3
+ ## 0.1.52 — 2026-11-21
4
+
5
+ ### Both gates judge every push on a command line, not only the last one
6
+
7
+ The policy gate judged only the LAST push in a line. Under P1,
8
+ `git push origin HEAD:main && git push origin feature/x` passed and the first
9
+ push reached `main`. The cause was in `planCommand`, which both gates read: it
10
+ keeps one target per repository, and each push into that repository overwrote
11
+ the previous one's argv. The target now carries `pushArgvs`, every push in
12
+ order, and the policy gate reads the destination, the deletion and the force of
13
+ each one. Any one push past the class refuses the line.
14
+
15
+ The secrets gate had the same shape on the remote. 0.1.51 unioned the refs of
16
+ two pushes but kept the last push's remote, and the range is "commits not on
17
+ that remote". So `git push upstream leaky && git push origin leaky`, with
18
+ `leaky` already on `origin`, scanned an empty range while `upstream` received
19
+ the branch for the first time. The remotes are now unioned too, and the range
20
+ is listed once per remote. A `gh pr create`, which names no remote, adds no
21
+ unnamed one beside a push that names its remote.
22
+
23
+ Three new tests. The policy-gate test runs six spellings under P1, both orders
24
+ among them; on 0.1.51 it is red. The secrets-gate pair is a planner test and a
25
+ gate test against real git and gitleaks; both are red on 0.1.51.
26
+
27
+ ### A quoted value with a space no longer hides git commit or git push
28
+
29
+ Reported from a real install. `git -c user.name="Jacek Janczura" commit -m x`,
30
+ the single-quoted `-c` spelling and `GIT_AUTHOR_NAME='Jacek Janczura' git
31
+ commit` all passed the secrets gate UNSCANNED with a key staged, while
32
+ `git -c user.name=JJ commit` was refused. `tokensOf` splits a segment on
33
+ whitespace before it drops the quotes, so the subcommand resolver read
34
+ `Janczura` as the verb, or, behind an assignment, as the program with `git` as
35
+ the verb. No target meant no scan. `env X=1 git commit` and
36
+ `for b in a; do git push ...; done` had the same hole with no quote at all. The
37
+ policy gate reads the same plan, so a quoted identity in front of `git push`
38
+ also walked past the deployment class.
39
+
40
+ `planCommand` now also reads each segment the way the shell splits it
41
+ (`shellWords`: single and double quotes, `$'...'`, backslashes), and peels
42
+ assignments and wrapper prefixes in a loop (`gitInvocation`). A verb either
43
+ reading finds counts, so every command the old reading recognised is handled
44
+ as before. `splitSegments` stays quote-blind, for the reason recorded on
45
+ `SEPARATORS`. A separator inside a quoted value in front of the subcommand
46
+ (`git -c user.name="A; B" commit`) leaves the verb unreadable, and that now
47
+ fails closed (`unreadableVerb`, refused by both gates) instead of passing.
48
+
49
+ The gate change is the patch from `fix/secrets-gate-quoted-commit` (0648f5c),
50
+ ported onto the 0.1.51 push code, with its fail-closed check replaced. The
51
+ patch decided one segment at a time, and review found three spellings that
52
+ still passed a staged key unscanned. In `GIT_AUTHOR_NAME="A; B" git commit`
53
+ the quote hiding `git` opened in the previous segment. In
54
+ `GIT_AUTHOR_NAME="A; cd /tmp" git commit` the second segment starts with `cd`,
55
+ which the walk handles and skips. In `GIT_AUTHOR_NAME="A; git -C <decoy>
56
+ commit" git commit` a commit is found, in a clean decoy repository, and stands
57
+ in for the real one. The check is now one linear pass over the whole line
58
+ (`quotedSeparatorHidesVerb`), split where the shell splits it. It is decided
59
+ by position: a line fails closed when a separator inside a quote comes at or
60
+ before the verb of a commit, push or add. A separator in a commit message
61
+ comes after the verb and does not trip it. Neither does one inside `"$(...)"`,
62
+ which the shell runs as commands and the quote-blind lexer already reads.
63
+
64
+ 41 tests in `hook-secrets-gate-quoting.test.mjs` (the branch's 36, plus the
65
+ spellings above, a value too long for any bounded look-back, and a push inside
66
+ a shell loop) and one in the policy-gate suite. On 0.1.51, 38 of the 41 are
67
+ red. With the branch's patch alone, 5 are red: the three assignment-separator
68
+ gate tests, the decoy, and the planner test that lists the separator
69
+ spellings.
70
+
71
+ ### A redirection's file descriptor is no longer read as a refspec
72
+
73
+ 0.1.51 left one spelling of a remote-branch deletion refused for gigabytes:
74
+ `git push origin :gone 2>/dev/null`. `splitSegments` ends a segment at `>`,
75
+ so the `2` stayed behind as the last word of the push. It is not a `:dst`
76
+ refspec, so the deletion was scanned as a wide push. `git push 2>&1` read
77
+ the same `2` as the remote, and the policy gate then named a remote called
78
+ `2`. `splitSegments` now drops a whole word of digits directly in front of
79
+ `<` or `>`. That is the shell's own rule for a descriptor: in `v2>x` the word
80
+ `v2` is an argument and stays.
81
+
82
+ Two new tests. The planner test has five redirect spellings plus the `2>&1`
83
+ remote and the `v2` control. The gate test runs against real git and
84
+ gitleaks. Both are red on 0.1.51.
85
+
86
+ ### An explicit lease's expected sha is no longer refused as an API key
87
+
88
+ `git push --force-with-lease=pv3/api-token-fix:<40-hex sha> origin ...` was
89
+ refused as `generic-api-key`. Gitleaks reads the expected value as a
90
+ high-entropy key whenever the ref in front of it carries a keyword (`secret`,
91
+ `token`, `api`, `key`, `auth`). The only workaround was a bare
92
+ `--force-with-lease`, which drops the expected value.
93
+
94
+ `planCommand` now records the `<ref>:<full lowercase hex>` slot of a lease on
95
+ a `git push`, with the repository that push targets. `decide` hides that one
96
+ value (same length, all zeros) from the command-text scan, and ONLY when
97
+ `git --no-lazy-fetch cat-file -e <hex>^{object}` finds it in that repository.
98
+ Everything else leaves the text scanned as before: a hex that names no object,
99
+ an object of another repository, an abbreviation, a git failure or a timeout.
100
+ Nothing else in the command changes. `--no-lazy-fetch` matters: in a partial
101
+ clone the question would otherwise fetch the missing object from the promisor
102
+ remote, which sends the suspected value off the machine as `want <hex>`.
103
+
104
+ The gate change is the patch from `fix/secrets-gate-lease-sha` (dce74d6),
105
+ ported onto this release's push code. 13 tests in
106
+ `hook-secrets-gate-lease-sha.test.mjs`; on 0.1.51, 5 are red, the reported
107
+ false refusal among them.
108
+
109
+ ### Release titles no longer lose the words of a leading code span
110
+
111
+ The GitHub releases for 0.1.48 to 0.1.51 were titled `0.1.51 — : deleting a
112
+ remote branch ...`: the first heading's code span was missing. The release job
113
+ pasted the title into a bash line as `--title "..."`, and inside double
114
+ quotes a backtick is command substitution, so `secrets-gate` ran as a command
115
+ and printed nothing. The title now reaches the shell through an environment
116
+ variable, and backticks are dropped from it, since a title renders no
117
+ Markdown. The four titles were corrected by hand.
118
+
119
+ Also corrected: the 0.1.51 entry said its 13 tests ran end to end against real
120
+ git and gitleaks. 8 of them test the parser and 5 run the full gate.
121
+
3
122
  ## 0.1.51 — 2026-11-21
4
123
 
5
124
  ### `secrets-gate`: deleting a remote branch is no longer refused for gigabytes it never sends
@@ -31,9 +150,10 @@ main` passed the real gate with a private key on `leaky`. The refs are now
31
150
  unioned. A deletion never replaces an earlier push, and a wide range stays
32
151
  wide.
33
152
 
34
- 13 new tests in `hook-secrets-gate-delete-refspec.test.mjs`, end to end against
35
- real git and gitleaks. On the unpatched gate 10 of them are red, the ticket's
36
- own `git push origin --delete gone` among them.
153
+ 13 new tests in `hook-secrets-gate-delete-refspec.test.mjs`: 8 test the parser
154
+ (`planCommand`) and 5 run the full gate against real git and gitleaks. On the
155
+ unpatched gate 10 of them are red, the ticket's own `git push origin --delete
156
+ gone` among them.
37
157
 
38
158
  The gate change is in `hooks/scripts/`, which is KERNEL in this repository. It
39
159
  was made in a session the operator opened for it with `boundaries.kernel:
package/README.md CHANGED
@@ -329,7 +329,7 @@ enforces the cap (3947 of 5000 characters). What each one assumes, when it
329
329
  fires and who invokes it, is in
330
330
  [skills and agents](https://jjanczur.github.io/tyran/skills/); the prompts
331
331
  themselves are in [`skills/`](skills/) and [`agents/`](agents/). Behind all of
332
- it: 1734 unit tests, run with `node --test "tests/**/*.test.mjs"`.
332
+ it: 1794 unit tests, run with `node --test "tests/**/*.test.mjs"`.
333
333
 
334
334
  ## Documentation
335
335
 
@@ -1993,7 +1993,13 @@ async function decideBash({ input, toolInput, root, runner, budget, boundaries,
1993
1993
  if (boundaries.push === 'allow') return PASS;
1994
1994
 
1995
1995
  const plan = planCommand(command, startDir);
1996
- const pushes = plan.targets.filter((t) => t.scanPush === true && Array.isArray(t.pushArgv));
1996
+ // EVERY push, not one per directory. A target is per repository and a line
1997
+ // can push the same repository twice; judging the target's last argv let
1998
+ // `git push origin HEAD:main && git push origin feature/x` reach `main`
1999
+ // under P1. `pushArgvs` is every push in that repository, in order.
2000
+ const pushes = plan.targets
2001
+ .filter((t) => t.scanPush === true && Array.isArray(t.pushArgv))
2002
+ .flatMap((t) => (Array.isArray(t.pushArgvs) ? t.pushArgvs : [t.pushArgv]).map((argv) => ({ dir: t.dir, argv })));
1997
2003
  // Asked of the LEXER, not spelled again here. The first version of this gate
1998
2004
  // carried its own alias test, which was a second spelling of one rule two
1999
2005
  // files apart — and the secrets gate, which had the same blind spot, went on
@@ -2008,6 +2014,17 @@ async function decideBash({ input, toolInput, root, runner, budget, boundaries,
2008
2014
  'to a protected branch while this gate saw no push at all.',
2009
2015
  );
2010
2016
  }
2017
+ // Same hole, opened by a separator inside a quoted value in front of the
2018
+ // subcommand (`git -c user.name="A; B" push origin main`): the lexer splits
2019
+ // there on purpose, so the verb is in a segment with no `git` in it.
2020
+ if (plan.unreadableVerb) {
2021
+ throw new PolicyFailure(
2022
+ 'a quoted value in front of the git subcommand holds a command separator (`;`, `&`, `|`, ' +
2023
+ 'a bracket), so which subcommand it runs is not readable from the command line',
2024
+ 'set the value first (`git config user.name "A B"`) or drop the separator from it, then run ' +
2025
+ 'the subcommand on its own.',
2026
+ );
2027
+ }
2011
2028
  if (pushes.length === 0) return PASS;
2012
2029
 
2013
2030
  const deployClass = await loadDeployClass(root);
@@ -2048,7 +2065,7 @@ async function decideBash({ input, toolInput, root, runner, budget, boundaries,
2048
2065
  }
2049
2066
 
2050
2067
  for (const target of pushes) {
2051
- const push = readPush(target.pushArgv);
2068
+ const push = readPush(target.argv);
2052
2069
  const dir = target.dir;
2053
2070
 
2054
2071
  if (push.unreadable.length > 0) {
@@ -331,6 +331,14 @@ export function splitSegments(command) {
331
331
  // what every consumer sees for a reason unrelated to splitting.
332
332
  current += ch;
333
333
  } else if (SEPARATORS.includes(ch)) {
334
+ // A redirection's file descriptor (`2>/dev/null`, `2>&1`, `0<in`) is a
335
+ // whole word of digits directly in front of `<` or `>`, and the shell
336
+ // never passes it to the command. Left in place it was the LAST WORD of
337
+ // the segment: `git push origin :gone 2>/dev/null` read `2` as a
338
+ // refspec, so the deletion was scanned as a wide push, and `git push
339
+ // 2>&1` read `2` as the remote. Only a whole word is a descriptor, which
340
+ // is the shell's own rule: `v2>x` passes `v2` and redirects stdout.
341
+ if (ch === '<' || ch === '>') current = current.replace(/(^|\s)\d+$/, '$1');
334
342
  out.push(current);
335
343
  current = '';
336
344
  } else {
@@ -353,6 +361,244 @@ export function tokensOf(segment) {
353
361
  .filter((w) => w !== '');
354
362
  }
355
363
 
364
+ /**
365
+ * Words of one segment as the SHELL splits them, for the subcommand slot.
366
+ *
367
+ * `tokensOf` splits on whitespace and only then drops quote characters, so
368
+ * `git -c user.name="Jacek Janczura" commit` read `Janczura` as the verb and
369
+ * `GIT_AUTHOR_NAME='Jacek Janczura' git commit` read `Janczura` as the
370
+ * program. Measured with two real findings staged: both, and the single-quoted
371
+ * `-c` spelling, PASSED UNSCANNED while `-c user.name=JJ` was refused. A
372
+ * quoted value with a space is how every agent sets a commit identity.
373
+ *
374
+ * So this reading honours single quotes, double quotes (with the backslash
375
+ * escapes the shell allows there), `$'...'` and unquoted backslashes. It is an
376
+ * ADDITIONAL reading, never a replacement: `planCommand` keeps `tokensOf` and
377
+ * asks both, so a spelling either one recognises is scanned. That is the
378
+ * direction this gate wants to be wrong in, and it is why the measured reason
379
+ * `splitSegments` stays quote-blind (see SEPARATORS) still holds.
380
+ *
381
+ * Nothing is expanded: `$VAR`, globs and `~` stay literal and still fail
382
+ * `isLiteralPath`. A quote still open at the end of the segment, which is what
383
+ * a quote-blind split through a quoted value looks like, simply ends the last
384
+ * word; `quotedSeparatorHidesVerb` is what reads that shape.
385
+ */
386
+ export function shellWords(segment) {
387
+ const text = String(segment);
388
+ const words = [];
389
+ let word = '';
390
+ let inWord = false;
391
+ let quote = null;
392
+ const open = (kind) => {
393
+ quote = kind;
394
+ };
395
+ for (let k = 0; k < text.length; k++) {
396
+ const ch = text[k];
397
+ if (quote === "'") {
398
+ if (ch === "'") quote = null;
399
+ else word += ch;
400
+ } else if (quote === "$'") {
401
+ if (ch === '\\' && k + 1 < text.length) word += text[++k];
402
+ else if (ch === "'") quote = null;
403
+ else word += ch;
404
+ } else if (quote === '"') {
405
+ if (ch === '\\' && k + 1 < text.length && '$`"\\\n'.includes(text[k + 1])) word += text[++k];
406
+ else if (ch === '"') quote = null;
407
+ else word += ch;
408
+ } else if (/\s/.test(ch)) {
409
+ if (inWord) words.push(word);
410
+ word = '';
411
+ inWord = false;
412
+ } else {
413
+ inWord = true;
414
+ if (ch === '\\') {
415
+ if (k + 1 < text.length) word += text[++k];
416
+ } else if (ch === "'" || ch === '"') {
417
+ open(ch);
418
+ } else if (ch === '$' && (text[k + 1] === "'" || text[k + 1] === '"')) {
419
+ open(text[k + 1] === "'" ? "$'" : '"');
420
+ k++;
421
+ } else {
422
+ word += ch;
423
+ }
424
+ }
425
+ }
426
+ if (inWord) words.push(word);
427
+ return { words };
428
+ }
429
+
430
+ /** `NAME=value` in the program slot: an assignment for the command after it. */
431
+ const ASSIGNMENT_RE = /^[A-Za-z_][A-Za-z0-9_]*=/;
432
+
433
+ /**
434
+ * Where the git program sits in a `shellWords` reading, and the environment
435
+ * assigned in front of it.
436
+ *
437
+ * Assignments and transparent prefixes are peeled in a LOOP, because each may
438
+ * follow the other: `env X=1 git commit` was a bypass with no quote at all,
439
+ * since the old reading peeled assignments once, then prefixes once, and read
440
+ * `X=1` as the program and `git` as the verb. A prefix's own options are
441
+ * peeled with it; `env -S STRING` splits STRING into the command it runs.
442
+ *
443
+ * When the program slot still is not git, the FIRST git word of the segment is
444
+ * taken instead. `timeout 60 git commit`, `sudo -u u git commit` and any
445
+ * wrapper this list does not know all run git, and the cost of being wrong the
446
+ * other way (`echo git commit`, unquoted) is a scan, not a pass.
447
+ */
448
+ export function gitInvocation(words) {
449
+ const all = [...words];
450
+ const env = {};
451
+ let k = 0;
452
+ for (;;) {
453
+ if (k < all.length && ASSIGNMENT_RE.test(all[k])) {
454
+ const at = all[k].indexOf('=');
455
+ env[all[k].slice(0, at)] = all[k].slice(at + 1);
456
+ k++;
457
+ continue;
458
+ }
459
+ if (k < all.length && TRANSPARENT_PREFIXES.has(basename(all[k]))) {
460
+ const prefix = basename(all[k]);
461
+ k++;
462
+ while (k < all.length && all[k].startsWith('-')) {
463
+ const flag = all[k];
464
+ k++;
465
+ if (flag === '--') break;
466
+ if (prefix !== 'env') continue;
467
+ let split = null;
468
+ if (flag === '-S' || flag === '--split-string') split = all[k++] ?? '';
469
+ else if (flag.startsWith('--split-string=')) split = flag.slice('--split-string='.length);
470
+ else if (flag.startsWith('-S')) split = flag.slice(2);
471
+ if (split !== null) all.splice(k, 0, ...shellWords(split).words);
472
+ }
473
+ continue;
474
+ }
475
+ break;
476
+ }
477
+ const index = k < all.length && isGitProgram(all[k]) ? k : all.findIndex((w, i) => i >= k && isGitProgram(w));
478
+ if (index === -1) return null;
479
+ return { index, words: all, tokens: all.slice(index), env };
480
+ }
481
+
482
+ /** The git verbs whose arguments decide what this gate scans. */
483
+ const PUBLISHING_VERBS = Object.freeze(['commit', 'push', 'add']);
484
+
485
+ /**
486
+ * True when a command separator sits inside a quoted value IN FRONT OF the
487
+ * verb of a `git commit`, `git push` or `git add`, within one command as the
488
+ * shell runs it.
489
+ *
490
+ * That is the shape `splitSegments`, which is quote-blind on purpose, cannot
491
+ * read: it cuts the command inside the value, and the pieces land in
492
+ * different segments. Three spellings defeated a check made one segment at a
493
+ * time, each measured to pass a staged key unscanned:
494
+ *
495
+ * - `GIT_AUTHOR_NAME="A; B" git commit`: the quote hiding `git` opened in
496
+ * the previous segment;
497
+ * - `GIT_AUTHOR_NAME="A; cd /tmp" git commit`: the second segment starts
498
+ * with `cd`, which the walk handles and skips;
499
+ * - `GIT_AUTHOR_NAME="A; git -C <decoy> commit" git commit`: a commit IS
500
+ * found, in a decoy repository, and stood in for the real one.
501
+ *
502
+ * So this is decided by POSITION, in one linear pass over the whole line: the
503
+ * line is split where the shell splits it, and a segment is marked when a
504
+ * separator inside a quote comes at or before the verb's word. A separator in
505
+ * a commit MESSAGE comes after the verb (`git commit -m "fix; x"`) and does
506
+ * not mark it. A command substitution, `"$(...)"` or backticks, is parsed by
507
+ * the shell as commands, and `splitSegments` already reads those as segments
508
+ * of their own, so a separator inside one is not counted.
509
+ */
510
+ export function quotedSeparatorHidesVerb(command) {
511
+ const text = stripHeredocBodies(command).replace(/\\\r?\n/g, ' ');
512
+ const modes = [];
513
+ let words = [];
514
+ let word = '';
515
+ let inWord = false;
516
+ let sepWord = -1;
517
+ let hidden = false;
518
+ const endWord = () => {
519
+ if (inWord) words.push(word);
520
+ word = '';
521
+ inWord = false;
522
+ };
523
+ const endSegment = () => {
524
+ endWord();
525
+ if (sepWord !== -1 && !hidden) {
526
+ const inv = gitInvocation(words);
527
+ const op = inv === null ? null : gitOperation(inv.tokens);
528
+ if (op !== null && PUBLISHING_VERBS.includes(op.name) && inv.index + op.index >= sepWord) hidden = true;
529
+ }
530
+ words = [];
531
+ sepWord = -1;
532
+ };
533
+ const literal = (ch) => {
534
+ const inSubstitution = modes.includes('$(') || modes.includes('`');
535
+ if (!inSubstitution && SEPARATORS.includes(ch) && sepWord === -1) sepWord = words.length;
536
+ word += ch;
537
+ };
538
+ for (let k = 0; k < text.length; k++) {
539
+ const ch = text[k];
540
+ const mode = modes[modes.length - 1];
541
+ if (mode === "'") {
542
+ if (ch === "'") modes.pop();
543
+ else literal(ch);
544
+ continue;
545
+ }
546
+ if (mode === "$'") {
547
+ if (ch === '\\' && k + 1 < text.length) word += text[++k];
548
+ else if (ch === "'") modes.pop();
549
+ else literal(ch);
550
+ continue;
551
+ }
552
+ if (mode === '"') {
553
+ if (ch === '\\' && k + 1 < text.length && '$`"\\\n'.includes(text[k + 1])) word += text[++k];
554
+ else if (ch === '"') modes.pop();
555
+ else if (ch === '$' && text[k + 1] === '(') {
556
+ modes.push('$(');
557
+ word += '$(';
558
+ k++;
559
+ } else if (ch === '`') {
560
+ modes.push('`');
561
+ word += ch;
562
+ } else literal(ch);
563
+ continue;
564
+ }
565
+ // Unquoted, or inside a command substitution, which parses like unquoted.
566
+ if (ch === '\\') {
567
+ inWord = true;
568
+ if (k + 1 < text.length) word += text[++k];
569
+ } else if ((mode === '$(' && ch === ')') || (mode === '`' && ch === '`')) {
570
+ modes.pop();
571
+ word += ch;
572
+ } else if (ch === "'" || ch === '"') {
573
+ modes.push(ch);
574
+ inWord = true;
575
+ } else if (ch === '$' && (text[k + 1] === "'" || text[k + 1] === '(')) {
576
+ modes.push(text[k + 1] === "'" ? "$'" : '$(');
577
+ if (text[k + 1] === '(') word += '$(';
578
+ inWord = true;
579
+ k++;
580
+ } else if (ch === '`') {
581
+ modes.push('`');
582
+ inWord = true;
583
+ word += ch;
584
+ } else if (mode !== undefined) {
585
+ // Inside a substitution: its words and separators belong to the inner
586
+ // command, which `splitSegments` reads as segments of its own.
587
+ inWord = true;
588
+ word += ch;
589
+ } else if (/\s/.test(ch)) {
590
+ endWord();
591
+ } else if (SEPARATORS.includes(ch)) {
592
+ endSegment();
593
+ } else {
594
+ inWord = true;
595
+ word += ch;
596
+ }
597
+ }
598
+ endSegment();
599
+ return hidden;
600
+ }
601
+
356
602
  export function isGitProgram(token) {
357
603
  const base = basename(token).toLowerCase();
358
604
  return base === 'git' || base === 'git.exe';
@@ -556,6 +802,14 @@ const UNMODELLABLE_REMEDY =
556
802
  'a shell. Write the path literally, run the command from that directory, or split it into ' +
557
803
  'separate tool calls so each one is unambiguous.';
558
804
 
805
+ /**
806
+ * `--force-with-lease=<ref>:<full object name>`. Group 1 is the flag and ref,
807
+ * group 2 the expected value. A ref cannot contain `:`, so the split is exact;
808
+ * only the FULL 40 (sha-1) or 64 (sha-256) lowercase hex is taken, because an
809
+ * abbreviation is not worth a second rule and stays scanned.
810
+ */
811
+ const LEASE_EXPECT = /^(--force-with-lease=[^:\s]+:)([0-9a-f]{40}|[0-9a-f]{64})$/;
812
+
559
813
  function flagValue(token) {
560
814
  for (const flag of ['--git-dir=', '--work-tree=']) {
561
815
  if (token.startsWith(flag)) return token.slice(flag.length);
@@ -577,6 +831,8 @@ export function planCommand(command, startDir) {
577
831
  const triggers = [];
578
832
  const unmodellable = [];
579
833
  const extraFiles = [];
834
+ /** `--force-with-lease=<ref>:<object name>` spellings, with the repo they target. */
835
+ const leaseExpects = [];
580
836
  /** dir -> what has to be scanned there */
581
837
  const targets = new Map();
582
838
 
@@ -597,6 +853,8 @@ export function planCommand(command, startDir) {
597
853
  const stack = [];
598
854
  /** Set when a git alias makes some subcommand of this line unreadable. */
599
855
  let aliased = false;
856
+ /** Set when a separator inside a quoted value hides which subcommand runs. */
857
+ let unreadableVerb = false;
600
858
  /** Set once a `git add` is seen: a later commit in the line will include it. */
601
859
  let pendingAdd = null;
602
860
 
@@ -680,23 +938,23 @@ export function planCommand(command, startDir) {
680
938
 
681
939
  // ---- which repository this segment would touch --------------------------
682
940
  const hasGit = raw.some(isGitProgram);
683
- let dir = cur;
684
- if (hasGit) {
941
+ const repoDir = (dashC, flagWords, gitDir, workTree) => {
942
+ let at = cur;
685
943
  // `-C` may repeat, each relative to the previous one (git's own rule).
686
- for (let k = 0; k < tokens.length; k++) {
687
- if (tokens[k] !== '-C') continue;
688
- const arg = tokens[k + 1];
944
+ for (let k = 0; k < dashC.length; k++) {
945
+ if (dashC[k] !== '-C') continue;
946
+ const arg = dashC[k + 1];
689
947
  if (arg === undefined || !isLiteralPath(arg)) {
690
948
  unmodellable.push({ what: '`git -C` names a directory that needs shell expansion' });
691
949
  } else {
692
- dir = resolvePath(dir, arg);
950
+ at = resolvePath(at, arg);
693
951
  }
694
952
  }
695
- const named = [envWorkTree, envGitDir, ...raw.map(flagValue)].filter((v) => v !== null && v !== undefined);
953
+ const named = [workTree, gitDir, ...flagWords.map(flagValue)].filter((v) => v !== null && v !== undefined);
696
954
  // Resolved against the directory this segment runs in, NOT against each
697
955
  // other: `--git-dir=r/.git --work-tree=r` names ONE repository twice,
698
956
  // and folding the second onto the first produced `r/r`.
699
- const base = dir;
957
+ const base = at;
700
958
  for (const value of named) {
701
959
  if (!isLiteralPath(value)) {
702
960
  unmodellable.push({ what: 'a `--git-dir`/`--work-tree` value needs shell expansion' });
@@ -706,9 +964,11 @@ export function planCommand(command, startDir) {
706
964
  // `--git-dir=repo/.git` names the repository through its metadata
707
965
  // directory. Review used exactly this spelling to walk past a rule
708
966
  // that only understood `-C`.
709
- dir = basename(abs) === '.git' ? dirname(abs) : abs;
967
+ at = basename(abs) === '.git' ? dirname(abs) : abs;
710
968
  }
711
- }
969
+ return at;
970
+ };
971
+ const dir = hasGit ? repoDir(tokens, raw, envGitDir, envWorkTree) : cur;
712
972
 
713
973
  // Asked of the SUBCOMMAND SLOT, never of the token bag.
714
974
  //
@@ -729,15 +989,50 @@ export function planCommand(command, startDir) {
729
989
  // `git remote add` and `git worktree add` had the same shape against
730
990
  // `gitAdd` — and `worktree add` is the command rule 7 tells every parallel
731
991
  // agent to run.
732
- const op = hasGit ? gitOperation(tokens) : null;
733
- const gitCommit = op !== null && op.name === 'commit';
992
+ //
993
+ // Two READINGS of the slot are asked, and a verb either one finds counts.
994
+ // `tokensOf` (whitespace, quotes dropped) is the one every rule below was
995
+ // measured on, and a verb it recognises is handled exactly as before.
996
+ // `shellWords` (quotes honoured) is what the shell actually runs, and it
997
+ // is the one that sees `git -c user.name="A B" commit`: see `shellWords`
998
+ // for the measured bypass. Each reading carries its OWN tokens and
999
+ // directory, because after a quoted value the old tokens are misaligned:
1000
+ // `git -C "a b" commit` would scan `a`.
1001
+ const parsed = shellWords(segment);
1002
+ const quoted = gitInvocation(parsed.words);
1003
+ const quotedOp = quoted === null ? null : gitOperation(quoted.tokens);
1004
+ const readings = [{ op: hasGit ? gitOperation(tokens) : null, tokens, dir: () => dir }];
1005
+ if (quotedOp !== null) {
1006
+ readings.push({
1007
+ op: quotedOp,
1008
+ tokens: quoted.tokens,
1009
+ dir: () => {
1010
+ // A wrapper that changes directory before git runs (`env -C`,
1011
+ // `sudo -D`) is not modelled; the old reading never saw it either.
1012
+ const before = quoted.words.slice(0, quoted.index);
1013
+ if (before.some((w) => w === '-C' || w === '-D' || w === '--chdir' || w.startsWith('--chdir='))) {
1014
+ unmodellable.push({ what: 'a wrapper changes directory before `git` runs' });
1015
+ }
1016
+ return repoDir(quoted.tokens, quoted.tokens, quoted.env.GIT_DIR ?? null, quoted.env.GIT_WORK_TREE ?? null);
1017
+ },
1018
+ });
1019
+ }
1020
+ const reading = (verb) => {
1021
+ const found = readings.find((r) => r.op !== null && r.op.name === verb);
1022
+ return found === undefined ? null : { op: found.op, tokens: found.tokens, dir: found.dir() };
1023
+ };
1024
+ const commitAt = reading('commit');
734
1025
  // NOT narrower than the token bag where it counts: `git subtree push`
735
1026
  // publishes for real and its verb is the second word, so the resolver
736
1027
  // returns that word rather than stopping at `subtree`. Dropping it would
737
1028
  // have traded one false positive for a false NEGATIVE on a real push,
738
1029
  // which is the wrong direction for this gate.
739
- const gitPush = op !== null && op.name === 'push';
740
- const gitAdd = op !== null && op.name === 'add';
1030
+ const pushAt = reading('push');
1031
+ const addAt = reading('add');
1032
+ const gitCommit = commitAt !== null;
1033
+ const gitPush = pushAt !== null;
1034
+ const gitAdd = addAt !== null;
1035
+
741
1036
  const hasGh = raw.some(isGhProgram);
742
1037
  const ghPublishes =
743
1038
  hasGh &&
@@ -745,7 +1040,7 @@ export function planCommand(command, startDir) {
745
1040
  (words.has('pr') || words.has('repo') || words.has('release') || words.has('gist'));
746
1041
 
747
1042
  if (gitAdd) {
748
- const after = tokens.slice(op.index + 1);
1043
+ const after = addAt.tokens.slice(addAt.op.index + 1);
749
1044
  const all = after.some((t) => t === '-A' || t === '--all' || t === '.' || t === '-u');
750
1045
  const named = [];
751
1046
  let widen = false;
@@ -764,12 +1059,13 @@ export function planCommand(command, startDir) {
764
1059
  }
765
1060
  // Naming files one by one is the commonest form an agent uses, and it
766
1061
  // was the form round 2 left open: only `-A`/`.` folded anything in.
767
- pendingAdd = { dir, all: all || widen, paths: named };
1062
+ pendingAdd = { dir: addAt.dir, all: all || widen, paths: named };
768
1063
  }
769
1064
 
770
1065
  if (gitCommit) {
771
- const commitAll = tokens.some((t) => t === '--all' || (isShortCluster(t) && t.includes('a')));
772
- note(dir, {
1066
+ const commitAll = commitAt.tokens.some((t) => t === '--all' || (isShortCluster(t) && t.includes('a')));
1067
+ const sameRepo = pendingAdd !== null && pendingAdd.dir === commitAt.dir;
1068
+ note(commitAt.dir, {
773
1069
  scanCommit: true,
774
1070
  // `git commit -a` stages tracked modifications as it runs, and
775
1071
  // `git add X && git commit` stages them in an earlier segment of the
@@ -777,9 +1073,9 @@ export function planCommand(command, startDir) {
777
1073
  // gate runs is NOT what the commit will contain, so the working tree
778
1074
  // is folded in. Round 1 declared this a limitation; closing it is
779
1075
  // cheaper than describing it.
780
- includeWorktree: commitAll || (pendingAdd !== null && pendingAdd.dir === dir),
781
- includeUntracked: pendingAdd !== null && pendingAdd.dir === dir && pendingAdd.all,
782
- includePaths: pendingAdd !== null && pendingAdd.dir === dir ? pendingAdd.paths : [],
1076
+ includeWorktree: commitAll || sameRepo,
1077
+ includeUntracked: sameRepo && pendingAdd.all,
1078
+ includePaths: sameRepo ? pendingAdd.paths : [],
783
1079
  });
784
1080
  triggers.push('a git commit (everything the commit would add is scanned)');
785
1081
  }
@@ -789,8 +1085,8 @@ export function planCommand(command, startDir) {
789
1085
  // lives on a private `upstream` be published to a public `origin`
790
1086
  // without ever being scanned. Review raised it as a hypothesis; it
791
1087
  // reproduced on the first attempt.
792
- const after = tokens
793
- .slice(op.index + 1)
1088
+ const after = pushAt.tokens
1089
+ .slice(pushAt.op.index + 1)
794
1090
  .filter((t) => !t.startsWith('-'))
795
1091
  .map((t) => (t.startsWith('+') ? t.slice(1) : t));
796
1092
  const remote = after[0] ?? null;
@@ -816,7 +1112,7 @@ export function planCommand(command, startDir) {
816
1112
  // would have been the third spelling of one rule in this repository
817
1113
  // (ADR-21), and the one that decides whether a push reaches production is
818
1114
  // not the place to start diverging.
819
- const pushArgv = tokens.slice(op.index + 1);
1115
+ const pushArgv = pushAt.tokens.slice(pushAt.op.index + 1);
820
1116
  const deletesOnly = readable && isDeletionOnly(pushArgv, after.slice(1));
821
1117
  // One line can push the same repository more than once. The scan is the
822
1118
  // UNION of what every segment publishes: letting the last segment's refs
@@ -824,25 +1120,58 @@ export function planCommand(command, startDir) {
824
1120
  // main` publish `leaky` unscanned, and a deletion, which adds nothing,
825
1121
  // must not replace a real push either. `pushRefs: []` is the wide range
826
1122
  // and stays wide.
827
- const prior = targets.get(dir);
1123
+ const prior = targets.get(pushAt.dir);
828
1124
  const priorPush = prior !== undefined && prior.scanPush === true ? prior : null;
1125
+ //
1126
+ // The REMOTES are unioned too, for the same reason. Which commits are
1127
+ // already public is a question about one remote (see `pushRange`), and
1128
+ // keeping only the last one let `git push upstream leaky && git push
1129
+ // origin leaky` scan `leaky --not --remotes=origin`: empty, because
1130
+ // `leaky` was on origin already, while upstream had never seen it.
1131
+ // `buildPayload` lists the range once per remote and scans the union.
829
1132
  let scan;
830
1133
  if (deletesOnly) {
831
- scan = priorPush !== null ? {} : { pushRemote: remote, pushRefs: [], pushDeletesOnly: true };
1134
+ scan =
1135
+ priorPush !== null ? {} : { pushRemote: remote, pushRemotes: [remote], pushRefs: [], pushDeletesOnly: true };
832
1136
  } else if (priorPush === null || priorPush.pushDeletesOnly === true) {
833
- scan = { pushRemote: remote, pushRefs: refs, pushDeletesOnly: false };
1137
+ scan = { pushRemote: remote, pushRemotes: [remote], pushRefs: refs, pushDeletesOnly: false };
834
1138
  } else {
835
1139
  // A prior `gh` publish can leave `pushRefs` unset, which is wide too.
836
1140
  const priorRefs = priorPush.pushRefs ?? [];
837
1141
  const wide = priorRefs.length === 0 || refs.length === 0;
838
- scan = { pushRemote: remote, pushRefs: wide ? [] : [...new Set([...priorRefs, ...refs])] };
1142
+ // A prior `gh pr create` names no remote (null). Beside a push that
1143
+ // names one it is not a second remote: counted as one, a repository
1144
+ // with two remotes refused `gh pr create && git push origin x`, which
1145
+ // `pushRange` cannot answer for an unnamed remote.
1146
+ const remotes = [...new Set([...(priorPush.pushRemotes ?? [priorPush.pushRemote]), remote])];
1147
+ const named = remotes.filter((r) => r !== null);
1148
+ scan = {
1149
+ pushRemote: remote,
1150
+ pushRemotes: named.length > 0 ? named : remotes,
1151
+ pushRefs: wide ? [] : [...new Set([...priorRefs, ...refs])],
1152
+ };
839
1153
  }
840
- note(dir, { scanPush: true, ...scan, pushArgv, pushReadable: readable });
1154
+ // Every push's argv, in order, deletions included. The policy gate
1155
+ // judges each one: keeping only the last let `git push origin HEAD:main
1156
+ // && git push origin feature/x` reach `main` under P1 while the gate
1157
+ // read `feature/x`. `pushArgv` is the last of them, for readers that
1158
+ // only ever see one push.
1159
+ const pushArgvs = [...(prior?.pushArgvs ?? []), pushArgv];
1160
+ note(pushAt.dir, { scanPush: true, ...scan, pushArgv, pushArgvs, pushReadable: readable });
841
1161
  triggers.push(
842
1162
  deletesOnly
843
1163
  ? 'a git push that only deletes remote refs (it publishes no objects; the command line is scanned)'
844
1164
  : 'a git push (every commit not already on the target remote is scanned)',
845
1165
  );
1166
+ // The expected value of an explicit lease is a git object name, which
1167
+ // gitleaks reads as a high-entropy `generic-api-key` whenever the ref in
1168
+ // front of it carries a keyword (`secret`, `token`, `api`...). Recorded
1169
+ // here, with the directory THIS segment targets, so `decide` can check it
1170
+ // against that repository before it hides anything from the scan.
1171
+ for (const t of pushArgv) {
1172
+ const lease = LEASE_EXPECT.exec(t);
1173
+ if (lease !== null) leaseExpects.push({ dir: pushAt.dir, spelled: t, sha: lease[2] });
1174
+ }
846
1175
  }
847
1176
  if (ghPublishes) {
848
1177
  // `gh pr create` publishes ONE branch — the PR's head — and adds no git
@@ -997,7 +1326,7 @@ export function planCommand(command, startDir) {
997
1326
  remedy: 'run the command without -c core.hooksPath=... (a bare `git config core.hooksPath` query is fine)',
998
1327
  });
999
1328
  }
1000
- if (gitCommit && tokens.some((t) => isShortCluster(t) && t.includes('n'))) {
1329
+ if (gitCommit && commitAt.tokens.some((t) => isShortCluster(t) && t.includes('n'))) {
1001
1330
  denials.push({
1002
1331
  code: DENIAL_CODES.NO_VERIFY,
1003
1332
  detail: "`-n` on git commit is --no-verify, which disables git's own hooks",
@@ -1005,7 +1334,7 @@ export function planCommand(command, startDir) {
1005
1334
  });
1006
1335
  }
1007
1336
  if (gitPush) {
1008
- for (const token of tokens) {
1337
+ for (const token of pushAt.tokens) {
1009
1338
  const forced =
1010
1339
  token.startsWith('--force') ||
1011
1340
  (isShortCluster(token) && token.includes('f')) ||
@@ -1049,16 +1378,31 @@ export function planCommand(command, startDir) {
1049
1378
  }
1050
1379
  }
1051
1380
 
1381
+ // FAIL CLOSED where a separator inside a quoted value hides the verb.
1382
+ // `splitSegments` is quote-blind on purpose, so `git -c user.name="A; B"
1383
+ // commit` arrives as `git -c user.name="A` (git, no verb) and ` B" commit`
1384
+ // (verb, no git), and no reading of either segment sees a commit. Asked of
1385
+ // the whole line, once, so no `continue` in the walk above can skip it.
1386
+ if (quotedSeparatorHidesVerb(command)) {
1387
+ unreadableVerb = true;
1388
+ unmodellable.push({
1389
+ what: 'a quoted value in front of the `git` subcommand holds a command separator, so which subcommand runs cannot be read',
1390
+ });
1391
+ }
1392
+
1052
1393
  // `aliased` counts as "something might be published here": without it the
1053
1394
  // unmodellable entry above is discarded by the filter below, which is
1054
- // exactly how the hole stayed open.
1055
- const needsScan = targets.size > 0 || extraFiles.length > 0 || aliased;
1395
+ // exactly how the hole stayed open. `unreadableVerb` is the same hole,
1396
+ // opened by a quoted separator instead of an alias.
1397
+ const needsScan = targets.size > 0 || extraFiles.length > 0 || aliased || unreadableVerb;
1056
1398
  return {
1057
1399
  aliased,
1400
+ unreadableVerb,
1058
1401
  denials,
1059
1402
  triggers: [...new Set(triggers)],
1060
1403
  targets: [...targets.values()],
1061
1404
  extraFiles,
1405
+ leaseExpects,
1062
1406
  // An unmodellable construct only matters if something is being published.
1063
1407
  // `cd "$D" && npm test` has no scan to misdirect.
1064
1408
  unmodellable: needsScan ? unmodellable : [],
@@ -1573,17 +1917,25 @@ export async function buildPayload(target, extraFiles, { runner, budget }) {
1573
1917
  // so there is no range to list. Its command line is still scanned by
1574
1918
  // `decide`, like every other command this gate sees.
1575
1919
  if (target !== null && target.scanPush && target.pushDeletesOnly !== true) {
1576
- const range = await pushRange(target.dir, target.pushRemote, target.pushRefs, {
1577
- runner, timeoutMs: budget(GIT_BUDGET_MS),
1578
- });
1579
- const listed = await git(['-C', target.dir, 'rev-list', '--objects', ...range], {
1580
- runner, timeoutMs: budget(GIT_BUDGET_MS), what: 'listing the objects this push would publish',
1581
- });
1920
+ // One range per remote the line pushes to (see `planCommand`): what is
1921
+ // already public on one remote is not on another. `addBlobs` reads each
1922
+ // object once, so the union costs nothing for what the ranges share.
1923
+ const remotes = Array.isArray(target.pushRemotes) && target.pushRemotes.length > 0
1924
+ ? target.pushRemotes
1925
+ : [target.pushRemote];
1582
1926
  const objects = [];
1583
- for (const line of String(listed).split('\n')) {
1584
- const space = line.indexOf(' ');
1585
- if (space === -1) continue; // a commit, which carries no path
1586
- objects.push({ sha: line.slice(0, space), path: line.slice(space + 1) });
1927
+ for (const remote of remotes) {
1928
+ const range = await pushRange(target.dir, remote, target.pushRefs, {
1929
+ runner, timeoutMs: budget(GIT_BUDGET_MS),
1930
+ });
1931
+ const listed = await git(['-C', target.dir, 'rev-list', '--objects', ...range], {
1932
+ runner, timeoutMs: budget(GIT_BUDGET_MS), what: 'listing the objects this push would publish',
1933
+ });
1934
+ for (const line of String(listed).split('\n')) {
1935
+ const space = line.indexOf(' ');
1936
+ if (space === -1) continue; // a commit, which carries no path
1937
+ objects.push({ sha: line.slice(0, space), path: line.slice(space + 1) });
1938
+ }
1587
1939
  }
1588
1940
  await addBlobs(target.dir, objects, add, { runner, budget });
1589
1941
  }
@@ -1907,6 +2259,40 @@ export function renderFindings(findings, map) {
1907
2259
 
1908
2260
  // ----------------------------------------------------------------- the gate
1909
2261
 
2262
+ /**
2263
+ * The command text with the expected value of an explicit lease hidden from
2264
+ * the scanner, and nothing else changed.
2265
+ *
2266
+ * `git push --force-with-lease=pv3/api-fix:<40 hex> origin ...` was refused as
2267
+ * `generic-api-key`: the ref carries a keyword and the object name's entropy is
2268
+ * above the rule's floor (measured, 1908 of 2000 recent shas). The value is
2269
+ * hidden ONLY when it names an object that exists in the repository the
2270
+ * segment targets: a hash cannot be chosen to carry a payload, while a 40-hex
2271
+ * that is no object is exactly what a pasted key looks like and stays scanned.
2272
+ * Same length, all zeros, so offsets and the byte count do not move. Any
2273
+ * failure to ask (no budget, git missing, timeout, not a repo) leaves the text
2274
+ * as it was: the question is only ever allowed to NARROW a refusal on proof.
2275
+ */
2276
+ async function maskLeaseExpects(command, leaseExpects, { runner, budget }) {
2277
+ let text = command;
2278
+ for (const { dir, spelled, sha } of leaseExpects) {
2279
+ const timeoutMs = budget(GIT_BUDGET_MS);
2280
+ if (timeoutMs <= 0) break;
2281
+ try {
2282
+ // `--no-lazy-fetch`: in a partial clone, asking about a missing object
2283
+ // makes git FETCH it from the promisor remote, sending the very value
2284
+ // under suspicion off the machine (measured: `want <hex>` on the wire).
2285
+ // A git too old to know the flag exits 129, which leaves the text scanned.
2286
+ const r = await runner('git', ['--no-lazy-fetch', '-C', dir, 'cat-file', '-e', `${sha}^{object}`], { timeoutMs });
2287
+ if (r.spawned !== true || r.timedOut === true || r.code !== 0) continue;
2288
+ } catch {
2289
+ continue;
2290
+ }
2291
+ text = text.split(spelled).join(spelled.slice(0, spelled.length - sha.length) + '0'.repeat(sha.length));
2292
+ }
2293
+ return text;
2294
+ }
2295
+
1910
2296
  export async function decide({ input, cwd, runner = runChild, startedAt = Date.now() } = {}) {
1911
2297
  const budget = makeBudget(startedAt);
1912
2298
  const toolName = field(input, 'tool_name');
@@ -2020,7 +2406,10 @@ export async function decide({ input, cwd, runner = runChild, startedAt = Date.n
2020
2406
 
2021
2407
  // The command line itself, through the same rule set. `git commit -m
2022
2408
  // "<key>"` puts a secret in history without it ever being a staged file.
2023
- const commandBytes = Buffer.from(command, 'utf8');
2409
+ const commandBytes = Buffer.from(
2410
+ await maskLeaseExpects(command, plan.leaseExpects, { runner, budget }),
2411
+ 'utf8',
2412
+ );
2024
2413
  const commandFindings = await scanBytes(commandBytes, { runner, budget, workDir });
2025
2414
  for (const f of commandFindings) findings.push({ ...f, line: null, inCommand: true });
2026
2415
  scanned.push('the command line itself');
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@jjanczur/tyran",
3
- "version": "0.1.51",
3
+ "version": "0.1.52",
4
4
  "description": "Command-line scripts for the Tyran task conductor (doctor, journal, schema, and repo tooling) for CI and terminals outside Claude Code. Installing this package does NOT install the Claude Code plugin — add that separately with `/plugin marketplace add jjanczur/tyran` inside Claude Code.",
5
5
  "type": "module",
6
6
  "engines": {