@sjawhar/pi-envoy 13.7.0 → 13.9.0

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.
Files changed (4) hide show
  1. package/README.md +261 -35
  2. package/dist/dispatch.js +722 -41
  3. package/dist/envoy.js +2542 -352
  4. package/package.json +1 -1
package/README.md CHANGED
@@ -84,9 +84,14 @@ items that do not fit are left out, and its last line says how many and that `di
84
84
  prints them all. It is read on every request and waits at most 800 ms for Dispatch. Past that,
85
85
  or when the read fails, the request carries the last list read, with the time it was read and why
86
86
  this read failed, or, when no list read has an item from the last 72 hours, one line saying the
87
- list could not be read and why. A Dispatch without the answers route is not asked again for 5
88
- minutes. The list sits at the tail so that a change in it costs only its own tokens: the cached
89
- conversation before it is sent byte for byte as before.
87
+ list could not be read and why. A Dispatch build older than the answers route answers it with its
88
+ own `404 NOT_FOUND` "no route for …". Against that Dispatch a request carries no such line, since
89
+ `dispatch answers` cannot read it either; a list read before from it is still carried, its
90
+ left-out line naming no command; the log says once per session that the Dispatch has no answers
91
+ route; and that Dispatch is not asked again for 5 minutes. Any other answer, a proxy's 404 page or
92
+ a 200 that is no answers list included, is a failed read. The list sits at the tail so that a
93
+ change in it costs only its own tokens: the cached conversation before it is sent byte for byte as
94
+ before.
90
95
 
91
96
  Oh My Pi also builds requests that are not turns of the conversation from it; those carry the
92
97
  skill but no list, and wait on no read: a side turn (a Dispatch BTW, the stop-time self-check,
@@ -253,9 +258,11 @@ document, not for coordination between roles.
253
258
 
254
259
  ## AskGate
255
260
 
256
- AskGate reviews each Dispatch write of a session's main agent before the write posts. One model
257
- call judges the write against the rules in `extensions/askgate/rules.md` and answers `allow` or
258
- `revise`. A `revise` answer carries the reason and the fix. The gate reviews these calls:
261
+ AskGate reviews each Dispatch write of a session's main agent before the write posts. The charter
262
+ check, one model call, judges the write against the rules in `extensions/askgate/rules.md` and
263
+ answers `allow` or `revise`. A `revise` answer carries the reason and the fix. A call that opens a
264
+ new ask for a person also gets the rules check (below), a second model call beside it. The gate
265
+ reviews these calls:
259
266
 
260
267
  - `dispatch ask`, `dispatch message`, `dispatch edit-ask`, `dispatch comment`, `dispatch doc-edit`
261
268
  and `dispatch request-approval`
@@ -299,7 +306,7 @@ in the next.
299
306
  **The form the gate reads.** One `dispatch` call, alone in the bash call:
300
307
 
301
308
  ```
302
- [cd <literal path> && ] dispatch <subcommand> <literal words…> [2>&1] [<<'DELIM' … DELIM] [| head|tail [-n N]]
309
+ [cd <literal path> && ] dispatch <subcommand> <literal words…> [2>&1] [<<'DELIM' … DELIM] [| head|tail [-n N]] [# --advisor-rebuttal '<line>']
303
310
  ```
304
311
 
305
312
  - The program is `dispatch` by name, or a literal path that ends in it.
@@ -313,8 +320,13 @@ in the next.
313
320
  after the `2>&1`. Its body is on the lines after the line that opens it.
314
321
  - One trailing pipe stage may read its output: `head` or `tail`, alone or with `-n N`, `-nN` or
315
322
  `-N`. The dry run leaves it out.
323
+ - One shell comment may stand where the command's line ends — after its last word and after every
324
+ `2>&1`, here-document opener and `head` or `tail` stage, which is where bash reads one — and
325
+ only when its words are override flags alone (`# --advisor-rebuttal '<line>'`, the form the gate
326
+ hands a rebutted command back in). It is read as those overrides, and no part of what runs:
327
+ `commandArgv` never holds it, so the marker binds the words bash hands the CLI.
316
328
  - Nothing else is in the call: no second command, no other pipe, no `;`, `&&`, `||` or `&`, no
317
- assignment, no other redirect and no comment.
329
+ assignment, no other redirect and no other comment.
318
330
 
319
331
  **Everything else runs, and the `dispatch` command enforces the review.** The gate reads no other
320
332
  form and refuses none: a call outside the literal grammar runs as written. What holds it back is
@@ -360,8 +372,18 @@ gated write only when it consumes one, so a write sent any other way is refused
360
372
  no marker, the gate appends an `AskGate note:` to that result. It names the first cause it found
361
373
  in the call, with the call's own text (an expansion in a value, a double-quoted value over lines
362
374
  with an expansion in it, a program that runs the write such as `xargs` or `timeout`, a pipe, a
363
- second command, an assignment, a redirect), and the change that puts the write in the literal
364
- form. The note is help only: the gate refuses nothing for it.
375
+ second command, an assignment, a redirect, a comment that is no override), and the change that
376
+ puts the write in the literal form. For a comment it says that AskGate reads a `#` only where
377
+ the command's line ends and only when its words are override flags alone. The note is
378
+ help only: the gate refuses nothing for it.
379
+ - **The unmarked write that carries an ask.** The `unmarked` entry reaches only this machine's
380
+ disk. Where such a write carries at least one ask for a person, the CLI counts those asks from
381
+ the write's own text (`newAsks` in `@legion/envoy-client/askgate-new-asks`) and writes the count
382
+ into the session's ledger as `asksCarried`, and pi-envoy publishes one decision record for it on
383
+ Dispatch (below), with the tool, the mode and that count and no ask text. The count is of the
384
+ asks the write carries, so a re-upload of ask blocks the stored version already holds counts
385
+ them as carried: in `warn` mode the write has already posted when the ledger is read, so a read
386
+ of the stored version would see the new text and count nothing.
365
387
 
366
388
  The gated writes are the same list for the gate and the CLI (`gatedWrite` in
367
389
  `@legion/envoy-client/askgate-marker`): the six commands above, an `issue` with a spec and an
@@ -416,12 +438,75 @@ bind: only the loaded gate reads the arm, so a session that chose block through
416
438
  no mode on disk until the gate's first main-agent `bash` or `eval` call, and none at all when the
417
439
  gate does not load — a write outside the literal form there posts with a warning. **An operator
418
440
  who selects block through the arm should also set `OMP_ASKGATE=block` for a hard guarantee**,
419
- which holds from the session's start and through a failed load. Two other refusals follow neither
420
- mode: no model role, and a gate that did not load, which refuses each literal call it would review
421
- in both modes, since neither can review anything.
422
-
423
- **The model.** The gate asks the session's `askgate` model role (`modelRoles.askgate`). When that
424
- role is not set, it asks the `default` role. A model that answers with an error passes the request
441
+ which holds from the session's start and through a failed load. Three refusals follow neither
442
+ mode: a match of the rules check (below), which refuses the write in both modes; no model role;
443
+ and a gate that did not load, the last two refusing each literal call they would review in both
444
+ modes, since neither can review anything.
445
+
446
+ **The rules check.** A call that opens a new ask for the person gets a second model call, beside
447
+ the charter call and on the same chain, deadline and transcript. That call knows two rules
448
+ (`extensions/askgate/rule-check.md`) and judges only the new asks:
449
+
450
+ - No change: the ask's own recommendation is to change nothing, such as to keep things as they
451
+ are, to take no action or to keep the current design.
452
+ - Untried access: the ask asks the person to do a step with their own hands (run a command,
453
+ change a setting, grant access, sign in), or says that only the person can do the step. The
454
+ rule matches only when neither the ask nor the transcript shows that the agent tried the step
455
+ with the access it has or can request. A step that needs the person's security key, a sign-in
456
+ to their own account in a browser, a payment or their own decision does not match. An ask that
457
+ also asks the person to choose between options with different outcomes does not match.
458
+
459
+ A new ask is a `dispatch ask`, an ask block that a `dispatch doc-edit` inserts, a block that it
460
+ retypes into an ask, an ask block in a `dispatch issue` spec, or an ask block in a markdown
461
+ upload whose `#id` the document does not already hold. When that document cannot be read, an
462
+ upload's ask blocks that carry an `#id` are left out — a stored version may hold any of them —
463
+ and only the blocks with no id are judged, so a re-upload of an unchanged document is never
464
+ refused for an ask block it already held.
465
+
466
+ The rules check runs only on a call the gate reads, which is the literal form above. A call in
467
+ any other form reaches no gate at all: the CLI refuses it in `block` mode and posts it with a
468
+ warning in `warn` mode, and the rules check never sees it. Where such a write carries an ask, the
469
+ Dispatch record below counts it.
470
+
471
+ A match refuses the call in `warn` mode and in `block` mode, so no part of the call posts and no
472
+ marker is minted for it. The refusal names the matching asks, each with its rule and the words
473
+ that match. It says what to do instead and how to send the call anyway. The agent sends the call
474
+ anyway in one of three ways:
475
+
476
+ - `--advisor-rebuttal '<line>'` on a `dispatch` command.
477
+ - `"advisor_rebuttal": "<line>"` in a device's JSON.
478
+ - The third attempt at the same thing on the same target: after the gate refuses one thing twice
479
+ on one target, it sends the third call that holds it without review. A thing is each new ask a
480
+ call opens, or the call as a whole when it opens none. A charter refusal counts on every thing
481
+ of the call, and a rules refusal counts on the asks it refused. Only a refusal counts: in `warn`
482
+ mode a charter `revise` sends the call, so it never moves the breaker, while a match of the
483
+ rules check refuses the call in either mode and always does. A call that opens an ask refused
484
+ once, or never, on that target is reviewed like any other, however often the gate refused other
485
+ asks there, and a call that opens no ask counts its own refusals, whatever asks were refused
486
+ there before it. An allow, a rebuttal or the third attempt starts every count on the target
487
+ again.
488
+
489
+ A rebuttal sends the call with no review by either check, and the entry records the line. The
490
+ CLI takes no such flag, so the gate moves it into a shell comment where the command's line ends,
491
+ after everything that runs, where the agent's record of its call still shows it and dispatch never
492
+ sees it; that command sent again is read as the same rebuttal and comes back unchanged. The
493
+ comment stands at the end of the command's line because that is the one place bash reads it as a
494
+ comment at all: every word of it is quoted, which keeps the comment's own quotes paired, but
495
+ nowhere else would that quoting hold — written where a single-quoted value is still open, the
496
+ quotes would pair around the agent's line and leave it outside them. The gate reads the commented
497
+ command back as the same call before it hands it over: an override no
498
+ word of the grammar can carry — a line holding both a `'` and a `$`, or a newline — is removed
499
+ instead, and the acknowledgement says so. A device takes no such field, so the gate removes it
500
+ before the call runs and says so. Either way the acknowledgement
501
+ quotes the override exactly as the agent sent it. A rules call that ends in an error, a timeout or
502
+ an answer that does not parse refuses nothing: the charter check decides. The third such rules
503
+ call in a row writes one warning, saying that the new asks of those three calls went unchecked and
504
+ that the check still runs on each new ask, to the host's plain log, shows it as a notice in a
505
+ session with a UI, and adds it to that call's own result. It is not one of the notices a session
506
+ shows at its start.
507
+
508
+ **The model.** Both checks ask the session's `askgate` model role (`modelRoles.askgate`). When that
509
+ role is not set, they ask the `default` role. A model that answers with an error passes the request
425
510
  to the next model of that role's `retry.fallbackChains` chain, on the same provider. When neither
426
511
  role resolves, the gate refuses the write in both modes and names the two roles. A session whose
427
512
  main model is on another provider than the gate's model is not reviewed: its transcript stays on
@@ -438,8 +523,8 @@ why. The note reaches a headless session too:
438
523
  | `no-verdict` | the model answered with no verdict the gate could read |
439
524
  | `halted` | three calls in a row reached no verdict, and the gate is paused for the session |
440
525
  | `skipped` | the session's main model is on another provider than the gate's |
441
- | `rebuttal` | the agent sent `--advisor-rebuttal <line>`, which is recorded and removed |
442
- | `breaker` | a third attempt on one target after two revise verdicts |
526
+ | `rebuttal` | the agent sent `--advisor-rebuttal <line>`, which is recorded and kept only as a shell comment, or `"advisor_rebuttal"`, which is recorded and removed |
527
+ | `breaker` | the third attempt at one thing on one target, after the gate refused it twice there |
443
528
  | `unreadable` (warn mode) | a file the literal call names was missing or not a regular file when the gate ran |
444
529
  | `abandoned` (warn mode) | the call or the run ended before the review answered |
445
530
  | `shutdown` (warn mode) | the session shut down before the review answered |
@@ -451,11 +536,14 @@ for `unreadable` and `unmarked`), those outcomes refuse the call instead. Only
451
536
  runs the agent's own command as written: a gate that fails breaks no valid write.
452
537
 
453
538
  **The time limit.** `OMP_ASKGATE_TIMEOUT_MS` sets the review's time limit. The default is 90 s. The
454
- gate holds the limit 5 s under `extensionHandlers.toolCallTimeoutMs`, the host's limit for one
455
- `tool_call` handler. That key is 30 s by default, so the limit is then 25 s. A review of a long
456
- session often takes longer than 25 s, and a review that times out lets the write post. Three
457
- timeouts in a row stop the gate for the rest of the session. Set the key to 120000 or more in the
458
- session's settings, for example in `~/.omp/agent/config.yml` or an overlay in `PI_CONFIG_FILES`:
539
+ gate holds the limit 5,000 ms under `extensionHandlers.toolCallTimeoutMs`, the host's limit for
540
+ one `tool_call` handler: the room its handler still needs once the limit passes, for the aborted
541
+ call's usage report and for the entry. The Dispatch record below is no part of it, since it runs
542
+ after the handler has returned. That key is 30 s by
543
+ default, so the limit is then 25,000 ms. A review of a long session can take longer than 25 s,
544
+ and a review that times out lets the write post. Three timeouts in a row stop the gate for the
545
+ rest of the session. Set the key to 120000 or more in the session's settings, for example in
546
+ `~/.omp/agent/config.yml` or an overlay in `PI_CONFIG_FILES`:
459
547
 
460
548
  ```yaml
461
549
  extensionHandlers:
@@ -463,20 +551,158 @@ extensionHandlers:
463
551
  ```
464
552
 
465
553
  When the limit is under 30 s, the gate logs one warning at start that names the key, the host's
466
- limit and the review's limit. It still reviews each write.
467
-
468
- `OMP_ASKGATE_DUMP` names a file that gets each review's two prompts. Every gated call writes one
469
- `advisor-gate` entry into the session's transcript, and `scripts/askgate-report.ts` reports over
470
- those entries: what the gate sent back and what the reviews cost, a count for each outcome, and
471
- every session that had a write the gate did not review, with its counts. The report counts a
472
- write as **sent back** when the gate did not pass it as sent: every entry whose decision is
473
- `revise` — a revise verdict, `no-model-role`, and in block mode `abandoned`, `shutdown` and
474
- `unmarked` — and every `unreadable`, `unmarked` or `load-failed` entry, whatever its mode, counted
475
- over every gated call, since some of them never reach a review; as a **refusal** when the write did
476
- not post (one sent back in block mode, and `no-model-role` and `load-failed`, which refuse in warn
554
+ limit and the review's limit. It still reviews each write. The key must be at least 15,000 ms,
555
+ since the gate does not bind on a limit that leaves under 10 s for a verdict. A session set under
556
+ 15,000 ms gets a gate that does not load, and a gate that did not load refuses every Dispatch
557
+ write it would have reviewed.
558
+
559
+ `OMP_ASKGATE_DUMP` names a file that gets the two prompts of each model call.
560
+
561
+ **The record.** Every gated call writes one `advisor-gate` entry into the session's transcript.
562
+ Every entry whose arguments the gate read carries `target`, the call's target in readable form:
563
+ the tool name, then each of `issue`, `ask`, `artifact`, `project` and `in_reply_to` that the input
564
+ carries, as `dispatch_ask issue=ACME-1`. An `unreadable` entry, and the `unmarked` entry pi-envoy
565
+ writes from the CLI's own ledger line, carry none: neither has the arguments to name one. The
566
+ third attempt (`outcome: "breaker"`) counts the refusals of
567
+ one thing on one such target, and `revisesForKey` counts every `revise` on it, the `warn` ones
568
+ included, since its counts last started again. A call that opens a new ask adds the fields of the
569
+ rules check:
570
+
571
+ - `rule`: `no_change` or `untried_access`, the rule that the first matching ask broke. The gate
572
+ sets it exactly when the rules check refused the call.
573
+ - `ruleAsk`: the number of that ask in the rules request, from 1.
574
+ - `ruleQuote`: the words of that ask that the rules call quoted.
575
+ - `ruleOutcome`: how the rules check ended: `match`, `none`, `error`, `timeout`, `no-verdict`,
576
+ `abandoned`, `shutdown` or `unjudged`. The gate sets it on each gated call that opens a new ask
577
+ and reached the model call. `unjudged` is the one with no model call: an upload whose stored
578
+ version the gate could not read and whose every ask block carries an `#id`, so it judged none
579
+ of the call's asks. The call is not refused for it; the charter check decides alone.
580
+ - `ruleModel`: the `provider/id` that answered the rules call.
581
+ - `ruleLatencyMs`: the time of the rules check, its document read included. `charterLatencyMs` is
582
+ the charter check's own time on the same clock; the two calls run side by side, so each says
583
+ what it cost of the entry's whole `latencyMs`.
584
+ - `ruleTextMissing`: `true` when the gate could not read the text of an ask and judged the ask
585
+ without it. A failed read of an upload's stored version never sets it: no ask of an upload
586
+ loses its own text.
587
+ - `ruleError`: the error text for `error` (the provider's, or the check's own when it fails before
588
+ a model answers), `timeout` for a timeout, and `no-verdict` for an answer that does not parse.
589
+ - `ruleAsksCut`: how many asks the request cut. The request lists every new ask, and aims to keep
590
+ the list within 32 KiB: each ask's text gets an equal share of it, at most 8 KiB, and an ask cut
591
+ to its share keeps its start and its end, where the rules read. The gate never leaves an ask out,
592
+ or cuts one below its start and its end, to stay within that bound: a write of very many ask
593
+ blocks, over a hundred, makes a longer request. An ask's `#id` is cut to 128 bytes.
594
+ - `ruleAsksPartial`: `true` when the call was judged on part of its asks, or on none of them
595
+ (`ruleOutcome: "unjudged"`): the gate could not read the document an upload replaces, so the ask
596
+ blocks carrying an `#id` were left out of the check.
597
+ - `mintSkipped`: `call-ended`, on a call whose decision let the write out and whose own tool ended
598
+ while the gate still held it. No marker was minted, since no command of that call can run.
599
+
600
+ `decision` is `revise` on a rules refusal in `warn` mode too. The gate refused a call exactly when
601
+ `decision` is `revise` and one of these is true: `verdictMode` is `block`, `outcome` is
602
+ `no-model-role` or `load-failed`, or `rule` is set. An `unreadable` or `unmarked` entry is a
603
+ refusal in `block` mode only, where its `decision` is `revise`; in `warn` mode its `decision` is
604
+ `allow`, and the write went out with the note that it was unreviewed. To find the refusals that
605
+ the agent overrode, join each rules refusal to the next entry with the same `target`. The agent
606
+ overrode the refusal when that entry's `outcome` is `rebuttal` or `breaker`.
607
+
608
+ `scripts/askgate-report.ts` reports over those entries: what the gate sent back and what the
609
+ reviews cost, a count for each outcome, every session that had a write the gate did not review,
610
+ with its counts, the markers it skipped, the outcomes and errors of the rules check, and the rules
611
+ refusals that the agent overrode. The report counts a write as **sent back** when the gate did not
612
+ pass it as sent: every entry whose decision is `revise` — a revise verdict, a rules refusal,
613
+ `no-model-role`, and in block mode `abandoned`, `shutdown` and `unmarked` — and every
614
+ `unreadable`, `unmarked` or `load-failed` entry, whatever its mode, counted over every gated call,
615
+ since some of them never reach a review; as a **refusal** when the write did not post (one sent
616
+ back in block mode, and `no-model-role`, `load-failed` and a rules refusal, which refuse in warn
477
617
  mode too); and as **unreviewed** when it posted with no review behind it, which is every `allow`
478
618
  whose outcome is no verdict (the table above, a rebuttal, a breaker trip and warn mode's
479
- `abandoned` and `shutdown` included).
619
+ `unreadable`, `unmarked`, `abandoned` and `shutdown` included).
620
+
621
+ **The Dispatch record.** The entry above reaches only the machine the session ran on. A session
622
+ that counts the rule decisions over a fortnight — a standing session holding a Dispatch token and
623
+ nothing else — reads them from Dispatch instead: every gated call whose rules check ran (every
624
+ entry with a `ruleOutcome`), every call the agent sent anyway (a rebuttal or the breaker, whose
625
+ record has `ruleOutcome: null` and the refusal's own `target`), and every write that reached the
626
+ CLI outside the form the gate reads and carried an ask for a person (`outcome: "unmarked"`, with
627
+ `asksCarried` above zero) are published to a Dispatch project document of the session's own,
628
+ `askgate-decisions-<session id>.md`.
629
+
630
+ - **What it carries.** The time, the session, `id` (the gated call's tool call id, and for an
631
+ unmarked write the CLI ledger line's place in its tool call, so a reader counts one decision
632
+ once), `source` (`pod` for a Legion role's session, which `LEGION_ISSUE` names, and `machine`
633
+ for every other), the project, `tool`, `target`, `rule`, `ruleOutcome`, `ruleError`,
634
+ `ruleTextMissing`, `ruleAsksCut`, `ruleAsksPartial`, `decision`, `outcome`, `verdictMode`,
635
+ `asksCarried`, `ruleLatencyMs`, `charterLatencyMs` and the plugin's version. **No ask text and
636
+ no quote leaves the session**, so nothing a person wrote travels with the counts.
637
+ - **Which project.** `OMP_ASKGATE_RECORD_PROJECT`, else `LEGION_PROJECT` (a Legion pod has no
638
+ envoy.json, so its environment is the only setting it can carry), else no record at all and no
639
+ Dispatch call.
640
+ - **When.** Once the call has been answered: the gate appends the call's `advisor-gate` entry,
641
+ returns, and then hands the record to the session's recorder, so no review is ever cut short to
642
+ pay for it. It never changes the decision. The write runs until Dispatch has answered it or the
643
+ session's shutdown cuts it — the client asks again under the call's own `Idempotency-Key`, and
644
+ nothing retries it from outside — so a Dispatch that is slow under load is waited
645
+ out rather than given up. A record that fails or that the shutdown cuts writes one line to the
646
+ host's log and appends one `advisor-gate-record` entry, carrying `toolCallId`, `tool`,
647
+ `recordError` and, for an unmarked write, the record's own `recordId`; the decision's own entry
648
+ stands as written. Once the session is shutting down, the one `session_shutdown` handler the
649
+ gate binds gives the records 1.25 s from that moment and then cuts them, whether or not the
650
+ gate loaded, and the gate's own handler waits for what is still pending inside the 1.5 s it
651
+ holds shutdown for, so a record still lands, and the entry of one that could not, before the
652
+ session is sealed; a record cut that way says the shutdown cut it. An unmarked write's record is
653
+ started from the `tool_result` the CLI's line reached, after that write's `advisor-gate` entry
654
+ is appended and awaited by nothing of the tool result, which returns while the record is still
655
+ in flight: the records of a session are written one at a time and each has the client's own
656
+ deadline, so a Dispatch that does not answer would otherwise stall every such write. It goes
657
+ through the one recorder the gate's own records use.
658
+ - **One document per session, written once and appended to.** The document's create carries a
659
+ header paragraph and no record; every record, the session's first included, is a fenced JSON
660
+ line appended through `docEdit`. That rule is what keeps a record safe, because an upload of a
661
+ name Dispatch already holds stores a new version of that document and the reader reads the
662
+ latest version alone, so a second upload would erase every record appended since the first. A
663
+ process holding no id for the session — a fresh process serving it, or one whose create was cut
664
+ — reads the document by its name, one request of a few bytes, and appends to that; it creates
665
+ one only where that read answers 404. The create carries an `Idempotency-Key` of the document's
666
+ own, `askgate-doc.` and the sha256 of the project and the name, and a body fixed for the
667
+ session — the header alone, with no record, no time and no plugin version in it — so every
668
+ attempt of it, in this process or another, is one intent Dispatch runs once: it replays a key
669
+ that finished, answers `409 KEY_IN_FLIGHT` while the first run lives, `409 KEY_COMMITTED` where
670
+ that run landed and lost its answer, and `422 KEY_REUSED` for a different body, and the last two
671
+ send the recorder back to the read and then to the append. Each append carries a key of its own,
672
+ the sha256 of the session and the record's id, so an append Dispatch ran late is replayed to its
673
+ next attempt rather than written twice; the same record sent again with another time in its body
674
+ gets `422 KEY_REUSED`, is not written, and is counted as not confirmed. Keys
675
+ belong to the login that sent them, and every Legion pod writes under the shared agent token,
676
+ which is one login for all of them (`requestKeyLogin`,
677
+ `packages/envoy/internal/dispatch/api/request_keys.go`); Dispatch keeps a key 24 h
678
+ (`IdempotencyKeyTTL`), well past the 10 minutes a create's run can hold it
679
+ (`keyedHandlerLimit`). The records of one session are written one at a time, each sent once the
680
+ one before it has settled, and each carries the time the gate made it, which is what the reader
681
+ counts and sorts by: a write given up on this side may still be running on Dispatch's while the
682
+ next is sent, so the order they land in is not the order they were made.
683
+ - **What is lost, and what is counted.** A session killed between a decision and its write loses
684
+ that one record, and a session that never reached a gated call writes no document. A record
685
+ that fails, or that the shutdown cuts, is unconfirmed too — and one given up that way may have
686
+ landed all the same, so a record the session could not confirm can still be in the document,
687
+ where the reader counts it once by its `id` and counts the second copy as a duplicate. What no
688
+ longer happens: a create given up here and committed on Dispatch after later records were
689
+ written cannot replace them, since every create of that document is the one keyed create, and
690
+ two processes writing one session's first record at the same moment make that same one create
691
+ between them. What the
692
+ machine could not get Dispatch to confirm is counted on the machine's own side: `--sessions`
693
+ counts the entries carrying a `recordError` as **decision records not confirmed**, an upper
694
+ bound on what the day's `--dispatch-project` counts cannot hold.
695
+
696
+ `scripts/askgate-report.ts --dispatch-project <KEY> --since <RFC 3339> [--json]` reads those
697
+ documents and prints the day's refusals by rule, the refusals the agent overrode, the calls
698
+ judged on part of their asks and those that judged none, the unmarked writes by mode with the asks
699
+ they carried, and the rules-call error rate, each split by `source`, with the documents and lines
700
+ it could not read, and the records it read twice, counted beside them. An unmarked write is in no
701
+ rules-call count and in no override count: no check judged it. Its `asksCarried` counts every ask
702
+ and ask block the write carries, so a re-upload of blocks a stored version already holds counts
703
+ them as carried. The same script's `--sessions <dir>` mode still reports the entries on disk, the
704
+ decision records not confirmed among them. Each flag is given once: the
705
+ script refuses a flag given twice by name, rather than reading only its last value.
480
706
 
481
707
  **What AskGate is not.** AskGate reviews the writes of a cooperating agent, so that a write that
482
708
  breaks its rules comes back with the reason before it posts. It is no sandbox. A process that