Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
16 changes: 8 additions & 8 deletions CONTEXT.md
Original file line number Diff line number Diff line change
Expand Up @@ -59,9 +59,13 @@ _Avoid_: cron, scheduler (as concept names), night shift
### Fleet & serving

**Server mode**:
The per-machine stance for where Sessions are served from, in three values. `standalone` — this machine spawns and owns its own chat server (the default; the only mode that ever spawns). `server` — this machine runs the Canonical Server as a system service and the panel attaches to it. `client` — this machine never serves; the panel attaches to the Canonical Server through a Managed Tunnel. Machine-scoped, never synced: a synced "client" landing on the server would silence the fleet.
The per-machine stance for where Sessions are served from, in three values. `standalone` — this machine spawns and owns its own chat server (the default; the only mode that ever spawns). `server` — this machine runs the Canonical Server as a system service and the panel attaches to it. `client` — this machine never serves; the panel attaches to the Canonical Server through a Managed Tunnel. Determined by `~/.amico/ops/fleet/fleet.json` (no file = standalone). Machine-scoped, never synced.
_Avoid_: profile, spawn vs attach (as concept names)

**Fleet config**:
The file at `~/.amico/ops/fleet/fleet.json` that declares this machine's fleet role and the canonical server's coordinates (`host`, `port`, `sshAlias`). No file on disk = standalone. The guard script, extension, and installer all resolve role from this file — never from a hardcoded hostname.
_Avoid_: fleet.toml, fleet settings (those are VS Code settings, a different thing)

**Canonical Server**:
The one chat server that owns the fleet's Session store — the single writer every panel attaches to. Runs as a system service on the machine in `server` Server mode, available headless (no editor required). Only one may exist per Fleet.
_Avoid_: master, primary, host
Expand All @@ -70,13 +74,9 @@ _Avoid_: master, primary, host
The user's machines acting as one logical studio: exactly one Canonical Server plus zero-or-more clients, all attaching to the same Session store.
_Avoid_: mesh, cluster

**Local fallback**:
The deliberate, user-invoked escape hatch: a `client` machine temporarily serving itself locally (a `standalone` spawn) while the Canonical Server is unreachable. Explicit about its trade-off — fleet history returns on reconnect, and Sessions made during fallback merge back into the Canonical Server on rejoin. Never silent: an active Local fallback is a first-class, visible state.
_Avoid_: offline mode, degraded mode

**Rejoin**:
The closing half of Local fallback: on reconnect, the client ships its local Session shard to the Canonical Server, which merges it as the single writer (id-guarded inserts, strictly-newer-wins per row, event-position guard, schema-drift column mapping). After Rejoin, fleet history is whole again — nothing strands on the client.
_Avoid_: sync (bidirectional connotation), upload
**Go Standalone**:
The user-invoked mode switch from `client` to `standalone` — the machine leaves the fleet and serves itself permanently. Not an escape hatch: a first-class choice. Sessions made locally stay local. Re-enrollment in a fleet is a separate flow (Enroll, deferred).
_Avoid_: local fallback, offline mode, degraded mode

**Fleet token**:
The shared secret authenticating a client to the Canonical Server's data routes — minted when the fleet server is enabled, stored at 0600, handed to clients during the ssh-based setup flow. The sibling of the per-boot server password (ADR 0002): that guards a spawned server its extension owns; this guards the service no extension spawns.
Expand Down
12 changes: 2 additions & 10 deletions packages/extension/package.json
Original file line number Diff line number Diff line change
Expand Up @@ -179,16 +179,8 @@
"title": "Amicode: Fleet — Repair (guard + tunnel)"
},
{
"command": "amicode.fleet.fallback.enter",
"title": "Amicode: Fleet — Enter Local Fallback (work offline)"
},
{
"command": "amicode.fleet.fallback.exit",
"title": "Amicode: Fleet — Exit Local Fallback (restore tunnel)"
},
{
"command": "amicode.fleet.rejoin",
"title": "Amicode: Fleet — Rejoin (merge fallback sessions)"
"command": "amicode.fleet.goStandalone",
"title": "Amicode: Fleet — Go Standalone (leave fleet, run locally)"
},
{
"command": "amicode.repo.sync",
Expand Down
8 changes: 3 additions & 5 deletions packages/extension/scripts/assert_fleet_guard.sh
Original file line number Diff line number Diff line change
Expand Up @@ -12,11 +12,10 @@ ok() { echo "[fleet-gate] ok $*"; }

[[ -f "$GUARD" ]] || fail "guard missing at $GUARD (fleet hardening not merged?)"
[[ -x "$GUARD" ]] || fail "guard not executable — chmod +x $GUARD"
grep -q 'Aarons-Mac-mini' "$GUARD" || fail "guard does not mention canonical host Aarons-Mac-mini"
grep -q 'fleet.json' "$GUARD" || fail "guard does not reference fleet.json config"
grep -q 'exit 1' "$GUARD" || fail "guard missing client exit 1 (would not prevent fork)"
grep -q 'FROZEN.*\.amico/server/bin/opencode' "$GUARD" || fail "guard missing frozen binary path"
grep -q 'FALLBACK.*\.amico/ops/fleet/fallback.json' "$GUARD" || fail "guard missing fallback marker check (CONTEXT.md Local fallback)"
grep -q 'Local fallback' "$GUARD" || fail "guard missing Local fallback comment/hint"
grep -q 'FLEET_CONFIG' "$GUARD" || fail "guard missing FLEET_CONFIG variable"
ok "guard $GUARD"

[[ -f "$INSTALL" ]] || fail "installer missing at $INSTALL"
Expand All @@ -32,8 +31,7 @@ ok "tunnel plist $PLIST"

# Guard + tunnel template are the source of truth for the installer; ensure the
# installer itself is consistent (it references both).
grep -q "FLEET_GUARD_REL" "$ROOT/packages/extension/src/fleet_health.ts" || fail "fleet_health.ts missing FLEET_GUARD_REL"
grep -q "FLEET_PORT.*4096" "$ROOT/packages/extension/src/fleet_health.ts" || fail "fleet_health.ts missing FLEET_PORT 4096"
grep -q "FLEET_GUARD_REL\|FLEET_CONFIG_PATH\|fleet.json" "$ROOT/packages/extension/src/fleet_health.ts" || fail "fleet_health.ts missing fleet config reference"

# Packaged copy must stay in sync with repo root (the VSIX ships the packaged copy).
PKG_GUARD="$ROOT/packages/extension/tools/fleet/amico-opencode-fleet-guard"
Expand Down
Loading
Loading