fix(settings): guard POST /api/setup against agent overwrites

.agents/skills/tinyclaw-admin/SKILL.md

@@ -174,11 +174,18 @@ curl -s http://localhost:3777/api/logs?limit=50 | jq
 
 ## Direct settings.json editing
 
-When the API server is not running, edit `~/.tinyclaw/settings.json` directly. Use `jq` for safe atomic edits:
+> **WARNING — agents should not edit settings.json directly.** Direct edits bypass all validation and can corrupt or destroy the running configuration. Agents running with `--dangerously-skip-permissions` have unrestricted file access, which makes an accidental overwrite unrecoverable. Always prefer the REST API (`PUT /api/agents`, `PUT /api/teams`, `PUT /api/settings`) which validates input, merges safely, and keeps the system consistent.
+>
+> Direct editing is a last resort for **human operators only** when the API server is not running and there is no other option.
+
+If a human operator must edit `~/.tinyclaw/settings.json` while the daemon is stopped, back up the file first and use `jq` for atomic edits:
 
 ```bash
 SETTINGS="$HOME/.tinyclaw/settings.json"
 
+# Always back up first
+cp "$SETTINGS" "$SETTINGS.bak"
+
 # Add an agent
 jq --arg id "analyst" --argjson agent '{"name":"Analyst","provider":"anthropic","model":"sonnet","working_directory":"'$HOME'/tinyclaw-workspace/analyst"}' \
   '.agents[$id] = $agent' "$SETTINGS" > "$SETTINGS.tmp" && mv "$SETTINGS.tmp" "$SETTINGS"
@@ -193,6 +200,10 @@ jq --arg id "research" --argjson team '{"name":"Research Team","agents":["analys
 
 After editing `settings.json`, run `tinyclaw restart` to pick up changes.
 
+## POST /api/setup is for initial setup only
+
+`POST /api/setup` **fully replaces** settings.json — it does not merge. It will be rejected with HTTP 409 if agents are already configured, unless `?force=true` is passed. Agents must never call this endpoint on a running system.
+
 ## Modifying TinyClaw source code
 
 When modifying TinyClaw's own code (features, bug fixes, new routes, etc.):

packages/server/src/routes/settings.ts

@@ -43,9 +43,21 @@ app.put('/api/settings', async (c) => {
 });
 
 // POST /api/setup — run initial setup (write settings + create directories)
+// Requires ?force=true if settings.json already exists with agents configured,
+// to prevent agents from accidentally wiping a live configuration.
 app.post('/api/setup', async (c) => {
+    const force = c.req.query('force') === 'true';
     const settings = (await c.req.json()) as Settings;
 
+    // Guard: refuse to overwrite an existing configured installation unless forced
+    if (!force && fs.existsSync(SETTINGS_FILE)) {
+        const existing = (() => { try { return JSON.parse(fs.readFileSync(SETTINGS_FILE, 'utf8')); } catch { return null; } })();
+        if (existing?.agents && Object.keys(existing.agents).length > 0) {
+            log('WARN', '[API] Setup blocked: settings.json already has agents configured. Use ?force=true to overwrite.');
+            return c.json({ ok: false, error: 'Settings already configured. Pass ?force=true to overwrite.' }, 409);
+        }
+    }
+
     if (settings.workspace?.path) {
         settings.workspace.path = expandHomePath(settings.workspace.path);
     }
@@ -57,8 +69,15 @@ app.post('/api/setup', async (c) => {
         }
     }
 
-    // Write settings.json
+    // Back up existing settings before overwriting
     fs.mkdirSync(path.dirname(SETTINGS_FILE), { recursive: true });
+    if (fs.existsSync(SETTINGS_FILE)) {
+        const backupPath = `${SETTINGS_FILE}.bak`;
+        fs.copyFileSync(SETTINGS_FILE, backupPath);
+        log('INFO', `[API] Setup: backed up existing settings to ${backupPath}`);
+    }
+
+    // Write settings.json
     fs.writeFileSync(SETTINGS_FILE, JSON.stringify(settings, null, 2) + '\n');
     log('INFO', '[API] Setup: settings.json written');