dsh-github-copilot 0.4.0-alpha.99 → 0.4.1

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 (110) hide show
  1. package/AGENTS.md +104 -16
  2. package/CHANGELOG.md +223 -0
  3. package/CONTRIBUTING.md +9 -0
  4. package/README.md +108 -18
  5. package/README.zh.md +99 -18
  6. package/deployment-baseline.json +227 -8
  7. package/docs/account-management-experience.md +143 -0
  8. package/docs/auto-high-cost.md +154 -0
  9. package/docs/auto-iteration-review.json +22 -0
  10. package/docs/auto-review-sampling.md +60 -0
  11. package/docs/auto-task-routing.md +8 -6
  12. package/docs/automatic-model-routing.md +33 -5
  13. package/docs/copilot-accounts.md +409 -0
  14. package/docs/copilot-compaction.md +23 -2
  15. package/docs/copilot-usage.md +24 -4
  16. package/docs/evidence-driven-iteration.md +86 -0
  17. package/docs/images/copilot-accounts-credits.png +0 -0
  18. package/docs/images/copilot-accounts.png +0 -0
  19. package/docs/images/copilot-current-provenance.json +39 -0
  20. package/docs/images/copilot-model-preferences.png +0 -0
  21. package/docs/images/copilot-search-routing.png +0 -0
  22. package/docs/images/copilot-session-continuation.png +0 -0
  23. package/docs/manual-compaction-recovery.md +50 -7
  24. package/docs/mockups/copilot-account-dropdown.html +71 -0
  25. package/docs/mockups/copilot-account-management.html +393 -0
  26. package/docs/model-compatibility-acceptance.md +34 -16
  27. package/docs/npm-distribution.md +9 -1
  28. package/docs/official-first-020-rc2.md +1 -0
  29. package/docs/plugin-diagnostics.md +452 -0
  30. package/docs/session-continuation.md +141 -0
  31. package/docs/session-search-routing.md +1 -1
  32. package/docs/single-route-migration.md +5 -4
  33. package/lib/client.js +4415 -846
  34. package/lib/client.js.map +1 -1
  35. package/lib/diagnostics-analysis-io.js +78 -0
  36. package/lib/diagnostics-analysis.js +425 -0
  37. package/lib/diagnostics-types-FVf6zjob.js +182 -0
  38. package/lib/index.js +10455 -6037
  39. package/lib/manual-compaction-recovery.js +163 -38
  40. package/lib/remote.js +593 -34
  41. package/lib/routed-web.js +1 -1
  42. package/lib/{search-routing-jzNYveyK.js → search-routing-CV2hs8as.js} +139 -139
  43. package/lib/types/account-dropdown.d.ts +22 -0
  44. package/lib/types/account-model-auth.d.ts +1 -1
  45. package/lib/types/authorization-code-clipboard.d.ts +4 -0
  46. package/lib/types/authorization-controller.d.ts +2 -0
  47. package/lib/types/auto-allocation-card.d.ts +9 -0
  48. package/lib/types/auto-allocation-evidence.d.ts +38 -0
  49. package/lib/types/auto-allocation.d.ts +24 -0
  50. package/lib/types/auto-model-host.d.ts +2 -0
  51. package/lib/types/auto-model-routing.d.ts +6 -2
  52. package/lib/types/auto-review-sampling.d.ts +6 -0
  53. package/lib/types/auto-task-classifier.d.ts +1 -1
  54. package/lib/types/background-compaction.d.ts +2 -2
  55. package/lib/types/client.d.ts +19 -3
  56. package/lib/types/compaction-continuation-ui.d.ts +29 -0
  57. package/lib/types/compaction-continuation.d.ts +48 -0
  58. package/lib/types/compaction-input-estimate.d.ts +24 -0
  59. package/lib/types/compaction-replay.d.ts +18 -0
  60. package/lib/types/composer-notice-style.d.ts +7 -0
  61. package/lib/types/config.d.ts +42 -2
  62. package/lib/types/context-evidence-ui.d.ts +18 -1
  63. package/lib/types/context-evidence.d.ts +152 -4
  64. package/lib/types/copilot-account-presentation.d.ts +7 -0
  65. package/lib/types/copilot-accounts-card.d.ts +43 -0
  66. package/lib/types/copilot-accounts-host.d.ts +93 -0
  67. package/lib/types/copilot-accounts-remote.d.ts +85 -0
  68. package/lib/types/copilot-accounts-types.d.ts +43 -0
  69. package/lib/types/copilot-auth.d.ts +9 -2
  70. package/lib/types/copilot-usage-card.d.ts +23 -0
  71. package/lib/types/copilot-usage-host.d.ts +9 -1
  72. package/lib/types/copilot-usage-remote.d.ts +2 -1
  73. package/lib/types/copilot-usage-types.d.ts +1 -0
  74. package/lib/types/diagnostics-analysis-io.d.ts +23 -0
  75. package/lib/types/diagnostics-analysis.d.ts +295 -0
  76. package/lib/types/diagnostics-card.d.ts +11 -0
  77. package/lib/types/diagnostics-client.d.ts +13 -0
  78. package/lib/types/diagnostics-collector.d.ts +36 -0
  79. package/lib/types/diagnostics-host.d.ts +72 -0
  80. package/lib/types/diagnostics-remote.d.ts +109 -0
  81. package/lib/types/diagnostics-types.d.ts +431 -0
  82. package/lib/types/manual-compaction-recovery.d.ts +18 -3
  83. package/lib/types/model-preferences-card.d.ts +1 -1
  84. package/lib/types/native-settings-style.d.ts +10 -0
  85. package/lib/types/parent-model-follow-card.d.ts +2 -11
  86. package/lib/types/preview-provider.d.ts +5 -0
  87. package/lib/types/preview-route.d.ts +7 -5
  88. package/lib/types/remote.d.ts +9 -6
  89. package/lib/types/replay-recovery-host.d.ts +2 -2
  90. package/lib/types/replay-recovery-ui.d.ts +3 -1
  91. package/lib/types/request-body-evidence.d.ts +3 -1
  92. package/lib/types/responses-replay-compat.d.ts +2 -1
  93. package/lib/types/responses-request-compression.d.ts +33 -0
  94. package/lib/types/session-accounts-controller.d.ts +20 -0
  95. package/lib/types/session-accounts-host.d.ts +33 -0
  96. package/lib/types/session-accounts-remote.d.ts +114 -0
  97. package/lib/types/session-accounts.d.ts +38 -0
  98. package/lib/types/session-continuation-host.d.ts +45 -0
  99. package/lib/types/session-continuation-remote.d.ts +22 -0
  100. package/lib/types/session-continuation-types.d.ts +62 -0
  101. package/lib/types/session-continuation-ui.d.ts +49 -0
  102. package/lib/types/session-continuation.d.ts +14 -0
  103. package/lib/types/turn-request-models.d.ts +55 -0
  104. package/lib/types/turn-selection-card.d.ts +15 -1
  105. package/lib/types/turn-selection-host.d.ts +23 -0
  106. package/lib/types/turn-selection-remote.d.ts +4 -0
  107. package/lib/types/turn-selection.d.ts +19 -4
  108. package/package.json +29 -12
  109. package/scripts/analyze-diagnostics.mjs +91 -0
  110. package/scripts/iteration-review.mjs +53 -0
@@ -0,0 +1,409 @@
1
+ # Copilot accounts
2
+
3
+ ## Delivery status
4
+
5
+ This document records the approved requirements and implementation design for
6
+ issues #297 and #305. It is not a release receipt or a claim of current
7
+ installation/runtime state. The existing single-account behavior remains the
8
+ compatibility baseline; publication, installation and loaded runtime state are
9
+ separate evidence.
10
+
11
+ ## Requirements
12
+
13
+ ### Native OAuth refresh and dispatched requests (#385)
14
+
15
+ In 0.4.0, every matching credential notification aborts managed wires, including
16
+ normal native refresh by another same-account request. Upgrade to 0.4.1 for the
17
+ narrow plugin-owned refresh exception. This is synthetic regression evidence,
18
+ not attribution of a particular live error to refresh.
19
+
20
+ Only a genuine native refresh through the plugin's public credential-store bridge
21
+ may qualify: normalized account grant, model entitlements and official
22
+ OAuth-derived endpoint must remain unchanged. Its exact returned object is
23
+ consumed once inside the serialized `modifyRecord` callback. Exactly one
24
+ synchronous record notification and matching returned committed grant confirm
25
+ the write. No refresh-wide timing flag or unchanged-token heuristic is used.
26
+ Failed, duplicated, delayed, unknown or externally produced notifications remain
27
+ revocation; Core's separately owned canonical adapter has no provenance seam
28
+ through this bridge and remains fail-closed.
29
+
30
+ The exception retains only HTTP streams already dispatched through the native
31
+ adapter's public Fetch seam, including concurrent streams for the same frozen
32
+ account. Metadata, prepared leases, search/recovery proof and retry snapshots are
33
+ still invalidated immediately. A new step/request must resolve fresh native auth
34
+ and validate current account metadata. An old prepared request cannot dispatch
35
+ after renewal; an already-dispatched request cannot use its old lease to make a
36
+ second physical HTTP attempt after renewal. Core retains retry/transaction
37
+ ownership; this plugin adds no resend or automatic retry. Account default changes
38
+ do not redirect frozen requests; each account's record remains isolated.
39
+
40
+ Account/endpoint/permission replacement, record removal, read/commit failure,
41
+ caller cancellation and disposal still revoke. Supplier expired-token rejection
42
+ and network failures can still terminate the original request; preserving a local
43
+ stream does not prove supplier acceptance. Identity/quota presentation caches
44
+ continue to invalidate on every notification, not reuse old credentials.
45
+
46
+ ### Selector switching and account-bound turns (#344)
47
+
48
+ A global switch changes only the selector. Explicit record-bound request leases
49
+ may be acquired during its preflight and CAS so already admitted turns can
50
+ prepare and dispatch their next native step with their frozen account. A new
51
+ turn still captures its account once at admission; it does not adopt a later
52
+ selector. Unbound/global leases remain blocked during switching, and all
53
+ requests remain blocked during credential authorization/removal/sign-out.
54
+ Pinned records cannot be reauthorized or removed until their leases end.
55
+ Cancellation, route eligibility, credential validity and account-model checks
56
+ remain independent. This is not automatic retry or permission to redirect an
57
+ existing turn. Deferred native fixtures exercise all three supported protocols
58
+ while the selector operation is still pending, not just after it settles.
59
+
60
+ ### Global switch responsiveness (#342)
61
+
62
+ Models first reads metadata-only `get()` and separately hydrates display names
63
+ with nonforcing `ensureIdentity()`. Slow inactive-name queries do not hold the
64
+ Switch control. Unknown names remain unknown; route/activity/membership evidence
65
+ still gates controls and the Host independently verifies any requested switch.
66
+ An identity hydration result captured before a mutation or actual Remote/
67
+ authorization/credential lifecycle replacement cannot overwrite newer state.
68
+ Parent callback identity changes alone do not recreate the account lifetime.
69
+
70
+ The Host overlaps fresh identity and available-model preflight under one
71
+ 60-second operation signal. It never replaces fresh verification with the
72
+ ten-minute display cache. Both must finish successfully before selector CAS;
73
+ identity key, membership, route/activity, canonical authorization and revision
74
+ checks remain, including post-commit confirmation. A failed branch aborts the
75
+ other and drains both before releasing the mutation fence, without automatic
76
+ retry or another account fallback. The strict save result updates the account
77
+ card; parent status refresh remains separate. This reduces a serial preflight
78
+ critical path to overlapping work, not zero network latency or proven live
79
+ timing. Synthetic deferred tests establish ordering, not production speed.
80
+
81
+ - Keep multiple independently authorized GitHub Copilot accounts in one DSH
82
+ profile. Models retains the global default. Sessions without an override
83
+ inherit that default at each new turn; explicit Session choices take priority.
84
+ - Models manages reauthorization/removal and the global default; Credits supports
85
+ add-only authorization without selection. Its compact no-search dropdown
86
+ applies to this Session's subsequent turns. No standalone
87
+ composer selector, one-turn override or DSH application identity replacement.
88
+ - Persist OAuth grants through the existing DSH credentials service. Use
89
+ official pi-ai login, refresh and transport, not copied credentials, a token
90
+ backup/refill scheme, a separate credential store, a second wire or Core edits.
91
+ - Preserve the existing `llm-pi-ai/github-copilot` record without moving or
92
+ copying it. It is the compatibility account when no active account is stored.
93
+ Newly added accounts are directly authorized into plugin-owned records.
94
+ - Changing the account must not change Session histories, selected models,
95
+ future global defaults, model exclusions or billing/Usage records. A selected
96
+ model unavailable to the new account fails explicitly, without substitution.
97
+ - Freeze an admitted turn's account before Auto assessment. Later Session/global
98
+ choices do not redirect its steps, native retries or hosted search. Block
99
+ reauthorization/removal of its pinned record until native turn end/disposal.
100
+ Never cancel a running answer automatically. Explain that encrypted historical replay can be
101
+ account-bound; do not silently remove replay or replay a message.
102
+ - No automatic fallback to another account on quota exhaustion, authorization
103
+ failure, missing records or invalid settings.
104
+
105
+ ## Public API evidence
106
+
107
+ Official DSH `0.2.0-rc.2`, commit
108
+ `639ed015397290b3745d163aafe02ffee4aa3f84`, exposes
109
+ `PiAiAdapterOptions.auth.credentials`. Its adapter source was compared
110
+ byte-for-byte with that commit. DSH `authorization.registerFlow()` registers a
111
+ flow per credential key; `credentials.modifyRecord()` serializes mutations.
112
+
113
+ Published pi-ai `0.87.1` accepts a public `CredentialStore` in `createModels()`.
114
+ `Models.login()` persists directly through that store. `Models.getAuth()`
115
+ refreshes OAuth under its serialized mutation; each account can supply an
116
+ independent store binding without changing provider IDs or model IDs.
117
+
118
+ An isolated experiment with unchanged pi-ai and synthetic in-memory stores
119
+ verified independent native login, no refresh for valid tokens, parallel
120
+ account-local refresh, captured-store stability after selection changes,
121
+ preservation after refresh failure, and independent logout. All HTTP was
122
+ mocked. This is SDK composition evidence, not live OAuth, DSH durable storage,
123
+ native gateway or model-call proof.
124
+
125
+ GitHub's authenticated `GET /user` returns the identity corresponding to the
126
+ GitHub authorization token. The current native OAuth requests `read:user`.
127
+ Its `refresh` field holds that GitHub token; the short-lived `access` field
128
+ holds a different Copilot request token. Never exchange their purposes.
129
+
130
+ The Copilot SDK `account.getQuota` contract at commit
131
+ `ef04633cc84e4ba8e79888a39259ca276f5de732` returns quota snapshots and accepts
132
+ an account selection identifier or GitHub token. It is an experimental
133
+ SDK/runtime RPC, not a pi-ai API or proof of cross-application AI credits.
134
+ This feature does not introduce another CLI runtime to obtain quota.
135
+
136
+ ## Ownership extension
137
+
138
+ The user explicitly approved this limited extension of the previous
139
+ single-record policy:
140
+
141
+ - Official canonical credentials remain under their existing owner.
142
+ - The plugin may own additional `github-copilot/account-<opaque-id>` records,
143
+ obtained by official OAuth writing directly into the target record.
144
+ - All records use the existing DSH credentials service and documented grant
145
+ normalization. No credentials enter Settings, Client, Remotes, logs or docs.
146
+ - Official pi-ai remains the OAuth and refresh implementation owner. The plugin
147
+ owns only account addressing, selection, lifecycle and safe presentation.
148
+ - This does not authorize Core changes, credential cloning, ambient credential
149
+ discovery, copied upstream catalogs or a second general transport adapter.
150
+
151
+ ## Account binding and persistence
152
+
153
+ Settings contain an opaque global active account identifier, written with a
154
+ path-level compare-and-swap in the existing `github-copilot` namespace. An
155
+ absent selector means the canonical compatibility account. An invalid selector
156
+ or missing selected record is an error, not permission to use canonical.
157
+ There is no persisted membership list: native `credentials.listRecords()`
158
+ enumerates record keys and kinds, while public identity stays in bounded
159
+ Host-memory cache. No usernames, grants or auxiliary account list are stored
160
+ in Settings. Hidden volatile `sessionAccounts` additionally persists bounded
161
+ `{sessionId, accountId}` overrides, changed through a separate path-level CAS.
162
+ Selecting the same account as the default is still an explicit override.
163
+ Choosing **Follow global default** removes only this Session's row.
164
+
165
+ A request captures an immutable account identifier, record key and selection
166
+ ownership. Its `CredentialStore.read/modify/delete` methods all refer to that
167
+ record. A mutable active-account lookup inside each store method is forbidden:
168
+ an A refresh must never commit into B after a switch.
169
+
170
+ Account identity uses GitHub host plus stable numeric user ID for duplicate
171
+ detection, not usernames or token strings. Identity reads are bounded,
172
+ Host-only, redirect-refusing and cancellation-aware. Normalize only required
173
+ public identity fields, discard unrelated `/user` fields, and reject results
174
+ whose credential/selection evidence changed during the read.
175
+ Host normalization and strict Remote decoding share the same bounded login
176
+ pattern. It accepts ordinary names and GitHub.com Enterprise Managed User names
177
+ with underscore-separated shortcodes, including setup admin names. This is not
178
+ support for a custom enterprise OAuth host; `enterpriseUrl` remains unsupported.
179
+ See [GitHub's official username rules](https://docs.github.com/en/enterprise-cloud@latest/admin/managing-iam/iam-configuration-reference/username-considerations-for-external-authentication).
180
+
181
+ Token refresh remains lazy. Inactive accounts need not hold fresh Copilot
182
+ tokens. Refresh uses native `Models.getAuth()` and the corresponding DSH record
183
+ mutation. Failure preserves the account's stored grant and does not affect
184
+ other records. Reauthorization targets the same account slot and must detect
185
+ unexpected identity replacement before activating it.
186
+
187
+ ## Add and switch transactions
188
+
189
+ Adding an account runs native OAuth in an independent slot. It does not
190
+ overwrite or change the active account. Identity and model metadata validation
191
+ must complete before the new slot can be selected. Partial authorization is
192
+ reported truthfully and can be retried or explicitly removed.
193
+
194
+ The Models card keeps the GitHub verification link, selectable manual URL,
195
+ one-time authorization code, copy action and cancellation together while
196
+ device authorization is pending. A confirmed OAuth completion is followed by
197
+ a separately reported identity-and-model verification phase; neither phase
198
+ changes the global default. The Host's operation state, not a Client guess,
199
+ proves when that verification phase begins. Normal pending authorization is
200
+ progress, not a terminal busy error; technical diagnostics remain available in
201
+ a collapsed disclosure. Unknown blockers are not replaced with a speculative
202
+ list. **Refresh account information** remains an identity refresh only and
203
+ does not complete or cancel authorization.
204
+
205
+ Switching has a preparation phase and a commit phase:
206
+
207
+ Route eligibility reads official rc.2 SettingsForms through redacted
208
+ `describe()` values and revision-bearing namespaces; it does not require the
209
+ retired `get()` method. Missing or malformed configuration still means
210
+ incomplete evidence, not an absent native route. The legacy reader remains
211
+ available for retained compatibility fixtures. Account persistence acceptance
212
+ uses real SettingsForms and the production route diagnostic, without an
213
+ eligibility override.
214
+
215
+ 1. Capture the selector revision and verify managed-only route eligibility.
216
+ 2. Validate target identity, refresh authorization as needed and check account
217
+ model metadata without publishing it as the active account.
218
+ 3. Hold an admission fence during commit. Existing account-pinned managed
219
+ turns may continue; unbound legacy preparation remains conservatively fenced.
220
+ 4. CAS the selector, read back committed settings and confirm target evidence.
221
+ 5. Update the default directory and UI without revoking another account's
222
+ running turn/proofs or writing model/history/default selection. Credential
223
+ replacement revokes only the matching account runtime and search/quota proof.
224
+
225
+ `COPILOT_ACCOUNTS_BUSY` is transient: each account status read reevaluates
226
+ current managed Agent activity, operation leases and authorization. A rejected
227
+ switch must not remain busy after that work settles. Reading status does not
228
+ refresh credentials or retry the rejected switch. In Models, use **Refresh
229
+ account information** after work ends to update the mounted view. With only
230
+ one saved account, first use **Add GitHub account**; a **Switch** control is
231
+ shown only for another saved account. No running work is cancelled for this.
232
+
233
+ Failed preparation leaves the old selector unchanged. A committed selector
234
+ followed by failed readback is reported as uncertain, never successful and
235
+ never automatically rolled back. Cross-process/external mutations are guarded
236
+ by revisions and evidence checks; an in-process fence is not a cross-namespace
237
+ or cross-process transaction guarantee.
238
+
239
+ Operations include model preparation, Auto assessment, model discovery,
240
+ native auth refresh, managed answer streams and hosted search. Release leases
241
+ on completion, failure, cancellation and disposal. Switching never terminates
242
+ native retries, rewrites native retry policy or manufactures Usage.
243
+ An abandoned signal-free prepared call has no public completion/cancellation
244
+ evidence; it conservatively retains its account mutation barrier until disposal.
245
+ Changing the global default can still proceed without redirecting that call.
246
+ A guessed idle timeout must not permit reauthorization/removal of its account.
247
+
248
+ ## Route compatibility
249
+
250
+ Core's canonical route still reads its canonical record. Do not intercept
251
+ Core's store, mutate its prototypes or mirror selected grants into its record.
252
+ The first multi-account delivery therefore requires a managed-only profile.
253
+ Existing canonical configuration, running/selected legacy routes, or
254
+ incomplete route evidence blocks switching with a named diagnostic.
255
+
256
+ Any migration uses the existing separately approved, explicit configuration
257
+ workflow. Enabling accounts does not remove native profiles, rewrite stored
258
+ Sessions or silently migrate their route IDs.
259
+
260
+ Sign-out deletes only the selected record. Inactive records remain intact.
261
+ For a noncanonical selection, the selector remains unchanged after sign-out:
262
+ the missing selected slot fails explicitly, never falls back to canonical.
263
+ In a managed-only profile with complete route/Session evidence and no admitted
264
+ activity, Models still permits an explicit CAS switch to a stored valid account
265
+ or Add into a new inactive slot. The missing-slot view remains an error even
266
+ when `switchable` is true for that recovery. Existing Sign in never recreates
267
+ the missing slot with an unverified replacement identity; use Add then Switch.
268
+
269
+ ## Presentation and quota
270
+
271
+ Models shows current identity and available accounts, Add, Switch and explicit
272
+ authorization recovery. Switch confirmation describes profile-wide impact and
273
+ history/replay risks. Activity and route blockers remain visible.
274
+
275
+ ![Models account controls at a mobile viewport](./images/copilot-accounts.png)
276
+
277
+ ![Read-only identity in Credits details](./images/copilot-accounts-credits.png)
278
+
279
+ These images render the actual candidate components with synthetic accounts
280
+ and quota in an isolated browser. They are not real authorization, supplier
281
+ availability or loaded Desktop evidence.
282
+
283
+ The separate `githubCopilotAccounts` namespace exposes `get`, `ensureIdentity`,
284
+ `refreshIdentity`, `add`, `cancel`, `switchAccount`, `reauthorize` and
285
+ `removeAccount`. Existing Remote descriptors are retained. The removal method
286
+ cannot be named `remove`: official rc.2 reserves that inherited service name
287
+ and rejects the entire Client contribution.
288
+
289
+ Credits shows the Session's next-turn account and quota under the existing title.
290
+ Its **Switch** dropdown marks the current choice, scrolls long lists internally
291
+ and offers **Follow global default** plus add-only authorization at the bottom.
292
+ Reauthorization, removal and global
293
+ selection remain in Models. Changing
294
+ the preference while a turn runs leaves that turn's old account pinned; the
295
+ popover identifies it separately. Other Sessions are unchanged. Unknown identity
296
+ is unavailable, not a stale username presented as current.
297
+
298
+ One Models **Manage** groups account management, the new-Session continuation
299
+ default and shared exact-ID model preferences. The existing Session policy is
300
+ under the composer Credits/usage popover → **Visible-history continuation** →
301
+ **Session policy**; it appears only for an open Session whose effective model
302
+ is the managed account-discovered Copilot route. Choose **On** after reviewing
303
+ the loss disclosure. This is distinct from the Models new-Session default and
304
+ applies to subsequent turns and managed native compaction summaries, including
305
+ on the same account. Active turns keep their captured policy; enabling does not
306
+ send or retry a message. See the [synthetic composer capture](./images/copilot-session-continuation.png)
307
+ and [continuation contract](./session-continuation.md). When off, an account change pauses for explicit
308
+ persistent-enable/keep-off/cancel consent. See the [approved experience and mock](./account-management-experience.md).
309
+
310
+ Completed managed turns have a compact **Account** disclosure alongside native
311
+ Usage/selection actions through the public assistant-actions slot. This is
312
+ request-account evidence, not billing attribution or a subagent account rollup.
313
+ It freezes a verified cached identity at admission. Missing identity starts one
314
+ nonforcing, bounded lookup for the exact admitted account without delaying model
315
+ delivery. A successful lookup may fill missing identity only while that same
316
+ turn/signal remains active and uncancelled, retaining the first verified name.
317
+ Account execution evidence is still created only on the first real ordinary
318
+ native chunk, not discovery, preparation or auxiliary Auto assessment. Late
319
+ lookups never backfill completed turns. Host memory retains at
320
+ most 64 Sessions and 128 turns per Session. Restart, cold history, eviction or a
321
+ request with no native delivery is unknown. Failed reads are distinct from
322
+ unknown evidence; Retry rereads the same turn without inference. Official rc.2
323
+ has no ignorable account-history event seam: no new durable event is emitted.
324
+ Only a login captured for that turn is shown; otherwise identity is explicitly
325
+ unavailable, never inferred from current settings or today's account selector.
326
+ Credits selector labels unknown original/saved authorizations without exposing
327
+ opaque record identifiers; these presentation labels do not fetch identity or
328
+ change account selection.
329
+
330
+ Identity and quota have separate error states but must share account evidence.
331
+ Models account mutations invalidate mounted Credits presentation before the
332
+ request and reject late responses. A data-free plugin-owned notification causes
333
+ a fresh read after settlement; it does not cancel native work or broadcast
334
+ identity, grants or quota between surfaces. Failed reads never restore the
335
+ previous username as current.
336
+ Missing quota is not zero; pooled, stale, request-based and credit-based
337
+ snapshots retain their distinct meanings. Do not claim cross-app aggregation
338
+ or relabel request counts as AI credits.
339
+
340
+ Visible Models and Credits surfaces ensure identity on mount, visibility return
341
+ and their sixty-second display cadence. `get` and `viewForAccount` remain
342
+ metadata-only. Nonforcing ensure reuses a fresh ten-minute identity, joins
343
+ same-account in-flight work and observes a thirty-second failure cooldown;
344
+ explicit **Refresh account information** bypasses cooldown but joins active
345
+ work. There is no render-driven request loop or background polling after
346
+ unmount. Credential changes revoke identity and pending work; cancelled or
347
+ unverified identity is never shown as current. Verified display names remain in
348
+ the bounded Host cache beyond the ten-minute revalidation interval; freshness
349
+ expiry alone never replaces an inactive account name with unknown. Names are
350
+ display metadata, not authorization/model-access proof, and are not persisted
351
+ across Host restarts. Models and Session Credits ensure missing configured
352
+ account names through the same per-account lookup without activating those
353
+ accounts. Membership limits bound the parallel lookups and each retains its
354
+ timeout/single flight/cooldown. Credential invalidation and failed verification
355
+ still clear names. Session ensure retains explicit
356
+ Agent lookup and rechecks account selection before returning.
357
+
358
+ Quota settles independently of identity renewal only after account-coherent
359
+ metadata checks. Identity failures cannot turn account quota into zero or
360
+ discard an otherwise valid same-account reading. Sanitized diagnostics separate
361
+ timeout, certificate, network, auth rejection, rate limiting and other HTTP
362
+ failures; no raw response/error text or credentials enter the Remote. These
363
+ diagnostics do not establish the cause of earlier screenshots or prove live
364
+ supplier health. Account switching, duplicate checks and reauthorization still
365
+ require fresh authenticated identity validation, not the presentation cache.
366
+
367
+ ## Acceptance gates
368
+
369
+ - Native public authorization and credentials services: independent writes,
370
+ cancellation, restart persistence, per-record serialization and strict grant
371
+ JSON. No changes to the official fixture implementation.
372
+ - Both public gateways and strict Client codecs: no credential fields, stable
373
+ descriptor identities, bounded arguments and visible errors.
374
+ - Exact published native adapter: correct account auth on all supported
375
+ protocols; account-local refresh and failure; no ambient fallback.
376
+ - Races: A refresh versus B selection, admission versus switch, external record
377
+ replacement, settings conflicts, disposal and late identity/quota responses.
378
+ - Behavior: absent-selector compatibility, missing-selector fail-closed,
379
+ duplicate identity, same-account renewal, canonical route blocker, selected
380
+ model missing, revoked permissions and account-bound replay.
381
+ - UI: Models global-default management, Session switching only inside Credits,
382
+ global inheritance/explicit same-value override, frozen running turns,
383
+ historical Account/unknown/read-error distinctions, dark/light/mobile,
384
+ keyboard interaction, loading/error states and no overlapping controllers.
385
+ - No native Usage filtering, history edits, default selection changes or
386
+ automatic model/account substitution.
387
+ - Full current rc.2 Windows/Linux CI, package and tarball gates, reviewed merge,
388
+ immutable GitHub Release and same-byte npm publication before claiming
389
+ delivery. Installation and restart need separate authorization.
390
+
391
+ ## Current evidence and limits
392
+
393
+ Focused native adapter and gateway tests use unchanged rc.2 public APIs and
394
+ synthetic credentials/HTTP. They exercise Responses, Chat Completions and
395
+ Anthropic account dispatch, immutable refresh bindings, strict gateway
396
+ reachability, target CAS, admission and same-identity renewal.
397
+
398
+ The temporary-profile persistence fixture uses native `LocalCredentialProvider`,
399
+ profile boot/Loader, ConfigEditor, SettingsForms CAS, authorization and SDK.
400
+ Independent grants and the selector survive disposal/reopen; stale CAS does
401
+ not replace the config fiber; account A refresh never writes B. It injects
402
+ model preflight, and mocks identity/provider
403
+ HTTP. It is not full production lifecycle or live OAuth qualification.
404
+
405
+ The local frozen install and full gate are blocked by HTTP 404s for unchanged
406
+ official rc.2 dependencies from the configured enterprise mirror. No package
407
+ versions, registry policy or Core artifacts were substituted. The complete
408
+ required Windows/Linux CI matrix remains the release gate; focused tests,
409
+ synthetic UI and persistence do not replace it or prove live model success.
@@ -1,5 +1,12 @@
1
1
  # Managed Copilot compaction budgets
2
2
 
3
+ Visible-history continuation does not impose a whole-request byte cap. Its
4
+ reasoning-only cancellable work bounds are separate from native token admission;
5
+ neither ciphertext length nor `COPILOT_CONTINUATION_REASONING_WORK_LIMIT` is
6
+ classified as context overflow. Enabled native automatic compaction still owns
7
+ summary commit and request rebuild before continuation filters the new payload.
8
+ See [continuation safety and evidence](./session-continuation.md#public-integration-and-safety).
9
+
3
10
  Tracking: [#146](https://github.com/cloga/dsh-github-copilot/issues/146). This is a plugin-only implementation; publication, loaded-runtime state and live-provider acceptance remain separate evidence.
4
11
 
5
12
  ## Why two protections are needed
@@ -49,10 +56,19 @@ Disabled auto recovery or zero retries are respected. Missing/mismatching option
49
56
 
50
57
  On official `0.2.0-rc.2`, Desktop presets may isolate `compaction` inside a child group, invisible to both the global plugin context and a plain `agent.ctx.get('compaction')`. The plugin uses the public `agentPresets.composedPreset()` and `serviceFor(agent, 'compaction')` methods to resolve the initiating Agent's current preset engine. A bound preset with no engine remains unavailable; it never borrows another scope's policy. Only an Agent without a bound preset uses its own context lookup. The lookup is repeated rather than caching a replaced engine. Auto's recovery-availability diagnostic uses the same helper.
51
58
 
52
- This fixes scope wiring, not a new automatic command: native pressure and `agent/request-error` still invoke the selected engine. Neither `/compact` nor `/copilot-compact` is called by this listener. If the optional manual recovery engine is selected, its automatic path remains the native single-summary path; segmented recovery stays manual-only. Ordinary timeout/transport failures do not become context overflow.
59
+ This fixes scope wiring, not a new automatic command: native pressure and `agent/request-error` still invoke the selected engine. Neither `/compact` nor `/copilot-compact` is called by this listener. If the recovery engine is selected, automatic segmentation defaults on for known oversized summary input or one exact native summary capacity failure, within the same native transaction. `automaticRecovery: false` restores its automatic single-summary path; native `auto: false` and retry bounds remain authoritative. Ordinary timeout/transport failures do not become context overflow.
53
60
 
54
61
  ## Summary purpose policy
55
62
 
63
+ Replay-scope rejection is not input overflow: a smaller summary request can still
64
+ carry old encrypted reasoning that the supplier refuses. Ordinary and automatic
65
+ compaction never inherit chat continuation consent. The selected recovery engine's
66
+ explicit `/copilot-compact visible-history` authorizes one lossy Responses summary
67
+ operation, with safe failure-code reporting and unchanged native transaction
68
+ ownership. Review [consent and bounded limitations](./manual-compaction-recovery.md#explicit-visible-history-summary-recovery)
69
+ before invoking. This does not decrypt or repair replay, rewrite source history,
70
+ retry a failed message or guarantee capacity recovery.
71
+
56
72
  Official `GenerateOptions.purpose` permits adapter-specific generation policy. For `purpose: 'compaction'`, `prefer-low` selects supported `minimal`, otherwise supported `low`, only when no effort was supplied or materialized by Core/the configured native profile. Explicit and resolved defaults win; unsupported low controls preserve the provider default. `preserve` disables this purpose default. Normal conversations and other purposes keep their existing reasoning behavior.
57
73
 
58
74
  The stock summary record takes its requested output cap from the owning compaction configuration. Therefore the plugin does not silently increase/decrease that cap in middleware or alter summary route identity. It preserves native `max-tokens` output truncation as failure, distinct from input overflow. Public summaries, encrypted replay and native stop reasons remain native-owned.
@@ -68,6 +84,7 @@ All three keys belong to the existing `github-copilot` settings namespace:
68
84
  | `requestBudgetSafetyTokens` | 4096 | Non-negative safe integer; more allowance means less usable input. Lowering it trades away preventive headroom and does not change native SDK safeguards. |
69
85
  | `requestBudgetPressureRatio` | 0.9 | 0.01 through 1, step 0.01, for eligible ordinary loop calls only. |
70
86
  | `compactionReasoning` | `prefer-low` | Supported low-cost default for otherwise unspecified summary effort; `preserve` keeps existing defaults. |
87
+ | `responsesRequestCompression` | `false` | Experimental, opt-in lossless gzip for eligible managed HTTP Responses requests; no context reduction or additional retry. |
71
88
 
72
89
  The existing `enabled` switch remains hosted-search-only. These controls do not change global/default model selection, enable another account route, or transfer conversation data to another provider.
73
90
 
@@ -75,6 +92,10 @@ The existing `enabled` switch remains hosted-search-only. These controls do not
75
92
 
76
93
  HTTP `408 / user_request_timeout` is separate from input-budget overflow. For the exact observed request-body timeout response, the managed route supplies a safe `COPILOT_REQUEST_BODY_TIMEOUT` diagnostic and final JSON UTF-8 byte count when available, while preserving native failure classification and retries. These bytes include serialized messages, tools and replay/attachments; they are not token occupancy or an advertised HTTP-size limit. Repeated unchanged retries cannot reduce the request. After retries exhaust, an explicit native compaction may reduce compressible history, but giant fixed prefixes/attachments and network/service faults may remain. The existing optional manual recovery engine must be separately selected; installing the account plugin does not enable it. No 408 triggers automatic compaction, hidden history trimming, credential refresh, model switching, timeout changes or a second retry loop. Consult [GitHub troubleshooting](https://docs.github.com/en/copilot/how-tos/troubleshoot-copilot/troubleshoot-common-issues) and [service status](https://www.githubstatus.com/) without bypassing network policy.
77
94
 
95
+ `github-copilot.responsesRequestCompression` is a separate, experimental, default-off upload mitigation. Explicit opt-in gzips only account-proven official Copilot HTTPS `/responses` POSTs with a string JSON body, at the existing plugin-owned Fetch seam after native serialization, replay normalization and context admission. Custom Fetch, other APIs, explicit `auto` and WebSocket remain unchanged. It starts at 256 KiB, skips compression work above 32 MiB, and requires at least 5% and 4 KiB savings; every ineligible, oversized or uneconomic body remains the original native request. The asynchronous work is cancellation/account/deadline fenced before dispatch. No route pinning, hidden trimming, token/admission changes, identity resend after 415, retry or model switch is added.
96
+
97
+ For a verified 408 after a compressed request, the diagnostic labels the original JSON composition bytes separately from the prepared gzip HTTP-body bytes (excluding transport framing). The compressed size is not confirmed delivered bytes, a token count, a provider size limit or proof of a network cause. A skipped compression may include one fixed reason; request bodies and headers are not retained. Synthetic controls support an opt-in mitigation only, not a universal provider capability or guaranteed 408 cure. Keep it off where endpoint support is unknown; disabling it affects later dispatches and installation never enables it.
98
+
78
99
  For [#263](https://github.com/cloga/dsh-github-copilot/issues/263), the same public final-body fetch hook additionally captures a monotonic fetch-invocation-to-response-header duration, before clone observation. This is round-trip latency, not measured upload progress, throughput or time spent reading the body. Only a verified exact error triggers numeric composition analysis; successful requests are not analyzed or retained.
79
100
 
80
101
  For #291, request-scoped public Node/Undici diagnostic channels also observe local body-write completion and native response-header timing, negotiated TLS ALPN when exposed, and a public Node writable-buffer count at body-write completion. Exactly one matching native request is required; no matching event, multiple requests (such as redirects), and more than eight request identities yield explicit unavailable, ambiguous or work-limited evidence, never combined partial timings. H2 connection evidence does not depend on H1-only header-write events; reused H2 sockets or custom transports may leave ALPN unavailable. Subscriptions stop when Fetch settles, including errors, before bounded response-clone analysis. Only an exact verified timeout emits these numeric observations; no request fields, headers, URLs, content, replay or credentials are retained or logged. The original Fetch arguments, signal, Response/error, dispatcher, proxy, connections and retries remain native-owned.
@@ -95,7 +116,7 @@ On official `0.2.0-rc.2`, the stock summarizer uses an explicitly configured sum
95
116
 
96
117
  Official configuration already supports a separate summary route and output cap. Selecting a suitable authorized route/cap is an explicit deployment choice, not an automatic fallback. Increasing the output cap consumes combined-context headroom; decreasing it can reproduce the observed incomplete-checkpoint failure.
97
118
 
98
- An explicit, separately selected recovery engine for compressible already-oversized **manual** summaries is specified in [manual compaction recovery](./manual-compaction-recovery.md). The default Basic engine and the preventive request guard remain unchanged. No hidden wire interceptor or automatic summary retry is used; the native summary event is unmarked when several real calls contributed to one checkpoint.
119
+ A separately selected recovery engine for compressible already-oversized manual and automatic summaries is specified in [compaction recovery](./manual-compaction-recovery.md). The stock Basic engine and preventive request guard remain unchanged. Selection requires explicit same-scope configuration migration, not installation alone. The selected engine bounds segmentation to 16 physical calls including an initial capacity failure; no hidden wire interceptor, arbitrary-error fallback or recursive retry is used. The native summary event is unmarked when several real calls contributed to one checkpoint.
99
120
 
100
121
  ## Official-first evidence and retirement
101
122
 
@@ -5,7 +5,7 @@ The optional composer control separates three quantities:
5
5
  | Quantity | Scope | Rule |
6
6
  | --- | --- | --- |
7
7
  | Context occupancy | Current native request/context window | Remains owned by DSH's native meter. |
8
- | Account usage and remaining allocation | GitHub account billing cycle, across Copilot applications | Display only validated provider quota data; identify stale snapshots explicitly. |
8
+ | Account usage and remaining allocation | Authorized GitHub account quota snapshot | Display only validated provider quota data; identify stale snapshots explicitly. Do not claim cross-application aggregation. |
9
9
  | Session credits | Complete provider-reported usage attributable to this DSH Session | Not displayed because the supported adapter does not supply it. Do not infer it from tokens, cost estimates or account balance changes. |
10
10
 
11
11
  ## Presentation
@@ -14,6 +14,14 @@ The control is an additive `conversation.composer.dock` contribution for the cur
14
14
 
15
15
  The compact control shows reported usage and remaining allocation where available. Its details explain the unit, budget, reset timestamp, freshness and unavailable data. Legacy premium requests must never be relabeled AI credits. A pooled organization account can have absolute credits used without a personal denominator; it does not imply unlimited use or expose a knowable organization balance. Percentage-only data must not create falsely precise absolute amounts.
16
16
 
17
+ The account extension described in [Copilot accounts](./copilot-accounts.md)
18
+ adds a readonly GitHub identity under the details title. Models retains account
19
+ authorization and the global default. Managed Sessions can select an already
20
+ authorized account inside Credits for subsequent turns, or restore global
21
+ inheritance; running turns remain on their frozen account. Identity and quota
22
+ must carry matching Session-account evidence before they are presented together.
23
+ Failure to read identity is not a different account or a zero balance.
24
+
17
25
  Detailed amounts are rounded to two decimal places for display; a positive amount below 0.01 is shown as `<0.01`, not zero. GitHub billing remains authoritative. Known individual budgets at 90% used show a low-budget warning, not a spending restriction. The plan link uses the supported Desktop browser handoff with a selectable URL fallback. Details use the browser's native popover top layer when available and a fixed-position fallback otherwise; no additional ReactDOM copy or private Core DOM access is introduced.
18
26
 
19
27
  Provider or Session changes, unmounting and missing supported runtime seams revoke the presentation's ownership. Optional capability failure must not disable sign-in, Models, search or ordinary chat. The installed/loaded Client determines the exact dock placement; the standalone design mockup is not proof of native placement.
@@ -32,7 +40,13 @@ The time beside **Retried model request** is the recorded retry backoff, not the
32
40
 
33
41
  The separate, strict `githubCopilotContextEvidence` session projection reads only routing and numeric usage from ordinary durable events. It keeps the last applicable input-plus-cache sample when a failed all-zero attempt is replayed. Model changes, compaction, surface replacement, conflicting source attribution and invalid metadata revoke the sample. It never reads message content or opaque replay, registers under a Core key, changes the native pressure projection, or rewrites durable history.
34
42
 
35
- An additive composer disclosure identifies missing or unreliable context evidence for the current open Copilot Session. Any retained count is explicitly a **historical input sample, not current occupancy**; no capacity or percentage is inferred. The native context ring and account Credits control remain separate and unchanged. Missing public projection/slot/runtime seams produce named diagnostics rather than guessed counts. Old histories can therefore still show native `0%`; the disclosure explains the uncertainty instead of claiming an in-place native-meter repair.
43
+ An additive composer disclosure identifies only a concrete failed-zero or invalid-sample incident for the current open Copilot Session. Ordinary request progress, a newly opened step and absence of a fresh sample do not create a warning. Any retained count is explicitly a **historical input sample, not current occupancy**; no capacity or percentage is inferred, and the copy does not assert what the separate native meter currently displays. The native context ring and account Credits control remain separate and unchanged. Missing, malformed or otherwise unknown projection/slot/runtime evidence produces a named diagnostic instead of a success-shaped UI or guessed count.
44
+
45
+ Compaction feedback shares this disclosure without turning sampling absence into a second warning. **Compaction completed** requires a matching native checkpoint and successful end, or the account-bound Host's confirmed native commit. The existing eight-second result can separately report a subsequent request outcome; running, failed, cancelled and unconfirmed compaction outcomes remain distinct. Once that transient result expires, ordinary post-compaction steps stay quiet unless they produce a concrete sampling incident. The native expandable **Context compacted** history row remains unchanged.
46
+
47
+ The independent projection retains only the latest compaction bracket, subsequent ordinary-request evidence and latest sequenced sampling incident. A normal successful settlement after that bracket is reported separately from an applicable input-plus-cache sample. It observes public step/header and same-step source/terminal metadata, including unchanged-header steps and retries; summary output is never a subsequent chat success. Missing usage can coexist with request success without becoming an incident. A failed zero or malformed/conflicting usage sample creates an incident; a later applicable valid sample clears it. Model changes, compaction and surface replacement revoke the old incident rather than allowing it to reappear for another route. A recorded post-compaction count is still historical, not exact current occupancy. No extra test message, automatic retry, content/replay read, durable event or replacement percentage is added. Projection state version 3 requests a native refold, not history conversion.
48
+
49
+ The transient commit/loss status follows the eight-second completion expiry and manual Close rules. Its registration-owned presentation bound moves with the notice into the context UI. A separate bounded Client presentation remembers dismissal by Session and incident sequence across ordinary remounts and Session switches. Dismissal hides only that incident; a newer independent incident can notify, and a later applicable valid sample clears the projection incident. Registration teardown or bounded eviction may discard presentation-only dismissal. Native compaction history remains expandable throughout.
36
50
 
37
51
  Local synthetic tests establish native-stream preservation, historical-fold and presentation behavior only. Exact published-adapter and public-registry acceptance, complete CI, publication and loaded Desktop state must be verified separately. No live provider call or Session restart is needed for these tests.
38
52
 
@@ -66,9 +80,15 @@ Synthetic unit/UI tests and exact unchanged Core accounting/registry fixtures pr
66
80
 
67
81
  ## Account data boundary
68
82
 
69
- The Host uses the existing `llm-pi-ai/github-copilot` OAuth grant through public credential APIs. GitHub's `copilot_internal/user` endpoint uses the GitHub grant, not a second sign-in or a newly pasted token. Access-token renewal remains owned by pi-ai; quota inspection must not introduce a refresh implementation or credential persistence.
83
+ The Host uses the selected account's OAuth grant through public credential APIs,
84
+ with `llm-pi-ai/github-copilot` retained for canonical compatibility. GitHub's
85
+ `copilot_internal/user` endpoint uses the GitHub grant, not a quota-specific
86
+ sign-in or a newly pasted token. Access-token renewal remains owned by pi-ai;
87
+ quota inspection must not introduce a refresh implementation or credential
88
+ persistence. The account-record extension has its own explicit ownership
89
+ contract in [Copilot accounts](./copilot-accounts.md).
70
90
 
71
- Quota requests are lazy, single-flight and bounded by timeout, response size and cache/failure policy. Account continuity is checked around asynchronous work and before releasing cached data. Authentication denial, sign-out, account invalidation or disposal must not release a previous account's snapshot. A same-account transient failure may expose a timestamped last-known snapshot, never a current balance. Responses and diagnostics exclude tokens, raw provider bodies and account identifiers. Requests do not follow redirects with the credential; custom enterprise hosts are not guessed.
91
+ Quota requests are lazy, single-flight and bounded by timeout, response size and cache/failure policy. Account continuity is checked around asynchronous work and before releasing cached data. Authentication denial, sign-out, account invalidation or disposal must not release a previous account's snapshot. A same-account transient failure may expose a timestamped last-known snapshot, never a current balance. Responses and diagnostics exclude tokens and raw provider bodies. An opaque plugin account identifier may bind a snapshot to readonly identity; it is not a token fingerprint or billing identifier. Requests do not follow redirects with the credential; custom enterprise hosts are not guessed.
72
92
 
73
93
  The plugin's default quota fetch lazily creates one request-scoped Undici agent for `https://api.github.com/copilot_internal/user`. It unions and deduplicates `tls.getCACertificates('default')` (including any configured extra CA certificates) and `tls.getCACertificates('system')`, with `rejectUnauthorized: true`. Node 22.19.0 provides both CA APIs; Undici 6 supports that runtime floor. The agent is reused for refreshes and destroyed on controller disposal. Injected test fetchers bypass the agent. No global dispatcher, environment variable, Desktop trust preference, model/search transport or credential owner is changed.
74
94
 
@@ -0,0 +1,86 @@
1
+ # Evidence-driven iteration
2
+
3
+ Complex features must retain the link between observations, decisions and
4
+ follow-up evaluation. A dashboard alone does not ensure contributors read the
5
+ evidence. Auto is the first required pilot (#332).
6
+
7
+ ## Before implementation
8
+
9
+ Read the last feature review and unresolved follow-up. State whether the
10
+ hypothesis is retained, changed or deferred. Declare policy version, observation
11
+ window, denominator and limitations: `observed`, `not-collected`,
12
+ `insufficient-sample` or `unavailable`. Missing data is not a passing result.
13
+ Define the expected improvement, guardrails and sample sufficiency before
14
+ analysis. Total turns alone are insufficient when candidate opportunities differ.
15
+
16
+ Record alternative validation when live observations are absent. Synthetic
17
+ distribution tests, types and native fixtures do not prove real workload quality,
18
+ billing or live activation. A review is not permission to implement everything
19
+ previously discussed or collect sensitive data.
20
+
21
+ ## Required Auto review
22
+
23
+ `docs/auto-iteration-review.json` is the latest repository-safe decision record.
24
+ The Auto task plan starts by validating and reading it before implementation:
25
+
26
+ ```sh
27
+ node scripts/iteration-review.mjs --report docs/auto-iteration-review.json
28
+ ```
29
+
30
+ The bounded dependency-free command validates structure, not the truth of
31
+ conclusions. It never scans profiles, calls DSH, reads credentials or uploads
32
+ data. Unknown fields are rejected; invalid input is not echoed. Human review is
33
+ still necessary to remove sensitive prose.
34
+
35
+ For routing, assessment, cost weights, continuity or assistance-policy PRs,
36
+ reference the review and its status, policy version, window/sample denominator,
37
+ decision and validation. Name the post-delivery review owner, trigger, metric
38
+ and action. Unrelated changes use N/A. CI checks the report and workflow wiring;
39
+ it cannot prove an author read the data or understood it.
40
+
41
+ ## Measurement contract
42
+
43
+ - Count decisions once per Agent/turn. Tool steps and retries are not new
44
+ decisions. Selected, attempted, delivered, finished, failed, cancelled and
45
+ unknown have different denominators; completion is not task success.
46
+ - For each eligible final-pool candidate capture effective weight, opportunity
47
+ and conditional expected share. Compare summed expected versus actual
48
+ selections, not raw percentages that ignore eligibility.
49
+ - Split category/eligibility changes from within-pool allocation and continuity.
50
+ Keep policy versions and candidate-set changes separate. Stable deterministic
51
+ seeds do not establish independent random trials.
52
+ - Record assessment source/outcome and timing only at observable boundaries;
53
+ adapter-first-text is not HTTP-first-byte.
54
+ - Do not infer credits from tokens, balance deltas or incomplete usage.
55
+ Unknown costs stay unavailable. Cache rates do not prove switching losses.
56
+
57
+ The first high-cost implementation retains bounded, local Host-lifetime
58
+ selection observations. At most 64 live Agent owners and 128 turns per owner
59
+ are retained; summary detail is bounded to 512 model/category/marking/continuity
60
+ strata and explicitly reports truncation. The current Session export includes
61
+ its retained observation timestamps. Restart, disposal and eviction lose
62
+ evidence; there is no complete traffic denominator or durable collector.
63
+ See [high-cost requirements](./auto-high-cost.md).
64
+
65
+ ## Privacy
66
+
67
+ Do not collect prompt/answer/tool content, replay, grants, account names or raw
68
+ Session IDs in reports. Do not write custom durable Core history events or
69
+ modify native Usage. Raw exports stay outside Git. Local read-only exports are
70
+ not automatic uploads; sharing requires approval for the specific data and
71
+ destination. Persistence requires a reviewed public storage seam, retention
72
+ and clearing, not an implicit extension of this pilot.
73
+
74
+ ## Post-delivery evaluation
75
+
76
+ Publication and effectiveness evaluation are separate milestones. Close the
77
+ delivery issue normally, while retaining a linked review task with an owner and
78
+ declared candidate-opportunity sample trigger. Review before the next policy
79
+ change even if that trigger is not met.
80
+
81
+ At review time, check sufficiency first. Record retain/change/defer, expected
82
+ versus observed behavior, regressions and uncertainty. Replace the latest
83
+ review instead of accumulating empty templates. If data remains absent, defer
84
+ explicitly and revise the collection action; never fabricate a favorable result.
85
+ No automatic reminder, paid advisor invocation, upload or self-tuning is
86
+ authorized by this workflow.
Binary file