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.

Added in review

Four commits. None of this is framed as closing a sandbox escape — lockdown is a
config-integrity control, the agent has an unfiltered shell, and that is
deliberate and tested. The argument throughout is the audit trail: a change that
takes effect should be visible in the PR carrying it.

Containment was checked per subtree, not per file. settings.yaml carries
the lockdown flag itself, the auth secret and every cron path, and a symlink
there was invisible — lockdown_workspace_problems returned [] and the
instance came up reporting lockdown = True with its tracked layer arriving from
a file no reviewer saw. With a relative link the target is an ordinary workspace
file the agent may write directly. This was an omission against a rule the branch
already set for itself: cron's jobs_file, system_file and gate_plugins_dir
each get a per-file check, including their default names as symlinks.

The write guard resolved its target, so a symlink at a reviewed name made it
conclude the write was outside the subtree and allow it. Both views are now
checked. The resolved one stays — it is what refuses the opposite direction, and
the inverse cases are pinned so a later refactor cannot swap one for the other.

A symlinked config/ directory is also refused now. git does not descend into
one, so git status -- <ws>/config reports nothing whatever is underneath: sync
calls the workspace clean while the daemon imports cron/gates/*.py from a
directory the config repo has never held a file of. Verified, not assumed.

skills/ and the root instruction files were writable under lockdown. The
branch made skills/ tracked config in one place and not the other:
skills/manager.py refuses create/update/delete/toggle, while the write guard
scoped itself to config/. So Write to skills/backdoor/SKILL.md was allowed,
discover() is not lockdown-gated and runs on every reload, and the planted file
became a live model-invocable skill with its own allowed-tools frontmatter
without the 403 ever being involved. No Bash required — which is the point,
since the stated standard is closing the path an agent takes by default and by
accident.

REVIEWED_DIRS and REVIEWED_ROOT_FILES name the surface once; sync's
dirty-state check uses the same list, so the guard and the check cannot disagree
about what a reviewed file is. A submodule inside the surface is promoted from
warning to blocking when locked, matching the rule already applied to gitignored
files. The docs said both things in the same section.

Widening the guard would have made PUT /api/memory/file/SOUL.md return 403 for
a file the web UI offers to edit, so both read endpoints now report read_only,
computed from the refusal itself, and the editor renders it read-only.

Lockdown now requires somewhere to sync from. lockdown: true on a workspace
with no git remote refused every local change while having no route to receive
one. Refused at startup rather than by ignoring the flag: treating a missing
remote as "not locked after all" would make removing a remote an unlock, and the
design already has two rules whose point is that no such path exists.

🤖 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.