@inkobytes/nexus 1.0.7 → 1.1.0

package/src/commands/claim.js

@@ -11,6 +11,7 @@ import { join } from 'path';
 import { cwd } from 'process';
 import { normalizeTarget } from '../lib/pathSafety.js';
 import { CANONICAL_MODEL_HANDLE_SET, CANONICAL_MODEL_HANDLES_TEXT, hasAgentAlias } from '../lib/agentScopes.js';
+import { refuseIfHalted } from './halt.js';
 
 const CORE_FILES = [
   '_NEXUS_CONSTITUTION.md',
@@ -46,6 +47,8 @@ function readFlag(args, name) {
 }
 
 export default function claim(args) {
+  refuseIfHalted('claim');
+
   const positional = [...args];
 
   const agentFlag = readFlag(positional, '--agent').trim();

package/src/commands/dashboard.js

@@ -11,6 +11,7 @@ import { join } from 'path';
 import { getConfig } from '../lib/config.js';
 import { listLocks } from '../lib/lockManager.js';
 import { readLedgerEntries } from './ledger.js';
+import { getHalt } from './halt.js';
 
 const DEFAULT_PORT = 13787;
 const MAX_PORT_SEARCH = 30;
@@ -24,7 +25,7 @@ export default function dashboard(args) {
     return;
   }
 
-  serveDashboard(resolveDashboardPort(args));
+  serveDashboard(resolveDashboardPort(args), resolveDashboardHost(args));
 }
 
 export function buildSnapshot() {
@@ -60,6 +61,7 @@ export function buildSnapshot() {
   return {
     generatedAt: new Date().toISOString(),
     repo: config.root,
+    halt: getHalt(),
     branch: git.branch,
     dirtyFiles: git.files,
     health: getHealth(config),
@@ -76,7 +78,7 @@ export function buildSnapshot() {
   };
 }
 
-function serveDashboard(port) {
+function serveDashboard(port, host) {
   const clients = new Set();
   const server = createServer((req, res) => {
     const url = new URL(req.url || '/', `http://${req.headers.host || '127.0.0.1'}`);
@@ -133,7 +135,13 @@ function serveDashboard(port) {
   }, 2000);
 
   server.on('close', () => clearInterval(interval));
-  listenOnAvailablePort(server, port, port === DEFAULT_PORT);
+  listenOnAvailablePort(server, port, port === DEFAULT_PORT, host);
+}
+
+// The dashboard has no auth, so network exposure is opt-in: localhost unless
+// the human passes --lan.
+export function resolveDashboardHost(args) {
+  return args.includes('--lan') ? '0.0.0.0' : '127.0.0.1';
 }
 
 export function resolveDashboardPort(args) {
@@ -146,7 +154,7 @@ export function resolveDashboardPort(args) {
   return value;
 }
 
-function listenOnAvailablePort(server, port, canSearch) {
+function listenOnAvailablePort(server, port, canSearch, host = '127.0.0.1') {
   let attempts = 0;
 
   const tryListen = (candidate) => {
@@ -159,11 +167,13 @@ function listenOnAvailablePort(server, port, canSearch) {
       throw err;
     });
 
-    server.listen(candidate, '0.0.0.0', () => {
+    server.listen(candidate, host, () => {
       const moved = candidate !== port ? ` (default ${port} was busy)` : '';
       console.log(`Nexus dashboard listening at http://127.0.0.1:${candidate}${moved}`);
-      for (const url of getLanUrls(candidate)) {
-        console.log(`Local network: ${url}`);
+      if (host === '0.0.0.0') {
+        for (const url of getLanUrls(candidate)) {
+          console.log(`Local network: ${url}`);
+        }
       }
       console.log('Press Ctrl+C to stop.');
     });

package/src/commands/db.js

@@ -8,8 +8,8 @@
  * nexus db schedule             Show cron setup instructions
  */
 
-import { existsSync, mkdirSync, copyFileSync, readdirSync, statSync, readFileSync, writeFileSync } from 'fs';
-import { join, basename } from 'path';
+import { existsSync, mkdirSync, copyFileSync, readdirSync, statSync, readFileSync, writeFileSync, openSync, closeSync } from 'fs';
+import { join, dirname, relative } from 'path';
 import { cwd, env } from 'process';
 import { spawnSync } from 'child_process';
 
@@ -38,7 +38,7 @@ function detectDatabases(root) {
         const stat = statSync(full);
         if (stat.isDirectory()) { scanDir(full, depth + 1); continue; }
         if (/\.(sqlite|sqlite3|db)$/.test(entry)) {
-          dbs.push({ type: 'sqlite', path: full, name: entry });
+          dbs.push({ type: 'sqlite', path: full, relPath: relative(root, full), name: entry });
         }
       } catch { /* skip unreadable */ }
     }
@@ -58,8 +58,12 @@ function detectDatabases(root) {
 }
 
 function backupSqlite(db, backupPath) {
-  copyFileSync(db.path, join(backupPath, db.name));
-  return db.name;
+  // Mirror the repo-relative path inside the backup so same-named DBs in
+  // different directories cannot overwrite each other.
+  const dest = join(backupPath, db.relPath);
+  mkdirSync(dirname(dest), { recursive: true });
+  copyFileSync(db.path, dest);
+  return db.relPath;
 }
 
 function backupPostgres(db, backupPath) {
@@ -72,10 +76,19 @@ function backupPostgres(db, backupPath) {
 }
 
 function backupMysql(db, backupPath) {
+  // DATABASE_URL comes from .env and is attacker-influenced; pass it as a
+  // literal argument and redirect in Node — never through a shell string.
   const outFile = join(backupPath, 'dump.sql');
-  const result = spawnSync('sh', ['-c', `mysqldump "${db.url}" > "${outFile}"`], {
-    encoding: 'utf-8', stdio: 'pipe',
-  });
+  const out = openSync(outFile, 'w');
+  let result;
+  try {
+    result = spawnSync('mysqldump', [db.url], {
+      encoding: 'utf-8', stdio: ['ignore', out, 'pipe'],
+    });
+  } finally {
+    closeSync(out);
+  }
+  if (result.error) throw new Error(`mysqldump failed: ${result.error.message}`);
   if (result.status !== 0) throw new Error(`mysqldump failed: ${result.stderr}`);
   return 'dump.sql';
 }
@@ -121,7 +134,7 @@ function runBackup(root, auto = false) {
       if (db.type === 'sqlite')   file = backupSqlite(db, backupPath);
       if (db.type === 'postgres') file = backupPostgres(db, backupPath);
       if (db.type === 'mysql')    file = backupMysql(db, backupPath);
-      results.push({ db: db.name, type: db.type, file, ok: true });
+      results.push({ db: db.name, path: db.relPath, type: db.type, file, ok: true });
       console.log(`[nexus db] ✓ ${db.type} ${db.name} → ${BACKUP_DIR}/${stamp}/${file}`);
     } catch (err) {
       results.push({ db: db.name, type: db.type, ok: false, error: err.message });
@@ -214,14 +227,18 @@ function runRestore(root, stamp) {
     const backupFile = join(backupPath, entry.file);
 
     if (entry.type === 'sqlite') {
-      // Find original path from manifest root
-      const originalPath = manifest.dbs.find(d => d.db === entry.db)
-        ? join(manifest.root, entry.db) : null;
-      if (originalPath && existsSync(backupFile)) {
-        copyFileSync(backupFile, originalPath);
-        console.log(`  ✓ sqlite ${entry.db} restored`);
+      // Older manifests stored only the basename; fall back so they stay restorable.
+      const rel = entry.path || entry.db;
+      const target = join(root, rel);
+      if (!existsSync(backupFile)) {
+        console.error(`  ✗ sqlite ${entry.db}: backup file missing — expected ${backupFile}`);
+        process.exitCode = 1;
+      } else if (!existsSync(dirname(target))) {
+        console.error(`  ✗ sqlite ${entry.db}: original directory is gone (${dirname(rel)}/) — restore manually from ${backupFile}`);
+        process.exitCode = 1;
       } else {
-        console.log(`  ✗ sqlite ${entry.db}: original path not found — copy manually from ${backupFile}`);
+        copyFileSync(backupFile, target);
+        console.log(`  ✓ sqlite ${entry.db} → ${rel}`);
       }
     }
 
@@ -235,7 +252,14 @@ function runRestore(root, stamp) {
     if (entry.type === 'mysql') {
       const url = env.DATABASE_URL || env.MYSQL_URL;
       if (!url) { console.log(`  ✗ mysql: DATABASE_URL not set`); continue; }
-      const result = spawnSync('sh', ['-c', `mysql "${url}" < "${backupFile}"`], { stdio: 'inherit' });
+      // Same injection surface as backupMysql: literal argument, fd redirection.
+      const input = openSync(backupFile, 'r');
+      let result;
+      try {
+        result = spawnSync('mysql', [url], { stdio: [input, 'inherit', 'inherit'] });
+      } finally {
+        closeSync(input);
+      }
       console.log(result.status === 0 ? `  ✓ mysql restored` : `  ✗ mysql restore failed`);
     }
   }

package/src/commands/doctor.js

@@ -10,39 +10,19 @@ import { listLocks } from '../lib/lockManager.js';
 import { getConfig } from '../lib/config.js';
 import { AGENT_SCOPE_LIST } from '../lib/agentScopes.js';
 import { DEFAULT_MATRIX, loadPermissions, getChmodPath } from '../lib/permissions.js';
-
-const MONTH_NAMES = [
-  'January',
-  'February',
-  'March',
-  'April',
-  'May',
-  'June',
-  'July',
-  'August',
-  'September',
-  'October',
-  'November',
-  'December',
-];
-
-const START_MARKER = '<!-- NEXUS-AGENT-PROTOCOL:START -->';
-const END_MARKER = '<!-- NEXUS-AGENT-PROTOCOL:END -->';
-
-const CONTINUITY_TEMPLATE = `# CONTINUITY
-Goal: Project setup
-State: Planning
-
-Now: Initial Nexus setup
-Next: Confirm first task
-Blockers: None
-Decisions:
-- Nexus manages swarm coordination
-- Continuity and memories are agent-local
-Files:
-- _NEXUS_QUEUE.md
-- _NEXUS_STANDUP.md
-`;
+import {
+  CONTINUITY_TEMPLATE,
+  END_MARKER,
+  MEMORY_INDEX_GUARDRAIL,
+  MEMORY_INDEX_TEMPLATE,
+  REQUIRED_CONTEXT_READ,
+  SKILL_CONTEXT_GUARDRAIL,
+  START_MARKER,
+  currentMemoryMonthFolder,
+  fullEntrypoint,
+  protocolBlock,
+} from '../lib/protocolText.js';
+import { HOOK_AGENT_CONFIGS, hookStatus } from './hooks.js';
 
 const LOCAL_DECISIONS_TEMPLATE = `# Decisions
 
@@ -53,148 +33,6 @@ const LOCAL_GITIGNORE_LINES = ['DECISIONS.md', 'docs-priv/', '.nexus/presence/']
 const STANDUP_FORMAT_GUIDANCE = 'YYYY-MM-DD HH:MM AM/PM @agent [STATUS]: message';
 const STANDUP_RULES_LINE = `*Rules: Append new entries at the bottom. One line per message. Use \`${STANDUP_FORMAT_GUIDANCE}\` so relevance is visible. Use 🧵 for long discussions.*`;
 
-const MEMORY_INDEX_TEMPLATE = `# Memory Index
-
-Newest first, max 10 visible entries.
-
-Format:
-
-- YYYY-Month/YYYY-MM-DD-HHMM-topic.md - short session label
-
-Entries live in month folders from the start, for example:
-
-- \`2026-January/2026-01-15-1030-project-setup.md\`
-- \`2026-February/2026-02-01-0900-debug-session.md\`
-
-This keeps monthly review simple: ask an agent to read one month folder and summarize the Markdown files.
-
-`;
-
-function currentMemoryMonthFolder(now = new Date()) {
-  return `${now.getFullYear()}-${MONTH_NAMES[now.getMonth()]}`;
-}
-
-function protocolBlock(agent) {
-  return `${START_MARKER}
-
-## Nexus Project Protocol
-
-This project uses Nexus for multi-agent coordination.
-
-### Start Here
-
-1. Read \`_NEXUS_CONSTITUTION.md\`.
-2. Read \`_NEXUS_QUEUE.md\` for executable priorities.
-3. Read \`_NEXUS_STANDUP.md\` for comms, decisions, and completion notes.
-4. Read \`USER.md\` if present for local human preferences.
-5. Read \`${agent.continuity}\` for current session state.
-6. Read \`${agent.memoryIndex}\` and the latest memory entry when resync is needed.
-
-### Nexus Rules
-
-- Claim before editing shared project files: \`nexus claim <path> @Agent "intent"\`.
-- Nexus is agent-native and file-native, not human-native: optimize for concurrency and rollback, not feature-commit aesthetics.
-- Release each claimed file as soon as it reaches a coherent checkpoint.
-- Never hold claims just to bundle a prettier feature commit; that blocks other agents.
-- Release finished work through Nexus: \`nexus release <path> "commit message"\`.
-- Use \`nexus next @Agent\` for the next safe queue task.
-- Do not free-roam into unassigned or \`Auto-flow: no\` work without user approval.
-- Direct user instruction can override queue order, but not claim/release, data, security, or approval gates.
-- If no safe task remains, announce \`Standby\` with what you are waiting for, then stop until user input, queue change, or explicit assignment.
-
-### Current File State
-
-- Treat previous chat context, cached model memory, and earlier reads as stale when file contents matter.
-- Before claiming what a file says, making edits, or judging current state, read the file from disk with a fresh command.
-- Treat \`nexus claim\` as the atomic lock-and-read boundary and its output as fresh file state for the claimed path.
-- If you read a shared file before claiming it, treat that read as stale after claim succeeds.
-- If another agent or tool may have touched the file since your last read, re-read it before editing.
-- If a claim appears stale, do not edit through it; run \`nexus status\` or \`nexus doctor\`, then clean only when ownership is clearly abandoned.
-
-### Drills
-
-Drill guidance is defined in \`_NEXUS_CONSTITUTION.md\`.
-If the situation resembles a drill, use that drill before acting.
-
-### Delegated Work
-
-- Lead agents own the repo effects of their subagents, tools, and parallel workers.
-- Claim the full path scope before delegating shared-file work.
-- Give subagents the claimed path, intent, non-goals, and boundaries.
-- Re-read affected files after subagent work before final edits, release, or current-state claims.
-- Mention delegated work in release or \`nexus standup\` notes when it affected files, tests, or risk.
-
-### Git Write Safety
-
-- Before git writes, verify \`pwd\`, repo root, branch/status, and remotes.
-- Stop if they do not match the requested project.
-- Never infer from similar folder names or cached context.
-- Require explicit confirmation before push/force-push, main/master, remote changes, or deletes.
-- To remove private agent files from git, untrack them; do not delete local folders.
-- Agent instruction files are shared protocol files; normal edits require claim/release, while \`nexus doctor --fix\` may update managed protocol blocks after user approval.
-- Agents work inside assigned work zones. If a change crosses work-zone boundaries or alters a shared contract another zone may depend on, announce it in \`_NEXUS_STANDUP.md\` before release and ask if coordination is needed.
-
-### Supply-Chain Safety
-
-- Do not install third-party packages that have existed for less than 14 days.
-- Before adding a new dependency, verify the package creation date and the specific version publish date.
-- If the package or version is younger than 14 days, or either date cannot be verified, stop and ask the user.
-- Run \`nexus doctor\` before installs; review any Security findings before running package scripts.
-- \`nexus doctor\` is cheap, local, and idempotent.
-- If \`nexus doctor\` reports Security, Package Privacy, Git Privacy, or supply-chain findings, stop and report before fixing or installing.
-- Treat install hooks and scripts with network commands, webhooks, raw sockets, SSH, or secret-looking variables as human-review only.
-- Prefer built-in runtime APIs and existing project dependencies when they fit.
-
-### Agent-Local Files
-
-\`${agent.continuity}\` and \`${agent.memoryIndex}\` are agent-local handoff files.
-They are exempt from Nexus claim/release unless the user says otherwise.
-
-### Memory Flow
-
-- On session start, read \`${agent.memoryIndex}\`.
-- If the index has entries, read the newest \`${agent.memoryDir}/YYYY-Month/YYYY-MM-DD-HHMM-topic.md\` entry.
-- Durable architecture and protocol decisions belong in \`DECISIONS.md\`; mention them in \`_NEXUS_STANDUP.md\` only when active agents need to coordinate around them.
-- Memory entries are session handoffs.
-- When writing your own memory entry, create the current month folder under \`${agent.memoryDir}\` if it is missing.
-- Do not create or repair other agents' memory folders manually; use \`nexus doctor --fix\` for broad scaffold repair.
-- On session end, pause, or checkpoint request:
-  1. Run \`nexus checkout @${agent.aliases[0]}\` to clear your presence heartbeat.
-  2. Create one new memory file: \`${agent.memoryDir}/YYYY-Month/YYYY-MM-DD-HHMM-topic.md\`.
-- Add the newest file to the top of \`${agent.memoryIndex}\`.
-- Keep the index to the 10 newest visible entries.
-- For monthly review, read one month folder such as \`${agent.memoryDir}/2026-January/\` and summarize the Markdown files.
-
-Memory entry format:
-
-\`\`\`markdown
-# YYYY-MM-DD-HHMM - <topic>
-
-## Session Summary
-- What we worked on: [<=50 words]
-- What got done: [bullet list, max 5]
-- Where we stopped: [exact state, <=30 words]
-
-## Next Session Needs
-- Immediate next task: [<=20 words]
-- Blockers: [None, or list]
-- Open questions: [if any]
-
-## Context to Carry
-- Key decisions made: [max 3 bullets]
-- Files touched: [max 5 paths]
-- Gotchas/warnings: [anything next session should watch for]
-\`\`\`
-
-${END_MARKER}
-`;
-}
-
-function fullEntrypoint(agent) {
-  return `# ${agent.label} Agent Guide
-
-${protocolBlock(agent)}`;
-}
 
 function upsertProtocolBlock(content, block) {
   const cleanContent = removeUnmanagedProtocolBlock(content);
@@ -347,6 +185,7 @@ function repairStandupGuidance(content) {
 export default function doctor(args) {
   const fix = args.includes('--fix');
   const json = args.includes('--json');
+  const checkHooks = args.includes('--hooks');
   const root = cwd();
   const colors = createColors();
   const sections = {
@@ -361,8 +200,10 @@ export default function doctor(args) {
     Memories: [],
     Locks: [],
     'Generated Artifacts': [],
+    Hooks: [],
     promptCHMOD: [],
     'Queue Authorship': [],
+    'Loop Readiness': [],
   };
   const changes = [];
   const config = getConfig(root);
@@ -423,6 +264,26 @@ export default function doctor(args) {
     sections['Generated Artifacts'].push(issue);
   }
 
+  if (checkHooks) {
+    for (const agent of Object.keys(HOOK_AGENT_CONFIGS)) {
+      const status = hookStatus(agent);
+      if (status.status === 'current') {
+        sections.Hooks.push({
+          issue: `${agent} Nexus hook is installed`,
+          fix: 'No action needed.',
+          ok: true,
+        });
+        continue;
+      }
+
+      const fixHint = `Run \`nexus hooks install --agent ${agent}\`${status.status === 'foreign' ? ' after reviewing the existing hook, or add `--force` to replace it' : ''}.`;
+      sections.Hooks.push({
+        issue: `${agent} Nexus hook is ${status.status} at ${status.path}`,
+        fix: fixHint,
+      });
+    }
+  }
+
   if (!ensureFile(join(root, 'DECISIONS.md'), LOCAL_DECISIONS_TEMPLATE, fix, changes)) {
     sections['Nexus Files'].push({
       issue: 'Missing local DECISIONS.md',
@@ -692,6 +553,21 @@ export default function doctor(args) {
     }
   }
 
+  // Loop readiness — autonomy above supervised requires a release verify gate
+  if (config.autonomy >= 1) {
+    if (!config.release.verifyCommand) {
+      sections['Loop Readiness'].push({
+        issue: `autonomy is ${config.autonomy} but release.verifyCommand is not configured — agents can compound on unverified commits`,
+        fix: 'Set release.verifyCommand in .nexus/config.json (e.g. "npm test") or lower autonomy to 0.',
+      });
+    } else {
+      sections['Loop Readiness'].push({
+        issue: `autonomy ${config.autonomy} with release verify gate configured (${config.release.verifyCommand})`,
+        ok: true,
+      });
+    }
+  }
+
   for (const relativePath of legacyCheckFiles) {
     const path = join(root, relativePath);
     if (!existsSync(path)) continue;
@@ -992,7 +868,7 @@ function isNexusProductRepo(root) {
 }
 
 function repairReadmeProtocolDoc(content) {
-  return content
+  let next = content
     .replace(
       [
         '- [ ] TASK/Codex: Add doctor stale-lock category',
@@ -1021,10 +897,6 @@ function repairReadmeProtocolDoc(content) {
         '  - Notes: Add a doctor section for stale locks with tests and clear fix guidance.',
       ].join('\n'),
     )
-    .replace(
-      'Keep items dashboard-friendly: include `Id`, `Epic`, `Status`, `Depends on`, `Files`, `Affinity`, `Cost`, `Auto-flow`, and `Notes`. Use `Files` to expose conflict surfaces, `Depends on` for hard blockers, and `Auto-flow: no` when a task needs planning or human approval before an agent grabs it.',
-      'Keep items dashboard-friendly: include `Id`, `Epic`, `Status`, `Depends on`, `Files`, `Affinity`, `Cost`, `Auto-flow`, and `Notes`. Use `Files` to expose conflict surfaces, `Depends on` for hard blockers, and `Auto-flow: no` when a task needs planning or human approval before an agent grabs it. Auto-flow work in `Ready Queue` should also include `Review: approved` and `Approved by: human`, or `doctor` will flag it and `nexus next` may skip it.',
-    )
     .replace(
       [
         '1. Run `nexus start` when entering an existing repo; it does not replace claim/release.',
@@ -1039,25 +911,39 @@ function repairReadmeProtocolDoc(content) {
         '1. Run `nexus start` when entering an existing repo; it does not replace claim/release.',
         '2. Read `_NEXUS_CONSTITUTION.md`.',
         '3. Read `USER.md` when present.',
-        '4. Read continuity and latest memory when present.',
+        `4. ${REQUIRED_CONTEXT_READ}`,
         '5. Read `_NEXUS_QUEUE.md` before taking follow-on work.',
         '6. Claim before touching shared project files.',
         '7. Release each claimed tracked file as soon as it reaches a coherent checkpoint.',
         '8. Use `nexus next @Agent` instead of free-roaming.',
       ].join('\n'),
     )
-    .replace(
-      'Agent-local continuity and memory files are exempt from claim/release unless the human says otherwise.',
-      'Agent-local continuity and memory files are exempt from claim/release unless the human says otherwise.\n\nNexus is agent-native and file-native, not human-native: optimize for concurrency and rollback, not feature-commit aesthetics. Do not hold claims to bundle related work into prettier feature commits; that blocks other agents waiting on files.',
-    )
     .replace(
       'The CLI is the coordination engine. The skill is the lean playbook for this flow: `start -> claim -> release`.',
       'The CLI is the coordination engine. The skill is the lean playbook for this flow: `start -> claim -> work -> release -> next`.',
     );
+
+  const queueReviewReadme = 'Auto-flow work in `Ready Queue` should also include `Review: approved` and `Approved by: human`, or `doctor` will flag it and `nexus next` may skip it.';
+  if (!next.includes(queueReviewReadme)) {
+    next = next.replace(
+      'Keep items dashboard-friendly: include `Id`, `Epic`, `Status`, `Depends on`, `Files`, `Affinity`, `Cost`, `Auto-flow`, and `Notes`. Use `Files` to expose conflict surfaces, `Depends on` for hard blockers, and `Auto-flow: no` when a task needs planning or human approval before an agent grabs it.',
+      `Keep items dashboard-friendly: include \`Id\`, \`Epic\`, \`Status\`, \`Depends on\`, \`Files\`, \`Affinity\`, \`Cost\`, \`Auto-flow\`, and \`Notes\`. Use \`Files\` to expose conflict surfaces, \`Depends on\` for hard blockers, and \`Auto-flow: no\` when a task needs planning or human approval before an agent grabs it. ${queueReviewReadme}`,
+    );
+  }
+
+  const agentNativeReadme = 'Nexus is agent-native and file-native, not human-native: optimize for concurrency and rollback, not feature-commit aesthetics. Do not hold claims to bundle related work into prettier feature commits; that blocks other agents waiting on files.';
+  if (!next.includes(agentNativeReadme)) {
+    next = next.replace(
+      'Agent-local continuity and memory files are exempt from claim/release unless the human says otherwise.',
+      `Agent-local continuity and memory files are exempt from claim/release unless the human says otherwise.\n\n${agentNativeReadme}`,
+    );
+  }
+
+  return next;
 }
 
 function repairNexusSkillDoc(content) {
-  return content
+  let next = content
     .replace(
       [
         '1. Run `nexus start`; set `NEXUS_AGENT` for your CLI, or pass `--agent @agy|@claude|@codex|@gemini`. Start is orientation only, not permission to edit.',
@@ -1085,13 +971,14 @@ function repairNexusSkillDoc(content) {
       ].join('\n'),
       [
         '8. Treat claim output as current file state. Ignore cached file memory when contents matter.',
-        '9. Work only inside the claimed surface and run focused validation.',
-        '10. Release each claimed tracked file through Nexus as soon as it reaches a coherent checkpoint:',
+        '9. If a hook blocks access because a path is unclaimed, stop and claim that exact path. Do not work around the hook with another command, cached content, or manual git operation.',
+        '10. Work only inside the claimed surface and run focused validation.',
+        '11. Release each claimed tracked file through Nexus as soon as it reaches a coherent checkpoint:',
       ].join('\n'),
     )
     .replace(
       '```\\n\\n## Queue Items',
-      '```\\n\\n11. Do not hold claims to bundle related work into a prettier feature commit. Nexus is agent-native and file-native: optimize for file availability, rollback safety, and agent throughput.\\n\\n## Queue Items',
+      '```\\n\\n12. Do not hold claims to bundle related work into a prettier feature commit. Nexus is agent-native and file-native: optimize for file availability, rollback safety, and agent throughput.\\n\\n## Queue Items',
     )
     .replace(
       [
@@ -1111,6 +998,25 @@ function repairNexusSkillDoc(content) {
       '- `Auto-flow: yes` means an agent can grab it after `nexus next`; use `no` when planning or human approval is needed.\n- `Notes` should carry dashboard-useful context, not a whole design doc.',
       '- `Auto-flow: yes` means an agent can grab it after `nexus next`; use `no` when planning or human approval is needed.\n- Auto-flow work in `Ready Queue` should include `Review: approved` and `Approved by: human`, or `doctor` will flag it and `nexus next` may skip it.\n- `Notes` should carry dashboard-useful context, not a whole design doc.',
     );
+
+  if (!next.includes('Continuity is the compaction-safe session ledger; latest memory is required startup/resume context.')) {
+    next = next.replace(
+      '- Agent-local continuity and memory files are claim-exempt unless the user says otherwise.',
+      `- Agent-local continuity and memory files are claim-exempt unless the user says otherwise.\n- ${SKILL_CONTEXT_GUARDRAIL}\n- ${MEMORY_INDEX_GUARDRAIL}`,
+    );
+  }
+
+  const mandatoryNote = 'If the user, repo, or hook says Nexus is active, treat this skill as mandatory workflow. It is not optional advice.';
+  if (!next.includes(mandatoryNote)) {
+    next = next.replace('## Loop', `${mandatoryNote}\n\n## Loop`);
+  }
+
+  next = next.replace(
+    '4. Read continuity and latest memory when present.',
+    `4. ${REQUIRED_CONTEXT_READ}`,
+  );
+
+  return next;
 }
 
 const SUSPICIOUS_SCRIPT_PATTERNS = [

package/src/commands/halt.js

@@ -0,0 +1,72 @@
+/**
+ * nexus halt "<reason>" — repo-wide circuit breaker.
+ * Writes .nexus/HALT; while it exists, claim, release, and next refuse and
+ * tell agents to stand by. Any agent or human may halt (an agent that smells
+ * swarm-level trouble should be able to stop everyone). Only humans resume —
+ * by convention, honored at session level, not mechanically enforced.
+ */
+
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'fs';
+import { join, dirname } from 'path';
+import { getConfig } from '../lib/config.js';
+
+export function getHaltPath() {
+  return join(getConfig().root, '.nexus', 'HALT');
+}
+
+export function getHalt() {
+  const path = getHaltPath();
+  if (!existsSync(path)) return null;
+  try {
+    const halt = JSON.parse(readFileSync(path, 'utf-8'));
+    return {
+      reason: halt.reason || '(no reason recorded)',
+      at: halt.at || 'unknown',
+      by: halt.by || 'unknown',
+    };
+  } catch {
+    // A corrupt HALT file still halts; never let a parse error unfreeze the swarm.
+    return { reason: '(unreadable HALT file)', at: 'unknown', by: 'unknown' };
+  }
+}
+
+export function refuseIfHalted(command) {
+  const halt = getHalt();
+  if (!halt) return;
+  console.error(`[HALTED] nexus ${command} refused — the swarm is halted.`);
+  console.error(`  Reason: ${halt.reason}`);
+  console.error(`  Since:  ${halt.at} by ${halt.by}`);
+  console.error('Stand by: append a dated standup line noting you are halted, then stop.');
+  console.error('Do not work around the halt with other tools. A human lifts it with `nexus resume`.');
+  process.exit(1);
+}
+
+export default function halt(args) {
+  const reason = (args[0] || '').trim();
+
+  if (!reason || reason.startsWith('--')) {
+    console.error('Usage: nexus halt "<reason>"');
+    process.exit(1);
+  }
+
+  const existing = getHalt();
+  if (existing) {
+    console.log(`[INFO] Swarm is already halted since ${existing.at} by ${existing.by}: ${existing.reason}`);
+    console.log('A human can lift it with `nexus resume`.');
+    return;
+  }
+
+  const by = process.env.NEXUS_AGENT
+    || (process.env.CLAUDECODE === '1' ? 'agent-session' : 'human');
+
+  const haltPath = getHaltPath();
+  mkdirSync(dirname(haltPath), { recursive: true });
+  writeFileSync(haltPath, JSON.stringify({
+    reason,
+    at: new Date().toISOString(),
+    by,
+  }, null, 2), 'utf-8');
+
+  console.log(`[HALT] Swarm halted: ${reason}`);
+  console.log('claim, release, and next now refuse repo-wide until a human runs `nexus resume`.');
+}