You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Commit 6a21c37
Browse filesBrowse the repository at this point in the historyBrowse files
docs(custody): source the host-write race and collapse unobservable main-slot states
auth/index.ts:73-89 is all() -> spread -> writeJson with no lock, no CAS, and
a non-atomic in-place write (util/filesystem.ts:61-84); the gap is tracked as
anomalyco/opencode#46128. Record the whole-file last-writer-wins across
providers, the deterministic OPENCODE_AUTH_CONTENT clobber as a checkable
precondition, the provider-specific severity (unverified for Anthropic), the
four fence-free mitigation candidates, and the strictness resolution proposed
for the raced-login question. Through the SDK an unparseable main slot is
indistinguishable from an absent one, so GONE collapses to SLOT_ABSENT for
main; the distinction survives only for fallback rows in our own store.
Copy file name to clipboardExpand all lines: docs/custody-state-machine.md
+58-8Lines changed: 58 additions & 8 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -99,7 +99,7 @@ Evaluated independently for main and for **each enabled OAuth fallback**.
99
99
|---|---|---|
100
100
|`mode`|`local` · `claustrum`| global, durable; the only global write in the barrier |
101
101
|`binding`|`VALID` · `INVALID` · `ABSENT`| the account's entry `{label, handle, credentialId}` in our provider block of the shared handle manifest. `INVALID` = entry present, handle or credentialId fails validation |
102
-
|`local`|`REAL` · `INERT` · `GONE`| main: `REAL` = usable material, `INERT` = recognise-set tombstone, `GONE` = `SLOT_ABSENT` or `SLOT_UNPARSEABLE`. Fallback: `REAL` = usable refresh material, `INERT` = refresh material absent, row otherwise valid, `GONE` = `ROW_UNPARSEABLE` (a row that is *absent* while a binding exists is the discovery operation, §7, not a coordinate) |
102
+
|`local`|`REAL` · `INERT` · `GONE`| main: `REAL` = usable material, `INERT` = recognise-set tombstone, `GONE` = slot absent **as observed through the SDK**. An unparseable main slot is unobservable: `Auth.all()` runs `Record.filterMap(decode)` (`auth/index.ts:65-66`), so a slot failing the `Info` schema reads as `undefined` and any later host write rewrites the file without it; for main, `GONE ≡ SLOT_ABSENT`. Fallback: `REAL` = usable refresh material, `INERT` = refresh material absent, row otherwise valid, `GONE` = `ROW_UNPARSEABLE` (our own store, so the distinction survives there; a row that is *absent* while a binding exists is the discovery operation, §7, not a coordinate) |
103
103
|`vault`|`USABLE` · `COLD` · `REAUTH` · `N/A`| resolved through the binding's handle. `COLD` = daemon unreachable or credential not resident (transient). `REAUTH` = record latched `needs_reauth`. `N/A` ⇔ `binding ∈ {ABSENT, INVALID}`|
104
104
105
105
Two facts about `GONE` for main, both from OpenCode source (`339536bc22`), change what it means:
@@ -163,7 +163,7 @@ vault-owned family.
163
163
| C6 | ABSENT | REAL | N/A |`NOT_ENROLLED`|**no**|**no** (this mode has no local refreshers) | none | none |`ck auth bind` after import, or `local`|
| C8 | INVALID | any | N/A |`CORRUPT_BINDING`|**no**|**inert**|**none**: never auto-repair a manifest entry | none |`ck auth bind --replace`, or `local`|
166
-
| C9 | VALID | GONE (main) | USABLE · COLD · REAUTH |`RESTORE_TOMBSTONE` → re-classify as C1 / C3 / C4 | per re-class | inert |`auth.json` ← WRITE set, **awaited in the factory before the loader pass**. `SLOT_UNPARSEABLE` logs a `warn` naming the fact, never the content, before overwriting. Write failure → `FAIL_CLOSED`, typed `main unavailable: slot unrestorable`| next boot | none on success |
166
+
| C9 | VALID | GONE (main) | USABLE · COLD · REAUTH |`RESTORE_TOMBSTONE` → re-classify as C1 / C3 / C4 | per re-class | inert |`auth.json` ← WRITE set, **awaited in the factory before the loader pass**. **BLOCKED under §13.1** (same host-write race as the install). Write failure → `FAIL_CLOSED`, typed `main unavailable: slot unrestorable`. (An unparseable slot cannot be distinguished from an absent one through the SDK, so no separate warn is possible; the host itself drops such an entry on its next write)| next boot | none on success |
167
167
| C10 | VALID | GONE (fallback = `ROW_UNPARSEABLE`) | any |`CORRUPT_ROW`|**no**| inert |**none**; state secrets retained | next reconcile | repair the row, or remove + re-discover |
168
168
169
169
Invariants pinning the combinations not rowed:
@@ -341,10 +341,51 @@ Everything the barrier fences is ours: config, sidecar, manifest, per-account re
341
341
-`RESTORE_TOMBSTONE` (C9) has the same race in the other direction: a login can land in the absent
342
342
slot between the factory's read and its awaited write.
343
343
344
-
The fingerprint is therefore **crash reconciliation only** (§4). What is needed is a
345
-
synchronisation mechanism grounded in OpenCode source: a lock `Auth.set` honours, a compare-and-set
346
-
primitive on the slot, an event that observes the write, or a host-side change. None was found in
347
-
`339536bc22`; the search was not exhaustive.
344
+
The fingerprint is therefore **crash reconciliation only** (§4).
345
+
346
+
**Source of the race** (OpenCode `339536bc22`, `packages/opencode/src/auth/index.ts:73-89`):
347
+
`Auth.set` is `all()` → spread → `writeJson`. No lock, no compare-and-set, no expected-value check,
348
+
and the write itself is **not atomic**: `util/filesystem.ts:61-84` is an in-place `writeFile`, not
349
+
temp-and-rename, so a concurrent reader can observe a partial file. No write event exists, and the
350
+
loader is memoised init-once. There is nothing at the host to honour; the gap is tracked upstream as
0 commit comments