diff --git a/library/qa/quality/2026-07-05-qa-report-prd-003-fleet-lifecycle.md b/library/qa/quality/2026-07-05-qa-report-prd-003-fleet-lifecycle.md
new file mode 100644
index 0000000..98678f7
--- /dev/null
+++ b/library/qa/quality/2026-07-05-qa-report-prd-003-fleet-lifecycle.md
@@ -0,0 +1,136 @@
+# QA Report: PRD-003 Fleet Lifecycle (nectar scope)
+
+**Plan document:** `library/requirements/backlog/prd-003-fleet-lifecycle-login-and-uninstall/` (superproject; index + 003a + 003b)
+**Audit date:** 2026-07-05
+**Base branch:** `main` (audit target: UNCOMMITTED changes)
+**Head:** `feature/fleet-lifecycle` @ nectar (uncommitted working tree)
+**Auditor:** quality-worker-bee
+**Ordering:** `security-worker-bee` ran first and remediated in place (report: `library/qa/security/2026-07-04-security-audit-prd-003-fleet-lifecycle.md`). No ordering violation.
+**Scope:** nectar-side ACs only: a-AC-1/2/3/5/6/7, b-AC-1..6, module AC-8/AC-9. AC ledger: `library/ledger/EXECUTION_LEDGER-fleet-lifecycle.md` (superproject).
+
+## Summary
+
+**PASS.** All fifteen nectar-scope acceptance criteria trace to implementation and named tests; the three security remediations (H1 atomic credentials write, M1 win32 `shell: true` npm probe, M2 https-validated printed URL plus terminal sanitization) regressed no AC, and the credentials writer's temp+rename rewrite provably preserves byte-compatibility with honeycomb's `DiskCredentials` shape. One Warning was found and remediated in place during this audit (the accepted "no hot-attach of brood/enricher on credential appearance" deviation was undocumented; a code comment now records it at the credentials-watch wiring). Gates after remediation: build clean, typecheck clean, 828 tests with 821 passing, 0 failing, 7 skipped (5 platform-conditional POSIX-mode skips on win32 plus the 2 documented environment-flaky live Deeplake probes, which self-skipped as "Deep Lake unreachable" this run; both files untouched by this branch and green in CI under `nectar_ci`).
+
+## Scorecard
+
+| Category      | Status | Notes |
+|---------------|--------|-------|
+| Completeness  | ✅ | All 15 nectar-scope ACs implemented with AC-named tests. |
+| Correctness   | ✅ | Security remediations verified non-regressive; gates green; login exit codes correct (0/1/2). |
+| Alignment     | ✅ | Bare verbs + aliases per orchestrator decision 4; three-part uninstall order matches the PRD's stop, unit, registry, state-dir sequence. |
+| Gaps          | ⚠️ | One documentation gap (undocumented accepted deviation), remediated in place during this audit. |
+| Detrimental   | ✅ | No regressions: existing verbs and handlers untouched; additive daemon options default to pre-003a behavior when unset. |
+
+## Critical Issues (must fix)
+
+None.
+
+## Warnings (should fix)
+
+- [x] **Accepted deviation "no hot-attach of brood/enricher on credential appearance" was undocumented**, `src/cli.ts:1345-1360` (pre-fix)
+
+  The W1-N ledger entry (2026-07-04 22:56) records the accepted deviation: a no-credentials boot does not hot-attach the brood/enricher subsystems when credentials later appear; only `/health` flips and active projects reconcile. Nothing in the code or knowledge docs recorded this, so a maintainer reading the credentials-watch wiring would reasonably assume login-after-boot fully activates the daemon. **REMEDIATED IN PLACE** (authorized by the audit dispatch): a concise `ACCEPTED DEVIATION` comment now sits at the `credentialsWatch` wiring in `runDaemon`, naming the dormant subsystems, the restart requirement, the honeycomb parity, and where a future hot-attach belongs (`daemon.ts` `onChange`). Comment-only change; build, typecheck, and the full suite re-ran green after it.
+
+  ```ts
+  // ACCEPTED DEVIATION (W1-N, ledger 2026-07-04): credentials appearing after
+  // boot flip /health healthy and reconcile active projects, but the
+  // creds-dependent subsystems assembled above from this boot-time snapshot
+  // (the durable store, brood wiring, enricher loop) are NOT hot-attached;
+  ```
+
+## Suggestions (consider improving)
+
+- [ ] **No leftover-temp-file assertion in the credentials-writer suite**, `test/credentials-writer.test.ts:22-58`
+
+  The registry deregister suite asserts the atomic rename left no `.tmp` file (`test/doctor-registry-deregister.test.ts:38`); the credentials-writer suite (which covers the security H1 temp+rename rewrite) does not. The happy path cannot leave one (rename consumes it) and the failure path force-removes it, but a one-line `readdirSync(dir)` assertion would pin the contract the same way the registry test does.
+
+- [ ] **`nectar install` auto-login still runs when the service-unit install failed**, `src/cli.ts:335-366`
+
+  `maybeAutoLoginOnInstall()` runs unconditionally after the registry write, so a machine where the unit install failed (`serviceResult.ok === false`, eventual exit 1) can still open a sign-in browser popup before the failure is reported. Best-effort login is by design and no AC forbids this, but gating the popup on `serviceResult.ok` would avoid a confusing popup-then-exit-1 sequence.
+
+- [ ] **Cross-repo note carried from the security wave (out of nectar scope):** nectar's M1 fix (`shell: true` on win32 for the constant-argv `npm.cmd` probe, `src/fleet-detection.ts:157-178`) intentionally diverges from honeycomb, whose audit left the identical dead probe as a documented Low (S3 silently absent on Windows there, failing toward SOLO, the popup direction). Ruling: honeycomb SHOULD adopt the same fix for contract parity on the fleet's primary platform; the mirrored fleet-detection contracts now behave differently on win32. This is a honeycomb-repo change and is deferred to that repo's next cycle; no nectar AC is affected.
+
+## Audit-directive verification (the four dispatched items)
+
+### 1. Security remediations did not regress any AC
+
+- **H1 (atomic credentials write), `src/hive-graph/deeplake-credentials.ts:753-778`.** Byte-compatibility with honeycomb's `DiskCredentials` survives the temp+rename rewrite: both writers serialize `JSON.stringify(record, null, 2) + "\n"`; nectar's written field set (`token`, `orgId`, `orgName`, `userName`, `workspaceId`, `apiUrl`, `savedAt`) is a strict subset of honeycomb's shape (`honeycomb/src/daemon/runtime/auth/credentials-store.ts:85-111`, where `agentId` and `tenancyConfirmedAt` are optional additive fields); `savedAt` is stamped server-side in both. The tests still prove it: `test/credentials-writer.test.ts:40-48` `deepEqual`s the exact on-disk JSON against the honeycomb shape AFTER the rename, `:60-69` asserts 0600 survives the rename on POSIX, `:71-93` asserts the fresh dir is 0700, and `test/device-flow-login.test.ts:94-99` round-trips a full login write through `loadDeepLakeCredentials`. The rename-replaces-inode property (a pre-existing loose-mode file never carries the new token) is documented in the writer's doc block.
+- **M1 (win32 `shell: true` npm probe), `src/fleet-detection.ts:157-178`.** Scoped to win32 only; every argv element is a compile-time constant; non-Windows keeps `shell: false`. a-AC-6 classification tests (`test/fleet-detection.test.ts`) exercise the S3 seam and remain green; the fail direction (any error resolves `false`, absent signal) is unchanged.
+- **M2 (printed URL validation + terminal sanitization), `src/auth/device-flow.ts:289-311, 499-503, 218`.** The printed `verification_uri` now refuses non-https with a clear `{ ok: false }` message, which conforms to AC-9 (terminate with an actionable error) rather than regressing a-AC-7; the a-AC-7 ordering tests (print before open, opener failure tolerated, non-https complete URL never opened, poll exhaustion bounded at `DEFAULT_MAX_POLLS`) all pass.
+
+### 2. The no-hot-attach deviation is now documented
+
+Found undocumented (repo-wide grep for hot-attach/reattach/subsystem-on-credentials found nothing); remediated as the Warning above.
+
+### 3. Regression sweep
+
+The `main()` dispatch (`src/cli.ts:1476-1558`) keeps every pre-existing verb routed to its unchanged handler: `daemon`, `install`, `uninstall` (handler upgraded per 003b, see traceability), `service-status` (now an alias of the new `status`, same `runServiceStatus` handler), `rebuild-projection`, `brood`, `prune`, `review-matches`, `search`, `projects`, `brooding`, `project --rebuild-projection`. New verbs: `login`, `start`, `stop`, `status`. The USAGE banner (`src/cli.ts:112-149`) documents every verb that dispatches and nothing that does not; `test/cli-verbs.test.ts:32-50` proves `--help` lists the lifecycle verbs and exits 0. The daemon assembly changes are additive and opt-in: `storageCredentialsPresent` undefined leaves the legacy `ok` posture (`src/daemon.ts:539-550`), `credentialsWatch` undefined arms nothing (`src/daemon.ts:622-649`), and the full pre-existing suite (818 pre-branch tests) passes unmodified; no existing test file needed edits for the `ServiceUninstallResult` contract change because no pre-existing test consumed `ServiceModule.uninstall` directly.
+
+### 4. Login UX coherence (AC-3 / AC-9)
+
+- Success: `Signed in as <name>. Using org <name> (<id>), workspace <id>.` then `nectar login: signed in; credentials written to <path>.`, exit 0 (`src/cli.ts:394-401`, `src/auth/device-flow.ts:551-558`).
+- Failures are plain-language and actionable, exit 1: `sign-in timed out before it was approved; run 'nectar login' again.`; `the sign-in code expired; run 'nectar login' again`; `sign-in was denied`; multi-org refusal names `--org=<id>` and enumerates the available orgs; the non-https refusal names the cause.
+- Flag misuse exits 2 with `nectar login: --org requires a value` / `unknown flag '<flag>'` on stderr (`src/cli.ts:359-365, 388-393`).
+- Bounded termination: poll cap 900, retry budget 3, slow_down growth; `test/device-flow-login.test.ts:307-349` proves exhaustion terminates with the actionable message and writes no credentials.
+
+## Plan Item Traceability
+
+| # | Plan Requirement | Status | Implementation Location | Tests / Notes |
+|---|---|---|---|---|
+| a-AC-1 | Fleet install: no popup/prompt; daemon serves 503 degraded (storage unreachable) on /health | ✅ | `src/health.ts:159-173` (`setStorageState`), `src/daemon.ts:539-550`, `src/cli.ts:1350` | `test/fleet-lifecycle-health.test.ts:11-34`, socket-level 503 + machine-readable reason `test/fleet-lifecycle-daemon.test.ts:68-113` |
+| a-AC-2 | Credentials appearing flips /health healthy without restart | ✅ | `src/credentials-watch.ts:46-88`, `src/daemon.ts:622-649, 1027-1029` | `test/fleet-lifecycle-daemon.test.ts:135-171` (same running daemon, manual timer); change-only semantics `test/fleet-lifecycle-health.test.ts:50-80`. Accepted deviation (health-only recovery, no brood/enricher hot-attach) now documented at `src/cli.ts:1351-1358` |
+| a-AC-3 | Solo + no credentials: install auto-opens the popup; credentials present: no popup | ✅ | `decideInstallLoginAction` + `maybeAutoLoginOnInstall`, `src/cli.ts:377-418, 358` | `test/install-login-decision.test.ts:10-21`; best-effort (never fails the install) per the a-AC-3 note in the PRD ("auto-popup fires from the install path, not from every daemon boot"), honored: daemon boot never pops |
+| a-AC-5 | `nectar login` exists, opens the popup in both modes, credentials readable on next storage attempt | ✅ | `src/auth/device-flow.ts:475-568`, `src/cli.ts:387-401` | `test/device-flow-login.test.ts:71-105` (round-trip through `loadDeepLakeCredentials`), tenancy explicitness `:198-252` |
+| a-AC-6 | Deterministic solo/fleet classification; fired signals visible | ✅ | `src/fleet-detection.ts:187-207` (any signal = fleet; `fleetSignalLine`), logged at install `src/cli.ts:424` | `test/fleet-detection.test.ts:23-118` (all signal combinations + S1 file reads) |
+| a-AC-7 | Headless: URL + code printed, polls to completion, never hangs or crashes | ✅ | `src/auth/device-flow.ts:494-527` (print before open, bounded poll), opener `:320-335` | `test/device-flow-login.test.ts:107-196, 254-349` (ordering, open failure, non-https refusal, slow_down growth, poll-cap exhaustion) |
+| b-AC-1 | `start` and `stop` on macOS, Linux, Windows | ✅ | `src/service/argv.ts:143-190` (per-manager argv incl. `sc`), `src/service/index.ts:392-432`, `src/lifecycle.ts:62-117`, CLI `src/cli.ts:203-224` | `test/service-start-stop.test.ts:48-87`, `test/lifecycle.test.ts:64-157`. Fixed-argv tested, not live-smoked (same posture the W2 verifier accepted for honeycomb) |
+| b-AC-2 | `uninstall` removes the OS unit (current + best-effort legacy) so it no longer boots | ✅ | `src/service/index.ts:344-390` (classified `ServiceUninstallResult`), `deregisterLegacy` `:434-458`, hard-failure surfacing `src/lifecycle.ts:190-205` | `test/lifecycle.test.ts:178-239` (genuine failure exits 1; already-absent stays exit 0), `test/service-start-stop.test.ts:89-103` |
+| b-AC-3 | `uninstall` deletes nectar's doctor registry entry, other entries intact | ✅ | `src/doctor-registry.ts:520-608` (`deregisterFromDoctor`, fleet + legacy candidates, atomic rewrite) | `test/doctor-registry-deregister.test.ts:18-104` (preservation, malformed-file report, both candidate files, no temp residue) |
+| b-AC-4 | `uninstall` removes only nectar's state dir; no registry wholesale, no `~/.deeplake` | ✅ | `src/lifecycle.ts:146-158` (`removeStateDir`: absolute-only, no symlink follow), wired to `nectarStateDir()` `src/cli.ts:270-283` | `test/lifecycle.test.ts:306-329` (non-absolute refused, symlink skipped) |
+| b-AC-5 | Existing spellings keep working as aliases | ✅ | `src/cli.ts:1509-1512` (`status` \|\| `service-status` to the same handler); `daemon`/`install`/`uninstall` spellings unchanged | `test/cli-verbs.test.ts:15-30`. Nectar's pre-003 verb set was `daemon`/`install`/`uninstall`/`service-status`; all still dispatch |
+| b-AC-6 | `uninstall` on a not-installed machine exits 0 "nothing to remove" | ✅ | `src/lifecycle.ts:239-253` (`anythingRemoved` gate), already-absent classification `src/service/index.ts:186-215` | `test/lifecycle.test.ts:161-174` |
+| AC-8 (nectar scope) | No deletion outside the enumerated allow-list | ✅ | `removeStateDir` guards (absolute, no symlink, single resolved dir); registry rewrite preserves all other entries and unknown keys | `test/lifecycle.test.ts:318-329`, `test/doctor-registry-deregister.test.ts:18-42` |
+| AC-9 (nectar scope) | Every flow terminates with a clear success or plain-language actionable error | ✅ | Bounded polls (`DEFAULT_MAX_POLLS`, `DEFAULT_MAX_RETRIES`), exit codes 0/1/2, per-step uninstall reporting, non-TTY multi-org refusal naming flags | `test/device-flow-login.test.ts:307-349`, `test/lifecycle.test.ts:110-121, 279-292`, `test/cli-verbs.test.ts:32-50` |
+| NG (003a) | No change to device-flow protocol or credential file format | ✅ | The client ports honeycomb's wire shapes verbatim; the written file is a subset-compatible `DiskCredentials` | Verified under directive 1 above |
+| NG (003b) | `uninstall` does not remove the npm package, `~/.deeplake`, or other products' dirs | ✅ | `src/lifecycle.ts:252` prints the package-left-in-place note; no `~/.deeplake` path in any removal | Orchestrator decision 5 honored |
+| NG (003a) | Hive onboarding/login-step untouched; no gate reintroduced that fails on 503-degraded | ✅ | No hive files touched; nectar only serves the degraded posture, never probes it | Fleet 0.5.1 probe posture unmodified |
+
+## Remediations applied during this audit
+
+| # | Severity | Change | File |
+|---|---|---|---|
+| 1 | Warning | Documented the accepted no-hot-attach deviation with an `ACCEPTED DEVIATION` comment at the credentials-watch wiring (comment-only; gates re-run green) | `src/cli.ts:1351-1358` |
+
+## Baseline verification (after remediation)
+
+| Check | Result |
+|---|---|
+| `npm run build` | exit 0, clean |
+| `npm run typecheck` | exit 0, clean |
+| `npm test` | exit 0: 828 tests, 821 pass, 0 fail, 7 skipped. Skips: 4 POSIX-mode assertions on win32, 1 POSIX-only permission warning test, and the 2 documented environment-flaky live Deeplake probes (`hive-graph-deeplake` round-trip, 018h vector ordering), which self-skipped as "Deep Lake unreachable" this run; both files untouched by this branch and green in CI under `nectar_ci` |
+
+## Files Changed
+
+- `library/qa/security/2026-07-04-security-audit-prd-003-fleet-lifecycle.md` (A), the security wave's audit record (input to this report, not audited content)
+- `src/auth/device-flow.ts` (A), in-process zero-dependency Deeplake device-flow client: code request, bounded poll, explicit tenancy, mint, `/me`, credential persist (a-AC-5/7)
+- `src/cli.ts` (M), `login`/`start`/`stop`/`status` verbs, install auto-popup decision, three-part uninstall wiring, daemon boot storage posture + credentials watch, USAGE update
+- `src/credentials-watch.ts` (A), change-only poll watch that flips the /health storage posture without restart (a-AC-2)
+- `src/daemon.ts` (M), additive `storageCredentialsPresent` + `credentialsWatch` assemble options; watch armed on start, drained on shutdown
+- `src/doctor-registry.ts` (M), additive `deregisterFromDoctor` (fleet + legacy candidate files, atomic, best-effort per file) (b-AC-3)
+- `src/fleet-detection.ts` (A), three-signal solo/fleet classifier with injectable seams and the win32 `shell: true` npm probe (a-AC-6)
+- `src/health.ts` (M), additive `storage` health slice + `setStorageState` (the sole runtime `status` toggle) (a-AC-1/2)
+- `src/hive-graph/deeplake-credentials.ts` (M), additive `DiskCredentials` shape + atomic `saveDeepLakeCredentials` writer (0700 dir, 0600 temp+rename)
+- `src/lifecycle.ts` (A), start/stop/uninstall orchestration behind injectable seams; guarded `removeStateDir` (b-AC-1/2/3/4/6)
+- `src/service/argv.ts` (M), additive per-manager `startCommands`/`stopCommands` (b-AC-1)
+- `src/service/index.ts` (M), `ServiceModule.start`/`stop`/`deregisterLegacy` + classified `ServiceUninstallResult` with `isAlreadyAbsentFailure` (b-AC-1/2/6)
+- `test/cli-verbs.test.ts` (A), verb dispatch + alias + USAGE coverage (b-AC-5, AC-9)
+- `test/credentials-writer.test.ts` (A), on-disk shape byte-compatibility + POSIX modes (a-AC-5)
+- `test/device-flow-login.test.ts` (A), login flow end-to-end through fake fetch: ordering, headless, tenancy, slow_down, poll exhaustion (a-AC-5/7, AC-9)
+- `test/doctor-registry-deregister.test.ts` (A), registry delete preservation/atomicity/best-effort (b-AC-3)
+- `test/fleet-detection.test.ts` (A), classification determinism + evidence line (a-AC-6)
+- `test/fleet-lifecycle-daemon.test.ts` (A), socket-level 503 + no-restart recovery on a running daemon (a-AC-1/2)
+- `test/fleet-lifecycle-health.test.ts` (A), health-state storage posture unit coverage (a-AC-1/2)
+- `test/install-login-decision.test.ts` (A), install popup decision matrix + login flag parsing (a-AC-3/5)
+- `test/lifecycle.test.ts` (A), start/stop/uninstall orchestration incl. hard-failure vs already-absent classification and state-dir guards (b-AC-1/2/4/6, AC-8/9)
+- `test/service-start-stop.test.ts` (A), per-manager start/stop argv + legacy deregister (b-AC-1/2)
diff --git a/library/qa/security/2026-07-04-security-audit-prd-003-fleet-lifecycle.md b/library/qa/security/2026-07-04-security-audit-prd-003-fleet-lifecycle.md
new file mode 100644
index 0000000..260eea7
--- /dev/null
+++ b/library/qa/security/2026-07-04-security-audit-prd-003-fleet-lifecycle.md
@@ -0,0 +1,69 @@
+# Security Audit - PRD-003 (fleet lifecycle: device-flow login, credentials writer, lifecycle verbs)
+
+- **Date:** 2026-07-04
+- **Auditor:** security-worker-bee
+- **Scope:** UNCOMMITTED changes on `feature/fleet-lifecycle` @ `C:/Users/mario/GitHub/the-apiary/nectar` (HEAD `a5b1b56`): the new in-process device-flow client `src/auth/device-flow.ts`, the credentials writer additions in `src/hive-graph/deeplake-credentials.ts`, `src/credentials-watch.ts`, `src/fleet-detection.ts`, `src/lifecycle.ts`, the doctor-registry deregister (`src/doctor-registry.ts`), service start/stop argv (`src/service/argv.ts`, `src/service/index.ts`), health storage posture (`src/health.ts`, `src/daemon.ts`), and the CLI login/install/start/stop/uninstall wiring (`src/cli.ts`), plus the ten new test suites.
+- **Ordering:** ran BEFORE `quality-worker-bee`. The only quality report on disk (`library/qa/quality/2026-07-02-wave-cde-quality-closeout.md`) predates this branch's work and does not cover it; no ordering inversion.
+- **Threat model:** same class as Hivemind - Deeplake credentials (`~/.deeplake/credentials.json`), device-flow auth against `api.deeplake.ai`, loopback daemon. This repo is zero-runtime-dependency TypeScript/Node, so the Deeplake SQL, MCP, and harness catalog items do not apply here; credential/token handling, subprocess hygiene, and filesystem containment items apply in full.
+
+---
+
+## Executive summary
+
+**One High finding and two Medium findings, all remediated in-session. Four Low findings documented and accepted. No Critical findings. Gates green post-fix (the single full-suite failure is the known environment-flaky live Deeplake ordering probe, excluded from judgment).**
+
+## Findings
+
+| # | Severity | Location | Finding | Disposition |
+|---|---|---|---|---|
+| H1 | **High** | `src/hive-graph/deeplake-credentials.ts:216-228` (pre-fix) | The credentials writer used a direct `writeFileSync` on the SHARED `~/.deeplake/credentials.json`. Two consequences: (a) a crash mid-write leaves a truncated/partial token file that breaks BOTH nectar and honeycomb until re-login (and flaps nectar's own credentials watch, which polls this file); (b) `writeFileSync`'s `mode: 0o600` applies only at file CREATION, so a pre-existing group/other-readable file (hand-written, or laid down loose by another tool) would receive the freshly minted long-lived org-bound token while STAYING world-readable - credential exposure, never-downgrade class. | **Fixed**: atomic same-directory temp + rename. The temp file is created at `0600` from birth (no write-then-chmod window), the rename replaces the old inode so a loose-mode predecessor never carries the new token, and the token-bearing temp is force-removed on any failure so no partial file survives. Verified by `test/credentials-writer.test.ts` (mode + shape assertions still green). |
+| M1 | Medium | `src/fleet-detection.ts:154-175` (pre-fix) | The S3 npm probe ran `execFile("npm.cmd", ..., { shell: false })` on win32. Since Node's CVE-2024-27980 hardening (all Node >= 20.12, and this repo requires >= 22), spawning a `.cmd` with `shell: false` throws EINVAL, so the probe's catch resolved `false` on EVERY Windows machine - silently blinding one of the three signals that suppress the auto sign-in popup, weakening the fleet-detection control on the product's primary platform. | **Fixed**: `shell: true` on win32 only. Safe here because every argv element is a compile-time constant (`ls -g @legioncodeinc/hive --depth 0`); no user input reaches the command line. Non-Windows platforms keep `shell: false`. |
+| M2 | Medium | `src/auth/device-flow.ts:481` and `:218` (pre-fix) | Server-derived strings reached the terminal unvalidated: the PRINTED `verification_uri` skipped the https-only check (only the browser-open path validated), and `verification_uri`, `user_code`, and truncated HTTP error bodies were echoed raw, allowing ANSI/control-character terminal escape injection from a compromised or spoofed auth response. Printing a non-https URL also instructs the user to open it manually, sidestepping the opener's https guard. | **Fixed**: the printed URL now goes through `validateVerificationUrl` and the flow refuses (clear `{ ok: false }` message, no hang) on a non-https `verification_uri`; a new `sanitizeForTerminal` strips C0/C1 control characters (including ESC) from the printed user code and from the truncated error bodies carried in `AuthHttpError`. |
+| L1 | Low | `src/hive-graph/deeplake-credentials.ts`, `src/doctor-registry.ts:217` | Predictable temp-file names (`pid` + timestamp) for the atomic writes. | Documented, accepted: consistent with the prior audit's accepted posture (2026-07-04 L4); the credentials dir is owner-only (`0700`) and the registry dir lives under the user-owned fleet root; rename is atomic. |
+| L2 | Low | `src/service/index.ts` `isAlreadyAbsentFailure` | The generic case-insensitive text fallback (`does not exist|cannot find|no such process|not[- ]loaded|could not find|not found`) could misclassify a GENUINE uninstall failure whose stderr coincidentally contains one of those phrases (for example a "config file not found" sub-error) as already-absent, masking a boot-resurrecting unit while `nectar uninstall` reports a friendly no-op. The locale-independent numeric checks (sc 1060, launchd exit 3) are correct. | Documented, accepted for now: the misclassification window is narrow, the conservative default (anything unmatched is a genuine failure) points the right way, and a per-manager pre-flight status query would be the robust follow-up. |
+| L3 | Low | `src/hive-graph/deeplake-credentials.ts` `saveDeepLakeCredentials` | The writer does not tighten a PRE-EXISTING loose-mode `~/.deeplake` DIRECTORY (`0700` applies only when nectar creates it), and `existsSync` follows a symlinked `~/.deeplake` into its target. The loader's `warnIfWorldReadable` advisory covers the file, not the dir. | Documented, accepted: the dir is shared with honeycomb/hivemind and chmod-ing it from nectar risks cross-tool surprise; a symlinked `~/.deeplake` requires home-directory write access, at which point the attacker already owns the trust boundary. |
+| L4 | Low | `src/auth/device-flow.ts` `resolveTenancy` | An explicit `--org=<id>` not present in the enumerated org list is accepted (`orgs.find(...) ?? { id: flags.org, name: flags.org }`) and passed to the mint. | Documented, accepted by design: the server is the authorization authority and refuses a mint for an org the account cannot access; the client-side list is UX, not an access control. |
+
+## Focus-area verification (checked clean)
+
+1. **Auth client token hygiene** (`src/auth/device-flow.ts`):
+   - The token rides ONLY in the `Authorization: Bearer` header (`authHeaders`); it never appears in a URL, log line, error message, or the `out` sink. `AuthHttpError` carries status + truncated server body only; the catch-all in `runDeviceFlowLogin` surfaces `err.message`, never response payloads that carry tokens (the only token-bearing responses are `resp.ok` paths that never feed an error).
+   - `device_code` is never printed; only `user_code` (by design, the user must type it) and the validated verification URL reach the terminal.
+   - Browser opener: fixed-argv `execFileSync`, `shell` never set (no shell), 5s timeout, `stdio: "ignore"`, https-only gate BEFORE any spawn; `open` (darwin) / `rundll32 url.dll,FileProtocolHandler` (win32) / `xdg-open` (else). Opener failure returns `false`, never crashes the flow (proven by `test/device-flow-login.test.ts` a-AC-7 cases).
+   - Poll floors honored: `Math.max(grant.interval || 5, 5) * 1000` floors at 5s, `slow_down` adds 5s and never shrinks, the poll count is hard-capped at `DEFAULT_MAX_POLLS` (900), and the retry budget for 429/5xx is bounded (3, exponential backoff). No hammering path exists.
+   - No token in any spawned process argv: the opener receives only the URL; the daemon direct-spawn (`src/cli.ts` `spawnDaemonDetached`) passes only `--experimental-sqlite <script> daemon`.
+2. **Credentials writer** (`src/hive-graph/deeplake-credentials.ts`): post-H1-fix the write is atomic (same-dir `0600` temp + rename), no partial file survives failure, no world-readable window exists at any point (mode set at open, rename swaps inodes), `savedAt` is stamped server-side ignoring caller input, and the dir is created `0700` when absent (test-verified on POSIX). Symlinked-dir posture documented as L3.
+3. **Fleet detection** (`src/fleet-detection.ts`): the S2 loopback probe is bounded by a 750ms `AbortController` with an unref'd, cleared timer; malformed or non-object registry JSON is tolerated (`registryFileHasHive` returns `false`, never throws); the S3 npm probe is fixed-argv `execFile` with a 5s timeout (M1 fixed the win32 leg). Fail direction is explicit and documented: any signal fires means FLEET (popup suppressed).
+4. **Uninstall / lifecycle** (`src/lifecycle.ts`, `src/cli.ts`, `src/doctor-registry.ts`): state-dir removal takes the RESOLVED absolute `nectarStateDir()` only (non-absolute refused), refuses a symlinked dir via `lstat` (no follow), and `rmSync(recursive)` does not follow symlinks inside the tree; only the `nectar` subdirectory of the fleet root is removed, never the root or another product's dir. The registry deregister rewrites atomically (temp + same-dir rename), removes ONLY entries with `name === "nectar"`, preserves every other daemon entry and unknown top-level key, reports (never clobbers) a present-but-malformed file, and treats an absent file as a clean no-op. A genuine current-unit removal failure is a hard exit-1, never swallowed (`ServiceUninstallResult.alreadyAbsent` classification).
+5. **Credentials watch** (`src/credentials-watch.ts`): a single `PollLoop` with a floored cadence (config floor 1s, default 30s), change-only `onChange` (never re-fires on the same value), idempotent start/stop with drain; the per-tick cost is one small-file read + parse. No unbounded resource growth, no re-read amplification.
+6. **Service start/stop argv** (`src/service/argv.ts`): every command is a constant-argv shape (`launchctl kickstart`/`bootout`, `systemctl start|stop`, `schtasks /Run|/End`, `sc start|stop`) executed through the existing `execFile` runner with `shell: false`; the only variables are the numeric `uid` and compile-time label constants.
+7. **Health surface** (`src/health.ts`, `src/daemon.ts`): the `storage.reason` value is the machine-readable constant `"credentials-missing"`; no path, org id, or token detail is added to the loopback `/health` body. Daemon log lines on the watch's `onChange` carry fixed strings, never credential values.
+8. **Supply chain:** `npm audit` reports 0 vulnerabilities (the package has zero runtime dependencies); no new dependencies were introduced by this branch.
+9. **Token-in-logs sweep:** repo-wide regex sweep over the changed files for token/secret-bearing writes to stdout/stderr/logs found none.
+
+## Files changed by remediation
+
+| File | Change |
+|---|---|
+| `src/hive-graph/deeplake-credentials.ts` | H1: atomic `0600` temp + rename write, temp cleanup on failure, doc update. |
+| `src/fleet-detection.ts` | M1: win32-only `shell: true` for the constant-argv `npm.cmd` probe, doc update. |
+| `src/auth/device-flow.ts` | M2: https-only validation of the PRINTED verification URL (refuse on non-https), new `sanitizeForTerminal` applied to the printed user code and truncated error bodies. |
+
+## Baseline verification (after remediation)
+
+| Check | Result |
+|---|---|
+| `npm run build` | clean |
+| `npm run typecheck` | clean |
+| Full `npm test` | 1 failing = `test/hive-graph-search-live.test.ts` (the known environment-flaky live Deeplake ordering probe; excluded from judgment per the orchestrator), 6 skipped (platform-conditional); everything else green |
+| Targeted suites (`device-flow-login`, `credentials-writer`, `fleet-detection`, `install-login-decision`, `lifecycle`) | 42 tests: 40 pass, 2 skipped (POSIX-mode checks on win32), 0 fail |
+| `npm audit` | 0 vulnerabilities |
+
+## Tooling note
+
+The workspace-mandated Aikido MCP scan was attempted on the remediated files but the local scanner is degraded: Opengrep exits with code 2 and returns an empty issues array (with an identical boilerplate log regardless of input), and the Checkov binary is missing (`checkov.exe ENOENT`). Run `/aikido:setup` to repair it; the manual catalog-driven audit above is the effective coverage for this branch.
+
+## Follow-ups (not blocking)
+
+- L2: consider a pre-flight `statusCommand` query in `ServiceModule.uninstall` so already-absent is determined by state, not stderr text matching.
+- The device-flow client does not honor the grant's `expires_in` (it relies on the 900-poll cap and the server's `expired_token` signal); wiring `expires_in` into the loop bound would tighten the failure message. Cosmetic.
diff --git a/src/auth/device-flow.ts b/src/auth/device-flow.ts
new file mode 100644
index 0000000..f5dfb4e
--- /dev/null
+++ b/src/auth/device-flow.ts
@@ -0,0 +1,568 @@
+/**
+ * The `api.deeplake.ai` device-flow login client for `nectar login` (PRD-003a
+ * a-AC-5 / a-AC-7).
+ *
+ * nectar previously had no login verb - it only READ the shared
+ * `~/.deeplake/credentials.json` and sat degraded until someone else wrote it.
+ * This module gives nectar its own in-process device-flow client so a solo
+ * install can self-serve. It speaks the SAME backend honeycomb speaks and ports
+ * honeycomb's request/response shapes VERBATIM from
+ * `honeycomb/src/daemon/runtime/auth/deeplake-issuer.ts` (READ as reference,
+ * reimplemented with Node built-ins per ADR-0002, never imported), so the
+ * written credential is byte-compatible and one login authenticates both tools.
+ *
+ * The HTTP contract:
+ *   - POST {apiUrl}/auth/device/code   -> { device_code, user_code, verification_uri,
+ *                                           verification_uri_complete, expires_in, interval }
+ *   - POST {apiUrl}/auth/device/token  -> { access_token, ... }, or 400 {error:
+ *                                           "authorization_pending"|"slow_down"|"expired_token"|"access_denied"}
+ *   - GET  {apiUrl}/organizations      -> [{ id, name }]
+ *   - GET  {apiUrl}/workspaces         -> { data: [{ id, name }] } or [{ id, name }]
+ *   - POST {apiUrl}/users/me/tokens    -> mint a long-lived org-bound token { token: { token } }
+ *   - GET  {apiUrl}/me                 -> { id, name, email? } (validate + display name)
+ *
+ * Ordering that a-AC-7 (headless) requires: the verification URL + user code are
+ * PRINTED before any browser-open attempt, and the browser opener never crashes
+ * or hangs the flow (a fixed-argv, no-shell, timed-out open that returns false
+ * on failure). The flow then polls to completion regardless of whether a browser
+ * opened.
+ *
+ * Tenancy is chosen EXPLICITLY, never a silent `orgs[0]` guess (parent AC-6):
+ * `--org`/`--workspace` flags win; a single org/workspace auto-selects; multiple
+ * prompt on a TTY; a non-TTY with no flags fails with a plain-language error
+ * naming the flags.
+ *
+ * The token is a SECRET: it rides ONLY in the `Authorization: Bearer` header,
+ * never a URL, log, or error message; the browser opener REFUSES any non-`https:`
+ * `verification_uri_complete`. Every seam (fetch, sleep, opener, tty, output,
+ * clock) is injectable so tests never hit the network or a real browser.
+ *
+ * Built-ins only (`node:child_process` for the opener) + the global `fetch`.
+ */
+import { execFileSync } from "node:child_process";
+import {
+  DEFAULT_DEEPLAKE_API_URL,
+  saveDeepLakeCredentials,
+  credentialsPath,
+  type DiskCredentials,
+} from "../hive-graph/deeplake-credentials.js";
+
+// ── Wire shapes (ported verbatim from honeycomb's issuer) ────────────────────
+
+/** `POST /auth/device/code` response. */
+export interface DeviceCodeResponse {
+  readonly device_code: string;
+  readonly user_code: string;
+  readonly verification_uri: string;
+  readonly verification_uri_complete: string;
+  readonly expires_in: number;
+  readonly interval: number;
+}
+
+/** `POST /auth/device/token` success response. */
+export interface DeviceTokenResponse {
+  readonly access_token: string;
+  readonly token_type?: string;
+  readonly expires_in?: number;
+}
+
+/** `GET /me` response. */
+export interface MeResponse {
+  readonly id: string;
+  readonly name: string;
+  readonly email?: string;
+}
+
+/** One org row from `GET /organizations`. */
+export interface OrgRow {
+  readonly id: string;
+  readonly name: string;
+}
+
+/** One workspace row from `GET /workspaces`. */
+export interface WorkspaceRow {
+  readonly id: string;
+  readonly name: string;
+}
+
+/** The minimal `fetch` response shape the client reads (a subset of the DOM `Response`). */
+export interface FetchResponse {
+  readonly ok: boolean;
+  readonly status: number;
+  json(): Promise<unknown>;
+  text(): Promise<string>;
+}
+
+/** The request init the client passes (method + headers + JSON body). */
+export interface FetchRequestInit {
+  readonly method?: string;
+  readonly headers?: Record<string, string>;
+  readonly body?: string;
+}
+
+/** The injectable `fetch` the client issues every request through. */
+export type FetchLike = (url: string, init?: FetchRequestInit) => Promise<FetchResponse>;
+
+/** A sleeper so the poll cadence is injectable (a test passes a no-wait sleeper). */
+export type Sleeper = (ms: number) => Promise<void>;
+
+/** The injectable browser opener; returns `true` iff it opened the URL. */
+export type BrowserOpener = (url: string) => boolean;
+
+/** The real wall-clock sleeper. */
+export const realSleeper: Sleeper = (ms: number): Promise<void> => new Promise((resolve) => setTimeout(resolve, ms));
+
+/** The `X-Deeplake-Client` header attributes traffic to nectar. */
+export const DEEPLAKE_CLIENT_HEADER = "X-Deeplake-Client";
+/** The nectar client-family value. */
+export const DEEPLAKE_CLIENT_VALUE = "nectar";
+/** The org-scoping header DeepLake reads. */
+export const DEEPLAKE_ORG_HEADER = "X-Activeloop-Org-Id";
+
+/** Long-lived mint duration: one year in seconds (honeycomb's `/users/me/tokens` duration). */
+const MINT_DURATION_SECONDS = 365 * 24 * 3600;
+
+/** Default retry budget on 429 / 5xx - bounded so a flaky backend surfaces rather than hangs. */
+export const DEFAULT_MAX_RETRIES = 3;
+
+/** The default device-flow poll cap - bounded so a stuck flow surfaces rather than hangs (a-AC-9). */
+export const DEFAULT_MAX_POLLS = 900;
+
+/** A redacted HTTP failure: carries the status + a truncated body, NEVER the token. */
+export class AuthHttpError extends Error {
+  readonly status: number;
+  constructor(status: number, message: string) {
+    super(message);
+    this.name = "AuthHttpError";
+    this.status = status;
+  }
+}
+
+/**
+ * Thrown when a link needs an explicit org/workspace choice but none was
+ * available (multiple candidates, no flags, no TTY) - the no-guess contract
+ * (parent AC-6). Carries the enumerated orgs so the CLI can print an actionable
+ * list. NEVER carries a token.
+ */
+export class TenancySelectionRequiredError extends Error {
+  readonly orgs: readonly OrgRow[];
+  constructor(message: string, orgs: readonly OrgRow[]) {
+    super(message);
+    this.name = "TenancySelectionRequiredError";
+    this.orgs = orgs;
+  }
+}
+
+/** Build the JSON headers an authenticated request carries (token in the header ONLY). */
+function authHeaders(token: string, orgId?: string): Record<string, string> {
+  const headers: Record<string, string> = {
+    Authorization: `Bearer ${token}`,
+    "Content-Type": "application/json",
+    [DEEPLAKE_CLIENT_HEADER]: DEEPLAKE_CLIENT_VALUE,
+  };
+  if (orgId !== undefined && orgId.length > 0) headers[DEEPLAKE_ORG_HEADER] = orgId;
+  return headers;
+}
+
+/** True for a status the hardened-fetch posture retries (rate-limit / transient server error). */
+function isRetryable(status: number): boolean {
+  return status === 429 || (status >= 500 && status <= 599);
+}
+
+/** The poll outcome: a token, or a bounded backoff signal. */
+export type PollOutcome = { readonly kind: "token"; readonly token: DeviceTokenResponse } | { readonly kind: "pending" } | { readonly kind: "slow_down" };
+
+/** The reusable `api.deeplake.ai` auth client (device flow + enumeration + mint). */
+export interface DeeplakeAuthClient {
+  readonly apiUrl: string;
+  requestDeviceCode(): Promise<DeviceCodeResponse>;
+  pollDeviceToken(deviceCode: string): Promise<PollOutcome>;
+  listOrgs(token: string): Promise<OrgRow[]>;
+  listWorkspaces(token: string, orgId: string): Promise<WorkspaceRow[]>;
+  reMint(token: string, orgId: string): Promise<string>;
+  getMe(token: string, orgId?: string): Promise<MeResponse>;
+}
+
+/** Options for {@link createDeeplakeAuthClient} (all seams injectable). */
+export interface DeeplakeAuthClientOptions {
+  readonly apiUrl?: string;
+  readonly fetch?: FetchLike;
+  readonly sleep?: Sleeper;
+  readonly maxRetries?: number;
+}
+
+/**
+ * Build the reusable auth client. `fetch`, `sleep`, and the retry budget are
+ * injectable; the production defaults are the global `fetch`, the real wall
+ * clock, and {@link DEFAULT_MAX_RETRIES}. The token never reaches a URL or a log.
+ */
+export function createDeeplakeAuthClient(options: DeeplakeAuthClientOptions = {}): DeeplakeAuthClient {
+  const apiUrl = (options.apiUrl ?? DEFAULT_DEEPLAKE_API_URL).replace(/\/+$/, "");
+  const doFetch = options.fetch ?? (globalThis.fetch as unknown as FetchLike);
+  const sleep = options.sleep ?? realSleeper;
+  const maxRetries = options.maxRetries ?? DEFAULT_MAX_RETRIES;
+
+  async function request(path: string, init: FetchRequestInit, expectJson: boolean): Promise<unknown> {
+    let lastStatus = 0;
+    for (let attempt = 0; attempt <= maxRetries; attempt += 1) {
+      const resp = await doFetch(`${apiUrl}${path}`, init);
+      if (resp.ok) {
+        return expectJson ? await resp.json().catch(() => null) : null;
+      }
+      lastStatus = resp.status;
+      if (isRetryable(resp.status) && attempt < maxRetries) {
+        await sleep(250 * 2 ** attempt);
+        continue;
+      }
+      const body = await resp.text().catch(() => "");
+      throw new AuthHttpError(resp.status, `auth API ${resp.status} for ${path}: ${sanitizeForTerminal(body.slice(0, 200))}`);
+    }
+    throw new AuthHttpError(lastStatus, `auth API ${lastStatus} for ${path} after ${maxRetries} retries`);
+  }
+
+  return {
+    apiUrl,
+    async requestDeviceCode(): Promise<DeviceCodeResponse> {
+      const body = await request(
+        "/auth/device/code",
+        { method: "POST", headers: { "Content-Type": "application/json", [DEEPLAKE_CLIENT_HEADER]: DEEPLAKE_CLIENT_VALUE } },
+        true,
+      );
+      return body as DeviceCodeResponse;
+    },
+    async pollDeviceToken(deviceCode: string): Promise<PollOutcome> {
+      const resp = await doFetch(`${apiUrl}/auth/device/token`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json", [DEEPLAKE_CLIENT_HEADER]: DEEPLAKE_CLIENT_VALUE },
+        body: JSON.stringify({ device_code: deviceCode }),
+      });
+      if (resp.ok) return { kind: "token", token: (await resp.json()) as DeviceTokenResponse };
+      if (resp.status === 400) {
+        const err = (await resp.json().catch(() => null)) as { error?: string } | null;
+        if (err?.error === "authorization_pending") return { kind: "pending" };
+        if (err?.error === "slow_down") return { kind: "slow_down" };
+        if (err?.error === "expired_token") throw new AuthHttpError(400, "the sign-in code expired; run 'nectar login' again");
+        if (err?.error === "access_denied") throw new AuthHttpError(400, "sign-in was denied");
+      }
+      throw new AuthHttpError(resp.status, `device-token poll failed: HTTP ${resp.status}`);
+    },
+    async listOrgs(token: string): Promise<OrgRow[]> {
+      const body = await request("/organizations", { method: "GET", headers: authHeaders(token) }, true);
+      return Array.isArray(body) ? (body as OrgRow[]) : [];
+    },
+    async listWorkspaces(token: string, orgId: string): Promise<WorkspaceRow[]> {
+      const body = await request("/workspaces", { method: "GET", headers: authHeaders(token, orgId) }, true);
+      const data = (body as { data?: WorkspaceRow[] } | null)?.data ?? body;
+      return Array.isArray(data) ? (data as WorkspaceRow[]) : [];
+    },
+    async reMint(token: string, orgId: string): Promise<string> {
+      const name = `nectar-cli-${Date.now()}`;
+      const body = await request(
+        "/users/me/tokens",
+        {
+          method: "POST",
+          headers: authHeaders(token),
+          body: JSON.stringify({ name, duration: MINT_DURATION_SECONDS, organization_id: orgId }),
+        },
+        true,
+      );
+      const minted = (body as { token?: { token?: unknown } } | null)?.token?.token;
+      if (typeof minted !== "string" || minted.length === 0) throw new AuthHttpError(0, "auth API minted no token");
+      return minted;
+    },
+    async getMe(token: string, orgId?: string): Promise<MeResponse> {
+      const body = await request("/me", { method: "GET", headers: authHeaders(token, orgId) }, true);
+      const me = body as Record<string, unknown> | null;
+      const id = typeof me?.id === "string" ? me.id : "";
+      const name = typeof me?.name === "string" ? me.name : "";
+      const email = typeof me?.email === "string" ? me.email : undefined;
+      return email !== undefined ? { id, name, email } : { id, name };
+    },
+  };
+}
+
+/**
+ * Strip C0/C1 control characters (including ESC) from a server-derived string
+ * before it reaches the terminal, so a compromised auth response cannot inject
+ * ANSI escape sequences into the user's terminal (security audit 2026-07-04).
+ */
+export function sanitizeForTerminal(value: string): string {
+  let out = "";
+  for (const ch of value) {
+    const code = ch.codePointAt(0) ?? 0;
+    const isControl = code < 0x20 || (code >= 0x7f && code <= 0x9f);
+    if (!isControl) out += ch;
+  }
+  return out;
+}
+
+/**
+ * Validate that a server-derived verification URL is safe to open. Returns the
+ * normalized href when it parses AND its scheme is `https:`; `null` otherwise -
+ * so a non-https `verification_uri_complete` is never opened.
+ */
+export function validateVerificationUrl(url: string): string | null {
+  try {
+    const parsed = new URL(url);
+    return parsed.protocol === "https:" ? parsed.href : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Open `url` in the OS browser - but ONLY if it is an `https:` URL. On open it
+ * uses a fixed-argv `execFileSync` (never a shell), bounded by a 5s timeout, and
+ * returns `false` on any failure so the caller's flow never crashes or hangs
+ * (a-AC-7): `open` (darwin) / `rundll32 url.dll,FileProtocolHandler` (win32) /
+ * `xdg-open` (linux).
+ */
+export function defaultBrowserOpener(url: string): boolean {
+  const safe = validateVerificationUrl(url);
+  if (safe === null) return false;
+  try {
+    if (process.platform === "darwin") {
+      execFileSync("open", [safe], { stdio: "ignore", timeout: 5000, windowsHide: true });
+    } else if (process.platform === "win32") {
+      execFileSync("rundll32", ["url.dll,FileProtocolHandler", safe], { stdio: "ignore", timeout: 5000, windowsHide: true });
+    } else {
+      execFileSync("xdg-open", [safe], { stdio: "ignore", timeout: 5000, windowsHide: true });
+    }
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/** The explicit flags a caller passes for tenancy selection. */
+export interface LoginFlags {
+  /** `--org=<id>`: pin the org, skipping the prompt. */
+  readonly org?: string;
+  /** `--workspace=<id>`: pin the workspace, skipping the prompt. */
+  readonly workspace?: string;
+}
+
+/** The resolved tenancy choice (ids + display names), never a silent guess. */
+export interface ResolvedTenancy {
+  readonly orgId: string;
+  readonly orgName: string;
+  readonly workspaceId: string;
+}
+
+/** The seams the login flow runs against (all injectable so tests never hit the network/browser). */
+export interface LoginSeams {
+  /** The injectable `fetch` (defaults to the global `fetch`). */
+  readonly fetch?: FetchLike;
+  /** The injectable poll sleeper (defaults to the real wall clock). */
+  readonly sleep?: Sleeper;
+  /** The browser opener (defaults to {@link defaultBrowserOpener}). */
+  readonly openBrowser?: BrowserOpener;
+  /** The user-facing output sink (defaults to stdout). NEVER receives the token. */
+  readonly out?: (line: string) => void;
+  /** Whether this is an interactive terminal (defaults to `process.stdin.isTTY === true`). */
+  readonly isTTY?: boolean;
+  /** Ask an interactive question (required to prompt for tenancy on a TTY). */
+  readonly question?: (prompt: string) => Promise<string>;
+  /** ISO "now" stamped into `savedAt` (defaults to the real clock). */
+  readonly now?: () => string;
+  /** Credentials dir override (tests point this at a temp HOME). */
+  readonly dir?: string;
+  /** The Deep Lake API base URL (defaults to {@link DEFAULT_DEEPLAKE_API_URL}). */
+  readonly apiUrl?: string;
+  /** A safety cap on poll attempts (defaults to {@link DEFAULT_MAX_POLLS}). */
+  readonly maxPolls?: number;
+}
+
+/** The result of a login attempt: success/failure + a plain-language message (a-AC-9). */
+export interface LoginResult {
+  readonly ok: boolean;
+  readonly message: string;
+  readonly credentialsPath?: string;
+  readonly orgId?: string;
+  readonly workspaceId?: string;
+}
+
+/**
+ * Resolve the EXPLICIT tenancy for a login (parent AC-6): flags win, a single
+ * org/workspace auto-selects, multiple prompt on a TTY, and a non-TTY with no
+ * flags throws {@link TenancySelectionRequiredError} naming the flags. NEVER a
+ * silent `orgs[0]` guess.
+ */
+export async function resolveTenancy(
+  client: DeeplakeAuthClient,
+  token: string,
+  flags: LoginFlags,
+  seams: LoginSeams,
+): Promise<ResolvedTenancy> {
+  const isTTY = seams.isTTY ?? process.stdin.isTTY === true;
+  const orgs = await client.listOrgs(token);
+  if (orgs.length === 0) throw new AuthHttpError(0, "no organizations are available for this account");
+
+  // ── choose the org ──
+  let org: OrgRow;
+  if (flags.org !== undefined && flags.org.length > 0) {
+    org = orgs.find((o) => o.id === flags.org) ?? { id: flags.org, name: flags.org };
+  } else if (orgs.length === 1) {
+    org = orgs[0] as OrgRow;
+  } else if (isTTY && seams.question !== undefined) {
+    org = await promptChoice(seams, orgs, "organization");
+  } else {
+    const list = orgs.map((o) => `${o.id} (${o.name})`).join(", ");
+    throw new TenancySelectionRequiredError(
+      `this account has multiple organizations; choose one with --org=<id> (and --workspace=<id>). Available orgs: ${list}`,
+      orgs,
+    );
+  }
+
+  // ── choose the workspace ──
+  let workspaceId: string;
+  if (flags.workspace !== undefined && flags.workspace.length > 0) {
+    workspaceId = flags.workspace;
+  } else {
+    const workspaces = await client.listWorkspaces(token, org.id);
+    if (workspaces.length === 1) {
+      workspaceId = (workspaces[0] as WorkspaceRow).id;
+    } else if (workspaces.length === 0) {
+      workspaceId = "default";
+    } else if (isTTY && seams.question !== undefined) {
+      workspaceId = (await promptChoice(seams, workspaces, "workspace")).id;
+    } else {
+      const list = workspaces.map((w) => `${w.id} (${w.name})`).join(", ");
+      throw new TenancySelectionRequiredError(
+        `org ${org.id} has multiple workspaces; choose one with --workspace=<id>. Available: ${list}`,
+        orgs,
+      );
+    }
+  }
+  return { orgId: org.id, orgName: org.name, workspaceId };
+}
+
+/** Prompt the user to pick one of `rows` on a TTY; re-asks until a valid choice is made. */
+async function promptChoice<T extends { id: string; name: string }>(
+  seams: LoginSeams,
+  rows: readonly T[],
+  label: string,
+): Promise<T> {
+  const out =
+    seams.out ??
+    ((line: string): void => {
+      process.stdout.write(`${line}\n`);
+    });
+  const question = seams.question;
+  if (question === undefined) throw new AuthHttpError(0, `cannot prompt for a ${label} without an interactive terminal`);
+  out(`Select a ${label}:`);
+  rows.forEach((r, i) => out(`  ${i + 1}. ${r.id} (${r.name})`));
+  for (let attempt = 0; attempt < 5; attempt += 1) {
+    const answer = (await question(`  Enter 1-${rows.length}: `)).trim();
+    const byNumber = Number.parseInt(answer, 10);
+    if (Number.isInteger(byNumber) && byNumber >= 1 && byNumber <= rows.length) return rows[byNumber - 1] as T;
+    const byId = rows.find((r) => r.id === answer);
+    if (byId !== undefined) return byId;
+    out(`  '${answer}' is not a valid ${label}; try again.`);
+  }
+  throw new AuthHttpError(0, `no valid ${label} was chosen`);
+}
+
+/**
+ * Run the `api.deeplake.ai` device flow to completion and persist the shared
+ * credential (a-AC-5). Never throws - every failure is caught and returned as a
+ * `{ ok: false, message }` with a plain-language, actionable message (a-AC-9).
+ *
+ * Ordering (a-AC-7): the verification URL + user code are PRINTED before any
+ * browser-open attempt; the opener failing never crashes the flow; polling runs
+ * to completion regardless.
+ */
+export async function runDeviceFlowLogin(flags: LoginFlags = {}, seams: LoginSeams = {}): Promise<LoginResult> {
+  const out =
+    seams.out ??
+    ((line: string): void => {
+      process.stdout.write(`${line}\n`);
+    });
+  const sleep = seams.sleep ?? realSleeper;
+  const opener = seams.openBrowser ?? defaultBrowserOpener;
+  const maxPolls = seams.maxPolls ?? DEFAULT_MAX_POLLS;
+  const apiUrl = seams.apiUrl ?? DEFAULT_DEEPLAKE_API_URL;
+  const client = createDeeplakeAuthClient({
+    apiUrl,
+    ...(seams.fetch !== undefined ? { fetch: seams.fetch } : {}),
+    ...(seams.sleep !== undefined ? { sleep: seams.sleep } : {}),
+  });
+
+  try {
+    const grant = await client.requestDeviceCode();
+
+    // a-AC-7: PRINT the code + URL BEFORE any browser open, so a headless run
+    // always shows the user how to finish even if no browser can open. The URL
+    // must validate https-only even for the PRINTED path (the user is being
+    // told to open it), and both server-derived strings are stripped of
+    // terminal control characters before echo (security audit 2026-07-04).
+    const printableUri = validateVerificationUrl(grant.verification_uri ?? "");
+    if (printableUri === null) {
+      return { ok: false, message: "sign-in failed: the auth service returned a non-https verification URL; refusing to continue." };
+    }
+    out(`To finish signing in, open ${printableUri} and enter code: ${sanitizeForTerminal(grant.user_code ?? "")}`);
+
+    const safe = validateVerificationUrl(grant.verification_uri_complete);
+    if (safe !== null) {
+      const opened = opener(safe);
+      out(opened ? "Opened your browser. Waiting for sign in..." : "Could not open a browser; open the URL above manually. Waiting for sign in...");
+    } else {
+      out("Waiting for sign in...");
+    }
+
+    // Poll to completion, honoring the grant interval and any slow_down backoff.
+    let intervalMs = Math.max(grant.interval || 5, 5) * 1000;
+    let accessToken: string | undefined;
+    for (let attempt = 0; attempt < maxPolls; attempt += 1) {
+      await sleep(intervalMs);
+      const outcome = await client.pollDeviceToken(grant.device_code);
+      if (outcome.kind === "token") {
+        accessToken = outcome.token.access_token;
+        break;
+      }
+      if (outcome.kind === "slow_down") intervalMs += 5000;
+    }
+    if (accessToken === undefined) {
+      return { ok: false, message: "sign-in timed out before it was approved; run 'nectar login' again." };
+    }
+
+    // Resolve tenancy EXPLICITLY (never a silent orgs[0] guess), mint the
+    // long-lived org-bound token, validate + hydrate the user name via /me.
+    const tenancy = await resolveTenancy(client, accessToken, flags, seams);
+    const longLived = await client.reMint(accessToken, tenancy.orgId);
+    const me = await client.getMe(longLived, tenancy.orgId);
+    const userName = me.name.length > 0 ? me.name : me.email !== undefined ? (me.email.split("@")[0] ?? "unknown") : "unknown";
+
+    const disk: DiskCredentials = {
+      token: longLived,
+      orgId: tenancy.orgId,
+      orgName: tenancy.orgName,
+      userName,
+      workspaceId: tenancy.workspaceId,
+      apiUrl: client.apiUrl,
+      savedAt: "",
+    };
+    const saveOptions = {
+      ...(seams.dir !== undefined ? { dir: seams.dir } : {}),
+      ...(seams.now !== undefined ? { clock: { now: seams.now } } : {}),
+    };
+    saveDeepLakeCredentials(disk, saveOptions);
+    const path = credentialsPath(seams.dir !== undefined ? { dir: seams.dir } : {});
+    out(`Signed in as ${userName}. Using org ${tenancy.orgName} (${tenancy.orgId}), workspace ${tenancy.workspaceId}.`);
+    return {
+      ok: true,
+      message: `nectar login: signed in; credentials written to ${path}.`,
+      credentialsPath: path,
+      orgId: tenancy.orgId,
+      workspaceId: tenancy.workspaceId,
+    };
+  } catch (err: unknown) {
+    if (err instanceof TenancySelectionRequiredError) {
+      return { ok: false, message: `nectar login: ${err.message}` };
+    }
+    if (err instanceof AuthHttpError) {
+      return { ok: false, message: `nectar login: ${err.message}` };
+    }
+    return { ok: false, message: `nectar login: ${err instanceof Error ? err.message : String(err)}` };
+  }
+}
diff --git a/src/cli.ts b/src/cli.ts
index 76c8965..ed87000 100644
--- a/src/cli.ts
+++ b/src/cli.ts
@@ -25,8 +25,9 @@
  * credentials the Deep Lake store already consumes and the project id + project
  * root from `NECTAR_PROJECT_ID` / `NECTAR_PROJECT_ROOT` (see USAGE).
  */
-import { realpathSync } from "node:fs";
-import { join } from "node:path";
+import { existsSync, lstatSync, realpathSync, rmSync } from "node:fs";
+import { isAbsolute, join } from "node:path";
+import { spawn } from "node:child_process";
 import { fileURLToPath } from "node:url";
 import { createInterface } from "node:readline/promises";
 import { assembleDaemon, type AssembledDaemon, type AssembleOptions } from "./daemon.js";
@@ -42,8 +43,19 @@ import {
 } from "./api/loopback-client.js";
 import type { ProjectsView } from "./projects-control.js";
 import type { HiveGraphSearchResult, HiveGraphHit } from "./hive-graph/search-types.js";
-import { createServiceModule, serviceStatus } from "./service/index.js";
-import { registerWithDoctor } from "./doctor-registry.js";
+import { createServiceModule, serviceStatus, type ServiceModule } from "./service/index.js";
+import { registerWithDoctor, deregisterFromDoctor } from "./doctor-registry.js";
+import { isLockHeldByLiveDaemon, readPidFile } from "./lock.js";
+import { nectarStateDir } from "./apiary-root.js";
+import { classifyFleet, fleetSignalLine } from "./fleet-detection.js";
+import { runDeviceFlowLogin, type LoginFlags, type LoginResult, type LoginSeams } from "./auth/device-flow.js";
+import {
+  runStartLifecycle,
+  runStopLifecycle,
+  runUninstallLifecycle,
+  removeStateDir,
+  type StateDirRemovalResult,
+} from "./lifecycle.js";
 import { emitInstalled, emitUninstalled, recordDaemonStart } from "./telemetry-usage/emit.js";
 import type { Tenancy } from "./hive-graph/model.js";
 import type { HiveGraphStore, AsyncHiveGraphStore } from "./hive-graph/store.js";
@@ -100,10 +112,16 @@ import {
 const USAGE = `nectar - semantic memory layer over a source tree
 
 Usage:
-  nectar daemon                 Start the hiveantennae daemon (127.0.0.1:3854, /health)
-  nectar install                Register the OS service unit + the doctor registry entry (PRD-003)
-  nectar uninstall              Deregister the OS service unit (PRD-003b)
-  nectar service-status         Report the OS service unit's running state (PRD-003b)
+  nectar daemon                 Start the hiveantennae daemon in the foreground (127.0.0.1:3854, /health)
+  nectar login [--org=<id>] [--workspace=<id>]
+                                Sign in via the Deeplake device flow and write ~/.deeplake/credentials.json (PRD-003a)
+  nectar install                Register the OS service unit + the doctor registry entry, and (solo, no
+                                credentials) auto-open the sign-in popup (PRD-003)
+  nectar start                  Start the daemon (via the OS service when registered, direct spawn otherwise) (PRD-003b)
+  nectar stop                   Stop the daemon (OS service and/or a direct SIGTERM) (PRD-003b)
+  nectar uninstall              Remove the OS service unit + the doctor registry entry + nectar's state dir (PRD-003b)
+  nectar status                 Report the OS service unit's running state (alias: service-status) (PRD-003b)
+  nectar service-status         Alias of 'nectar status' (PRD-003b)
   nectar brood [flags]          Full-codebase brood (PRD-007). --dry-run previews cost locally;
                                 a mutating brood runs against the durable Deep Lake store (needs
                                 Portkey configured). Flags: --force, --limit N, --dry-run, --model <id>
@@ -140,6 +158,167 @@ function preferSystemScope(): boolean {
   return (process.env["NECTAR_SERVICE_SYSTEM"] ?? "") === "1";
 }
 
+/** Build the OS service module the lifecycle verbs front (PRD-003b). */
+function lifecycleServiceModule(): ServiceModule {
+  return createServiceModule({ execPath: resolveServiceExecPath(), preferSystemScope: preferSystemScope() });
+}
+
+/** True when a live nectar daemon currently holds the lock (PRD-003b). */
+function isDaemonRunning(): boolean {
+  return isLockHeldByLiveDaemon(resolveConfig().lockFilePath);
+}
+
+/** The pid recorded in the pid file, or null (PRD-003b). */
+function readDaemonPid(): number | null {
+  return readPidFile(resolveConfig().pidFilePath);
+}
+
+/** Send a signal to a pid without throwing; returns true when delivered (PRD-003b). */
+function sendSignal(pid: number, signal: NodeJS.Signals): boolean {
+  try {
+    process.kill(pid, signal);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/** Directly spawn `nectar daemon` detached (the fallback when no OS unit is registered, PRD-003b b-AC-1). */
+function spawnDaemonDetached(): number | null {
+  try {
+    const script = process.argv[1] ?? resolveServiceExecPath();
+    const child = spawn(process.execPath, ["--experimental-sqlite", script, "daemon"], {
+      detached: true,
+      stdio: "ignore",
+    });
+    child.unref();
+    return child.pid ?? null;
+  } catch {
+    return null;
+  }
+}
+
+/** Remove nectar's resolved state dir under the fleet root, guarded (b-AC-4 / AC-8). */
+function removeNectarStateDir(): StateDirRemovalResult {
+  return removeStateDir(nectarStateDir(), {
+    isAbsolute: (p) => isAbsolute(p),
+    exists: (p) => existsSync(p),
+    isSymlink: (p) => {
+      try {
+        return lstatSync(p).isSymbolicLink();
+      } catch {
+        return false;
+      }
+    },
+    rm: (p) => rmSync(p, { recursive: true, force: true }),
+  });
+}
+
+/** True when valid Deep Lake credentials currently resolve (a present-but-malformed file reads as absent). */
+function credentialsPresent(): boolean {
+  try {
+    loadDeepLakeCredentials();
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/** Parse `--org`/`--workspace` (both `--flag value` and `--flag=value`) for `nectar login` (PRD-003a a-AC-5). */
+export function parseLoginFlags(args: readonly string[]): { flags: LoginFlags; errors: readonly string[] } {
+  const errors: string[] = [];
+  let org: string | undefined;
+  let workspace: string | undefined;
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i] ?? "";
+    if (arg === "--org") {
+      const v = args[i + 1];
+      if (v === undefined || v.startsWith("--")) errors.push("--org requires a value");
+      else {
+        org = v;
+        i++;
+      }
+    } else if (arg.startsWith("--org=")) {
+      org = arg.slice("--org=".length);
+    } else if (arg === "--workspace") {
+      const v = args[i + 1];
+      if (v === undefined || v.startsWith("--")) errors.push("--workspace requires a value");
+      else {
+        workspace = v;
+        i++;
+      }
+    } else if (arg.startsWith("--workspace=")) {
+      workspace = arg.slice("--workspace=".length);
+    } else {
+      errors.push(`unknown flag '${arg}'`);
+    }
+  }
+  const flags: LoginFlags = {
+    ...(org !== undefined ? { org } : {}),
+    ...(workspace !== undefined ? { workspace } : {}),
+  };
+  return { flags, errors };
+}
+
+/**
+ * Run the device-flow login against the real seams (stdout output, a TTY-backed
+ * question when interactive). Shared by `nectar login` and the `nectar install`
+ * solo auto-popup. Closes the readline interface it opened. Never throws (the
+ * flow returns a `LoginResult`).
+ */
+async function performLogin(flags: LoginFlags): Promise<LoginResult> {
+  const isTTY = process.stdin.isTTY === true;
+  const rl = isTTY ? createInterface({ input: process.stdin, output: process.stdout }) : undefined;
+  const seams: LoginSeams = {
+    out: (line: string) => process.stdout.write(`${line}\n`),
+    isTTY,
+    ...(rl !== undefined ? { question: (prompt: string) => rl.question(prompt) } : {}),
+  };
+  try {
+    return await runDeviceFlowLogin(flags, seams);
+  } finally {
+    rl?.close();
+  }
+}
+
+/** `nectar login` (PRD-003a a-AC-5): the device-flow sign-in verb, in both solo and fleet mode. */
+async function runLogin(args: readonly string[]): Promise<number> {
+  const { flags, errors } = parseLoginFlags(args);
+  if (errors.length > 0) {
+    for (const err of errors) process.stderr.write(`nectar login: ${err}\n`);
+    return 2;
+  }
+  const result = await performLogin(flags);
+  if (result.ok) {
+    process.stdout.write(`${result.message}\n`);
+    return 0;
+  }
+  process.stderr.write(`${result.message}\n`);
+  return 1;
+}
+
+/** `nectar start` (PRD-003b b-AC-1): front the OS unit, direct-spawn otherwise. */
+async function runStart(): Promise<number> {
+  return runStartLifecycle({
+    service: lifecycleServiceModule(),
+    isDaemonRunning,
+    readPid: readDaemonPid,
+    spawnDaemon: spawnDaemonDetached,
+    io: { out: (l) => process.stdout.write(`${l}\n`), err: (l) => process.stderr.write(`${l}\n`) },
+  });
+}
+
+/** `nectar stop` (PRD-003b b-AC-1): stop the OS unit and/or SIGTERM the running pid. */
+async function runStop(): Promise<number> {
+  return runStopLifecycle({
+    service: lifecycleServiceModule(),
+    isDaemonRunning,
+    readPid: readDaemonPid,
+    sendSignal,
+    io: { out: (l) => process.stdout.write(`${l}\n`), err: (l) => process.stderr.write(`${l}\n`) },
+  });
+}
+
 /**
  * `nectar install` (PRD-003): lays down the OS service unit (003b) AND appends
  * nectar's entry to doctor's registry (003c) - the same installer performs
@@ -170,6 +349,14 @@ async function runInstall(): Promise<number> {
     return 1;
   }
 
+  // PRD-003a a-AC-3: the solo first-install auto-popup. Evaluate fleet detection
+  // + credentials LIVE from the install verb (never from daemon boot): with hive
+  // detected, defer to hive and open nothing; with credentials already present,
+  // open nothing; solo with no credentials, auto-open the device-flow sign-in.
+  // Best-effort - a sign-in that fails/times out never fails the install (the
+  // daemon sits degraded and `nectar login` can finish it later).
+  await maybeAutoLoginOnInstall();
+
   // Usage telemetry: fired only on full success, after the user-facing output.
   // emitInstalled never throws and is bounded, so it cannot alter the exit code.
   if (serviceResult.ok) {
@@ -179,20 +366,77 @@ async function runInstall(): Promise<number> {
   return serviceResult.ok ? 0 : 1;
 }
 
-/** `nectar uninstall` (PRD-003b): deregisters the OS service unit so it does not resurrect. */
+/**
+ * The `nectar install` auto-popup decision (PRD-003a a-AC-3), factored out as a
+ * pure function so the "open only when solo AND no credentials" rule is
+ * unit-testable without the install verb's side effects.
+ *   - fleet detected           -> `"defer-to-hive"` (never a popup).
+ *   - solo + credentials exist  -> `"already-signed-in"` (no popup).
+ *   - solo + no credentials     -> `"open-sign-in"` (auto-popup).
+ */
+export type InstallLoginAction = "defer-to-hive" | "already-signed-in" | "open-sign-in";
+export function decideInstallLoginAction(fleetMode: "solo" | "fleet", hasCredentials: boolean): InstallLoginAction {
+  if (fleetMode === "fleet") return "defer-to-hive";
+  if (hasCredentials) return "already-signed-in";
+  return "open-sign-in";
+}
+
+/**
+ * The `nectar install` solo auto-popup decision (PRD-003a a-AC-3). Classifies
+ * the machine solo-vs-fleet, logs which signals fired (a-AC-6), and only opens
+ * the device-flow sign-in when solo AND no credentials exist. Fully best-effort:
+ * any failure here is reported but never propagated so it cannot fail the install.
+ */
+async function maybeAutoLoginOnInstall(): Promise<void> {
+  try {
+    const classification = await classifyFleet();
+    process.stdout.write(`nectar install: ${fleetSignalLine(classification)}\n`);
+    const action = decideInstallLoginAction(classification.mode, credentialsPresent());
+    if (action === "defer-to-hive") {
+      process.stdout.write(
+        "nectar install: hive detected; deferring sign-in to hive (no browser popup). " +
+          "nectar reports degraded until hive-side login writes ~/.deeplake/credentials.json, then goes healthy without a restart.\n",
+      );
+      return;
+    }
+    if (action === "already-signed-in") {
+      process.stdout.write("nectar install: credentials already present; no sign-in needed.\n");
+      return;
+    }
+    process.stdout.write("nectar install: no hive detected and no credentials; starting sign-in...\n");
+    const result = await performLogin({});
+    process.stdout.write(`${result.message}\n`);
+    if (!result.ok) {
+      process.stdout.write("nectar install: sign-in did not complete; run 'nectar login' to finish it later.\n");
+    }
+  } catch (err) {
+    process.stdout.write(
+      `nectar install: could not evaluate sign-in (${err instanceof Error ? err.message : String(err)}); ` +
+        "run 'nectar login' to sign in.\n",
+    );
+  }
+}
+
+/**
+ * `nectar uninstall` (PRD-003b b-AC-2/3/4/6): the three-part contract - stop the
+ * daemon, remove the OS service unit (current + legacy), delete nectar's doctor
+ * registry entry, and remove nectar's state dir - each best-effort with a
+ * per-step report. A not-installed machine exits 0 "nothing to remove".
+ */
 async function runUninstall(): Promise<number> {
-  const serviceModule = createServiceModule({
-    execPath: resolveServiceExecPath(),
-    preferSystemScope: preferSystemScope(),
+  const code = await runUninstallLifecycle({
+    service: lifecycleServiceModule(),
+    isDaemonRunning,
+    readPid: readDaemonPid,
+    sendSignal,
+    deregisterFromDoctor: () => deregisterFromDoctor(),
+    removeStateDir: removeNectarStateDir,
+    io: { out: (l) => process.stdout.write(`${l}\n`), err: (l) => process.stderr.write(`${l}\n`) },
   });
-  const result = await serviceModule.uninstall();
-  process.stdout.write(`${result.message}\n`);
-  // Usage telemetry (NEC-042 item 4 / AC-018l.11): fire only AFTER the uninstall
-  // outcome is known, and only on success - a failed/aborted uninstall must not
-  // emit a `nectar_uninstalled` event. emitUninstalled never throws and is
-  // bounded, so it cannot alter the exit code.
-  if (result.ok) await emitUninstalled();
-  return result.ok ? 0 : 1;
+  // Usage telemetry (NEC-042 item 4 / AC-018l.11): fire only on a clean uninstall.
+  // emitUninstalled never throws and is bounded, so it cannot alter the exit code.
+  if (code === 0) await emitUninstalled();
+  return code;
 }
 
 /** `nectar service-status` (PRD-003b): reports the OS service manager's coarse state. */
@@ -1100,6 +1344,28 @@ async function runDaemon(): Promise<void> {
 
   const options: AssembleOptions = {
     broodPrereqs,
+    // PRD-003a a-AC-1: boot 503 degraded when no credentials resolved, so the
+    // pre-login fleet posture is honest; the watch below flips it healthy the
+    // moment credentials appear (a-AC-2), no restart needed.
+    //
+    // ACCEPTED DEVIATION (W1-N, ledger 2026-07-04): credentials appearing after
+    // boot flip /health healthy and reconcile active projects, but the
+    // creds-dependent subsystems assembled above from this boot-time snapshot
+    // (the durable store, brood wiring, enricher loop) are NOT hot-attached;
+    // they stay dormant until the next daemon restart. Same posture as
+    // honeycomb. If hot-attach ever lands, it belongs in the credentialsWatch
+    // onChange path in daemon.ts.
+    storageCredentialsPresent: creds !== undefined,
+    credentialsWatch: {
+      probe: () => {
+        try {
+          loadDeepLakeCredentials();
+          return true;
+        } catch {
+          return false;
+        }
+      },
+    },
     ...(activeProjects !== undefined ? { activeProjects } : {}),
     ...(live !== undefined && primaryTenancy !== undefined && primary !== undefined
       ? {
@@ -1228,15 +1494,28 @@ async function main(argv: readonly string[]): Promise<number> {
     return 0;
   }
 
+  if (command === "login") {
+    return runLogin(argv.slice(1));
+  }
+
   if (command === "install") {
     return runInstall();
   }
 
+  if (command === "start") {
+    return runStart();
+  }
+
+  if (command === "stop") {
+    return runStop();
+  }
+
   if (command === "uninstall") {
     return runUninstall();
   }
 
-  if (command === "service-status") {
+  // `status` is the bare verb; `service-status` is its alias (PRD-003b b-AC-5).
+  if (command === "status" || command === "service-status") {
     return runServiceStatus();
   }
 
diff --git a/src/credentials-watch.ts b/src/credentials-watch.ts
new file mode 100644
index 0000000..1072ce4
--- /dev/null
+++ b/src/credentials-watch.ts
@@ -0,0 +1,88 @@
+/**
+ * The credentials watch (PRD-003a a-AC-2).
+ *
+ * nectar resolves the shared `~/.deeplake/credentials.json` ONCE at daemon boot
+ * (`cli.ts` `runDaemon`), so a daemon that booted before login sat degraded
+ * forever. This watch closes that gap: on the daemon's existing poll cadence
+ * (mirroring the {@link ActiveProjectsController} reconcile loop's use of the
+ * injected {@link PollLoop} timer seam) it re-resolves whether valid credentials
+ * are present and, whenever the answer CHANGES, fires `onChange`. The daemon
+ * wires `onChange` to `health.setStorageState`, so `/health` transitions from
+ * 503 degraded to 200 healthy the moment credentials appear - with no restart
+ * and no manual step.
+ *
+ * The `probe` seam is what makes this a genuine re-resolution rather than a bare
+ * existence check: the production probe attempts `loadDeepLakeCredentials()` and
+ * reports whether a store could be built (a present-but-malformed file reads as
+ * absent, exactly as the boot path treats it). Every seam is injectable so a
+ * test drives the whole surface under a manual clock without touching the real
+ * home or the real filesystem.
+ *
+ * Built-ins only (the timer seam); zero runtime dependencies.
+ */
+import { PollLoop, realTimer, type Timer } from "./poll-loop.js";
+
+export interface CredentialsWatchDeps {
+  /**
+   * Re-resolve whether valid Deeplake credentials are currently present. The
+   * production probe runs `loadDeepLakeCredentials()` and returns `false` on any
+   * failure (absent / malformed / missing field); a test injects a fake.
+   */
+  probe(): boolean;
+  /**
+   * Called with the resolved presence WHENEVER it changes (including the first
+   * evaluation, when the prior state is unknown). Never called twice in a row
+   * with the same value.
+   */
+  onChange(present: boolean): void;
+  /** Poll cadence in ms (default: the daemon's poll interval). */
+  readonly intervalMs: number;
+  /** Injected timer (tests). Default: the real timer. */
+  readonly timer?: Timer;
+  /** Observe a probe error routed out of the poll loop. Default: no-op. */
+  readonly onError?: (err: unknown) => void;
+}
+
+export class CredentialsWatch {
+  private readonly deps: CredentialsWatchDeps;
+  private readonly loop: PollLoop;
+  private last: boolean | undefined;
+  private started = false;
+
+  constructor(deps: CredentialsWatchDeps) {
+    this.deps = deps;
+    this.loop = new PollLoop({
+      tick: () => this.evaluate(),
+      floorMs: Math.max(1, deps.intervalMs),
+      timer: deps.timer ?? realTimer,
+      ...(deps.onError !== undefined ? { onError: deps.onError } : {}),
+    });
+  }
+
+  /**
+   * Evaluate the probe once. Fires `onChange` (and returns `true`, so the poll
+   * loop treats the tick as "did work") only when the resolved presence differs
+   * from the last observed value; otherwise a no-op returning `false`.
+   */
+  evaluate(): boolean {
+    const present = this.deps.probe();
+    if (present === this.last) return false;
+    this.last = present;
+    this.deps.onChange(present);
+    return true;
+  }
+
+  /** Arm the watch (the loop fires an immediate first tick at delay 0). Idempotent. */
+  start(): void {
+    if (this.started) return;
+    this.started = true;
+    this.loop.start();
+  }
+
+  /** Disarm the loop and drain any in-flight probe. Idempotent. */
+  async stop(): Promise<void> {
+    this.loop.stop();
+    await this.loop.whenIdle();
+    this.started = false;
+  }
+}
diff --git a/src/daemon.ts b/src/daemon.ts
index 895423a..a39e37b 100644
--- a/src/daemon.ts
+++ b/src/daemon.ts
@@ -52,6 +52,7 @@ import { mountHiveGraphApi, type MountHiveGraphOptions } from "./api/hive-graph-
 import { createBroodGuard, type BroodGuard } from "./brood-guard.js";
 import type { Timer } from "./poll-loop.js";
 import { ActiveProjectsController } from "./active-projects-runtime.js";
+import { CredentialsWatch } from "./credentials-watch.js";
 import type { ProjectContextFactory } from "./project-supervisor.js";
 import type { ActiveProjectResolution } from "./hive-graph/active-projects.js";
 import {
@@ -170,6 +171,33 @@ export interface AssembleOptions extends RuntimeConfigOverrides {
   /** Embeddings config overrides (default: resolve from `process.env`). Lets a test set the health `embeddings.provider` label without env. */
   readonly embeddings?: EmbeddingsConfigOverrides;
 
+  // ── PRD-003a: solo-vs-fleet login deferral (the degraded-until-login posture) ──
+  /**
+   * The durable-store credentials presence at boot (PRD-003a a-AC-1). When
+   * `false`, `/health` boots 503 degraded with `storage.reason:
+   * "credentials-missing"` while the daemon stays up; when `true`, it boots ok.
+   * Absent (undefined) leaves the legacy `ok` posture unchanged - so every
+   * existing caller/test that never sets it is unaffected.
+   */
+  readonly storageCredentialsPresent?: boolean;
+  /**
+   * A credentials watch (PRD-003a a-AC-2): when set, `start()` arms a poll loop
+   * that re-resolves credentials on the poll cadence and flips `/health` between
+   * degraded and healthy WITHOUT a restart the moment
+   * `~/.deeplake/credentials.json` appears (or disappears). `shutdown()` stops
+   * it. Absent -> no watch (the pre-003a behavior).
+   */
+  readonly credentialsWatch?: {
+    /** Re-resolve whether valid credentials are present (production: `loadDeepLakeCredentials`). */
+    probe(): boolean;
+    /** Poll cadence override (default: `config.pollIntervalMs`). */
+    intervalMs?: number;
+    /** Injected timer for the watch loop (deterministic tests). */
+    timer?: Timer;
+    /** Observe a probe error. */
+    onError?: (err: unknown) => void;
+  };
+
   // ── Wave C daemon wiring (PRD-007 / PRD-011 / PRD-016) ──────────────────────
   /** Project tenancy shared by the enricher loop, the auto-brood trigger, and the boot projection load (default: an empty placeholder — an empty store yields no work). */
   readonly tenancy?: Tenancy;
@@ -511,6 +539,18 @@ export function assembleDaemon(options: AssembleOptions = {}): AssembledDaemon {
     health.setBroodingState({ reason: broodPrereqs.ready ? null : broodPrereqs.reason });
   }
 
+  // PRD-003a a-AC-1: set the durable-store reachability posture at assembly, so
+  // a credentials-missing boot serves 503 degraded immediately (before the first
+  // watch tick). Only applied when the caller declares it; absent leaves the
+  // legacy `ok` default untouched (every pre-003a test path is unaffected).
+  if (options.storageCredentialsPresent !== undefined) {
+    health.setStorageState(
+      options.storageCredentialsPresent
+        ? { reachable: true, reason: null }
+        : { reachable: false, reason: "credentials-missing" },
+    );
+  }
+
   const runtimeDirOverride = hasExplicitRuntimeDirOverride(options);
   let telemetryDbPath = options.telemetryDbPath ?? telemetryDbPathForRuntimeDir(config.runtimeDir);
 
@@ -579,6 +619,35 @@ export function assembleDaemon(options: AssembleOptions = {}): AssembledDaemon {
         })
       : null;
 
+  // PRD-003a a-AC-2: the credentials watch. On each poll it re-resolves whether
+  // credentials are present and, on a change, flips the /health storage posture
+  // (degraded <-> healthy) with no restart. When credentials appear it also asks
+  // the active-project supervisor to reconcile (a no-op when unwired).
+  const credentialsWatch: CredentialsWatch | null =
+    options.credentialsWatch !== undefined
+      ? new CredentialsWatch({
+          probe: options.credentialsWatch.probe,
+          onChange: (present) => {
+            health.setStorageState(
+              present ? { reachable: true, reason: null } : { reachable: false, reason: "credentials-missing" },
+            );
+            log({
+              level: "info",
+              scope: "credentials",
+              msg: present ? "credentials resolved; storage reachable" : "credentials absent; storage unreachable",
+            });
+            if (present && activeProjectsController !== null) {
+              void activeProjectsController.reconcileNow().catch((err: unknown) => {
+                log({ level: "error", scope: "credentials", msg: "reconcile after credentials appeared failed", err: String(err) });
+              });
+            }
+          },
+          intervalMs: options.credentialsWatch.intervalMs ?? config.pollIntervalMs,
+          ...(options.credentialsWatch.timer !== undefined ? { timer: options.credentialsWatch.timer } : {}),
+          ...(options.credentialsWatch.onError !== undefined ? { onError: options.credentialsWatch.onError } : {}),
+        })
+      : null;
+
   // ── PRD-016: the enricher steady-state loop ─────────────────────────────────
   // The loop reads/writes the SYNCHRONOUS EnricherStore seam; its per-cycle stats
   // feed the /health enricher slice through `enricherHealthSink`. Started on
@@ -955,6 +1024,10 @@ export function assembleDaemon(options: AssembleOptions = {}): AssembledDaemon {
         activeProjectsController.start();
       }
 
+      // PRD-003a a-AC-2: arm the credentials watch so a login that lands after
+      // boot flips /health healthy without a restart.
+      credentialsWatch?.start();
+
       return boundPort;
     })();
 
@@ -1005,6 +1078,14 @@ export function assembleDaemon(options: AssembleOptions = {}): AssembledDaemon {
         log({ level: "error", scope: "active-projects", msg: "stop failed", err: String(err) });
       }
     }
+    // PRD-003a a-AC-2: stop the credentials watch before the lock releases.
+    if (credentialsWatch !== null) {
+      try {
+        await credentialsWatch.stop();
+      } catch (err) {
+        log({ level: "error", scope: "credentials", msg: "watch stop failed", err: String(err) });
+      }
+    }
 
     // AC-018a.10/11 (NEC-033): await the in-flight worker tick and bootSettled
     // under a bounded timeout so a shutdown that catches the worker busy drains
diff --git a/src/doctor-registry.ts b/src/doctor-registry.ts
index 0f4952e..b646dde 100644
--- a/src/doctor-registry.ts
+++ b/src/doctor-registry.ts
@@ -273,3 +273,93 @@ export function registerWithDoctor(
 
   return { registryPath, entry, created: !fileExisted, replaced };
 }
+
+/**
+ * The candidate registry files nectar's entry may live in (PRD-003b b-AC-3): the
+ * fleet-root `registry.json` AND the legacy `~/.honeycomb/doctor.daemons.json`,
+ * so `uninstall` deletes the entry from whichever carries it. Deduped.
+ */
+export function doctorRegistryCandidatePaths(
+  home: string = homedir(),
+  env: NodeJS.ProcessEnv = process.env,
+): readonly string[] {
+  const fleetRoot = resolveApiaryRoot(env, { home });
+  const candidates = [join(fleetRoot, "registry.json"), join(legacyRuntimeDir(home), "doctor.daemons.json")];
+  return [...new Set(candidates)];
+}
+
+/** The outcome of deregistering nectar from one registry file. */
+export interface DeregisterFileResult {
+  /** The registry file path this result is for. */
+  readonly registryPath: string;
+  /** True when the file existed on disk. */
+  readonly fileExisted: boolean;
+  /** True when a nectar entry was present and removed. */
+  readonly removed: boolean;
+  /** A plain-language reason the file could not be processed (malformed / write failed), or null. */
+  readonly error: string | null;
+}
+
+/** The aggregate outcome of {@link deregisterFromDoctor} across every candidate file. */
+export interface DeregisterResult {
+  readonly files: readonly DeregisterFileResult[];
+  /** True when a nectar entry was removed from at least one file. */
+  readonly removedAny: boolean;
+}
+
+export interface DeregisterFromDoctorOptions {
+  /** Override the registry file paths (default: {@link doctorRegistryCandidatePaths}). */
+  readonly registryPaths?: readonly string[];
+}
+
+/**
+ * Delete nectar's entry (keyed by `name: "nectar"`) from doctor's registry
+ * (PRD-003b b-AC-3), checking BOTH the fleet-root `registry.json` and the legacy
+ * `~/.honeycomb/doctor.daemons.json`. Every OTHER daemon's entry AND every
+ * unknown top-level key is preserved byte-for-byte; the write is atomic (temp +
+ * same-directory rename). Unlike the install writer, this is best-effort per
+ * file: a present-but-malformed registry is reported as an `error` rather than
+ * throwing, so `uninstall` never crashes on one bad file. An absent file is a
+ * clean no-op (`fileExisted: false`).
+ */
+export function deregisterFromDoctor(options: DeregisterFromDoctorOptions = {}): DeregisterResult {
+  const paths = options.registryPaths ?? doctorRegistryCandidatePaths();
+  const files = paths.map(deregisterOne);
+  return { files, removedAny: files.some((f) => f.removed) };
+}
+
+/** Remove nectar's entry from a single registry file, best-effort (never throws). */
+function deregisterOne(registryPath: string): DeregisterFileResult {
+  let existing: ExistingRegistry;
+  try {
+    existing = readExistingRegistry(registryPath);
+  } catch (err) {
+    // A present-but-malformed file: report, do not clobber, do not throw.
+    return {
+      registryPath,
+      fileExisted: true,
+      removed: false,
+      error: err instanceof Error ? err.message : String(err),
+    };
+  }
+
+  if (!existing.fileExisted) {
+    return { registryPath, fileExisted: false, removed: false, error: null };
+  }
+  const hadNectar = existing.daemons.some(isNectarEntry);
+  if (!hadNectar) {
+    return { registryPath, fileExisted: true, removed: false, error: null };
+  }
+  const kept = existing.daemons.filter((raw) => !isNectarEntry(raw));
+  try {
+    writeRegistryAtomic(registryPath, { ...existing.root, daemons: kept });
+  } catch (err) {
+    return {
+      registryPath,
+      fileExisted: true,
+      removed: false,
+      error: err instanceof Error ? err.message : String(err),
+    };
+  }
+  return { registryPath, fileExisted: true, removed: true, error: null };
+}
diff --git a/src/fleet-detection.ts b/src/fleet-detection.ts
new file mode 100644
index 0000000..0cb7682
--- /dev/null
+++ b/src/fleet-detection.ts
@@ -0,0 +1,207 @@
+/**
+ * Solo-vs-fleet detection for nectar (PRD-003a a-AC-6).
+ *
+ * nectar must decide whether Hive is installed alongside it BEFORE it initiates
+ * any device-flow login. The rule ("authentication is a HIVE concern when Hive
+ * is present; solo installs self-serve") is settled by three LIVE signals,
+ * evaluated at each decision point (the `install` verb):
+ *
+ *   S1 - a `daemons` entry named "hive" in the registry, reading BOTH the fleet
+ *        root `registry.json` (`~/.apiary/registry.json`) and the legacy
+ *        `~/.honeycomb/doctor.daemons.json` (whichever exist).
+ *   S2 - any HTTP response from `http://127.0.0.1:3853/health` within a short
+ *        (~750ms) budget (AbortController + the global `fetch`).
+ *   S3 - `@legioncodeinc/hive` present in `npm ls -g @legioncodeinc/hive
+ *        --depth 0` (best-effort `execFile`, NEVER a shell; any failure means
+ *        the signal is absent).
+ *
+ * Classification (orchestrator decision, do not re-litigate): ANY signal fired
+ * means FLEET; none means SOLO. Suppressing a popup wrongly is cheap; opening
+ * one wrongly is the bug this module exists to kill. The result records which
+ * signals fired so the caller can log the evidence (a-AC-6).
+ *
+ * This mirrors honeycomb's `src/shared/fleet-detection.ts` contract but is
+ * implemented independently against nectar's own `apiary-root` helpers, never
+ * imported across the process boundary (ADR-0002). Every signal is behind an
+ * injectable seam so tests drive the whole surface deterministically: no
+ * network, no real home dir, no `npm` subprocess.
+ *
+ * Built-ins only (`node:fs`, `node:child_process` loaded lazily) + the global
+ * `fetch`; zero runtime dependencies.
+ */
+import { execFile } from "node:child_process";
+import { existsSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { legacyRuntimeDir, resolveApiaryRoot } from "./apiary-root.js";
+
+/** The Hive portal loopback host (S2). */
+export const HIVE_HOST = "127.0.0.1" as const;
+/** The Hive portal loopback port (S2): 3853, distinct from nectar's 3854. */
+export const HIVE_PORT = 3853 as const;
+/** The npm global package name that proves Hive is installed (S3). */
+export const HIVE_NPM_PACKAGE = "@legioncodeinc/hive" as const;
+/** The registry `daemons[].name` that proves Hive is registered (S1). */
+export const HIVE_REGISTRY_NAME = "hive" as const;
+/** The fleet-root registry file name (`~/.apiary/registry.json`) - S1 primary source. */
+const FLEET_REGISTRY_FILE_NAME = "registry.json" as const;
+/** The legacy registry file name (`~/.honeycomb/doctor.daemons.json`) - S1 compat source. */
+const LEGACY_REGISTRY_FILE_NAME = "doctor.daemons.json" as const;
+/** The default budget (ms) for the live Hive-port probe (S2). */
+export const FLEET_PORT_PROBE_TIMEOUT_MS = 750;
+
+/** The two mutually-exclusive machine classifications. */
+export type FleetMode = "solo" | "fleet";
+
+/** Which of the three detection signals fired. */
+export interface FleetSignals {
+  /** S1: a Hive entry exists in the fleet or legacy registry file. */
+  readonly registryHiveEntry: boolean;
+  /** S2: the Hive portal answered on 127.0.0.1:3853 within the probe budget. */
+  readonly hivePortAnswering: boolean;
+  /** S3: `@legioncodeinc/hive` is present in the npm global tree. */
+  readonly hiveNpmGlobal: boolean;
+}
+
+/** The deterministic classification result - the mode plus the evidence for it (a-AC-6). */
+export interface FleetClassification {
+  /** `fleet` when ANY signal fired; `solo` when none did. */
+  readonly mode: FleetMode;
+  /** The raw per-signal booleans. */
+  readonly signals: FleetSignals;
+  /** Human-readable labels of the signals that fired (for logs / status). */
+  readonly firedSignals: readonly string[];
+}
+
+/**
+ * The injectable seams. Production leaves all unset (the real fs / fetch / npm
+ * defaults apply); a test injects each to drive the classification without
+ * touching the network, the real home, or an `npm` subprocess.
+ */
+export interface FleetDetectionSeams {
+  /** Override S1 wholesale (else the default reads the two registry files under `home`/`env`). */
+  readonly readRegistrySignal?: () => boolean;
+  /** Override S2 wholesale (else the default probes 127.0.0.1:3853/health). */
+  readonly probeHivePort?: (timeoutMs: number) => Promise<boolean>;
+  /** Override S3 wholesale (else the default runs `npm ls -g` best-effort). */
+  readonly npmGlobalHasHive?: () => Promise<boolean>;
+  /** The home dir the registry paths resolve under. Defaults to `os.homedir()`. */
+  readonly home?: string;
+  /** The env the fleet root resolves from. Defaults to `process.env`. */
+  readonly env?: NodeJS.ProcessEnv;
+  /** The platform (steers the npm binary name). Defaults to `process.platform`. */
+  readonly platform?: NodeJS.Platform;
+}
+
+/** True when the registry document at `path` carries a `daemons[]` entry named "hive". */
+function registryFileHasHive(path: string): boolean {
+  if (!existsSync(path)) return false;
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(readFileSync(path, "utf8"));
+  } catch {
+    return false;
+  }
+  if (typeof parsed !== "object" || parsed === null) return false;
+  const daemons = (parsed as { daemons?: unknown }).daemons;
+  if (!Array.isArray(daemons)) return false;
+  return daemons.some(
+    (entry) => typeof entry === "object" && entry !== null && (entry as { name?: unknown }).name === HIVE_REGISTRY_NAME,
+  );
+}
+
+/** The candidate registry paths S1 reads: the fleet-root file, then the legacy file. */
+export function registryCandidatePaths(seams: FleetDetectionSeams = {}): readonly string[] {
+  const env = seams.env ?? process.env;
+  const home = seams.home ?? homedir();
+  const rootOptions = {
+    ...(seams.home !== undefined ? { home: seams.home } : {}),
+    ...(seams.platform !== undefined ? { platform: seams.platform } : {}),
+  };
+  return [
+    join(resolveApiaryRoot(env, rootOptions), FLEET_REGISTRY_FILE_NAME),
+    join(legacyRuntimeDir(home), LEGACY_REGISTRY_FILE_NAME),
+  ];
+}
+
+/** The default S1: read the fleet + legacy registry files for a Hive entry. */
+export function defaultReadRegistrySignal(seams: FleetDetectionSeams = {}): boolean {
+  return registryCandidatePaths(seams).some(registryFileHasHive);
+}
+
+/** The default S2: any HTTP answer from the Hive portal within `timeoutMs` proves it is up. */
+export async function defaultProbeHivePort(timeoutMs: number = FLEET_PORT_PROBE_TIMEOUT_MS): Promise<boolean> {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+  if (typeof timer.unref === "function") timer.unref();
+  try {
+    await fetch(`http://${HIVE_HOST}:${HIVE_PORT}/health`, { method: "GET", signal: controller.signal });
+    return true;
+  } catch {
+    return false;
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+/**
+ * The default S3: `npm ls -g @legioncodeinc/hive --depth 0`, best-effort and
+ * fixed-argv. Any failure (npm missing, a non-zero exit because the package
+ * is absent, a timeout) resolves `false` - the signal is present only when npm
+ * exits 0 AND names the package. `npm` ships as `npm.cmd` on Windows, and since
+ * Node's CVE-2024-27980 hardening a `.cmd` cannot be spawned with `shell: false`
+ * (it throws EINVAL, which would silently blind this signal on every Windows
+ * machine), so win32 alone sets `shell: true` - safe here because every argv
+ * element is a compile-time constant, never user input.
+ */
+export function defaultNpmGlobalHasHive(seams: FleetDetectionSeams = {}): Promise<boolean> {
+  return new Promise<boolean>((resolve) => {
+    try {
+      const platform = seams.platform ?? process.platform;
+      const win32 = platform === "win32";
+      execFile(
+        win32 ? "npm.cmd" : "npm",
+        ["ls", "-g", HIVE_NPM_PACKAGE, "--depth", "0"],
+        { timeout: 5000, windowsHide: true, shell: win32 },
+        (err, stdout) => {
+          if (err) {
+            resolve(false);
+            return;
+          }
+          resolve(typeof stdout === "string" && stdout.includes(HIVE_NPM_PACKAGE));
+        },
+      );
+    } catch {
+      resolve(false);
+    }
+  });
+}
+
+/**
+ * Classify the machine solo-vs-fleet from the three LIVE signals (a-AC-6). ANY
+ * signal fired means FLEET; none means SOLO. Deterministic for a given machine
+ * state, and the result records which signals fired so the caller can log the
+ * evidence. S2 (the network probe) and S3 (the npm read) run concurrently; S1
+ * is a cheap synchronous file read.
+ */
+export async function classifyFleet(seams: FleetDetectionSeams = {}): Promise<FleetClassification> {
+  const registryHiveEntry = (seams.readRegistrySignal ?? (() => defaultReadRegistrySignal(seams)))();
+  const [hivePortAnswering, hiveNpmGlobal] = await Promise.all([
+    (seams.probeHivePort ?? defaultProbeHivePort)(FLEET_PORT_PROBE_TIMEOUT_MS),
+    (seams.npmGlobalHasHive ?? (() => defaultNpmGlobalHasHive(seams)))(),
+  ]);
+  const signals: FleetSignals = { registryHiveEntry, hivePortAnswering, hiveNpmGlobal };
+  const firedSignals: string[] = [];
+  if (registryHiveEntry) firedSignals.push("registry Hive entry");
+  if (hivePortAnswering) firedSignals.push("Hive portal on 127.0.0.1:3853");
+  if (hiveNpmGlobal) firedSignals.push(`npm global ${HIVE_NPM_PACKAGE}`);
+  return { mode: firedSignals.length > 0 ? "fleet" : "solo", signals, firedSignals };
+}
+
+/** A one-line, log-friendly summary of a classification (a-AC-6 supportability). */
+export function fleetSignalLine(classification: FleetClassification): string {
+  if (classification.mode === "fleet") {
+    return `fleet detection: FLEET (signals fired: ${classification.firedSignals.join(", ")}).`;
+  }
+  return "fleet detection: SOLO (no Hive signals fired: no registry entry, no 127.0.0.1:3853 answer, no npm global).";
+}
diff --git a/src/health.ts b/src/health.ts
index 29dca0e..a7c3931 100644
--- a/src/health.ts
+++ b/src/health.ts
@@ -14,6 +14,21 @@ export type PipelineStatus = "ok" | "degraded";
 export interface HealthBody {
   status: PipelineStatus;
   uptimeMs: number;
+  /**
+   * PRD-003a (a-AC-1 / a-AC-2): the durable-store reachability posture, which is
+   * the sole determinant of the coarse `status` bit today. A daemon that booted
+   * without resolvable Deeplake credentials reports `reachable: false` with
+   * `reason: "credentials-missing"`, which flips `status` to `degraded` so
+   * `/health` answers 503 while the process stays up (the pre-login fleet
+   * posture). When credentials appear (`nectar login` or a hive-side login), the
+   * credentials watch flips this back to `reachable: true` / `status: ok` without
+   * a restart. `reachable: true` (the default) leaves the daemon `ok`.
+   */
+  storage: {
+    reachable: boolean;
+    /** Machine-readable reason storage is unreachable (`"credentials-missing"`), or null when reachable. */
+    reason: string | null;
+  };
   brooding: {
     active: boolean;
     /**
@@ -105,6 +120,10 @@ export class HealthState {
   private startedAtMs = Date.now();
   private status: PipelineStatus = "ok";
 
+  readonly storage: HealthBody["storage"] = {
+    reachable: true,
+    reason: null,
+  };
   readonly brooding: HealthBody["brooding"] = {
     active: false,
     reason: null,
@@ -146,6 +165,21 @@ export class HealthState {
     this.startedAtMs = atMs;
   }
 
+  /**
+   * Set the durable-store reachability posture (PRD-003a a-AC-1 / a-AC-2) and
+   * flip the coarse `status` bit accordingly: `reachable: false` degrades the
+   * daemon (`/health` -> 503) with the given machine-readable reason;
+   * `reachable: true` restores `ok` (200) and clears the reason. This is the
+   * only runtime path that toggles `status` today, so a credentials-missing boot
+   * serves 503 degraded while the process stays up, and the credentials watch
+   * restores 200 without a restart the moment credentials appear.
+   */
+  setStorageState(state: { reachable: boolean; reason: string | null }): void {
+    this.storage.reachable = state.reachable;
+    this.storage.reason = state.reachable ? null : state.reason;
+    this.status = state.reachable ? "ok" : "degraded";
+  }
+
   /**
    * Record the resolved provider state (PRD-010 / PRD-014, decision #20's
    * purpose-built health shape). Resolved ONCE at assemble/start from the
@@ -258,6 +292,7 @@ export class HealthState {
     return {
       status: this.status,
       uptimeMs: Math.max(0, nowMs - this.startedAtMs),
+      storage: { ...this.storage },
       brooding: { ...this.brooding },
       enricher: { ...this.enricher },
       projection: { ...this.projection },
diff --git a/src/hive-graph/deeplake-credentials.ts b/src/hive-graph/deeplake-credentials.ts
index 9a9e48a..3dbde52 100644
--- a/src/hive-graph/deeplake-credentials.ts
+++ b/src/hive-graph/deeplake-credentials.ts
@@ -22,7 +22,7 @@
  * `redactToken` (`src/daemon/runtime/auth/credentials-store.ts:254-257`, its
  * `defaultCredentialProvider` variant).
  */
-import { existsSync, readFileSync, statSync } from "node:fs";
+import { existsSync, mkdirSync, readFileSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { join } from "node:path";
 
@@ -162,6 +162,93 @@ function warnIfWorldReadable(path: string, options: LoadCredentialsOptions): voi
   );
 }
 
+/**
+ * POSIX mode for the credentials file: owner read/write only (PRD-003a). On
+ * win32 these bits are a documented best-effort no-op (NTFS ACLs, not POSIX).
+ */
+export const CREDENTIALS_FILE_MODE = 0o600;
+/** POSIX mode for the credentials dir: owner read/write/execute only (PRD-003a). */
+export const CREDENTIALS_DIR_MODE = 0o700;
+
+/**
+ * The full ON-DISK credential shape `nectar login` writes (PRD-003a a-AC-5),
+ * BYTE-COMPATIBLE with honeycomb's `DiskCredentials`
+ * (`honeycomb/src/daemon/runtime/auth/credentials-store.ts`) so one login
+ * authenticates both tools against the SAME `~/.deeplake/credentials.json`.
+ * `token` + `orgId` are load-bearing; the rest are Hivemind-shape fields the
+ * reader tolerates as optional (`loadDeepLakeCredentials` requires only
+ * `token`/`orgId`/`workspaceId`). Written verbatim, never logged.
+ */
+export interface DiskCredentials {
+  /** The org-bound bearer token (SECRET; never logged in full). */
+  readonly token: string;
+  /** The org id the token is bound to. */
+  readonly orgId: string;
+  /** The human-readable org name (display only). */
+  readonly orgName?: string;
+  /** The authenticated user's display name (Hivemind field). */
+  readonly userName?: string;
+  /** The active workspace id (maps to honeycomb's in-memory `workspace`). */
+  readonly workspaceId?: string;
+  /** The Deep Lake API base URL the credential was minted against. */
+  readonly apiUrl?: string;
+  /** ISO 8601 timestamp stamped server-side on save. */
+  readonly savedAt: string;
+}
+
+/** Options for {@link saveDeepLakeCredentials}: the (test-overridable) dir + an injectable clock. */
+export interface SaveCredentialsOptions extends LoadCredentialsOptions {
+  /** Stamps `savedAt`. Default: the real wall clock. */
+  readonly clock?: { now(): string };
+}
+
+/**
+ * Persist a {@link DiskCredentials} record to the SHARED
+ * `~/.deeplake/credentials.json` (PRD-003a a-AC-5), byte-compatible with
+ * honeycomb's `saveDiskCredentials`: the dir is created at `0700` if absent, the
+ * file is written at `0600`, and `savedAt` is stamped server-side from the
+ * injected clock (IGNORING any value on the input - the timestamp is evidence,
+ * not caller input). The token is carried verbatim and NEVER logged here.
+ *
+ * The write is ATOMIC (security audit 2026-07-04): the payload lands in a
+ * same-directory temp file created at `0600`, then renames over the target. A
+ * crash mid-write can never leave a truncated shared credential file for a
+ * concurrent reader (honeycomb, or nectar's own credentials watch), and because
+ * the rename replaces the old inode, a pre-existing loose-mode (e.g. 0644)
+ * credentials file never receives the fresh token - the replacement is
+ * owner-only from birth, with no write-then-chmod window.
+ *
+ * Returns the persisted record (with the stamped `savedAt`) so a caller need not
+ * re-read. The written shape is exactly what {@link loadDeepLakeCredentials}
+ * reads back, so `nectar`'s next storage attempt succeeds.
+ */
+export function saveDeepLakeCredentials(
+  disk: DiskCredentials,
+  options: SaveCredentialsOptions = {},
+): DiskCredentials {
+  const dir = credentialsDir(options);
+  if (!existsSync(dir)) {
+    mkdirSync(dir, { recursive: true, mode: CREDENTIALS_DIR_MODE });
+  }
+  const now = options.clock?.now ?? (() => new Date().toISOString());
+  const stamped: DiskCredentials = { ...disk, savedAt: now() };
+  const target = credentialsPath(options);
+  const tmpPath = join(dir, `.${CREDENTIALS_FILE_NAME}.${process.pid}.${Date.now()}.tmp`);
+  try {
+    writeFileSync(tmpPath, `${JSON.stringify(stamped, null, 2)}\n`, { mode: CREDENTIALS_FILE_MODE });
+    renameSync(tmpPath, target);
+  } catch (err) {
+    // Never leave a token-bearing temp file behind on failure.
+    try {
+      rmSync(tmpPath, { force: true });
+    } catch {
+      /* best-effort cleanup */
+    }
+    throw err;
+  }
+  return stamped;
+}
+
 /**
  * Redact a token for logs and errors. Never echoes a token in full: keeps the
  * last 4 chars for correlation, masks the rest. An empty/short value collapses
diff --git a/src/lifecycle.ts b/src/lifecycle.ts
new file mode 100644
index 0000000..a37179a
--- /dev/null
+++ b/src/lifecycle.ts
@@ -0,0 +1,254 @@
+/**
+ * The `nectar start` / `stop` / `uninstall` lifecycle orchestration (PRD-003b
+ * b-AC-1/2/3/4/6).
+ *
+ * These verbs FRONT the machinery nectar already has - the OS service module
+ * (`service/index.ts`), the daemon lock/pid files (`lock.ts`), the doctor
+ * registry writer (`doctor-registry.ts`), and the fleet-root state dir
+ * (`apiary-root.ts`) - never fork it. Every external effect is behind an
+ * injectable seam so the orchestration is fully hermetic in tests (no real
+ * service manager, no real signals, no real home dir).
+ *
+ * - start: already-running -> a friendly no-op; otherwise start the registered
+ *   OS unit, falling back to a direct detached spawn when no unit is registered.
+ * - stop: best-effort stop the OS unit AND signal the running pid, so both a
+ *   service-managed and a directly-spawned daemon stop. Idempotent (a not-running
+ *   daemon is a friendly no-op).
+ * - uninstall: the three-part contract in order - stop the daemon, remove the OS
+ *   unit (current + legacy best-effort), delete nectar's doctor registry entry,
+ *   remove nectar's state dir (resolved absolute path only, never a glob, never
+ *   following a symlink out of the root). Each step is best-effort with a
+ *   per-step report; a not-installed machine exits 0 "nothing to remove" (b-AC-6);
+ *   a real per-step failure exits 1 with a plain-language, actionable error.
+ *   The CURRENT-label service unit is the one exception to "best-effort never
+ *   fails the run": {@link ServiceModule.uninstall} classifies its own outcome
+ *   (see {@link ServiceUninstallResult}), and a GENUINE removal failure (not
+ *   merely the unit having been already absent) is a hard failure here too -
+ *   a swallowed error there would leave a unit that resurrects on next boot
+ *   while `nectar uninstall` reports success (b-AC-2 / AC-9). The remaining
+ *   steps still run best-effort so a partial uninstall never wedges. The
+ *   legacy-label deregister stays fully best-effort/non-fatal, since a legacy
+ *   unit being absent is the norm, not the exception.
+ *
+ * Built-ins only.
+ */
+import type { ServiceModule, ServiceResult, ServiceUninstallResult } from "./service/index.js";
+import type { DeregisterResult } from "./doctor-registry.js";
+
+/** The output/error sinks the verbs write through (injected so tests capture them). */
+export interface LifecycleIo {
+  out(line: string): void;
+  err(line: string): void;
+}
+
+// ── start ────────────────────────────────────────────────────────────────────
+
+export interface StartLifecycleDeps {
+  readonly service: ServiceModule;
+  /** True when a live daemon currently holds the lock. */
+  isDaemonRunning(): boolean;
+  /** The pid recorded in the pid/lock file, or null. */
+  readPid(): number | null;
+  /** Directly spawn the daemon (detached). Returns the spawned pid, or null on failure. */
+  spawnDaemon(): number | null;
+  readonly io: LifecycleIo;
+}
+
+/**
+ * `nectar start` (b-AC-1). If a daemon is already running, a friendly no-op.
+ * Otherwise start the registered OS unit; if no unit is registered (the manager
+ * start argv fails), fall back to a direct detached spawn.
+ */
+export async function runStartLifecycle(deps: StartLifecycleDeps): Promise<number> {
+  if (deps.isDaemonRunning()) {
+    const pid = deps.readPid();
+    deps.io.out(`nectar is already running${pid !== null ? ` (pid ${pid})` : ""}.`);
+    return 0;
+  }
+  const viaService = await deps.service.start();
+  if (viaService.ok) {
+    deps.io.out(viaService.message);
+    return 0;
+  }
+  const pid = deps.spawnDaemon();
+  if (pid === null) {
+    deps.io.err(
+      `nectar start: could not start via the OS service (${viaService.message}) and the direct spawn failed. ` +
+        "Try 'nectar daemon' in a terminal to see the error.",
+    );
+    return 1;
+  }
+  deps.io.out(`nectar daemon started directly (pid ${pid}).`);
+  return 0;
+}
+
+// ── stop ─────────────────────────────────────────────────────────────────────
+
+export interface StopLifecycleDeps {
+  readonly service: ServiceModule;
+  isDaemonRunning(): boolean;
+  readPid(): number | null;
+  /** Send a signal to a pid; returns true when the signal was delivered. */
+  sendSignal(pid: number, signal: NodeJS.Signals): boolean;
+  readonly io: LifecycleIo;
+}
+
+/**
+ * `nectar stop` (b-AC-1). Best-effort stops the registered OS unit AND signals
+ * the running pid, so both a service-managed and a directly-spawned daemon stop.
+ * A not-running daemon is a friendly no-op. Always exits 0 (idempotent, AC-9).
+ */
+export async function runStopLifecycle(deps: StopLifecycleDeps): Promise<number> {
+  const running = deps.isDaemonRunning();
+  const pid = deps.readPid();
+  if (!running && pid === null) {
+    deps.io.out("nectar is not running; nothing to stop.");
+    return 0;
+  }
+  const viaService = await deps.service.stop();
+  if (viaService.ok) deps.io.out(viaService.message);
+  let signalled = false;
+  if (pid !== null) signalled = deps.sendSignal(pid, "SIGTERM");
+  if (signalled) deps.io.out(`Sent SIGTERM to the nectar daemon (pid ${pid}).`);
+  if (!viaService.ok && !signalled) {
+    deps.io.out("nectar stop: no running daemon was signalled (it may already be stopped).");
+  }
+  return 0;
+}
+
+// ── uninstall ──────────────────────────────────────────────────────────────────
+
+/** The classified outcome of removing nectar's state dir. */
+export type StateDirRemovalStatus = "removed" | "absent" | "skipped-symlink" | "failed";
+
+export interface StateDirRemovalResult {
+  readonly status: StateDirRemovalStatus;
+  readonly path: string;
+  readonly reason?: string;
+}
+
+/** The minimal fs surface {@link removeStateDir} needs (injected so tests are hermetic). */
+export interface StateDirFs {
+  isAbsolute(path: string): boolean;
+  exists(path: string): boolean;
+  /** True iff the path itself is a symlink (an lstat, NOT following it). */
+  isSymlink(path: string): boolean;
+  /** Recursively remove the directory (force). Never follows a symlink out of the root. */
+  rm(path: string): void;
+}
+
+/**
+ * Remove nectar's state dir by RESOLVED ABSOLUTE PATH only (b-AC-4 / AC-8): a
+ * non-absolute path is refused; an absent dir is a clean no-op; a path that is
+ * itself a symlink is refused (so a symlinked state dir never lets a delete
+ * escape the fleet root). Never globs. Returns the classified outcome.
+ */
+export function removeStateDir(dir: string, fs: StateDirFs): StateDirRemovalResult {
+  if (!fs.isAbsolute(dir)) {
+    return { status: "failed", path: dir, reason: "refusing to remove a non-absolute state dir path" };
+  }
+  if (!fs.exists(dir)) return { status: "absent", path: dir };
+  if (fs.isSymlink(dir)) return { status: "skipped-symlink", path: dir };
+  try {
+    fs.rm(dir);
+    return { status: "removed", path: dir };
+  } catch (err) {
+    return { status: "failed", path: dir, reason: err instanceof Error ? err.message : String(err) };
+  }
+}
+
+export interface UninstallLifecycleDeps {
+  readonly service: ServiceModule;
+  isDaemonRunning(): boolean;
+  readPid(): number | null;
+  sendSignal(pid: number, signal: NodeJS.Signals): boolean;
+  /** Delete nectar's entry from doctor's registry file(s). */
+  deregisterFromDoctor(): DeregisterResult;
+  /** Remove nectar's resolved state dir (guarded). */
+  removeStateDir(): StateDirRemovalResult;
+  readonly io: LifecycleIo;
+}
+
+/**
+ * `nectar uninstall` (b-AC-2/3/4/6): the three-part contract in order. Each step
+ * is best-effort with a per-step report. A not-installed machine exits 0 with a
+ * friendly "nothing to remove" (b-AC-6); a real failure (a malformed registry it
+ * could not rewrite, or a state-dir removal error) exits 1 with an actionable
+ * message.
+ */
+export async function runUninstallLifecycle(deps: UninstallLifecycleDeps): Promise<number> {
+  const io = deps.io;
+  let hardFailure = false;
+
+  // 1. Stop the daemon (so doctor never sees a registered-but-gone product mid-flight).
+  const daemonWasRunning = deps.isDaemonRunning();
+  const pid = deps.readPid();
+  await deps.service.stop();
+  if (pid !== null) deps.sendSignal(pid, "SIGTERM");
+  if (daemonWasRunning) io.out("Stopped the running nectar daemon.");
+
+  // 2. Remove the OS service unit (current label, plus best-effort legacy label).
+  // b-AC-2 / AC-9: a GENUINE current-unit removal failure (classified by the
+  // service module, not merely "the unit was already absent") is a hard
+  // failure - it must not be swallowed into a reported success while a
+  // boot-resurrecting unit survives. The already-absent case stays the
+  // friendly no-op it always was.
+  const unit: ServiceUninstallResult = await deps.service.uninstall();
+  const legacy: ServiceResult = await deps.service.deregisterLegacy();
+  const serviceRemoved = unit.ok;
+  if (unit.ok || unit.alreadyAbsent) {
+    io.out(unit.message);
+  } else {
+    hardFailure = true;
+    io.err(`Could not remove the nectar service unit: ${unit.message}`);
+  }
+  io.out(legacy.message);
+
+  // 3. Delete nectar's doctor registry entry (leaving every other entry intact).
+  const registry = deps.deregisterFromDoctor();
+  for (const f of registry.files) {
+    if (f.error !== null) {
+      hardFailure = true;
+      io.err(`Could not update the doctor registry at ${f.registryPath}: ${f.error}`);
+    } else if (f.removed) {
+      io.out(`Deleted nectar's doctor registry entry from ${f.registryPath}.`);
+    }
+  }
+
+  // 4. Remove nectar's state dir (resolved absolute path only, no symlink follow).
+  const dir = deps.removeStateDir();
+  switch (dir.status) {
+    case "removed":
+      io.out(`Removed nectar's state dir at ${dir.path}.`);
+      break;
+    case "absent":
+      break;
+    case "skipped-symlink":
+      io.err(`Skipped nectar's state dir at ${dir.path}: it is a symlink; remove it manually if that was intended.`);
+      break;
+    case "failed":
+      hardFailure = true;
+      io.err(`Could not remove nectar's state dir at ${dir.path}: ${dir.reason ?? "unknown error"}`);
+      break;
+    default: {
+      const unreachable: never = dir.status;
+      throw new Error(`unhandled state-dir status: ${String(unreachable)}`);
+    }
+  }
+
+  const anythingRemoved = daemonWasRunning || serviceRemoved || registry.removedAny || dir.status === "removed";
+
+  if (hardFailure) {
+    io.err(
+      "nectar uninstall: one or more steps failed (see above). Resolve them and re-run 'nectar uninstall', " +
+        "or remove the paths manually.",
+    );
+    return 1;
+  }
+  if (!anythingRemoved) {
+    io.out("nectar uninstall: nothing to remove; nectar does not appear to be installed.");
+    return 0;
+  }
+  io.out("nectar uninstall: done. (The npm package itself is left in place; remove it with your package manager if desired.)");
+  return 0;
+}
diff --git a/src/service/argv.ts b/src/service/argv.ts
index edde39a..92d4ce4 100644
--- a/src/service/argv.ts
+++ b/src/service/argv.ts
@@ -135,6 +135,55 @@ export function legacyUninstallCommands(plan: ServicePlan, uid: number): readonl
   }
 }
 
+/**
+ * The argv to START an ALREADY-REGISTERED unit (PRD-003b b-AC-1), without
+ * creating it. Fronts the existing unit the installer laid down; when no unit is
+ * registered these commands fail and the CLI falls back to a direct spawn.
+ *   - launchd:  `kickstart -k <domain>/<label>` (start, restarting if running).
+ *   - systemd:  `systemctl [--user] start nectar.service`.
+ *   - schtasks: `/Run /TN nectar`.
+ *   - sc:       `sc start nectar`.
+ */
+export function startCommands(plan: ServicePlan, uid: number): readonly ServiceCommand[] {
+  switch (plan.manager) {
+    case "launchd":
+      return [{ command: "launchctl", args: ["kickstart", "-k", launchdServiceTarget(plan, uid)] }];
+    case "systemd": {
+      const scopeArgs = plan.scope === "user" ? ["--user"] : [];
+      return [{ command: "systemctl", args: [...scopeArgs, "start", SYSTEMD_UNIT_NAME] }];
+    }
+    case "schtasks":
+      return [{ command: "schtasks", args: ["/Run", "/TN", WINDOWS_TASK_NAME] }];
+    case "sc":
+      return [{ command: "sc", args: ["start", WINDOWS_TASK_NAME] }];
+  }
+}
+
+/**
+ * The argv to STOP a running unit (PRD-003b b-AC-1) WITHOUT removing it, so a
+ * later `start` can bring it back.
+ *   - launchd:  `bootout <domain>/<label>` (unload the running job; a KeepAlive
+ *               job cannot relaunch a booted-out target in this session).
+ *   - systemd:  `systemctl [--user] stop nectar.service` (a clean stop is not a
+ *               crash, so `Restart=` does not relaunch it).
+ *   - schtasks: `/End /TN nectar`.
+ *   - sc:       `sc stop nectar`.
+ */
+export function stopCommands(plan: ServicePlan, uid: number): readonly ServiceCommand[] {
+  switch (plan.manager) {
+    case "launchd":
+      return [{ command: "launchctl", args: ["bootout", launchdServiceTarget(plan, uid)] }];
+    case "systemd": {
+      const scopeArgs = plan.scope === "user" ? ["--user"] : [];
+      return [{ command: "systemctl", args: [...scopeArgs, "stop", SYSTEMD_UNIT_NAME] }];
+    }
+    case "schtasks":
+      return [{ command: "schtasks", args: ["/End", "/TN", WINDOWS_TASK_NAME] }];
+    case "sc":
+      return [{ command: "sc", args: ["stop", WINDOWS_TASK_NAME] }];
+  }
+}
+
 /** The single argv to QUERY status. The caller interprets the command's exit/stdout. */
 export function statusCommand(plan: ServicePlan, uid: number): ServiceCommand {
   switch (plan.manager) {
diff --git a/src/service/index.ts b/src/service/index.ts
index e31f6a9..6550e67 100644
--- a/src/service/index.ts
+++ b/src/service/index.ts
@@ -26,7 +26,9 @@ import { createExecFileRunner, type CommandResult, type CommandRunner } from "./
 import {
   installCommands,
   legacyUninstallCommands,
+  startCommands,
   statusCommand,
+  stopCommands,
   uninstallCommands,
   type ServiceCommand,
 } from "./argv.js";
@@ -54,6 +56,24 @@ export interface ServiceResult {
   readonly message: string;
 }
 
+/**
+ * The outcome of {@link ServiceModule.uninstall}, additionally classified so a
+ * caller (the lifecycle's `uninstall` verb) can tell a genuine removal failure
+ * from the unit simply having been absent already (PRD-003b b-AC-2 / AC-9): a
+ * boot-resurrecting unit left behind by a swallowed "it was probably already
+ * gone" error is exactly the failure mode this classification exists to catch.
+ */
+export interface ServiceUninstallResult extends ServiceResult {
+  /**
+   * True when the manager reported the unit was not registered/found rather
+   * than a real error (permission denied, manager unreachable, etc.). A
+   * true `alreadyAbsent` is a friendly no-op; `ok` stays false either way
+   * since nothing was actually removed by THIS call - callers should only
+   * treat `alreadyAbsent === false` as requiring a hard failure.
+   */
+  readonly alreadyAbsent: boolean;
+}
+
 /** Per-command timeout for a service-manager shell-out (these are fast, local commands). */
 const SERVICE_COMMAND_TIMEOUT_MS = 15_000;
 
@@ -146,6 +166,37 @@ function lastNonEmptyLine(text: string): string | null {
   return lines.length > 0 ? (lines[lines.length - 1] ?? null) : null;
 }
 
+/**
+ * True when a failed uninstall command's result indicates the unit was
+ * already absent (not currently registered) rather than a genuine removal
+ * failure. Each service manager reports "not found" differently; `sc.exe`'s
+ * numeric `ERROR_SERVICE_DOES_NOT_EXIST` (1060) and launchd's `ESRCH`-derived
+ * exit code (3) are locale-independent, so they are checked directly. Every
+ * manager additionally falls back to a broad, case-insensitive text match
+ * over stdout/stderr/detail. Anything that does not match is conservatively
+ * treated as a GENUINE failure (never silently swallowed) - this is the
+ * classification b-AC-2 / AC-9 depend on.
+ */
+function isAlreadyAbsentFailure(manager: ServicePlan["manager"], result: CommandResult | null): boolean {
+  if (result === null) return false;
+  const text = `${result.detail ?? ""} ${result.stderr} ${result.stdout}`.toLowerCase();
+  const genericAbsent = /does not exist|cannot find|no such process|not[- ]loaded|could not find|not found/;
+  switch (manager) {
+    case "launchd":
+      return result.code === 3 || genericAbsent.test(text);
+    case "systemd":
+      return genericAbsent.test(text);
+    case "schtasks":
+      return genericAbsent.test(text);
+    case "sc":
+      return result.code === 1060 || genericAbsent.test(text);
+    default: {
+      const unreachable: never = manager;
+      return unreachable;
+    }
+  }
+}
+
 /**
  * Run an ordered list of commands, stopping at nothing (every result is recorded)
  * but reporting the first hard failure (and its result, for {@link describeFailure}).
@@ -167,10 +218,17 @@ async function runAll(
   return { allOk: firstFailure === null, firstFailure, firstFailureResult };
 }
 
-/** The service module surface: install / uninstall the OS service unit. */
+/** The service module surface: install / uninstall / start / stop the OS service unit. */
 export interface ServiceModule {
   install(): Promise<ServiceResult>;
-  uninstall(): Promise<ServiceResult>;
+  /** Remove the CURRENT-label unit, classified so a genuine failure is never mistaken for a no-op. */
+  uninstall(): Promise<ServiceUninstallResult>;
+  /** Start an already-registered unit (PRD-003b b-AC-1). */
+  start(): Promise<ServiceResult>;
+  /** Stop a running unit without removing it (PRD-003b b-AC-1). */
+  stop(): Promise<ServiceResult>;
+  /** Best-effort deregister the legacy-labelled unit + remove its unit file (PRD-003b b-AC-2). */
+  deregisterLegacy(): Promise<ServiceResult>;
 }
 
 /**
@@ -263,13 +321,14 @@ export function createServiceModule(deps: ServiceModuleDeps): ServiceModule {
       };
     },
 
-    async uninstall(): Promise<ServiceResult> {
+    async uninstall(): Promise<ServiceUninstallResult> {
       let p: ServicePlan;
       try {
         p = plan();
       } catch (error) {
         return {
           ok: false,
+          alreadyAbsent: false,
           message: `Could not unregister the nectar service: ${error instanceof Error ? error.message : "unknown error"}.`,
         };
       }
@@ -291,24 +350,103 @@ export function createServiceModule(deps: ServiceModuleDeps): ServiceModule {
 
       if (!allOk) {
         const detail = describeFailure(firstFailureResult);
+        const alreadyAbsent = isAlreadyAbsentFailure(p.manager, firstFailureResult);
         log({
-          level: "warn",
+          level: alreadyAbsent ? "info" : "warn",
           scope: "service",
           msg: "uninstall_command_failed",
           command: firstFailure?.command,
           detail,
+          alreadyAbsent,
         });
+        if (alreadyAbsent) {
+          return {
+            ok: false,
+            alreadyAbsent: true,
+            message: `nectar ${p.manager} unit was already absent (nothing to remove).`,
+          };
+        }
         return {
           ok: false,
-          message: `Removed the nectar unit file; a deregister command (${firstFailure?.command ?? "unknown"}) reported an error (often because it was already gone): ${detail}.`,
+          alreadyAbsent: false,
+          message: `Could not remove the nectar ${p.manager} unit (${firstFailure?.command ?? "unknown"}): ${detail}.`,
         };
       }
       log({ level: "info", scope: "service", msg: "uninstalled", manager: p.manager, scope2: p.scope });
       return {
         ok: true,
+        alreadyAbsent: false,
         message: `nectar service unregistered (${p.manager}, ${scopePhrase(p)}). It will not start on next boot.`,
       };
     },
+
+    async start(): Promise<ServiceResult> {
+      let p: ServicePlan;
+      try {
+        p = plan();
+      } catch (error) {
+        return {
+          ok: false,
+          message: `Could not start the nectar service: ${error instanceof Error ? error.message : "unknown error"}.`,
+        };
+      }
+      const { allOk, firstFailure, firstFailureResult } = await runAll(runner, startCommands(p, uid));
+      if (!allOk) {
+        return {
+          ok: false,
+          message: `The nectar ${p.manager} unit did not start (${firstFailure?.command ?? "unknown"}): ${describeFailure(firstFailureResult)}.`,
+        };
+      }
+      log({ level: "info", scope: "service", msg: "started", manager: p.manager });
+      return { ok: true, message: `nectar started via ${p.manager} (${scopePhrase(p)}).` };
+    },
+
+    async stop(): Promise<ServiceResult> {
+      let p: ServicePlan;
+      try {
+        p = plan();
+      } catch (error) {
+        return {
+          ok: false,
+          message: `Could not stop the nectar service: ${error instanceof Error ? error.message : "unknown error"}.`,
+        };
+      }
+      const { allOk, firstFailure, firstFailureResult } = await runAll(runner, stopCommands(p, uid));
+      if (!allOk) {
+        return {
+          ok: false,
+          message: `The nectar ${p.manager} unit did not stop cleanly (${firstFailure?.command ?? "unknown"}): ${describeFailure(firstFailureResult)}.`,
+        };
+      }
+      log({ level: "info", scope: "service", msg: "stopped", manager: p.manager });
+      return { ok: true, message: `nectar stopped via ${p.manager} (${scopePhrase(p)}).` };
+    },
+
+    async deregisterLegacy(): Promise<ServiceResult> {
+      let p: ServicePlan;
+      try {
+        p = plan();
+      } catch (error) {
+        return {
+          ok: false,
+          message: `Could not deregister the legacy nectar service: ${error instanceof Error ? error.message : "unknown error"}.`,
+        };
+      }
+      // Best-effort: legacy commands fail harmlessly when no legacy unit exists.
+      const { allOk } = await runAll(runner, legacyUninstallCommands(p, uid));
+      try {
+        const legacyPath = legacyUnitPath(p);
+        if (legacyPath !== "") fs.removeFile(legacyPath);
+      } catch {
+        // Best-effort cleanup only; a remove failure never fails the uninstall.
+      }
+      return {
+        ok: true,
+        message: allOk
+          ? `legacy nectar unit deregistered (${p.manager}).`
+          : `legacy nectar unit deregister attempted (${p.manager}); it was likely already absent.`,
+      };
+    },
   };
 }
 
@@ -351,7 +489,7 @@ export {
   legacyUnitPath,
 } from "./platform.js";
 export { NECTAR_RUN_COMMAND, RESTART_SEC, WINDOWS_RESTART_INTERVAL, renderUnit } from "./templates.js";
-export { installCommands, uninstallCommands, legacyUninstallCommands, statusCommand } from "./argv.js";
+export { installCommands, uninstallCommands, legacyUninstallCommands, startCommands, stopCommands, statusCommand } from "./argv.js";
 export type { ServiceCommand } from "./argv.js";
 export { createExecFileRunner } from "./command-runner.js";
 export type { CommandRunner, CommandResult, CommandRunOptions } from "./command-runner.js";
diff --git a/test/cli-verbs.test.ts b/test/cli-verbs.test.ts
new file mode 100644
index 0000000..e89454c
--- /dev/null
+++ b/test/cli-verbs.test.ts
@@ -0,0 +1,50 @@
+/**
+ * PRD-003b b-AC-5: the new bare verbs (start/stop/uninstall/login/status) are
+ * wired, and every existing spelling (daemon/install/uninstall/service-status)
+ * keeps working, with `service-status` an alias of the new `status` verb.
+ * `main(["--help"])` lists them and exits 0 (AC-9: a clear terminating flow).
+ */
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { main } from "../dist/cli.js";
+
+const src = readFileSync(fileURLToPath(new URL("../dist/cli.js", import.meta.url)), "utf8");
+
+test("b-AC-5 status and service-status route to the SAME handler (alias)", () => {
+  assert.match(src, /command === "status" \|\| command === "service-status"/, "service-status is an alias of status");
+});
+
+test("b-AC-5 the new bare verbs are dispatched", () => {
+  assert.match(src, /command === "login"/);
+  assert.match(src, /command === "start"/);
+  assert.match(src, /command === "stop"/);
+  assert.match(src, /command === "uninstall"/);
+});
+
+test("b-AC-5 the existing spellings keep working (daemon / install / service-status)", () => {
+  assert.match(src, /command === "daemon"/);
+  assert.match(src, /command === "install"/);
+  assert.match(src, /command === "service-status"/);
+});
+
+test("AC-9 main --help lists the lifecycle + login verbs and exits 0", async () => {
+  const lines: string[] = [];
+  const original = process.stdout.write.bind(process.stdout);
+  (process.stdout as unknown as { write: (s: string) => boolean }).write = (s: string) => {
+    lines.push(String(s));
+    return true;
+  };
+  let code: number;
+  try {
+    code = await main(["--help"]);
+  } finally {
+    (process.stdout as unknown as { write: typeof original }).write = original;
+  }
+  const usage = lines.join("");
+  assert.equal(code, 0);
+  for (const verb of ["nectar login", "nectar start", "nectar stop", "nectar uninstall", "nectar status"]) {
+    assert.ok(usage.includes(verb), `USAGE documents '${verb}'`);
+  }
+});
diff --git a/test/credentials-writer.test.ts b/test/credentials-writer.test.ts
new file mode 100644
index 0000000..37ccc52
--- /dev/null
+++ b/test/credentials-writer.test.ts
@@ -0,0 +1,93 @@
+/**
+ * PRD-003a a-AC-5: `saveDeepLakeCredentials` writes the shared
+ * `~/.deeplake/credentials.json` in a shape byte-compatible with honeycomb's
+ * DiskCredentials, at owner-only permissions, with a server-stamped `savedAt`.
+ */
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { existsSync, mkdtempSync, readFileSync, rmSync, statSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import {
+  saveDeepLakeCredentials,
+  loadDeepLakeCredentials,
+  CREDENTIALS_FILE_MODE,
+  CREDENTIALS_DIR_MODE,
+} from "../dist/hive-graph/deeplake-credentials.js";
+
+function tmpDir(): string {
+  return mkdtempSync(join(tmpdir(), "nectar-creds-"));
+}
+
+test("a-AC-5 saveDeepLakeCredentials writes the honeycomb DiskCredentials shape, readable by loadDeepLakeCredentials", () => {
+  const dir = tmpDir();
+  try {
+    const saved = saveDeepLakeCredentials(
+      {
+        token: "tok-abc",
+        orgId: "org-1",
+        orgName: "Org One",
+        userName: "Ada",
+        workspaceId: "ws-1",
+        apiUrl: "https://api.deeplake.ai",
+        savedAt: "IGNORED",
+      },
+      { dir, clock: { now: () => "2026-07-04T12:00:00.000Z" } },
+    );
+    assert.equal(saved.savedAt, "2026-07-04T12:00:00.000Z", "savedAt is stamped server-side, ignoring the input");
+
+    const onDisk = JSON.parse(readFileSync(join(dir, "credentials.json"), "utf8"));
+    assert.deepEqual(onDisk, {
+      token: "tok-abc",
+      orgId: "org-1",
+      orgName: "Org One",
+      userName: "Ada",
+      workspaceId: "ws-1",
+      apiUrl: "https://api.deeplake.ai",
+      savedAt: "2026-07-04T12:00:00.000Z",
+    });
+
+    const loaded = loadDeepLakeCredentials({ dir });
+    assert.equal(loaded.token, "tok-abc");
+    assert.equal(loaded.orgId, "org-1");
+    assert.equal(loaded.workspaceId, "ws-1");
+    assert.equal(loaded.apiUrl, "https://api.deeplake.ai");
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test("a-AC-5 the credentials file is written owner-only on POSIX", { skip: process.platform === "win32" }, () => {
+  const dir = tmpDir();
+  try {
+    saveDeepLakeCredentials({ token: "t", orgId: "o", workspaceId: "w", savedAt: "" }, { dir });
+    const mode = statSync(join(dir, "credentials.json")).mode & 0o777;
+    assert.equal(mode, CREDENTIALS_FILE_MODE, "the token file is 0600 (owner read/write only)");
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test(
+  "a-AC-5 a freshly-created credentials directory is 0700 and its file is 0600, on POSIX",
+  { skip: process.platform === "win32" },
+  () => {
+    const base = tmpDir();
+    try {
+      // Use a NOT-YET-EXISTING subdirectory so saveDeepLakeCredentials's
+      // mkdirSync actually runs (the shared tmpDir() helper pre-creates the
+      // dir itself, which would skip the mkdirSync branch entirely).
+      const dir = join(base, "fresh", ".deeplake");
+      assert.equal(existsSync(dir), false, "the dir must not exist yet for the mkdirSync(mode) path to be exercised");
+
+      saveDeepLakeCredentials({ token: "t", orgId: "o", workspaceId: "w", savedAt: "" }, { dir });
+
+      const dirMode = statSync(dir).mode & 0o777;
+      assert.equal(dirMode, CREDENTIALS_DIR_MODE, "the credentials dir is created at 0700 (owner rwx only)");
+      const fileMode = statSync(join(dir, "credentials.json")).mode & 0o777;
+      assert.equal(fileMode, CREDENTIALS_FILE_MODE, "the credentials file is 0600 (owner rw only)");
+    } finally {
+      rmSync(base, { recursive: true, force: true });
+    }
+  },
+);
diff --git a/test/device-flow-login.test.ts b/test/device-flow-login.test.ts
new file mode 100644
index 0000000..9d48d7b
--- /dev/null
+++ b/test/device-flow-login.test.ts
@@ -0,0 +1,349 @@
+/**
+ * PRD-003a a-AC-5 / a-AC-7: `nectar login` runs the device flow to completion
+ * and writes credentials nectar can read; the verification URL + code are
+ * printed BEFORE any browser open; a browser-open failure never crashes the
+ * flow; a non-https completion URL is never opened; and tenancy is chosen
+ * EXPLICITLY (never a silent orgs[0] guess).
+ */
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, rmSync, existsSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import {
+  runDeviceFlowLogin,
+  validateVerificationUrl,
+  defaultBrowserOpener,
+  DEFAULT_MAX_POLLS,
+  type FetchLike,
+  type FetchResponse,
+  type LoginSeams,
+} from "../dist/auth/device-flow.js";
+import { loadDeepLakeCredentials } from "../dist/hive-graph/deeplake-credentials.js";
+
+function tmpDir(): string {
+  return mkdtempSync(join(tmpdir(), "nectar-login-"));
+}
+
+function jsonResp(status: number, ok: boolean, payload: unknown): FetchResponse {
+  return {
+    ok,
+    status,
+    json: async () => payload,
+    text: async () => JSON.stringify(payload),
+  };
+}
+
+interface FakeBackend {
+  readonly orgs?: Array<{ id: string; name: string }>;
+  readonly workspaces?: Array<{ id: string; name: string }>;
+  readonly completeUrl?: string;
+  readonly pollsBeforeToken?: number;
+}
+
+function makeFetch(be: FakeBackend = {}): { fetch: FetchLike; tokenCall(): number } {
+  let tokenPolls = 0;
+  const fetch: FetchLike = async (url) => {
+    if (url.endsWith("/auth/device/code")) {
+      return jsonResp(200, true, {
+        device_code: "dc-123",
+        user_code: "WXYZ-1234",
+        verification_uri: "https://login.deeplake.ai/device",
+        verification_uri_complete: be.completeUrl ?? "https://login.deeplake.ai/device?code=WXYZ-1234",
+        expires_in: 900,
+        interval: 5,
+      });
+    }
+    if (url.endsWith("/auth/device/token")) {
+      tokenPolls += 1;
+      if (tokenPolls < (be.pollsBeforeToken ?? 1)) return jsonResp(400, false, { error: "authorization_pending" });
+      return jsonResp(200, true, { access_token: "short-lived-token" });
+    }
+    if (url.endsWith("/organizations")) return jsonResp(200, true, be.orgs ?? [{ id: "org-1", name: "Org One" }]);
+    if (url.endsWith("/workspaces")) return jsonResp(200, true, { data: be.workspaces ?? [{ id: "ws-1", name: "WS One" }] });
+    if (url.endsWith("/users/me/tokens")) return jsonResp(200, true, { token: { token: "long-lived-XYZ" } });
+    if (url.endsWith("/me")) return jsonResp(200, true, { id: "u1", name: "Ada Lovelace", email: "ada@x.io" });
+    return jsonResp(404, false, { error: "not_found" });
+  };
+  return { fetch, tokenCall: () => tokenPolls };
+}
+
+test("a-AC-5 a successful device-flow login writes credentials nectar can read back", async () => {
+  const dir = tmpDir();
+  const opened: string[] = [];
+  try {
+    const { fetch } = makeFetch();
+    const seams: LoginSeams = {
+      fetch,
+      sleep: async () => {},
+      openBrowser: (url) => {
+        opened.push(url);
+        return true;
+      },
+      out: () => {},
+      isTTY: false,
+      now: () => "2026-07-04T00:00:00.000Z",
+      dir,
+    };
+    const result = await runDeviceFlowLogin({}, seams);
+    assert.equal(result.ok, true, result.message);
+    assert.equal(result.orgId, "org-1");
+    assert.equal(result.workspaceId, "ws-1");
+    assert.ok(existsSync(join(dir, "credentials.json")));
+
+    // The written file is byte-compatible with what loadDeepLakeCredentials reads.
+    const creds = loadDeepLakeCredentials({ dir });
+    assert.equal(creds.token, "long-lived-XYZ", "the minted long-lived token is persisted, not the short-lived one");
+    assert.equal(creds.orgId, "org-1");
+    assert.equal(creds.workspaceId, "ws-1");
+    assert.equal(creds.apiUrl, "https://api.deeplake.ai");
+
+    assert.deepEqual(opened, ["https://login.deeplake.ai/device?code=WXYZ-1234"], "opened the validated https completion URL");
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test("a-AC-7 the verification URL and code are printed BEFORE any browser-open attempt", async () => {
+  const dir = tmpDir();
+  try {
+    const { fetch } = makeFetch();
+    const events: Array<{ kind: "out" | "open"; text: string }> = [];
+    const seams: LoginSeams = {
+      fetch,
+      sleep: async () => {},
+      openBrowser: (url) => {
+        events.push({ kind: "open", text: url });
+        return true;
+      },
+      out: (line) => events.push({ kind: "out", text: line }),
+      isTTY: false,
+      dir,
+    };
+    const result = await runDeviceFlowLogin({}, seams);
+    assert.equal(result.ok, true);
+    const codeIndex = events.findIndex((e) => e.kind === "out" && e.text.includes("WXYZ-1234"));
+    const openIndex = events.findIndex((e) => e.kind === "open");
+    assert.ok(codeIndex >= 0, "the user code was printed");
+    assert.ok(openIndex >= 0, "the browser open was attempted");
+    assert.ok(codeIndex < openIndex, "the code was printed before the browser was opened");
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test("a-AC-7 a browser-open failure never crashes the flow; it completes and writes credentials", async () => {
+  const dir = tmpDir();
+  try {
+    const { fetch } = makeFetch();
+    const out: string[] = [];
+    const result = await runDeviceFlowLogin(
+      {},
+      {
+        fetch,
+        sleep: async () => {},
+        openBrowser: () => false, // simulate a headless / failed open
+        out: (l) => out.push(l),
+        isTTY: false,
+        dir,
+      },
+    );
+    assert.equal(result.ok, true, "the flow polls to completion even when the browser could not open");
+    assert.ok(existsSync(join(dir, "credentials.json")));
+    assert.ok(out.some((l) => /open the URL above manually/i.test(l)), "the user is told to open the URL manually");
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test("a-AC-7 a non-https completion URL is never opened, and the flow still completes", async () => {
+  const dir = tmpDir();
+  try {
+    const { fetch } = makeFetch({ completeUrl: "http://insecure.example/device" });
+    const opened: string[] = [];
+    const result = await runDeviceFlowLogin(
+      {},
+      {
+        fetch,
+        sleep: async () => {},
+        openBrowser: (url) => {
+          opened.push(url);
+          return true;
+        },
+        out: () => {},
+        isTTY: false,
+        dir,
+      },
+    );
+    assert.equal(result.ok, true);
+    assert.deepEqual(opened, [], "a non-https verification_uri_complete is refused, never opened");
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test("a-AC-7 validateVerificationUrl accepts https and refuses everything else", () => {
+  assert.equal(validateVerificationUrl("https://login.deeplake.ai/x"), "https://login.deeplake.ai/x");
+  assert.equal(validateVerificationUrl("http://login.deeplake.ai/x"), null);
+  assert.equal(validateVerificationUrl("not a url"), null);
+  assert.equal(validateVerificationUrl("file:///etc/passwd"), null);
+});
+
+test("a-AC-7 defaultBrowserOpener refuses a non-https URL without invoking any opener", () => {
+  // Returns false BEFORE any execFileSync, so this touches no subprocess.
+  assert.equal(defaultBrowserOpener("http://insecure.example"), false);
+  assert.equal(defaultBrowserOpener("javascript:alert(1)"), false);
+});
+
+test("a-AC-5 multiple orgs with no flags on a non-TTY fails clearly naming the flags (never a silent orgs[0])", async () => {
+  const dir = tmpDir();
+  try {
+    const { fetch } = makeFetch({ orgs: [{ id: "org-1", name: "One" }, { id: "org-2", name: "Two" }] });
+    const result = await runDeviceFlowLogin(
+      {},
+      { fetch, sleep: async () => {}, openBrowser: () => true, out: () => {}, isTTY: false, dir },
+    );
+    assert.equal(result.ok, false, "no silent guess is made");
+    assert.match(result.message, /--org=/, "the error names the --org flag");
+    assert.equal(existsSync(join(dir, "credentials.json")), false, "no credentials were written on the refusal");
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test("a-AC-5 explicit --org / --workspace flags are honored on a non-TTY multi-tenancy account", async () => {
+  const dir = tmpDir();
+  try {
+    const { fetch } = makeFetch({ orgs: [{ id: "org-1", name: "One" }, { id: "org-2", name: "Two" }] });
+    const result = await runDeviceFlowLogin(
+      { org: "org-2", workspace: "ws-9" },
+      { fetch, sleep: async () => {}, openBrowser: () => true, out: () => {}, isTTY: false, dir },
+    );
+    assert.equal(result.ok, true, result.message);
+    const creds = loadDeepLakeCredentials({ dir });
+    assert.equal(creds.orgId, "org-2");
+    assert.equal(creds.workspaceId, "ws-9");
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test("a-AC-5 a TTY prompt selects among multiple orgs (never a silent guess)", async () => {
+  const dir = tmpDir();
+  try {
+    const { fetch } = makeFetch({ orgs: [{ id: "org-1", name: "One" }, { id: "org-2", name: "Two" }] });
+    const result = await runDeviceFlowLogin(
+      {},
+      {
+        fetch,
+        sleep: async () => {},
+        openBrowser: () => true,
+        out: () => {},
+        isTTY: true,
+        question: async () => "2", // choose the second org
+        dir,
+      },
+    );
+    assert.equal(result.ok, true, result.message);
+    assert.equal(loadDeepLakeCredentials({ dir }).orgId, "org-2");
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test("a-AC-7 a slow_down poll response grows the interval (never hammers the token endpoint)", async () => {
+  const dir = tmpDir();
+  try {
+    let tokenPolls = 0;
+    const sleepCalls: number[] = [];
+    const fetch: FetchLike = async (url) => {
+      if (url.endsWith("/auth/device/code")) {
+        return jsonResp(200, true, {
+          device_code: "dc-slow",
+          user_code: "SLOW-0001",
+          verification_uri: "https://login.deeplake.ai/device",
+          verification_uri_complete: "https://login.deeplake.ai/device?code=SLOW-0001",
+          expires_in: 900,
+          interval: 5,
+        });
+      }
+      if (url.endsWith("/auth/device/token")) {
+        tokenPolls += 1;
+        // pending, then two slow_downs, then approved.
+        if (tokenPolls === 1) return jsonResp(400, false, { error: "authorization_pending" });
+        if (tokenPolls === 2 || tokenPolls === 3) return jsonResp(400, false, { error: "slow_down" });
+        return jsonResp(200, true, { access_token: "short-lived-token" });
+      }
+      if (url.endsWith("/organizations")) return jsonResp(200, true, [{ id: "org-1", name: "Org One" }]);
+      if (url.endsWith("/workspaces")) return jsonResp(200, true, { data: [{ id: "ws-1", name: "WS One" }] });
+      if (url.endsWith("/users/me/tokens")) return jsonResp(200, true, { token: { token: "long-lived-XYZ" } });
+      if (url.endsWith("/me")) return jsonResp(200, true, { id: "u1", name: "Ada Lovelace" });
+      return jsonResp(404, false, { error: "not_found" });
+    };
+    const result = await runDeviceFlowLogin(
+      {},
+      {
+        fetch,
+        sleep: async (ms) => {
+          sleepCalls.push(ms);
+        },
+        openBrowser: () => true,
+        out: () => {},
+        isTTY: false,
+        dir,
+      },
+    );
+    assert.equal(result.ok, true, result.message);
+    assert.deepEqual(
+      sleepCalls,
+      [5000, 5000, 10000, 15000],
+      "each slow_down response grows the NEXT poll wait by 5s; a plain pending never changes it",
+    );
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test("a-AC-9 poll exhaustion at DEFAULT_MAX_POLLS terminates with a plain-language, actionable error (never hangs)", async () => {
+  const dir = tmpDir();
+  try {
+    let tokenPolls = 0;
+    const fetch: FetchLike = async (url) => {
+      if (url.endsWith("/auth/device/code")) {
+        return jsonResp(200, true, {
+          device_code: "dc-stuck",
+          user_code: "STUCK-0001",
+          verification_uri: "https://login.deeplake.ai/device",
+          verification_uri_complete: "https://login.deeplake.ai/device?code=STUCK-0001",
+          expires_in: 900,
+          interval: 5,
+        });
+      }
+      if (url.endsWith("/auth/device/token")) {
+        tokenPolls += 1;
+        // Never approved: the sign-in sits pending forever, so the flow must
+        // give up at the bounded cap rather than poll indefinitely.
+        return jsonResp(400, false, { error: "authorization_pending" });
+      }
+      return jsonResp(404, false, { error: "not_found" });
+    };
+    const result = await runDeviceFlowLogin(
+      {},
+      {
+        fetch,
+        sleep: async () => {},
+        openBrowser: () => true,
+        out: () => {},
+        isTTY: false,
+        dir,
+      },
+    );
+    assert.equal(result.ok, false, "an unapproved sign-in never fabricates success");
+    assert.match(result.message, /timed out/i, "a plain-language message, not a hang or an unhandled throw");
+    assert.match(result.message, /nectar login/i, "names the actionable retry command");
+    assert.equal(tokenPolls, DEFAULT_MAX_POLLS, "polling stops exactly at the bounded cap, never looping forever");
+    assert.equal(existsSync(join(dir, "credentials.json")), false, "no credentials are written on a timeout");
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+});
diff --git a/test/doctor-registry-deregister.test.ts b/test/doctor-registry-deregister.test.ts
new file mode 100644
index 0000000..c6a7993
--- /dev/null
+++ b/test/doctor-registry-deregister.test.ts
@@ -0,0 +1,104 @@
+/**
+ * PRD-003b b-AC-3: `deregisterFromDoctor` deletes nectar's entry from doctor's
+ * registry, leaving every other entry and unknown top-level key intact, atomic
+ * (temp + rename), and best-effort (a malformed file is reported, not clobbered
+ * or thrown).
+ */
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, readFileSync, readdirSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { deregisterFromDoctor } from "../dist/doctor-registry.js";
+
+function tmpDir(): string {
+  return mkdtempSync(join(tmpdir(), "nectar-dereg-"));
+}
+
+test("b-AC-3 deletes nectar's entry and preserves every other daemon + unknown top-level key", () => {
+  const dir = tmpDir();
+  try {
+    const registryPath = join(dir, "registry.json");
+    const honeycomb = { name: "honeycomb", healthUrl: "http://127.0.0.1:3850/health", pidPath: "/x/hc.pid" };
+    writeFileSync(
+      registryPath,
+      JSON.stringify({ schemaHint: 7, daemons: [honeycomb, { name: "nectar", healthUrl: "http://127.0.0.1:3854/health" }] }, null, 2) + "\n",
+      "utf8",
+    );
+
+    const result = deregisterFromDoctor({ registryPaths: [registryPath] });
+    assert.equal(result.removedAny, true);
+    assert.equal(result.files[0]?.removed, true);
+    assert.equal(result.files[0]?.error, null);
+
+    const parsed = JSON.parse(readFileSync(registryPath, "utf8"));
+    assert.equal(parsed.schemaHint, 7, "unknown top-level key survives");
+    assert.equal(parsed.daemons.length, 1, "only nectar was removed");
+    assert.deepEqual(parsed.daemons[0], honeycomb, "honeycomb's entry is byte-for-byte intact");
+    assert.equal(readdirSync(dir).filter((n) => n.endsWith(".tmp")).length, 0, "atomic rename left no temp file");
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test("b-AC-3 an absent registry file is a clean no-op (fileExisted false, removed false)", () => {
+  const dir = tmpDir();
+  try {
+    const result = deregisterFromDoctor({ registryPaths: [join(dir, "registry.json")] });
+    assert.equal(result.removedAny, false);
+    assert.equal(result.files[0]?.fileExisted, false);
+    assert.equal(result.files[0]?.removed, false);
+    assert.equal(result.files[0]?.error, null);
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test("b-AC-3 a registry with no nectar entry is left untouched (removed false, no error)", () => {
+  const dir = tmpDir();
+  try {
+    const registryPath = join(dir, "registry.json");
+    const body = JSON.stringify({ daemons: [{ name: "hive" }] }, null, 2) + "\n";
+    writeFileSync(registryPath, body, "utf8");
+    const result = deregisterFromDoctor({ registryPaths: [registryPath] });
+    assert.equal(result.removedAny, false);
+    assert.equal(result.files[0]?.removed, false);
+    assert.equal(readFileSync(registryPath, "utf8"), body, "the file is untouched when nectar is absent");
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test("b-AC-3 a malformed registry is reported as an error, never clobbered or thrown (best-effort)", () => {
+  const dir = tmpDir();
+  try {
+    const registryPath = join(dir, "registry.json");
+    writeFileSync(registryPath, "{ not valid json", "utf8");
+    const result = deregisterFromDoctor({ registryPaths: [registryPath] });
+    assert.equal(result.removedAny, false);
+    assert.notEqual(result.files[0]?.error, null, "the malformed file is reported as an error");
+    assert.equal(readFileSync(registryPath, "utf8"), "{ not valid json", "the broken file is left exactly as it was");
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test("b-AC-3 removes nectar from whichever of the two candidate files carries it", () => {
+  const dir = tmpDir();
+  try {
+    const fleet = join(dir, "registry.json");
+    const legacy = join(dir, "doctor.daemons.json");
+    writeFileSync(fleet, JSON.stringify({ daemons: [{ name: "hive" }] }), "utf8");
+    writeFileSync(legacy, JSON.stringify({ daemons: [{ name: "nectar" }, { name: "doctor" }] }), "utf8");
+
+    const result = deregisterFromDoctor({ registryPaths: [fleet, legacy] });
+    assert.equal(result.removedAny, true);
+    assert.equal(result.files[0]?.removed, false, "the fleet file had no nectar entry");
+    assert.equal(result.files[1]?.removed, true, "the legacy file's nectar entry was removed");
+
+    const legacyParsed = JSON.parse(readFileSync(legacy, "utf8"));
+    assert.deepEqual(legacyParsed.daemons.map((d: { name: string }) => d.name), ["doctor"]);
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+});
diff --git a/test/fleet-detection.test.ts b/test/fleet-detection.test.ts
new file mode 100644
index 0000000..408fc34
--- /dev/null
+++ b/test/fleet-detection.test.ts
@@ -0,0 +1,118 @@
+/**
+ * PRD-003a a-AC-6: solo/fleet classification is deterministic for a given
+ * machine state, ANY signal means FLEET, and which signals fired is visible for
+ * supportability.
+ */
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, mkdirSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import {
+  classifyFleet,
+  fleetSignalLine,
+  defaultReadRegistrySignal,
+  registryCandidatePaths,
+  HIVE_NPM_PACKAGE,
+} from "../dist/fleet-detection.js";
+
+function tmpDir(): string {
+  return mkdtempSync(join(tmpdir(), "nectar-fleet-"));
+}
+
+test("a-AC-6 no signals fired -> SOLO, and the log line says so", async () => {
+  const result = await classifyFleet({
+    readRegistrySignal: () => false,
+    probeHivePort: async () => false,
+    npmGlobalHasHive: async () => false,
+  });
+  assert.equal(result.mode, "solo");
+  assert.deepEqual(result.signals, { registryHiveEntry: false, hivePortAnswering: false, hiveNpmGlobal: false });
+  assert.deepEqual(result.firedSignals, []);
+  assert.match(fleetSignalLine(result), /SOLO/);
+});
+
+test("a-AC-6 the live port answer alone means FLEET (any signal wins)", async () => {
+  const result = await classifyFleet({
+    readRegistrySignal: () => false,
+    probeHivePort: async () => true,
+    npmGlobalHasHive: async () => false,
+  });
+  assert.equal(result.mode, "fleet");
+  assert.deepEqual(result.firedSignals, ["Hive portal on 127.0.0.1:3853"]);
+  assert.match(fleetSignalLine(result), /FLEET/);
+  assert.match(fleetSignalLine(result), /127\.0\.0\.1:3853/);
+});
+
+test("a-AC-6 the registry Hive entry alone means FLEET", async () => {
+  const result = await classifyFleet({
+    readRegistrySignal: () => true,
+    probeHivePort: async () => false,
+    npmGlobalHasHive: async () => false,
+  });
+  assert.equal(result.mode, "fleet");
+  assert.deepEqual(result.firedSignals, ["registry Hive entry"]);
+});
+
+test("a-AC-6 the npm-global signal alone means FLEET and names the package", async () => {
+  const result = await classifyFleet({
+    readRegistrySignal: () => false,
+    probeHivePort: async () => false,
+    npmGlobalHasHive: async () => true,
+  });
+  assert.equal(result.mode, "fleet");
+  assert.deepEqual(result.firedSignals, [`npm global ${HIVE_NPM_PACKAGE}`]);
+});
+
+test("a-AC-6 all three signals are recorded when they all fire (deterministic evidence)", async () => {
+  const result = await classifyFleet({
+    readRegistrySignal: () => true,
+    probeHivePort: async () => true,
+    npmGlobalHasHive: async () => true,
+  });
+  assert.equal(result.mode, "fleet");
+  assert.equal(result.firedSignals.length, 3);
+});
+
+test("a-AC-6 S1 reads a hive entry from the fleet-root registry.json", () => {
+  const dir = tmpDir();
+  try {
+    const fleetRoot = join(dir, "apiary");
+    mkdirSync(fleetRoot, { recursive: true });
+    writeFileSync(
+      join(fleetRoot, "registry.json"),
+      JSON.stringify({ daemons: [{ name: "hive" }, { name: "nectar" }] }),
+      "utf8",
+    );
+    const fired = defaultReadRegistrySignal({ env: { APIARY_HOME: fleetRoot }, home: dir });
+    assert.equal(fired, true);
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test("a-AC-6 S1 is absent when neither registry file names hive", () => {
+  const dir = tmpDir();
+  try {
+    const fleetRoot = join(dir, "apiary");
+    mkdirSync(fleetRoot, { recursive: true });
+    writeFileSync(join(fleetRoot, "registry.json"), JSON.stringify({ daemons: [{ name: "nectar" }] }), "utf8");
+    const fired = defaultReadRegistrySignal({ env: { APIARY_HOME: fleetRoot }, home: dir });
+    assert.equal(fired, false);
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test("a-AC-6 S1 reads BOTH the fleet-root and legacy registry candidate paths", () => {
+  const dir = tmpDir();
+  try {
+    const fleetRoot = join(dir, "apiary");
+    const paths = registryCandidatePaths({ env: { APIARY_HOME: fleetRoot }, home: dir });
+    assert.equal(paths.length, 2);
+    assert.ok(paths[0]?.endsWith(join("apiary", "registry.json")));
+    assert.ok(paths[1]?.endsWith(join(".honeycomb", "doctor.daemons.json")));
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+});
diff --git a/test/fleet-lifecycle-daemon.test.ts b/test/fleet-lifecycle-daemon.test.ts
new file mode 100644
index 0000000..2497d56
--- /dev/null
+++ b/test/fleet-lifecycle-daemon.test.ts
@@ -0,0 +1,171 @@
+/**
+ * PRD-003a a-AC-1 / a-AC-2 (daemon integration): a daemon that boots without
+ * credentials serves 503 degraded on /health, and the credentials watch flips it
+ * to 200 healthy on the SAME running daemon (no restart) the moment the probe
+ * reports credentials present.
+ */
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { get as httpGet } from "node:http";
+import { assembleDaemon } from "../dist/index.js";
+import { healthHttpStatus } from "../dist/health.js";
+import type { Timer } from "../dist/poll-loop.js";
+
+const silent = (): void => {};
+
+function tmpRuntimeDir(): string {
+  return mkdtempSync(join(tmpdir(), "nectar-fleet-daemon-"));
+}
+
+/** A manual timer: tasks are queued, not run, until `flush()` fires the queued ones. */
+function manualTimer(): { timer: Timer; flush: () => void; pending: () => number } {
+  let nextHandle = 1;
+  let tasks: Array<{ handle: number; fn: () => void }> = [];
+  return {
+    timer: {
+      set(fn: () => void, _ms: number): unknown {
+        const handle = nextHandle++;
+        tasks.push({ handle, fn });
+        return handle;
+      },
+      clear(handle: unknown): void {
+        tasks = tasks.filter((t) => t.handle !== handle);
+      },
+    },
+    flush(): void {
+      const pending = tasks;
+      tasks = [];
+      for (const t of pending) t.fn();
+    },
+    pending: () => tasks.length,
+  };
+}
+
+/** A minimal socket-level GET, over real HTTP (node:http), never `fetch`-ing through an in-process shortcut. */
+function fetchHealthOverSocket(port: number): Promise<{ status: number; body: unknown }> {
+  return new Promise((resolve, reject) => {
+    const req = httpGet({ host: "127.0.0.1", port, path: "/health" }, (res) => {
+      let raw = "";
+      res.setEncoding("utf8");
+      res.on("data", (chunk: string) => {
+        raw += chunk;
+      });
+      res.on("end", () => {
+        try {
+          resolve({ status: res.statusCode ?? 0, body: JSON.parse(raw) });
+        } catch (err) {
+          reject(err instanceof Error ? err : new Error(String(err)));
+        }
+      });
+    });
+    req.on("error", reject);
+  });
+}
+
+test("a-AC-1 a real socket GET /health on a credentials-missing daemon returns 503 with the machine-readable reason", async () => {
+  const runtimeDir = tmpRuntimeDir();
+  const daemon = assembleDaemon({
+    port: 0,
+    runtimeDir,
+    log: silent,
+    storageCredentialsPresent: false,
+  });
+  try {
+    const port = await daemon.start();
+    const { status, body } = await fetchHealthOverSocket(port);
+    assert.equal(status, 503, "the real HTTP response code (not just the in-process snapshot) is 503");
+    const parsed = body as { status: string; storage: { reachable: boolean; reason: string | null } };
+    assert.equal(parsed.status, "degraded");
+    assert.equal(parsed.storage.reachable, false);
+    assert.equal(
+      parsed.storage.reason,
+      "credentials-missing",
+      "the machine-readable reason rides in the real HTTP response body",
+    );
+  } finally {
+    await daemon.shutdown();
+    rmSync(runtimeDir, { recursive: true, force: true });
+  }
+});
+
+test("a-AC-1 a daemon that boots without credentials serves 503 degraded with reason credentials-missing", async () => {
+  const runtimeDir = tmpRuntimeDir();
+  const daemon = assembleDaemon({
+    port: 0,
+    runtimeDir,
+    log: silent,
+    storageCredentialsPresent: false,
+  });
+  try {
+    await daemon.start();
+    const body = daemon.health.snapshot();
+    assert.equal(body.status, "degraded");
+    assert.equal(healthHttpStatus(body.status), 503);
+    assert.equal(body.storage.reachable, false);
+    assert.equal(body.storage.reason, "credentials-missing");
+  } finally {
+    await daemon.shutdown();
+    rmSync(runtimeDir, { recursive: true, force: true });
+  }
+});
+
+test("a-AC-1 a daemon that boots WITH credentials serves 200 ok", async () => {
+  const runtimeDir = tmpRuntimeDir();
+  const daemon = assembleDaemon({
+    port: 0,
+    runtimeDir,
+    log: silent,
+    storageCredentialsPresent: true,
+  });
+  try {
+    await daemon.start();
+    const body = daemon.health.snapshot();
+    assert.equal(body.status, "ok");
+    assert.equal(healthHttpStatus(body.status), 200);
+    assert.equal(body.storage.reachable, true);
+  } finally {
+    await daemon.shutdown();
+    rmSync(runtimeDir, { recursive: true, force: true });
+  }
+});
+
+test("a-AC-2 the credentials watch flips /health from 503 to 200 without a restart", async () => {
+  const runtimeDir = tmpRuntimeDir();
+  const clock = manualTimer();
+  let credentialsPresent = false;
+  const daemon = assembleDaemon({
+    port: 0,
+    runtimeDir,
+    log: silent,
+    storageCredentialsPresent: false,
+    credentialsWatch: {
+      probe: () => credentialsPresent,
+      intervalMs: 1000,
+      timer: clock.timer,
+    },
+  });
+  try {
+    await daemon.start();
+    // Boot posture: degraded (503).
+    assert.equal(daemon.health.snapshot().status, "degraded");
+    assert.equal(healthHttpStatus(daemon.health.snapshot().status), 503);
+
+    // Credentials appear; drive one watch tick on the SAME running daemon.
+    credentialsPresent = true;
+    clock.flush();
+    // Allow any microtasks from the poll tick to settle.
+    await new Promise((r) => setImmediate(r));
+
+    const body = daemon.health.snapshot();
+    assert.equal(body.status, "ok", "the daemon transitioned to healthy WITHOUT a restart");
+    assert.equal(healthHttpStatus(body.status), 200);
+    assert.equal(body.storage.reachable, true);
+    assert.equal(body.storage.reason, null);
+  } finally {
+    await daemon.shutdown();
+    rmSync(runtimeDir, { recursive: true, force: true });
+  }
+});
diff --git a/test/fleet-lifecycle-health.test.ts b/test/fleet-lifecycle-health.test.ts
new file mode 100644
index 0000000..6d8d3c4
--- /dev/null
+++ b/test/fleet-lifecycle-health.test.ts
@@ -0,0 +1,80 @@
+/**
+ * PRD-003a a-AC-1: a credentials-missing daemon serves 503 degraded on /health
+ * with a machine-readable reason, while every other behavior is preserved.
+ * PRD-003a a-AC-2: the credentials watch flips /health healthy without restart.
+ */
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { HealthState, healthHttpStatus } from "../dist/health.js";
+import { CredentialsWatch } from "../dist/credentials-watch.js";
+
+test("a-AC-1 setStorageState(unreachable) degrades /health to 503 with a machine-readable reason", () => {
+  const h = new HealthState();
+  // Fresh default is reachable/ok (200) so pre-003a callers are unaffected.
+  assert.equal(h.snapshot().status, "ok");
+  assert.equal(h.snapshot().storage.reachable, true);
+  assert.equal(h.snapshot().storage.reason, null);
+  assert.equal(healthHttpStatus(h.snapshot().status), 200);
+
+  h.setStorageState({ reachable: false, reason: "credentials-missing" });
+  const body = h.snapshot();
+  assert.equal(body.status, "degraded");
+  assert.equal(body.storage.reachable, false);
+  assert.equal(body.storage.reason, "credentials-missing", "the machine-readable reason names the cause");
+  assert.equal(healthHttpStatus(body.status), 503, "degraded maps to HTTP 503");
+});
+
+test("a-AC-1 the degraded storage posture preserves the brooding dormancy reason (other behavior intact)", () => {
+  const h = new HealthState();
+  h.setBroodingState({ active: false, reason: "credentials_missing" });
+  h.setStorageState({ reachable: false, reason: "credentials-missing" });
+  const body = h.snapshot();
+  assert.equal(body.status, "degraded");
+  assert.equal(body.brooding.reason, "credentials_missing", "brooding dormancy reason still surfaced alongside the 503");
+});
+
+test("a-AC-2 setStorageState(reachable) restores /health to 200 and clears the reason (no restart)", () => {
+  const h = new HealthState();
+  h.setStorageState({ reachable: false, reason: "credentials-missing" });
+  assert.equal(h.snapshot().status, "degraded");
+
+  // The credentials watch calls this on the SAME running state - no restart.
+  h.setStorageState({ reachable: true, reason: null });
+  const body = h.snapshot();
+  assert.equal(body.status, "ok");
+  assert.equal(body.storage.reachable, true);
+  assert.equal(body.storage.reason, null, "the reason clears when storage becomes reachable");
+  assert.equal(healthHttpStatus(body.status), 200);
+});
+
+test("a-AC-2 CredentialsWatch fires onChange only when the probed presence changes", () => {
+  let present = false;
+  const changes: boolean[] = [];
+  const watch = new CredentialsWatch({
+    probe: () => present,
+    onChange: (p) => changes.push(p),
+    intervalMs: 1000,
+  });
+
+  // First evaluation observes the initial (false) state and reports it.
+  assert.equal(watch.evaluate(), true, "the first evaluation is a change (unknown -> false)");
+  assert.deepEqual(changes, [false]);
+
+  // No change while the probe stays false.
+  assert.equal(watch.evaluate(), false, "no change when the probe is unchanged");
+  assert.deepEqual(changes, [false]);
+
+  // Credentials appear -> a change to true (the login-lands transition).
+  present = true;
+  assert.equal(watch.evaluate(), true, "a false -> true transition is a change");
+  assert.deepEqual(changes, [false, true]);
+
+  // Idempotent while present.
+  assert.equal(watch.evaluate(), false);
+  assert.deepEqual(changes, [false, true]);
+
+  // Credentials removed -> a change back to false.
+  present = false;
+  assert.equal(watch.evaluate(), true);
+  assert.deepEqual(changes, [false, true, false]);
+});
diff --git a/test/install-login-decision.test.ts b/test/install-login-decision.test.ts
new file mode 100644
index 0000000..24d6859
--- /dev/null
+++ b/test/install-login-decision.test.ts
@@ -0,0 +1,36 @@
+/**
+ * PRD-003a a-AC-3: `nectar install` opens the device-flow popup ONLY when solo
+ * AND no credentials exist; fleet detected or credentials present -> no popup.
+ * Plus the `nectar login` flag parsing (a-AC-5).
+ */
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { decideInstallLoginAction, parseLoginFlags } from "../dist/cli.js";
+
+test("a-AC-3 fleet detected -> defer to hive (never a popup), regardless of credentials", () => {
+  assert.equal(decideInstallLoginAction("fleet", false), "defer-to-hive");
+  assert.equal(decideInstallLoginAction("fleet", true), "defer-to-hive");
+});
+
+test("a-AC-3 solo with credentials present -> no popup", () => {
+  assert.equal(decideInstallLoginAction("solo", true), "already-signed-in");
+});
+
+test("a-AC-3 solo with NO credentials -> open the sign-in popup", () => {
+  assert.equal(decideInstallLoginAction("solo", false), "open-sign-in");
+});
+
+test("a-AC-5 parseLoginFlags accepts --org=<id> / --workspace=<id> and the spaced forms", () => {
+  assert.deepEqual(parseLoginFlags(["--org=o1", "--workspace=w1"]), { flags: { org: "o1", workspace: "w1" }, errors: [] });
+  assert.deepEqual(parseLoginFlags(["--org", "o2", "--workspace", "w2"]), { flags: { org: "o2", workspace: "w2" }, errors: [] });
+  assert.deepEqual(parseLoginFlags([]), { flags: {}, errors: [] });
+});
+
+test("a-AC-5 parseLoginFlags reports a missing value and an unknown flag", () => {
+  const missing = parseLoginFlags(["--org"]);
+  assert.deepEqual(missing.flags, {});
+  assert.ok(missing.errors.some((e) => /--org requires a value/.test(e)));
+
+  const unknown = parseLoginFlags(["--nope"]);
+  assert.ok(unknown.errors.some((e) => /unknown flag '--nope'/.test(e)));
+});
diff --git a/test/lifecycle.test.ts b/test/lifecycle.test.ts
new file mode 100644
index 0000000..755ff60
--- /dev/null
+++ b/test/lifecycle.test.ts
@@ -0,0 +1,329 @@
+/**
+ * PRD-003b b-AC-1 (start/stop), b-AC-4 / AC-8 (state-dir removal guard), b-AC-6
+ * (friendly nothing-to-remove), AC-9 (every flow terminates). The lifecycle
+ * verbs are exercised through their injectable seams (no real service manager,
+ * signals, or filesystem).
+ */
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import {
+  runStartLifecycle,
+  runStopLifecycle,
+  runUninstallLifecycle,
+  removeStateDir,
+  type StateDirFs,
+} from "../dist/lifecycle.js";
+import type { ServiceModule, ServiceResult, ServiceUninstallResult } from "../dist/service/index.js";
+import type { DeregisterResult } from "../dist/doctor-registry.js";
+
+function fakeService(
+  over: {
+    install?: ServiceResult;
+    uninstall?: ServiceUninstallResult;
+    start?: ServiceResult;
+    stop?: ServiceResult;
+    deregisterLegacy?: ServiceResult;
+  } = {},
+  calls: string[] = [],
+): ServiceModule {
+  return {
+    install: async () => {
+      calls.push("install");
+      return over.install ?? { ok: true, message: "installed" };
+    },
+    uninstall: async () => {
+      calls.push("uninstall");
+      return over.uninstall ?? { ok: true, alreadyAbsent: false, message: "removed unit" };
+    },
+    start: async () => {
+      calls.push("start");
+      return over.start ?? { ok: true, message: "started via systemd" };
+    },
+    stop: async () => {
+      calls.push("stop");
+      return over.stop ?? { ok: true, message: "stopped via systemd" };
+    },
+    deregisterLegacy: async () => {
+      calls.push("deregisterLegacy");
+      return over.deregisterLegacy ?? { ok: true, message: "legacy deregistered" };
+    },
+  };
+}
+
+function io() {
+  const out: string[] = [];
+  const err: string[] = [];
+  return { out, err, io: { out: (l: string) => out.push(l), err: (l: string) => err.push(l) } };
+}
+
+const noRegistry: DeregisterResult = { files: [{ registryPath: "/x/registry.json", fileExisted: false, removed: false, error: null }], removedAny: false };
+const removedRegistry: DeregisterResult = { files: [{ registryPath: "/x/registry.json", fileExisted: true, removed: true, error: null }], removedAny: true };
+
+// ── start (b-AC-1) ──
+
+test("b-AC-1 start: an already-running daemon is a friendly no-op (exit 0)", async () => {
+  const sink = io();
+  const code = await runStartLifecycle({
+    service: fakeService(),
+    isDaemonRunning: () => true,
+    readPid: () => 4242,
+    spawnDaemon: () => {
+      throw new Error("must not spawn when already running");
+    },
+    io: sink.io,
+  });
+  assert.equal(code, 0);
+  assert.ok(sink.out.some((l) => /already running \(pid 4242\)/.test(l)));
+});
+
+test("b-AC-1 start: starts via the OS service when the manager start succeeds", async () => {
+  const sink = io();
+  let spawned = false;
+  const code = await runStartLifecycle({
+    service: fakeService(),
+    isDaemonRunning: () => false,
+    readPid: () => null,
+    spawnDaemon: () => {
+      spawned = true;
+      return 1;
+    },
+    io: sink.io,
+  });
+  assert.equal(code, 0);
+  assert.equal(spawned, false, "no direct spawn when the OS service started it");
+  assert.ok(sink.out.some((l) => /started via systemd/.test(l)));
+});
+
+test("b-AC-1 start: falls back to a direct spawn when no OS unit is registered", async () => {
+  const sink = io();
+  const code = await runStartLifecycle({
+    service: fakeService({ start: { ok: false, message: "unit not found" } }),
+    isDaemonRunning: () => false,
+    readPid: () => null,
+    spawnDaemon: () => 9999,
+    io: sink.io,
+  });
+  assert.equal(code, 0);
+  assert.ok(sink.out.some((l) => /started directly \(pid 9999\)/.test(l)));
+});
+
+test("b-AC-1 / AC-9 start: a clear error when both the service and the direct spawn fail (exit 1)", async () => {
+  const sink = io();
+  const code = await runStartLifecycle({
+    service: fakeService({ start: { ok: false, message: "unit not found" } }),
+    isDaemonRunning: () => false,
+    readPid: () => null,
+    spawnDaemon: () => null,
+    io: sink.io,
+  });
+  assert.equal(code, 1);
+  assert.ok(sink.err.some((l) => /could not start/.test(l)));
+});
+
+// ── stop (b-AC-1) ──
+
+test("b-AC-1 stop: a not-running daemon is a friendly no-op (exit 0)", async () => {
+  const sink = io();
+  const code = await runStopLifecycle({
+    service: fakeService(),
+    isDaemonRunning: () => false,
+    readPid: () => null,
+    sendSignal: () => {
+      throw new Error("must not signal when nothing is running");
+    },
+    io: sink.io,
+  });
+  assert.equal(code, 0);
+  assert.ok(sink.out.some((l) => /not running; nothing to stop/.test(l)));
+});
+
+test("b-AC-1 stop: stops the OS unit AND signals the running pid", async () => {
+  const sink = io();
+  const signals: Array<{ pid: number; sig: string }> = [];
+  const code = await runStopLifecycle({
+    service: fakeService(),
+    isDaemonRunning: () => true,
+    readPid: () => 555,
+    sendSignal: (pid, sig) => {
+      signals.push({ pid, sig });
+      return true;
+    },
+    io: sink.io,
+  });
+  assert.equal(code, 0);
+  assert.deepEqual(signals, [{ pid: 555, sig: "SIGTERM" }]);
+  assert.ok(sink.out.some((l) => /stopped via systemd/.test(l)));
+  assert.ok(sink.out.some((l) => /Sent SIGTERM.*555/.test(l)));
+});
+
+// ── uninstall (b-AC-2/3/4/6, AC-9) ──
+
+test("b-AC-6 uninstall on a not-installed machine exits 0 with a friendly nothing-to-remove message", async () => {
+  const sink = io();
+  const code = await runUninstallLifecycle({
+    service: fakeService({ uninstall: { ok: false, alreadyAbsent: true, message: "no unit to remove" } }),
+    isDaemonRunning: () => false,
+    readPid: () => null,
+    sendSignal: () => false,
+    deregisterFromDoctor: () => noRegistry,
+    removeStateDir: () => ({ status: "absent", path: "/x/.apiary/nectar" }),
+    io: sink.io,
+  });
+  assert.equal(code, 0);
+  assert.ok(sink.out.some((l) => /nothing to remove/.test(l)));
+});
+
+// ── uninstall unit-removal classification (b-AC-2 / AC-9) ──
+
+test("b-AC-2 a failed current-unit removal exits nonzero and names the failure", async () => {
+  const sink = io();
+  const order: string[] = [];
+  const code = await runUninstallLifecycle({
+    service: fakeService(
+      {
+        uninstall: {
+          ok: false,
+          alreadyAbsent: false,
+          message: "Could not remove the nectar launchd unit (launchctl bootout): Operation not permitted.",
+        },
+      },
+      order,
+    ),
+    isDaemonRunning: () => false,
+    readPid: () => null,
+    sendSignal: () => false,
+    deregisterFromDoctor: () => {
+      order.push("deregister");
+      return removedRegistry;
+    },
+    removeStateDir: () => {
+      order.push("removeStateDir");
+      return { status: "removed", path: "/x/.apiary/nectar" };
+    },
+    io: sink.io,
+  });
+  assert.equal(code, 1, "a genuine current-unit removal failure is a hard failure, never swallowed into exit 0");
+  assert.ok(
+    sink.err.some((l) => /Could not remove the nectar service unit/.test(l) && /Operation not permitted/.test(l)),
+    "the failed step is named in plain language with the underlying error",
+  );
+  assert.ok(sink.err.some((l) => /one or more steps failed/.test(l)), "the final summary names re-run guidance");
+  // The remaining best-effort steps still ran despite the hard failure.
+  assert.ok(order.includes("deregister"), "the registry delete still ran after a failed unit removal");
+  assert.ok(order.includes("removeStateDir"), "the state-dir removal still ran after a failed unit removal");
+});
+
+test("b-AC-2 an already-absent unit stays a friendly no-op with exit 0", async () => {
+  const sink = io();
+  const code = await runUninstallLifecycle({
+    service: fakeService({
+      uninstall: {
+        ok: false,
+        alreadyAbsent: true,
+        message: "nectar launchd unit was already absent (nothing to remove).",
+      },
+    }),
+    isDaemonRunning: () => false,
+    readPid: () => null,
+    sendSignal: () => false,
+    deregisterFromDoctor: () => removedRegistry,
+    removeStateDir: () => ({ status: "removed", path: "/x/.apiary/nectar" }),
+    io: sink.io,
+  });
+  assert.equal(code, 0, "an already-absent unit never turns into a hard failure");
+  assert.ok(
+    sink.out.some((l) => /already absent/.test(l)),
+    "the already-absent unit message is a friendly out-line, not an error",
+  );
+  assert.equal(sink.err.length, 0, "no error is printed for an already-absent unit");
+});
+
+test("b-AC-2/3/4 uninstall runs the three-part contract in order (stop, unit, registry, state dir)", async () => {
+  const sink = io();
+  const order: string[] = [];
+  const service = fakeService({}, order);
+  let signalled = false;
+  const code = await runUninstallLifecycle({
+    service,
+    isDaemonRunning: () => true,
+    readPid: () => 777,
+    sendSignal: () => {
+      signalled = true;
+      order.push("signal");
+      return true;
+    },
+    deregisterFromDoctor: () => {
+      order.push("deregister");
+      return removedRegistry;
+    },
+    removeStateDir: () => {
+      order.push("removeStateDir");
+      return { status: "removed", path: "/x/.apiary/nectar" };
+    },
+    io: sink.io,
+  });
+  assert.equal(code, 0);
+  assert.equal(signalled, true);
+  // stop (service.stop + signal) precedes unit removal precedes registry precedes state dir.
+  const iStop = order.indexOf("stop");
+  const iUnit = order.indexOf("uninstall");
+  const iReg = order.indexOf("deregister");
+  const iDir = order.indexOf("removeStateDir");
+  assert.ok(iStop >= 0 && iStop < iUnit, "stop before unit removal");
+  assert.ok(iUnit < iReg, "unit removal before registry delete");
+  assert.ok(iReg < iDir, "registry delete before state-dir removal");
+  assert.ok(sink.out.some((l) => /Deleted nectar's doctor registry entry/.test(l)));
+  assert.ok(sink.out.some((l) => /Removed nectar's state dir/.test(l)));
+});
+
+test("AC-9 uninstall exits 1 with an actionable error when the state-dir removal fails", async () => {
+  const sink = io();
+  const code = await runUninstallLifecycle({
+    service: fakeService(),
+    isDaemonRunning: () => false,
+    readPid: () => null,
+    sendSignal: () => false,
+    deregisterFromDoctor: () => removedRegistry,
+    removeStateDir: () => ({ status: "failed", path: "/x/.apiary/nectar", reason: "EACCES" }),
+    io: sink.io,
+  });
+  assert.equal(code, 1);
+  assert.ok(sink.err.some((l) => /Could not remove nectar's state dir.*EACCES/.test(l)));
+});
+
+// ── removeStateDir guard (b-AC-4 / AC-8) ──
+
+function stubFs(over: Partial<StateDirFs>): StateDirFs {
+  return {
+    isAbsolute: () => true,
+    exists: () => true,
+    isSymlink: () => false,
+    rm: () => {},
+    ...over,
+  };
+}
+
+test("b-AC-4 removeStateDir removes an absent dir as a clean no-op", () => {
+  const result = removeStateDir("/abs/.apiary/nectar", stubFs({ exists: () => false }));
+  assert.equal(result.status, "absent");
+});
+
+test("b-AC-4 removeStateDir removes a normal absolute dir", () => {
+  let removed = "";
+  const result = removeStateDir("/abs/.apiary/nectar", stubFs({ rm: (p) => (removed = p) }));
+  assert.equal(result.status, "removed");
+  assert.equal(removed, "/abs/.apiary/nectar");
+});
+
+test("AC-8 removeStateDir refuses a non-absolute path (never a glob-relative delete)", () => {
+  const result = removeStateDir("relative/nectar", stubFs({ isAbsolute: () => false }));
+  assert.equal(result.status, "failed");
+  assert.match(result.reason ?? "", /non-absolute/);
+});
+
+test("AC-8 removeStateDir refuses to delete a symlinked state dir (never follows a symlink out of the root)", () => {
+  let rmCalled = false;
+  const result = removeStateDir("/abs/.apiary/nectar", stubFs({ isSymlink: () => true, rm: () => (rmCalled = true) }));
+  assert.equal(result.status, "skipped-symlink");
+  assert.equal(rmCalled, false, "a symlinked state dir is never removed (its target is left alone)");
+});
diff --git a/test/service-start-stop.test.ts b/test/service-start-stop.test.ts
new file mode 100644
index 0000000..5331a80
--- /dev/null
+++ b/test/service-start-stop.test.ts
@@ -0,0 +1,103 @@
+/**
+ * PRD-003b b-AC-1: the service module's `start`/`stop` front the OS unit with
+ * the right per-manager argv. b-AC-2: `deregisterLegacy` best-effort removes the
+ * legacy-labelled unit + its file.
+ */
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { createServiceModule } from "../dist/service/index.js";
+import { startCommands, stopCommands } from "../dist/service/argv.js";
+import { resolveServicePlan } from "../dist/service/platform.js";
+import type { CommandResult, CommandRunner } from "../dist/service/command-runner.js";
+import type { ServiceFs } from "../dist/service/index.js";
+import type { ServiceEnvironment } from "../dist/service/platform.js";
+
+function fakeFs(): ServiceFs & { removed: string[] } {
+  const removed: string[] = [];
+  return {
+    removed,
+    mkdirp() {},
+    writeFile() {},
+    removeFile(path: string) {
+      removed.push(path);
+    },
+  };
+}
+
+function okRunner(calls: { command: string; args: readonly string[] }[] = []): CommandRunner {
+  return {
+    async run(command, args): Promise<CommandResult> {
+      calls.push({ command, args });
+      return { ok: true, code: 0, stdout: "", stderr: "" };
+    },
+  };
+}
+
+function failingRunner(): CommandRunner {
+  return {
+    async run(): Promise<CommandResult> {
+      return { ok: false, code: 1, stdout: "", stderr: "boom", detail: "boom" };
+    },
+  };
+}
+
+function linuxEnv(overrides: Partial<ServiceEnvironment> = {}): ServiceEnvironment {
+  return { platform: "linux", home: "/home/op", privileged: false, execPath: "/usr/local/bin/nectar", ...overrides };
+}
+
+test("b-AC-1 startCommands/stopCommands build the systemd start/stop argv (no create/delete)", () => {
+  const plan = resolveServicePlan(linuxEnv());
+  assert.deepEqual(startCommands(plan, 0), [{ command: "systemctl", args: ["--user", "start", "nectar.service"] }]);
+  assert.deepEqual(stopCommands(plan, 0), [{ command: "systemctl", args: ["--user", "stop", "nectar.service"] }]);
+});
+
+test("b-AC-1 startCommands/stopCommands build the launchd argv", () => {
+  const plan = resolveServicePlan(linuxEnv({ platform: "darwin", home: "/Users/op" }));
+  assert.deepEqual(startCommands(plan, 501), [{ command: "launchctl", args: ["kickstart", "-k", "gui/501/com.legioncode.nectar"] }]);
+  assert.deepEqual(stopCommands(plan, 501), [{ command: "launchctl", args: ["bootout", "gui/501/com.legioncode.nectar"] }]);
+});
+
+test("b-AC-1 startCommands/stopCommands build the Windows schtasks argv", () => {
+  const plan = resolveServicePlan(linuxEnv({ platform: "win32", home: "C:/Users/op" }));
+  assert.deepEqual(startCommands(plan, 0), [{ command: "schtasks", args: ["/Run", "/TN", "nectar"] }]);
+  assert.deepEqual(stopCommands(plan, 0), [{ command: "schtasks", args: ["/End", "/TN", "nectar"] }]);
+});
+
+test("b-AC-1 service.start runs the manager start argv and reports ok", async () => {
+  const calls: { command: string; args: readonly string[] }[] = [];
+  const svc = createServiceModule({ execPath: "/usr/local/bin/nectar", fs: fakeFs(), runner: okRunner(calls), environment: linuxEnv() });
+  const result = await svc.start();
+  assert.equal(result.ok, true);
+  assert.deepEqual(calls[0]?.args, ["--user", "start", "nectar.service"]);
+});
+
+test("b-AC-1 service.start reports ok:false when no unit is registered (the manager start fails)", async () => {
+  const svc = createServiceModule({ execPath: "/usr/local/bin/nectar", fs: fakeFs(), runner: failingRunner(), environment: linuxEnv() });
+  const result = await svc.start();
+  assert.equal(result.ok, false, "a failed manager start is reported so the CLI can fall back to a direct spawn");
+  assert.match(result.message, /did not start/);
+});
+
+test("b-AC-1 service.stop runs the manager stop argv", async () => {
+  const calls: { command: string; args: readonly string[] }[] = [];
+  const svc = createServiceModule({ execPath: "/usr/local/bin/nectar", fs: fakeFs(), runner: okRunner(calls), environment: linuxEnv() });
+  const result = await svc.stop();
+  assert.equal(result.ok, true);
+  assert.deepEqual(calls[0]?.args, ["--user", "stop", "nectar.service"]);
+});
+
+test("b-AC-2 deregisterLegacy best-effort removes the legacy systemd unit + file, always ok", async () => {
+  const fs = fakeFs();
+  const calls: { command: string; args: readonly string[] }[] = [];
+  const svc = createServiceModule({ execPath: "/usr/local/bin/nectar", fs, runner: okRunner(calls), environment: linuxEnv() });
+  const result = await svc.deregisterLegacy();
+  assert.equal(result.ok, true, "legacy deregister is best-effort and never fails the uninstall");
+  assert.deepEqual(calls[0]?.args, ["--user", "disable", "--now", "hivenectar.service"], "targets the legacy unit name");
+  assert.deepEqual(fs.removed, ["/home/op/.config/systemd/user/hivenectar.service"], "removes the legacy unit file");
+});
+
+test("b-AC-2 deregisterLegacy stays ok even when the legacy unit is already gone (runner fails)", async () => {
+  const svc = createServiceModule({ execPath: "/usr/local/bin/nectar", fs: fakeFs(), runner: failingRunner(), environment: linuxEnv() });
+  const result = await svc.deregisterLegacy();
+  assert.equal(result.ok, true, "an already-absent legacy unit is not an error");
+});