fix(amika): use Admin workspace profile keys

.github/workflows/ci.yml

@@ -55,6 +55,7 @@ jobs:
             libwebkit2gtk-4.1-dev \
             libayatana-appindicator3-dev \
             librsvg2-dev \
+            expect \
             patchelf \
             sqlite3
       - name: Report Linux FUSE coverage
@@ -75,6 +76,8 @@ jobs:
         run: cargo test --workspace --all-targets
       - name: Run real Linux FUSE smoke test
         run: LOCALITY_FUSE_SMOKE=1 LOCALITY_FUSE_SMOKE_REQUIRED=1 tests/linux_fuse_smoke.sh
+      - name: Run Amika snapshot shell test
+        run: make test-init-amika-locality-snapshot
       - name: Install desktop dependencies
         run: npm ci
         working-directory: apps/desktop

Makefile

@@ -189,7 +189,7 @@ audit-oauth-service: $(OAUTH_SERVICE_NODE_MODULES_STAMP) ## Audit OAuth service
 	$(OAUTH_SERVICE_NPM) audit
 
 .PHONY: test
-test: test-rust ## Run the default test suite.
+test: test-rust test-init-amika-locality-snapshot ## Run the default test suite.
 
 .PHONY: test-rust
 test-rust: ## Run all Rust workspace tests.
@@ -239,6 +239,10 @@ test-launch-readiness-wrappers: ## Validate launch-readiness wrapper defaults.
 	tests/launch_readiness_aws_wrapper.sh
 	tests/init_amika_locality_snapshot.sh
 
+.PHONY: test-init-amika-locality-snapshot
+test-init-amika-locality-snapshot: ## Validate secure Amika snapshot initialization and interruption cleanup.
+	tests/init_amika_locality_snapshot.sh
+
 .PHONY: fmt
 fmt: ## Format Rust code.
 	$(CARGO) fmt --all

docs/cli.md

@@ -73,14 +73,20 @@ Library callers cannot opt out accidentally: convenience sandbox, profile-key,
 session-credential, and generation-2 materialization APIs inspect the default
 state root, while `*_at_state_root` variants accept an explicit state root.
 
-For a fresh remote Amika environment, the repository helper creates a sandbox,
+For a remote Amika environment, the repository helper creates a fresh sandbox,
 checks out the current repository revision for scenario evidence, downloads the
 versioned Locality `v0.3.7` Linux package, verifies its pinned SHA-256, extracts
 the released `loc` binary without installing desktop dependencies, and streams
-a one-time bootstrap token to `loc sandbox init` over standard input. After
+a reusable Workspace Profile key from the Admin UI to `loc sandbox init` over
+standard input. After
 materialization, the helper runs its inline Notion-only launch-gate scenario,
 prints the prompt, and prints `/home/amika/final_report.md`.
 
+The local machine needs `amika`, `git`, Python 3.11 or newer, and `expect` on `PATH`.
+Install Expect with `brew install expect` on macOS or `sudo apt-get install
+expect` on Debian/Ubuntu. Expect provides the PTY transport used to stream the
+credentials without putting them in arguments or logs.
+
 The helper uses the existing Azure Codex setup. Export the Azure key locally;
 the script streams it directly to the remote Codex process without placing it
 in command arguments or writing it to a sandbox file:
@@ -89,22 +95,41 @@ in command arguments or writing it to a sandbox file:
 export AZURE_OPENAI_API_KEY=<azure-key>
 ```
 
-Then read a reusable Workspace Profile key from the administration portal without
-adding it to shell history
-and run the helper from this repository:
+In `https://api.dev.locality.dev/admin/access`, select a ready Workspace Profile
+and create a key. The plaintext is shown once. Read it without adding it to
+shell history and run the helper from this repository:
 
 ```bash
-read -rs LOCALITY_BOOTSTRAP_TOKEN
+read -rs LOCALITY_PROFILE_KEY
 printf '%s\n' "$LOCALITY_PROFILE_KEY" | \
   scripts/init-amika-locality-snapshot.sh \
     --api-url https://api.dev.locality.dev
 unset LOCALITY_PROFILE_KEY
 ```
 
-The key can launch multiple short-lived sandboxes until revoked. The helper creates a uniquely named sandbox, publishes
-the workspace at `/home/amika/locality-snapshot`, uses only `/home/amika` paths
-in the prompt, and leaves the sandbox running for inspection. Use `--name` when
-a stable sandbox name is needed.
+The key remains reusable until it expires or is revoked. The helper creates a
+uniquely named sandbox, publishes the workspace at
+`/home/amika/locality-snapshot`, uses only `/home/amika` paths in the prompt,
+and leaves the sandbox running for inspection. It refuses `--reuse`: repository
+cleanliness cannot make an existing sandbox a trusted boundary for a Workspace
+Profile key or Azure credential. A name collision fails before either
+credential is sent. The helper never deletes or replaces the colliding sandbox.
+If replacement is intended, make that destructive action separately and
+explicitly, then rerun the helper:
+
+```bash
+amika sandbox delete --remote --force --delete-volumes saga-locality-snapshot
+printf '%s\n' "$LOCALITY_PROFILE_KEY" | \
+  scripts/init-amika-locality-snapshot.sh \
+    --api-url https://api.dev.locality.dev \
+    --name saga-locality-snapshot
+```
+
+Revoke the temporary Workspace Profile key in Admin after testing.
+An existing generation-2 root is owned by the exact Profile key bytes used to
+create it. Creating a new key for the same Workspace Profile does not authorize
+refresh of that old root. After revocation, use a fresh sandbox and materialize
+a new root with the new key.
 
 ## Provider Connections