@staix/agent-hub 0.30.0 → 0.31.0

package/docs/verification/2026-11-05-hardcoded-values-classification-rules.md

@@ -0,0 +1,257 @@
+# Hard-coded values inventory: how a key is classified (#1180, task #738)
+
+Date: 2026-11-05. Refs #1180. `scripts/inventory-hardcoded-values.classifications.json` is plain JSON that the generator parses as a map from key to class, so it has no place for a header: this file is that header. It was written **before** any key of the baseline was labelled, from two sources only: the K01 to K18 reasons of [the closure](2026-10-30-operational-settings-closure.md) and the finding of [the ratchet record](2026-11-05-hardcoded-values-ratchet.md) that a reader who knew only the closure agreed with the committed file on 58% of a sample. It is not fitted to the sample that checks it.
+
+A key names one literal in one function (`file:function:kind:name=value#n`). Ask the questions in order and stop at the first that answers. The class says **why the value is a constant**, not how important it is.
+
+1. **Test seam.** The literal is the fallback of an injection point that exists for tests, and the code or its name says so: a `/** Test seam ... */` option, a `*ForTest` helper, a port a test replaces, or an environment variable that only a test, a gate or a benchmark sets (`AHUB_CHECK_HANG_S`, `AHUB_*_MS` knobs read with `${VAR:-N}` or `process.env.X ?? N`). A default parameter (`ms = 90000`, `limit = 20`) or a bare `opts.x ?? N` is **not** a test seam: see rule 5.
+2. **Contract.** The value is part of a representation, a wire or storage shape, or an accepted API: a protocol or schema number, a format or identifier width, a unit conversion (`1000`, `86400000`, `60`), an index or position in a stored or parsed structure, a bound that is part of a control message's or a tool's documented shape, `?? 0` or `Math.max(x, 1)` that gives the meaning of an absent or zero stored value, and a default that is **exported or published**: the default of a configuration key (`DEFAULT_CONFIG`, a `*_SETTING.defaultValue`), a tool schema's `minimum` or `maximum`, a declared model context size. A default that only lives in the function that reads it is not published: it is operational (rule 5). Changing a contract changes what stored or exchanged data means.
+3. **Safety floor.** The value bounds what comes from outside the hub's own control, or what could exhaust it: a cap on a path, name, id, command, request, model or foreign-hub text, a truncation of such text before it is shown or stored, a limit on a parser, a proof or a diagnostic read, a native-session ownership record limit. Changing it changes what untrusted input the hub accepts or shows.
+4. **Operational.** Everything else that tunes how the hub behaves without changing what its data means or what it accepts: timeouts, deadlines, polling and batching intervals, retry and backoff numbers, retention and window lengths, TTLs, hub-internal caps on its own queues, caches and lists, display and page sizes, benchmark and smoke-script deadlines and sizes, the numbers inside a backoff expression.
+5. **The three confusable cases, which the first reader got wrong** (the committed file treats each as operational unless rule 1 to 3 applies on its own):
+   - a **hub-internal cap** on the hub's own lists, queues, caches or batches (`slice(0, 50)` of the hub's own rows, a queue cap) is operational, not a safety floor. A cap on text that came from a peer, a model or another project is a safety floor.
+   - an **injected default** (`opts.x ?? N`, `config.x ?? N`, `input.x ?? N`) and a **default parameter** (`function f(ms = 90000)`, `list(limit = 20)`) are operational: the injection point or the parameter makes the value tunable, it does not make it a seam. They are a test seam only under rule 1 (an environment knob or a documented test seam), and a contract only under rule 2 (exported or published).
+   - a **script or smoke deadline** (`scripts/`, `AbortSignal.timeout(N)`, a benchmark's window or size) is operational.
+
+A key that none of these decides is **not labelled**: it stays in the baseline and is reported for a ruling. The rules are the reason a label is written, so a label that needs a new rule adds that rule here first.
+
+## How a batch is checked
+
+Before a batch is written, a fresh blind sample of 80 already-decided keys is drawn at random with a recorded seed, each is labelled from the code with only these rules (the committed label is not shown), and the labels are compared with the file. The batch is written only at 85% agreement or more, and the figure and the disagreements go in the batch's PR. A sample that fails the bar sends the disagreement back to these rules before any key is labelled.
+
+## What a batch labels, and what it leaves in the baseline
+
+A batch labels only shapes where the committed file is consistent with these rules: module constants, timers, deadlines and `Math.min`/`Math.max` clamps, injected defaults, script and benchmark values, and bounds and truncations in `src/adapters`, `src/models`, `scripts/` and `src/local`. The baseline keeps every length bound and every truncation (`.slice`, `.substring`) in `src/hub`, `src/cli`, `src/ui`, `src/rooms` and `src/broker`: the file labels those inconsistently (in `src/hub`, 91 safety floor, 61 contract and 63 operational for length bounds), so no reading of the code can reach the bar there, and their convention is a separate decision by the conductor (the working rule: a bound on text, ids or input from a peer, model or another project is a safety floor; a wire-shape limit on our own protocol is a contract; the hub's own list caps are operational). The sample that checks a batch is drawn only from the same population.
+
+## Calibration record
+
+| Round | Seed | Population | Reader | Agreement | Result |
+| --- | --- | --- | --- | ---: | --- |
+| 1 | 738001 | every decided key | blind reader, these rules | 62 of 80 (77.5%) | below the 85% bar: 18 misses, 12 of them in length bounds, truncations and defaults; the rules were corrected for default parameters and environment knobs and the population narrowed |
+| 2 | 738002 | decided keys outside the `src/hub`, `src/cli`, `src/ui`, `src/rooms`, `src/broker` length bounds and truncations | blind reader, corrected rules | 56 of 80 (70.0%) | below the bar: 24 misses (below) |
+| 3 | 738005 | the 303 decided keys the mechanical rules below cover | the mechanical rules | 78 of 80 (97.5%) | passes, **in-sample**: the rules were written after reading the file's labels |
+
+Round 2 misses, by cause (the starting evidence for #739): 10 literals read as a contract that the file calls operational (a `= 0` reduce start, a `?? 2048` max-tokens default, config-shaped `*_s = 90` defaults, a `timeout_s > 86_400` bound, `hops = 2`, `id = 0`, `start = 0`); 7 read as operational that the file calls a safety floor (200-character error and output truncations, `Math.min(8000, ...)` timeout clamps); 4 read as operational that the file calls a test seam (default parameters such as `timeoutMs = 2000`, `idleTimeoutMs = 600_000`, `opts.pollMs ?? 2000`); 2 read as a safety floor that the file calls operational (`MAX_FILES = 4096`, `totalBytes = 512 MiB`); 1 read as operational that the file calls a contract. The file itself is internally consistent only 78 to 88% on these shapes (default-parameter timeouts 78%, `Math.min(<ms>, ...)` 87%, constants named `MAX_*` 50%), and for `src/hub` length bounds and truncations it is 42% and 48%, so no reading of the code reaches 85% on them.
+
+## The mechanical rules of the first batch (#738)
+
+A key is labelled by a rule only when the rule is a pure function of its name, kind, value and file, and the committed file agrees with that rule on at least 94% of the keys it already decides. The rules, with how the file agrees with each over every decided key (the whole file, not the sample):
+
+| Rule | Label | Decided keys it covers | File agrees |
+| --- | --- | ---: | ---: |
+| R1 a `constant` named `*_MS`, except unit conversions (`DAY_MS`, `MIN_MS`, ...), `*DATE_MAX_MS`, `*WINDOW_MS` and the security exclusion R1x below | operational | 51 | 94% |
+| R1x a `*_MS` constant that bounds replay, revocation or rate: the window in which a replayable request is still accepted, how long a revoked or rotated credential stays valid, or the floor on how often an agent turn may be triggered | safety floor | 0 | none |
+| R2 an inline literal that is the argument of `setTimeout`, `setInterval`, `Bun.sleep`, `sleep`, `AbortSignal.timeout` or `this.backOff` | operational | 134 | 98% |
+| R3 an inline default named `*_s`, `*_min` or `*_ms` (a config-shaped value) | operational | 37 | 100% |
+| R5 a `0` or `1` that starts a reduce, loop or counter (`start`, `id`, `count`, `sum`, `i`, `*.reduce`) | operational | 8 | 100% |
+| R6 a `.slice` or `.substring` of error, output or message text in `scripts/benchmarks/` | safety floor | 28 | 96% |
+
+R1x is the conductor's ruling on the review of PR #1212, not a calibrated rule: the committed file had no decided key of that kind (its decided `*GRACE_MS` keys are process-kill grace periods and `RATE_LIMIT_MS` throttles a log line, all operational), so its agreement is not measured. It labels four baseline keys: `tool-request.ts` `MAX_FUTURE_MS` (the replay window of request ids), `broker/store.ts` and `rooms/store.ts` `GRACE_MS` (how long a rotated epoch's frames stay accepted, which bounds how long a revoked member's key still works) and `schedules.ts` `MIN_EVERY_MS` (the floor that stops a schedule triggering an agent turn more often than every 15 minutes, a spend guard).
+
+R4 (a `maxTokens` or `contextWindow` default, 97%) and R7 (a length bound in `src/adapters`, `src/models`, `src/local`, 91%) agree with the file, but no baseline key was labelled by R4, and R7's five baseline keys have no exact agreeing precedent, so they stay in the baseline. Taken together the rules agree with 303 of the 311 decided keys they cover (97.4%) and with 97% and 98% on the two halves of a by-file hold-out (files split by a hash of their path), which is the same data seen differently, not an independent reader.
+
+Not labelled, on purpose: every length bound and truncation in `src/hub`, `src/cli`, `src/ui`, `src/rooms` and `src/broker`; `Math.min`/`Math.max` clamps of a timeout; default-parameter timeouts (`timeoutMs = 2000`); `MAX_*` and `*_BYTES` constants; unit conversions. #739 settles their convention first and then relabels the inconsistent existing entries by name.
+
+## The `src/hub` convention for bounds and truncations (#739)
+
+Ruled by the conductor on 2026-11-05. It decides bounds (`x.length > N`, `Object.keys(x).length > N`, a byte limit) and truncations (`.slice(0, N)`, `.substring`) in `src/hub`. Ask in order:
+
+1. A validation bound on an argument of a **documented tool or control message** is a **contract**, whether or not `hub-tools.ts` repeats the number: it is part of that message's shape.
+2. A bound or truncation on **free text, ids or raw input that no message shape defines** (a peer's body, a model's output, another project's or GitHub's text, a person's input) is a **safety floor**.
+3. A cap on **the hub's own lists, batches or reports**, which the hub trims, pages or reports as truncated, is **operational**.
+4. A bound on the **shape of a documented file format the person writes** (config, profile, role, extension, text projection) is a **contract**, like a documented message.
+
+Truncations (`.slice`, `.substring`) are decided by what is cut:
+
+5. A **shortened id, hash or commit** (`commit.slice(0, 12)`, `sha256.slice(0, 16)`, a log timestamp used as an evidence id) is a **contract**: a displayed identity format that other tools and people match on.
+6. The **hub's own list** cut to N (`pending.slice(0, 64)`, `history.slice(-5)`) is **operational**, and so is a **display cap on the hub's own report** (`pool.walk.length > 16`, `paths.length > 20`, a held-rows cap).
+7. **Text cut for a log line, notice or reply** is a **safety floor** only when the cut text **originates outside the hub process**: a model, a peer, a person, another project, a native hook process, or a subprocess, network, git or file-parse error that can carry external content. The hub's own composed message, or its own internal error text logged locally, is **operational**. Ask where the text comes from, not where it goes.
+
+A number is never evidence by itself. Many unrelated schema entries share `32`, `64`, `256` or `4096`, so "the same number appears in `hub-tools.ts`" decides nothing: the first measurement of #739 counted 280 of 378 `src/hub` bounds as mirrors of a schema by number, and only a handful really repeat a tool schema's limit once the call sites are read.
+
+### What the committed file did before this change (measured on `8e44babc`)
+
+| Shape | Decided keys | operational | safety floor | contract |
+| --- | ---: | ---: | ---: | ---: |
+| `src/hub` length bounds | 213 | 63 | 91 | 59 |
+| `src/hub` truncations (`.slice`) | 151 | 73 | 47 | 31 |
+
+Among the 213, those that refuse or validate input (171) were 77 safety floor, 53 contract and 41 operational, and the file labelled the same kind of check differently by file: `tasks.ts` 19 of 20 contract, `sdlc.ts` 14 of 22 safety floor, `test-integrity.ts` 6 of 6 safety floor. Across the whole decided file 214 expressions appear in more than one place and 28 of them carried conflicting labels (133 keys), mostly default-parameter timeouts and `Math.min`/`Math.max` clamps, which this change does not touch.
+
+### Existing labels changed by this convention (44, by key, old to new)
+
+All 173 decided `src/hub` validation bounds (outside `hub-tools.ts`) were read at their call sites. 44 contradicted the convention and are changed; every other decided bound already agrees with it and was left alone, including `deferred-hub.ts` `env.body.length > 1_000_000` and `delivery-hints.ts` `row.id.length > 256` (a peer's raw body and a hub-built hint, no message shape: safety floor). Group membership is a reading of each call site, reviewed by the conductor.
+
+#### A. Argument of a documented tool or control message: to contract (19)
+
+Reason: Each is an argument of a documented tool or control message (`taskOpBody`, `uiAction`, `recoveryOp`, `onMessage`, the check runner's `files`, the planning `deps` list). The bound is part of that message's shape, whether or not `hub-tools.ts` repeats the number.
+
+| Key | Old | New |
+| --- | --- | --- |
+| `check-runner.ts` `request.files.length > 32=32` (in `start`) | operational | contract |
+| `daemon.ts` `a.files.length > 32=32` (in `taskOpBody`) | safety floor | contract |
+| `daemon.ts` `a.delivery_id.length > 256=256` (in `taskOpBody`) | safety floor | contract |
+| `daemon.ts` `a.delivery_id.length > 256=256` (in `taskOpBody`) | safety floor | contract |
+| `daemon.ts` `a.reason.length > 2000=2000` (in `taskOpBody`) | safety floor | contract |
+| `daemon.ts` `a.superseded_by.length > 2000=2000` (in `taskOpBody`) | safety floor | contract |
+| `daemon.ts` `a.release.length > 100=100` (in `taskOpBody`) | safety floor | contract |
+| `daemon.ts` `liveIssues.length > 32=32` (in `uiAction`) | operational | contract |
+| `daemon.ts` `a.to.length > 32=32` (in `uiAction`) | operational | contract |
+| `daemon.ts` `msg.operationId.length > 128=128` (in `recoveryOp`) | operational | contract |
+| `daemon.ts` `msg.launchId.length <= 128=128` (in `onMessage`) | operational | contract |
+| `daemon.ts` `msg.launchId.length <= 128=128` (in `onMessage`) | operational | contract |
+| `daemon.ts` `msg.launchId.length <= 128=128` (in `onMessage`) | operational | contract |
+| `daemon.ts` `msg.reason.length > 2000=2000` (in `onMessage`) | operational | contract |
+| `daemon.ts` `msg.id.length > 256=256` (in `onMessage`) | operational | contract |
+| `daemon.ts` `msg.reason.length > 2000=2000` (in `onMessage`) | operational | contract |
+| `daemon.ts` `(msg.liveIssues ?? []).length > 32=32` (in `onMessage`) | operational | contract |
+| `daemon.ts` `(msg.liveIssues ?? []).length > 32=32` (in `onMessage`) | operational | contract |
+| `planning.ts` `value.length > 64=64` (in `planningPatch`) | operational | contract |
+
+#### B. Text or replies from GitHub, another project or a person: to safety floor (6)
+
+Reason: Each bounds text or a reply that comes from GitHub, another project or a person, which no tool or control message defines, so it limits untrusted input.
+
+| Key | Old | New |
+| --- | --- | --- |
+| `dogfood-read.ts` `r.pull_requests.length <= 100=100` (in `validRun`) | operational | safety floor |
+| `github-import.ts` `row.title.length>300=300` (in `<anonymous>`) | operational | safety floor |
+| `github-import.ts` `row.body.length>8000=8000` (in `<anonymous>`) | operational | safety floor |
+| `sdlc-queue.ts` `p.baseRefName.length > 200=200` (in `<anonymous>`) | operational | safety floor |
+| `sdlc-queue.ts` `threads.nodes.length > 100=100` (in `finalSnapshot`) | operational | safety floor |
+| `sdlc-queue.ts` `checks.nodes.length > 100=100` (in `finalSnapshot`) | operational | safety floor |
+
+#### C. The hub's own derived list: to operational (1)
+
+Reason: A cap on the hub's own derived list, which the hub builds itself and reports as truncated, so it tunes a list size and is not an input bound.
+
+| Key | Old | New |
+| --- | --- | --- |
+| `task-code-symbols.ts` `brief.reviewable.length > 500=500` (in `buildTaskCodeSymbols`) | safety floor | operational |
+
+#### D. Shape of a documented file the person writes: to contract (18)
+
+Reason: Each is the bound on the shape of a documented file format the person writes (config, profile, role, extension or text projection), which is a contract like a documented message (the conductor's wording of the convention).
+
+| Key | Old | New |
+| --- | --- | --- |
+| `github-import.ts` `value.length<=100=100` (in `selectionText`) | operational | contract |
+| `path-policy.ts` `raw.length > 64=64` (in `policyPaths`) | safety floor | contract |
+| `config-tier.ts` `part.length > 64=64` (in `<anonymous>`) | safety floor | contract |
+| `text-projection.ts` `Object.keys(raw).length > 16=16` (in `projectionConfig`) | safety floor | contract |
+| `text-projection.ts` `argv.length > 16=16` (in `projectionConfig`) | safety floor | contract |
+| `text-projection.ts` `arg.length > 2000=2000` (in `<anonymous>`) | safety floor | contract |
+| `profiles.ts` `Object.keys(data.classes).length > 32=32` (in `resolveProfile`) | safety floor | contract |
+| `profiles.ts` `Object.keys(data.role_text).length > 8=8` (in `resolveProfile`) | operational | contract |
+| `profiles.ts` `data.example_checks.length > 16=16` (in `resolveProfile`) | operational | contract |
+| `profiles.ts` `data.review_checklist.length > 16=16` (in `resolveProfile`) | safety floor | contract |
+| `profiles.ts` `value.length > 500=500` (in `<anonymous>`) | operational | contract |
+| `planning.ts` `Object.keys(input).length > 64=64` (in `planningWipLimits`) | operational | contract |
+| `roles.ts` `sanitize(body).length > 2000=2000` (in `parseRole`) | safety floor | contract |
+| `roles.ts` `files.length > 64=64` (in `loadRoleCatalog`) | safety floor | contract |
+| `roles.ts` `Object.keys(raw).length > 64=64` (in `catalogAssignments`) | safety floor | contract |
+| `roles.ts` `ids.length > 2=2` (in `catalogAssignments`) | safety floor | contract |
+| `roles.ts` `roles.length > 2=2` (in `catalogSection`) | safety floor | contract |
+| `roles.ts` `text.length > 2000=2000` (in `taskRoleText`) | safety floor | contract |
+
+
+### Additional relabels (47, by key, old to new)
+
+A second round, after the first sample showed the convention did not decide truncations. Each change was asserted against its old label when applied; nothing else changed. The 17 truncations that fit no line (for example `action-class.ts` `text.slice(i, i + 256)`, `permission-payload.ts` `full.slice` 600, `envelope.ts` `noteLine`) keep their labels.
+
+#### Shortened id, hash or commit: to contract (6)
+
+| Key | Old | New |
+| --- | --- | --- |
+| `ask.ts` `l.slice=10` (in `id`) | operational | contract |
+| `daemon.ts` `publicStatus.generation.slice=8` (in `generation`) | operational | contract |
+| `deliverables.ts` `createHash(sha256).update(${format}\0${path}).digest(hex).slice=12` (in `deliverableId`) | operational | contract |
+| `registry.ts` `createHash(sha256).update(root).digest(hex).slice=24` (in `idFor`) | operational | contract |
+| `research.ts` `createHash(sha256).update(projectId).digest(hex).slice=16` (in `projectKey`) | operational | contract |
+| `task-code-group.ts` `r.head.slice=8` (in `head`) | operational | contract |
+
+#### The hub's own list cut to N: to operational (10)
+
+| Key | Old | New |
+| --- | --- | --- |
+| `activity.ts` `u.locations.slice=12` (in `updateActivity`) | safety floor | operational |
+| `tasks.ts` `(Array.isArray(v) ? v : typeof v === string ? [v] : []).map(text).filter((p): p is string => !!p).slice=50` (in `textList`) | safety floor | operational |
+| `tasks.ts` `holders.slice=8` (in `detail`) | safety floor | operational |
+| `tasks.ts` `history.slice=-5` (in `publicHistory`) | safety floor | operational |
+| `tasks.ts` `[...this.incomingBacklog].sort((a, b) => a - b).slice=64` (in `incoming`) | contract | operational |
+| `tasks.ts` `[...pending].sort((a, b) => a - b).slice=64` (in `ids`) | contract | operational |
+| `tasks.ts` `pool.walk.slice=16` (in `walk`) | safety floor | operational |
+| `tasks.ts` `paths.slice=20` (in `list`) | safety floor | operational |
+| `tasks.ts` `[...new Set([taskNode, ...symbols.nodes, ...about])].slice=64` (in `saveNative`) | safety floor | operational |
+| `text-projection.ts` `(process.env.PATH ?? /usr/bin:/bin).split(:).slice=32` (in `choices`) | safety floor | operational |
+
+#### Text cut for a log line, notice or reply: to safety floor (origin test noted per entry) (21)
+
+| Key | Old | New | Origin of the cut text |
+| --- | --- | --- | --- |
+| `ask.ts` `raw.slice=2000` (in `answer`) | operational | safety floor | model output |
+| `conflicts.ts` `String(r.title).slice=100` (in `<anonymous>`) | operational | safety floor | another agent's task title |
+| `daemon.ts` `sanitize(row.key).slice=160` (in `retainedConfigAfterReload`) | operational | safety floor | a rejected config key the person wrote |
+| `daemon.ts` `sanitize(row.reason).slice=1200` (in `retainedConfigAfterReload`) | operational | safety floor | a rejected config reason built from the person's config value |
+| `daemon.ts` `${v.title ? ${v.title}: : }${v.text}.replace(/\s+/g, ).slice=160` (in `memoryLine`) | operational | safety floor | memory text written by peers and the model |
+| `daemon.ts` `${v.title ?? }\n${v.text}.slice=1500` (in `note`) | operational | safety floor | memory note text written by peers and the model |
+| `daemon.ts` `${c.title ?? }\n${c.text}.slice=600` (in `note`) | operational | safety floor | memory note text written by peers and the model |
+| `daemon.ts` `JSON.stringify(v).slice=60` (in `peerArg`) | operational | safety floor | the caller's tool argument echoed in a refusal |
+| `daemon.ts` `sanitize(e.reason ?? delivery retries exhausted).replace(/\s+/g, ).slice=300` (in `reason`) | operational | safety floor | a delivery retry reason, which can carry a native adapter's error text |
+| `daemon.ts` `e.env.body.slice=200` (in `<anonymous>`) | operational | safety floor | a peer's message body logged |
+| `daemon.ts` `v.text.slice=600` (in `text`) | operational | safety floor | memory text written by peers and the model |
+| `daemon.ts` `msg.tool.slice=64` (in `tool`) | operational | safety floor | a native hook process's tool name |
+| `daemon.ts` `msg.toolUseId.slice=128` (in `toolUseId`) | operational | safety floor | a native hook process's tool use id |
+| `daemon.ts` `msg.sessionId.slice=128` (in `sessionId`) | operational | safety floor | a native hook process's session id |
+| `daemon.ts` `String(msg.question).slice=80` (in `title`) | operational | safety floor | a person's question to ahub ask |
+| `daemon.ts` `String(msg.question).slice=300` (in `text`) | operational | safety floor | a person's question to ahub ask |
+| `deliverables.ts` `extra[0]!.slice=32` (in `own`) | operational | safety floor | an unknown field name from the caller's deliverable |
+| `packs.ts` `(error as Error).message.slice=200` (in `reason`) | operational | safety floor | a project role-pack file's parse error, which echoes the file's content |
+| `progress.ts` `tool.slice=80` (in `name`) | operational | safety floor | a native hook process's tool name |
+| `progress.ts` `item.name.slice=80` (in `name`) | operational | safety floor | a progress item sent by a peer |
+| `progress.ts` `item.source.slice=40` (in `source`) | operational | safety floor | a progress item sent by a peer |
+
+#### Display caps on the hub's own report: to operational (5)
+
+| Key | Old | New |
+| --- | --- | --- |
+| `tasks.ts` `pool.walk.length > 16=16` (in `walk`) | safety floor | operational |
+| `tasks.ts` `paths.length > 20=20` (in `list`) | safety floor | operational |
+| `tasks.ts` `result.length < 32=32` (in `outsideIds`) | safety floor | operational |
+| `daemon.ts` `guarded.length > 200=200` (in `prepareConfiguration`) | safety floor | operational |
+| `delivery-hints.ts` `result.rows.length >= 32=32` (in `heldDeliveryHints`) | safety floor | operational |
+
+#### Bounds on the shape of the person's config (`config-reload.ts`): to contract (5)
+
+| Key | Old | New |
+| --- | --- | --- |
+| `config-reload.ts` `Object.keys(v).length > 256=256` (in `table`) | operational | contract |
+| `config-reload.ts` `v.length > 4096=4096` (in `text`) | operational | contract |
+| `config-reload.ts` `v.length > 128=128` (in `peers`) | safety floor | contract |
+| `config-reload.ts` `v.length > 16_384=16_384` (in `openValue`) | operational | contract |
+| `config-reload.ts` `v.length > 1024=1024` (in `openValue`) | safety floor | contract |
+
+#### Three omissions found by the second sample: to contract (3)
+
+The first list of argument bounds missed three that the convention (line 1) already covers; found when the blind reader labelled them contract.
+
+| Key | Old | New | Why |
+| --- | --- | --- | --- |
+| `workflow.ts` `p.criteria.length > 32=32` (in `criteriaReceipt`) | operational | contract | the `criteria` argument of `hub_sdlc_record` (schema `maxItems: 32`) |
+| `workflow.ts` `c.refs.length > 8=8` (in `<anonymous>`) | operational | contract | the `refs` of one criterion of `hub_sdlc_record` (schema `maxItems: 8`) |
+| `claude-launch-proof.ts` `row.launchId.length > 128=128` (in `readClaudeLaunchProof`) | operational | contract | the `launchId` control field, the same bound that `daemon.ts` `onMessage` already labels contract |
+
+### Calibration of the `src/hub` convention (#739)
+
+The population is the 365 decided `src/hub` bounds and truncations (`hub-tools.ts` excluded). Each round is a blind 80-sample read with only the convention, the committed labels hidden.
+
+| Round | Seed | File state | Agreement | Bounds | Truncations |
+| --- | --- | --- | ---: | ---: | ---: |
+| 1 | 739101 | after the first 44 relabels, lines 1 to 4 only | 56 of 80 (70.0%) | 36 of 44 (82%) | 20 of 36 (56%) |
+| 2 | 739202 | after 47 more relabels, lines 1 to 7 | 71 of 80 (88.8%) | 42 of 47 (89%) | 29 of 33 (88%) |
+
+Round 2 clears the 85% bar. It is **in-sample in one respect**: lines 5 to 7 and the 47 relabels were written after round 1's misses, so the sample measures whether the convention now decides what it was extended to decide, not an independent reader. A fresh seed drawn from the relabelled file is the check that matters, and it was drawn only after the relabels were applied.
+
+Round 2's nine misses: three are keys the first list left out (`workflow.ts` criteria 32, criterion refs 8 and `claude-launch-proof.ts` launchId 128, relabelled contract above); `check-runner.ts` `lines.slice(-40)` (a cut of a subprocess's output, which line 7 calls safety floor, labelled by me operational) and `version.stdout.trim().slice(0, 80)` (the converse); `daemon.ts` `schedules pass failed: ...message.slice(0, 160)` and `tasks.ts` `task.title.slice(0, 120)` (a memory title from the task's own title, where whether the origin is outside the hub is a judgement); `execution-budget.ts` `input.id.length > 200` and `delivery-hints.ts` `held.rows.length > 32`. The remaining disagreements are about where text originates, and line 7 is the place to sharpen if a later sample falls short.
+
+No baseline key is labelled in this change. That is #741.

package/docs/verification/2026-11-05-hardcoded-values-ratchet.md

@@ -0,0 +1,55 @@
+# Hard-coded values inventory: why it drifted, and the ratchet that stops it (#1180, task #719)
+
+Date: 2026-11-05. Refs #1180. The issue stays open: its AC1 (zero unknown keys) is not met by this change. This record exists so the follow-up that classifies the rest starts from measurements, not from a guess.
+
+## Cause
+
+Not a generator bug. `scripts/inventory-hardcoded-values.ts` and `scripts/inventory-hardcoded-values.classifications.json` were committed together by #764 on 2026-10-24, and nothing ever ran the generator again: no step of `scripts/check.sh`, no workflow and no test. The file was edited by hand twice (#1099 changed one value, #1167 removed 11 keys), and every other change to `src/` and `scripts/` added constants nobody classified.
+
+Measured by running the generator at past commits:
+
+| Commit | Date | Unknown keys |
+| --- | --- | ---: |
+| `7c1d2065` (#764, the commit that added the inventory) | 2026-10-24 | 22 |
+| `b454e527` | 2026-10-25 | 63 |
+| `438e9b23` | 2026-10-28 | 527 |
+| `9680a4db` | 2026-11-02 | 1065 |
+| `8511d01a` (#1099) | 2026-11-02 | 1087 |
+| main at `4b34fab1` | 2026-11-05 | 1438 |
+
+The 22 at #764's own head are the memory-code files that landed in the same week. The 1282 in the issue and the 1438 here are the same drift counted at two commits. At this commit 3243 inventory entries exist, 1805 were decided, 1438 were unknown and 36 committed keys matched nothing (the code they named had moved or changed).
+
+## What this change does
+
+1. Removes the 36 stale keys.
+2. Classifies 216 unknown keys by precedent in the file itself, and nothing else. A key is adopted only when every already-decided key sharing its parts agrees, taking the tiers in this order and stopping at the first that decides:
+   - same file, kind, name and value (82 keys): leave-one-out accuracy over the committed decisions 99.4%;
+   - same file, kind and name (44 keys): 97.6%;
+   - same kind, name and value, with at least two agreeing precedents (72 keys): 95.7%;
+   - same kind and name, with at least two agreeing precedents (18 keys): 94.1%.
+   The same two weaker tiers with a single precedent measured 92.6% and 89.2%, which is why they need two. The 216 are 109 contract, 81 operational, 23 safety floor and 3 test seam.
+3. Puts the other 1222 unknown keys in `scripts/inventory-hardcoded-values.baseline.json`, the list of known-unclassified keys. They are not classified. `bun scripts/inventory-hardcoded-values.ts --check` fails on any unknown key that is not in that list, on a baseline key that has since been classified, and on a baseline key that matches no entry. The baseline only shrinks. `scripts/check.sh` runs the check with the other once-only steps.
+
+## What this change does not do, and why
+
+It classifies none of the 1222 remaining keys. The attempt was measured first. 190 of them were labelled by reading each literal's source line against the K01-K18 reasons of `2026-10-30-operational-settings-closure.md`, then 80 already-decided entries (seeded random draw, labels hidden) were labelled the same way and compared with the committed file: **47 of 80 agreed (58%)**. The disagreements were systematic, not noise:
+
+| Committed class | I labelled | Count | Typical case |
+| --- | --- | ---: | --- |
+| operational | safety floor | 12 | a hub-internal cap constant (`MAX_STATES = 256`, `tasks.length > 500`, a 1024-entry map) |
+| operational | contract | 7 | a saturating `Math.max(0, ...)`, a `limit < 1` check |
+| operational | test seam | 6 | a smoke script's `deadline`, an injected `opts.x ?? N` default |
+| contract | safety floor | 5 | a short id or text slice bound |
+| safety floor | operational | 2 | a `termMs`/`killMs` in a review-isolation stop |
+
+So the file's operative rule for `operational` is wider than the prose of the K groups: a hub-internal cap, an injected default and a script deadline all count as operational, and the prose does not say so. A rule pass built from the K-group text was 65% accurate on the 1805 decided entries and a text-feature classifier 71%, so neither decides anything. Writing 1222 labels at 58% would be the blind classification the issue forbids.
+
+## How the remaining 1222 get classified
+
+As a separate task, in batches a person can review, under these rules:
+
+- Before the first batch, write the rule for each confusable case into the header of the classifications file or this record: hub-internal caps, injected `opts.x ?? N` defaults, script deadlines, short id and hash slices, saturating zero bounds.
+- Each batch is labelled by those written rules, never by feel.
+- Each batch needs a fresh blind sample of 80 already-decided entries labelled by the same rules, and an agreement of 85% or more with the committed file, before the batch is written.
+- Classifying a key means adding it to the classifications file and removing it from the baseline in the same commit; `--check` refuses the half-done state.
+- Do not regenerate `docs/verification/2026-10-24-hardcoded-values.md`: `test/operational-settings.test.ts` reads it by row.

package/docs/verification/2026-11-06-rooms-presence-cost.md

@@ -0,0 +1,152 @@
+# Rooms presence producer cost
+
+Refs #1204, CI task 742. Historical macOS comparisons and Linux candidate
+measurements and targeted hosted macOS candidate acceptance are recorded below.
+
+## Failed jobs and revision attribution
+
+- [PR 1217 macOS job](https://github.com/STAIxBWLB/agent-hub/actions/runs/42098376188/job/127501666095)
+  checked out `92486ab5c48b4c0281643750590fa6693aaaa7e6` and timed out the
+  unchanged 1,000-flip test at 20,025.68 ms.
+- [PR 1215 macOS job](https://github.com/STAIxBWLB/agent-hub/actions/runs/42074839676/job/127420743582)
+  checked out `dc9e482c659a29fa3f6b4597bc04219f5b5f3fbd` and timed out at
+  20,034.80 ms.
+- The workflow checks out the PR head. Neither failed head contains T2 commit
+  `3185dd4c57e36213a8ca398dd304f3284daa03ed`. Their rooms files, Bus,
+  delivery journal and delivery test are byte-identical to
+  `b7aec7d5621e25e0ea1df1e5b8b7366b92512bfe` in those paths.
+- The requested b7..3185 range has only two intervening commits: handoff T2
+  `b5c2525495b42a986207308af815e530f78c0c61`, then rooms T2. The old
+  producer path reproduces at b7 itself, so the observed failures do not establish
+  T2 as a first bad commit.
+
+## Measured producer paths
+
+The repo-only preload `scripts/diagnose-presence-cost-742.ts` counts fixed
+method names and inclusive wall time, never argument text or ids. The original
+test and its 20-second guard are unchanged.
+
+The natural run is separate from a controlled scheduling probe. In the probe,
+the first hot publication waits for the existing serial seal before calling the
+original producer. No state flag is overwritten. This exercises an idle producer
+instead of relying on a boot-time publication still being in flight.
+
+Pinned Bun 1.4.2, Linux x64, frozen installs on dgx02:
+
+| Runtime and mode | Flip phase | Sequence reservations in phase | Store transactions in phase | Bus persists, whole case |
+| --- | ---: | ---: | ---: | ---: |
+| Pre-fix natural, `0a32d86a` | 2 ms | 0 | 0 | 4 |
+| b7, controlled idle entry | 10,645 ms | 1,000 | 3,173 | 4 |
+| b5c, controlled idle entry | 11,324 ms | 1,000 | 3,161 | 4 |
+| Pre-fix `ab751794`, controlled idle entry | 11,868 ms | 1,000 | 4,145 | 4 |
+| Fixed FIFO candidate `2452b905`, controlled idle entry | 109 ms | 7 | 33 | 4 |
+
+The pre-fix ab751 phase spent 2,401 ms inside sequence reservation and 5,205 ms
+inside Store transactions. These measurements overlap and must not be added.
+Transaction timing includes SQL and durable I/O; this is not a separate fsync
+syscall trace. The Store uses DELETE journaling and synchronous EXTRA. The data
+does not attribute all remaining time to either crypto or the filesystem.
+
+b7 and b5c were separate historical checkouts with the same diagnostic preload.
+0a32/ab751 include only close guards and the diagnostic on top of 3185; their room
+producer was still unchanged. The b7/b5c comparison and named-red checks ran from
+the diagnostic harness at `11e3121f51eff2a9cd60eb95400e568051163072`.
+
+The code defect is cancellation of scheduled coalesced work: ordinary calls
+clear the pending republish before starting another seal. If the producer is
+already busy, calls collapse; if it starts idle, an awaited loop can repeatedly
+reserve durable counters. Task 740's persist fix remains effective: all measured
+cases retain four Bus persists.
+
+## Fix and regressions
+
+- Ordinary calls reuse pending republish; response/forced-request priority stays.
+- Chat observations precede the chat, and the chat slot is reserved synchronously
+  before awaiting the earlier presence. This avoids overtaking by a concurrent
+  chat. Tests check ciphertext and real Store insertion order.
+- Receipt durability, ACK ordering, caps and actual-send exposure/current fences
+  remain covered by unchanged backpressure tests and new focused regressions.
+- Closed public and deferred publication return before touching the journal or
+  observers. Live storage failures still propagate.
+- A failed presence barrier remains an error of its reserved chat, rather than
+  a successful empty send or an unhandled rejection.
+
+## Hosted macOS reference comparison
+
+The [reference job](https://github.com/STAIxBWLB/agent-hub/actions/runs/42106515415/job/127522644864)
+ran on Darwin arm64 with Bun 1.4.2. Each result below is the unchanged test with
+the same diagnostic preload; controlled scheduling is labelled separately.
+
+| Runtime and mode | Whole test | Flip phase | Reservations | Store transaction time in phase |
+| --- | ---: | ---: | ---: | ---: |
+| b7, natural | 17,806.52 ms | 17,110 ms | 1,000 | 1,194 ms |
+| b7, controlled idle entry | 18,798.21 ms | 16,656 ms | 1,000 | 1,438 ms |
+| b5c, natural | 698.92 ms | 4 ms | 0 | 0 ms |
+| b5c, controlled idle entry | 17,084.92 ms | 16,440 ms | 1,000 | 1,065 ms |
+| 3185, natural | 710.99 ms | 2 ms | 0 | 0 ms |
+| 3185, controlled idle entry | 17,604.82 ms | 16,902 ms | 1,000 | 1,139 ms |
+
+The slow producer therefore costs about 16.4-17.1 ms per flip on this runner.
+For 3185, sequence reservation accounts for 511 ms inside the overlapping
+1,139 ms Store transaction time; durable I/O is not the dominant measured time.
+The remaining seal/async producer work was not split into separate CPU/syscall
+traces. All cases retain four Bus persists, confirming the task-740 fix remains.
+
+The range's lower bound is not unconditionally fast: b7 naturally selects the
+slow path in this job. A monotonic good/bad bisect cannot assign the defect to a
+newer commit; exhaustive comparison of the two intervening commits shows the
+pre-existing scheduling path. This is not a claim that the failed jobs merely
+needed their timeout increased.
+
+The job completed all six cases above, then failed because abbreviated reference
+924 was absent from that checkout. That final workflow error does not invalidate
+the completed cases, but supplies no 924 measurement. The follow-up explicitly
+fetches its full SHA and checks the candidate separately.
+
+Controlled red evidence uses unchanged historical source with only the new
+regression file copied into an isolated checkout:
+
+- At 3185, the count test fails its named assertion: expected one reserve,
+  received 1,001.
+- At pre-FIFO-fix 7b99, the concurrent-chat test fails its named assertion with
+  B before A.
+- The existing seed classifier accepted both as assertion failures, not timeouts
+  or runtime diagnostics.
+
+## Hosted macOS candidate acceptance
+
+The [candidate job](https://github.com/STAIxBWLB/agent-hub/actions/runs/42110940560/job/127537997562)
+passed on Darwin arm64, Bun 1.4.2 at
+`e269d5c3be4a81fbd95220d760fb1f104fae3e3f`:
+
+- The unchanged, unprofiled AC1 test passed in 787.72 ms under its original
+  20-second guard.
+- All 19 focused close, coalescing and unchanged backpressure tests passed,
+  with 210 expectations and no failures.
+- Natural candidate profile: whole test 692.06 ms, flip phase 2 ms, no sequence
+  reservations or Store transactions in that phase.
+- Controlled idle-entry candidate profile: whole test 783.51 ms, flip phase
+  114 ms, six reservations and 26 Store transactions in that phase.
+- The explicitly fetched historical 924 head passed naturally in 669.40 ms,
+  but controlled idle entry took 18,277.53 ms (17,679 ms in the flip phase,
+  1,000 reservations, 2,883 Store transactions). Its transaction time was
+  2,082 ms, overlapping the 1,078 ms sequence-reservation time.
+
+This confirms the scheduling-dependent cause and candidate improvement on
+macOS without changing an assertion or timeout. The job is targeted evidence,
+not a full PR gate. Production source is unchanged since 11e312; subsequent
+changes add evidence and remove the temporary diagnostic workflows.
+
+## Evidence limits
+
+- Latest focused source check at 11e312 passed 12 tests, 0 failed, 94 expectations.
+  Earlier 2452 passed 18 focused/backpressure tests and the controlled AC1 case.
+- The first reference run measured b7, b5c and 3185; the successful candidate
+  job additionally measured the full 924 SHA. Neither temporary workflow is
+  retained in the final change.
+- The original failed macOS jobs did not record per-flip counters. Attribution
+  of those exact executions to this reproduced path remains an inference;
+  hosted reference measurements establish the slow path; the separate candidate
+  job supplies targeted macOS acceptance. Linux timing alone is not macOS acceptance.
+- No original test assertion or timeout was changed. No Mac-local gate, live
+  room enrollment, native-account acceptance or release is claimed.

package/docs/verification/claude-shell-wrapper-native.py

@@ -68,7 +68,7 @@ results=[]
 for raw_binary in args.claude:
  binary=pathlib.Path(raw_binary).resolve(); identity=ROOT/('identity-'+binary.name); identity.mkdir()
  version=subprocess.run([str(binary),'--version'],env={'HOME':str(identity),'CLAUDE_CONFIG_DIR':str(identity/'config'),'PATH':'/usr/bin:/bin'},capture_output=True,text=True,timeout=10)
- assert version.returncode==0 and version.stdout.strip().split()[0] in ('2.1.309','2.1.310','2.1.314','2.1.316'),(version.returncode,version.stdout)
+ assert version.returncode==0 and version.stdout.strip().split()[0] in ('2.1.309','2.1.310','2.1.314','2.1.316','2.1.318'),(version.returncode,version.stdout)
  label=version.stdout.strip().split()[0]; digest=sha(binary)
  for mode in ('context','normalized'):
   d=ROOT/(label+'-'+mode); d.mkdir(); home=d/'home';home.mkdir(); work=d/"work 'quoted'";work.mkdir();(work/'sub').mkdir()

package/docs/verified.json

@@ -2,7 +2,7 @@
   "schemaVersion": 1,
   "documents": {
     "README.md": {
-      "verifiedAgainst": "8612cfd740abd013689532d993ebc981548510bb",
+      "verifiedAgainst": "af37f8fd8b44a2c566aa47629ec5b02ee9f91d69",
       "paths": [
         "package.json",
         "src/",
@@ -11,14 +11,14 @@
       ]
     },
     "docs/security.md": {
-      "verifiedAgainst": "8612cfd740abd013689532d993ebc981548510bb",
+      "verifiedAgainst": "af37f8fd8b44a2c566aa47629ec5b02ee9f91d69",
       "paths": [
         "src/",
         "templates/"
       ]
     },
     "docs/operations.md": {
-      "verifiedAgainst": "8612cfd740abd013689532d993ebc981548510bb",
+      "verifiedAgainst": "af37f8fd8b44a2c566aa47629ec5b02ee9f91d69",
       "paths": [
         "package.json",
         "src/",
@@ -35,7 +35,7 @@
       ]
     },
     "docs/quickstart.md": {
-      "verifiedAgainst": "8612cfd740abd013689532d993ebc981548510bb",
+      "verifiedAgainst": "af37f8fd8b44a2c566aa47629ec5b02ee9f91d69",
       "paths": [
         "package.json",
         "src/",
@@ -43,7 +43,7 @@
       ]
     },
     "docs/agent-notes/adapters.md": {
-      "verifiedAgainst": "8612cfd740abd013689532d993ebc981548510bb",
+      "verifiedAgainst": "af37f8fd8b44a2c566aa47629ec5b02ee9f91d69",
       "paths": [
         "src/adapters/",
         "src/pi/",
@@ -81,7 +81,7 @@
       ]
     },
     "docs/agent-notes/benchmarks.md": {
-      "verifiedAgainst": "8612cfd740abd013689532d993ebc981548510bb",
+      "verifiedAgainst": "af37f8fd8b44a2c566aa47629ec5b02ee9f91d69",
       "paths": [
         "scripts/benchmarks/",
         "test/benchmarks/",
@@ -93,7 +93,7 @@
       ]
     },
     "docs/agent-notes/budget.md": {
-      "verifiedAgainst": "8612cfd740abd013689532d993ebc981548510bb",
+      "verifiedAgainst": "af37f8fd8b44a2c566aa47629ec5b02ee9f91d69",
       "paths": [
         "src/hub/budget.ts",
         "src/cli/statusline-tee.ts",
@@ -117,7 +117,7 @@
       ]
     },
     "docs/agent-notes/bus.md": {
-      "verifiedAgainst": "8612cfd740abd013689532d993ebc981548510bb",
+      "verifiedAgainst": "af37f8fd8b44a2c566aa47629ec5b02ee9f91d69",
       "paths": [
         "src/hub/bus.ts",
         "src/hub/envelope.ts",
@@ -132,7 +132,7 @@
       ]
     },
     "docs/agent-notes/daemon.md": {
-      "verifiedAgainst": "8612cfd740abd013689532d993ebc981548510bb",
+      "verifiedAgainst": "af37f8fd8b44a2c566aa47629ec5b02ee9f91d69",
       "paths": [
         "src/hub/daemon.ts",
         "src/hub/control-client.ts",
@@ -223,7 +223,7 @@
       ]
     },
     "docs/agent-notes/local-worker.md": {
-      "verifiedAgainst": "8612cfd740abd013689532d993ebc981548510bb",
+      "verifiedAgainst": "af37f8fd8b44a2c566aa47629ec5b02ee9f91d69",
       "paths": [
         "src/adapters/local-worker.ts",
         "src/local/",
@@ -243,7 +243,7 @@
       ]
     },
     "docs/agent-notes/tasks.md": {
-      "verifiedAgainst": "8612cfd740abd013689532d993ebc981548510bb",
+      "verifiedAgainst": "af37f8fd8b44a2c566aa47629ec5b02ee9f91d69",
       "paths": [
         "src/hub/tasks.ts",
         "src/hub/board.ts",
@@ -291,7 +291,7 @@
       ]
     },
     "docs/agent-notes/tests.md": {
-      "verifiedAgainst": "8612cfd740abd013689532d993ebc981548510bb",
+      "verifiedAgainst": "af37f8fd8b44a2c566aa47629ec5b02ee9f91d69",
       "paths": [
         "test/",
         "scripts/check.sh",
@@ -320,7 +320,7 @@
       ]
     },
     "docs/agent-notes/README.md": {
-      "verifiedAgainst": "8612cfd740abd013689532d993ebc981548510bb",
+      "verifiedAgainst": "af37f8fd8b44a2c566aa47629ec5b02ee9f91d69",
       "paths": [
         "src/cli/console-state.ts",
         "src/cli/attention.ts",
@@ -329,7 +329,7 @@
       ]
     },
     "src/cli/help.ts": {
-      "verifiedAgainst": "8612cfd740abd013689532d993ebc981548510bb",
+      "verifiedAgainst": "af37f8fd8b44a2c566aa47629ec5b02ee9f91d69",
       "paths": [
         "src/cli/main.ts",
         "src/cli/launch.ts",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@staix/agent-hub",
-  "version": "0.30.0",
+  "version": "0.31.0",
   "description": "Native multi-agent hub: Claude Code, Codex, Kimi Code, Pi and local inference as peers in one project",
   "license": "MIT",
   "type": "module",
@@ -17,18 +17,17 @@
     "bun": ">=1.4.2"
   },
   "dependencies": {
-    "@staix/agent-mem": "0.20.1"
+    "@staix/agent-mem": "0.21.0"
   },
   "devDependencies": {
     "@modelcontextprotocol/sdk": "^1.27.1",
+    "@staix/agent-console": "0.1.3",
     "@types/bun": "^1.3.0",
     "typescript": "^5.8.0"
   },
   "files": [
     ".claude-plugin",
     "src",
-    "src/pet/window.jxa.js",
-    "src/pet/window.html",
     "plugins",
     "templates",
     "scripts/check-docs.mjs",