Lockdown: remote-only, read-only mode (10/13)

[alex-clickhouse]

What

With lockdown set, configuration comes only from the tracked workspace layer — both machine-local layers are dropped — and the runtime write paths that would mutate tracked config refuse with a message saying what to do instead.

The flag is honoured only in settings.yaml, so a local edit cannot unlock an instance, and NERVE_LOCKDOWN in the service definition anchors it outside every file on the box. Load fails closed on a missing required secret. Machine-local keys the locked bundle leaves to the defaults are reported by name, at load and at validate time.

Why

An instance whose agent can edit its own configuration can edit the limits on what it may do. Lockdown makes the reviewed repo the only source of configuration, so changing behaviour requires a merged pull request rather than a local write.

That only holds if the flag itself is out of reach, which is why it is read from the tracked file alone and why the environment anchor exists: NERVE_LOCKDOWN lives in the systemd unit or the compose file, the one place neither the agent nor a config edit reaches. The anchor also selects the workspace, so the file that decides everything else cannot decide which file that is.

Dropping the machine layers has a consequence worth stating plainly: any key whose natural home is config.yaml now has nowhere to be said, and the declared default answers for it on every locked box — invisibly, in the diff of the change that turned lockdown on. So those keys are named while the config loads and while it validates, separated into values that are shareable and should be moved to the tracked layer, and values that are machine-local where the default may still be the wrong answer. telegram.enabled additionally flips its fallback under lockdown: the declared default is on, and a box where Telegram was deliberately switched off must not start serving DMs with full agent access because the shared settings happened to carry a resolvable token.

Scope, stated plainly: this covers the tools that name a path. Bash is auto-approved on the same code path, so this is an audit trail and a guard against the ordinary edit, not a sandbox. Filtering command strings would look like a boundary without being one; real sandboxing is separate work.

🤖 Generated with Claude Code

[Copilot]

Pull request overview

Implements “lockdown” mode to make instances remote-only and read-only with respect to git-tracked workspace config, tightening both config loading/validation and runtime write paths so a locked box only runs reviewed, synced configuration.

Changes:

• Add lockdown config semantics: drop machine-local layers when locked, require/validate secrets, and enforce workspace/config subtree containment (incl. cron path containment and symlink escape protections).
• Add runtime write guards (REST routes, agent tool backends, skills/tasks/memory/cron write paths) to refuse edits that would mutate tracked config under lockdown, with clearer HTTP/error reporting.
• Tighten workspace sync + validation/reporting so locked instances refuse .gitignored config-subtree files, surface unresolved env refs even when tolerated, and report “merged but not applied” when reload fails.

Reviewed changes

Copilot reviewed 27 out of 27 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
tests/test_sync_service.py	Adds coverage for locked sync behavior (ignored gate plugin refusal) and apply/reporting paths.
tests/test_lockdown.py	Comprehensive tests for lockdown loading, anchoring, containment, and write guards across subsystems.
tests/test_backup.py	Verifies config subtree is captured in backups but not restored/written back; tests restore allowlist.
nerve/templates/config/settings.yaml	Documents lockdown behavior and operational guidance in the settings template.
nerve/tasks/manager.py	Guards task “done” move from deleting tracked config under lockdown.
nerve/sync_service.py	Adds locked sync mode, propagates validator info, and reloads config on apply with error reporting.
nerve/skills/manager.py	Adds lockdown write guards and validates skill IDs to prevent path traversal deletes.
nerve/memory/manager.py	Refuses writes into tracked config subtree under lockdown for caller-supplied paths.
nerve/gateway/server.py	Adds exception handlers for LockdownError (403) and SkillIdError (400).
nerve/gateway/routes/tasks.py	Guards task file writes (DB-provided path) from landing in tracked config under lockdown.
nerve/gateway/routes/memory.py	Guards arbitrary workspace writes from landing in tracked config under lockdown.
nerve/gateway/routes/external_agents.py	Blocks external-agent mutations under lockdown.
nerve/gateway/routes/config.py	Passes locked into sync and avoids reporting “ok” when apply/reload failed.
nerve/gateway/auth.py	Fail-closed authentication behavior when locked and jwt secret missing.
nerve/cron/service.py	Warns when locked instance has no user cron entries due to legacy fallback being disabled.
nerve/cron/jobs.py	Guards save_jobs so it can’t write tracked cron config under lockdown.
nerve/cron/gates.py	Clarifies behavior rationale around gate build failures (documentation/comment change).
nerve/config.py	Core lockdown implementation: anchor env vars, strict lockdown parsing, containment checks, secret guards, runtime write refusal helpers.
nerve/config_validate.py	Adds locked-view validation controls (assume_locked), anchor awareness, unresolved-env reporting, and lockdown-specific checks.
nerve/cli.py	Wires --assume-lockdown into nerve config validate; passes locked mode into sync.
nerve/channels/telegram.py	Refuses pairing flow under lockdown and ensures no in-memory bypass.
nerve/backup.py	Separates backup-collect vs restore-allowlist; blocks restoring workspace/config from bundles and warns.
nerve/agent/tools/handlers/tasks.py	Blocks task write/update/done paths from mutating tracked config under lockdown.
nerve/agent/backends/codex/backend.py	Adds best-effort lockdown refusal for codex file-change approvals when approvals are enabled.
nerve/agent/backends/claude.py	Adds lockdown denial for path-naming write tools and repeats it in pre-tool hooks.
docs/cron.md	Documents cron path containment rules under lockdown.
docs/config.md	Adds end-to-end lockdown documentation, anchor behavior, CI validation guidance, and new CLI flag docs.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.