Agent Updates

kernel/bin/agent

@@ -1592,7 +1592,18 @@ var BARE_AGENT_SKILL_SEED_REL = Object.freeze([
   'skills/agent-ops/SKILL.md',
   'skills/xai-compat/SKILL.md',
   'skills/holesail/SKILL.md',
-  'skills/hdms/SKILL.md'
+  'skills/hdms/SKILL.md',
+  'skills/bareos-code-change/SKILL.md',
+  'skills/hyperdrive-replication/SKILL.md',
+  'skills/protomux-channel/SKILL.md',
+  'skills/ctx-api-change/SKILL.md',
+  'skills/proc-node-change/SKILL.md',
+  'skills/seed-rpc-change/SKILL.md',
+  'skills/coreutils-command-change/SKILL.md',
+  'skills/shell-grammar-change/SKILL.md',
+  'skills/docs-contract-update/SKILL.md',
+  'skills/pear-runtime-debug/SKILL.md',
+  'skills/holepunch-local-mirror/SKILL.md'
 ])
 
 /**
@@ -2987,6 +2998,46 @@ async function bareWebRunTool(o) {
 
 /** OpenAI-style tool schemas + dispatch (preamble for /bin/agent). */
 
+/**
+ * Host-checkout verification hints (keep loosely aligned with scripts/lib/agent-check-hints-data.mjs).
+ * @param {string} combined paths + topic
+ * @returns {string[]}
+ */
+function bareAgentVerificationHintsList(combined) {
+  const c = String(combined || '').toLowerCase()
+  /** @type {string[]} */
+  const hints = []
+  if (/(^|\/)kernel\/|kernel\\|\/boot\/init|lib\/init|lib\\init/.test(c)) {
+    hints.push('npm run bundle:kernel', 'node scripts/verify-kernel-seeder-parity.mjs')
+  }
+  if (/bare-os-coreutils|kernel\/bin|kernel\\bin/.test(c)) {
+    hints.push('npm run build -w bare-os-coreutils', 'node scripts/verify-man-coverage.mjs')
+  }
+  if (/bare-os-booter|bare-os-ctx-api/.test(c)) {
+    hints.push(
+      'npm run test -w bare-os-booter',
+      'node scripts/verify-ctx-api-feature-bits.mjs'
+    )
+  }
+  if (/bare-os-protocol|seed-rpc|channel\.js/.test(c)) {
+    hints.push('npm run test -w bare-os-protocol')
+  }
+  if (/bare-os-seeder/.test(c)) {
+    hints.push('node scripts/verify-kernel-seeder-parity.mjs')
+  }
+  if (/bare-os-bare-libs|kernel\/lib\/bare|kernel\\lib\\bare/.test(c)) {
+    hints.push('npm run build -w bare-os-bare-libs', 'node scripts/verify-bundle-health.mjs')
+  }
+  if (/shell|sh\.js|test\.js/.test(c) && /booter/.test(c)) {
+    hints.push('npm run test:shell-fast')
+  }
+  if (/docs\/|handbook\/|developer-guide\//.test(c)) {
+    hints.push('npm run pretest', 'node scripts/verify-doc-links.mjs')
+  }
+  if (!hints.length) hints.push('npm run pretest', 'npm test')
+  return [...new Set(hints)]
+}
+
 /**
  * @param {string} s
  */
@@ -3811,6 +3862,40 @@ function bareAgentToolDefinitions() {
         }
       }
     },
+    {
+      type: 'function',
+      function: {
+        name: 'verification_hints',
+        description:
+          'Suggest npm/node verification commands for a developer working at the Bare OS git checkout on the host (paths or topic keywords). Does not run commands.',
+        parameters: {
+          type: 'object',
+          properties: {
+            topic: {
+              type: 'string',
+              description: 'Free-text task or area (e.g. kernel init, seed RPC, shell)'
+            },
+            paths_touched: {
+              type: 'string',
+              description:
+                'Optional comma-separated path-like strings from the repo (forward slashes ok)'
+            }
+          }
+        }
+      }
+    },
+    {
+      type: 'function',
+      function: {
+        name: 'runtime_diagnostic_bundle',
+        description:
+          'Non-secret snapshot: ctx API version, optional resource status, and allowlisted /proc/bare_os files that exist (features, swarm, metrics). Prefer over many separate read_proc_file calls.',
+        parameters: {
+          type: 'object',
+          properties: {}
+        }
+      }
+    },
     {
       type: 'function',
       function: {
@@ -5398,6 +5483,61 @@ async function bareAgentDispatchTool(o) {
       )
     }
 
+    if (toolName === 'verification_hints') {
+      const topic = typeof args.topic === 'string' ? args.topic : ''
+      const pathsTouch =
+        typeof args.paths_touched === 'string' ? args.paths_touched : ''
+      appendProgress('verification_hints')
+      const combined = topic + ' ' + pathsTouch.replace(/,/g, ' ')
+      const hints = bareAgentVerificationHintsList(combined)
+      return bareAgentJsonResult({
+        ok: true,
+        scope_note:
+          'Suggested commands apply to the Bare OS git checkout on the host (npm/node at repo root). They do not run automatically.',
+        suggested_commands: hints
+      })
+    }
+
+    if (toolName === 'runtime_diagnostic_bundle') {
+      appendProgress('runtime_diagnostic_bundle')
+      /** @type {Record<string, unknown>} */
+      const bundle = {}
+      bundle.bareOsCtxApiVersion =
+        typeof ctx.bareOsCtxApiVersion !== 'undefined' ? ctx.bareOsCtxApiVersion : null
+      try {
+        if (typeof ctx.bareOsGetResourceStatus === 'function')
+          bundle.resources = ctx.bareOsGetResourceStatus()
+      } catch {
+        bundle.resources_error = true
+      }
+      /** @type {Record<string, unknown>} */
+      const procParts = {}
+      const list = BARE_AGENT_PROC_READ_ALLOWLIST
+      if (vfs && typeof vfs.readFile === 'function') {
+        for (let i = 0; i < list.length; i++) {
+          const procPath = list[i]
+          try {
+            const buf = await vfs.readFile(procPath)
+            if (!buf || !buf.length) continue
+            let t =
+              typeof ctx.b4a !== 'undefined' && ctx.b4a && typeof ctx.b4a.toString === 'function'
+                ? ctx.b4a.toString(buf)
+                : String(new TextDecoder().decode(buf))
+            if (t.length > 80_000) t = t.slice(0, 80_000) + '\n… truncated'
+            try {
+              procParts[procPath] = JSON.parse(t)
+            } catch {
+              procParts[procPath] = t
+            }
+          } catch {
+            /* missing path */
+          }
+        }
+      }
+      bundle.proc = procParts
+      return bareAgentJsonResult({ ok: true, bundle })
+    }
+
     if (toolName === 'web_fetch') {
       const url = typeof args.url === 'string' ? args.url : ''
       let hostHint = ''
@@ -5830,6 +5970,32 @@ Prefer tools over guessing for filesystem and shell facts.
 
 Reply format (mandatory): Every message you stream to the user must be plain text only — readable in a terminal without a Markdown renderer. Do not use Markdown or similar markup: no emphasis/backtick/code-fence/link syntax, no # headings, no list markers used as markup. Structure with blank lines, short paragraphs, indentation, ALL CAPS or dashed lines for section breaks if needed, and bare URLs when linking. Paths and commands appear as normal text.`
 
+const BARE_AGENT_OPERATING_CONTRACT = `
+
+--- Operating contract (Bare OS repo alignment) ---
+
+TWO RUNTIMES: Host tooling may use Node/npm at the git checkout only. Inside this guest image there is NO node/npm/npx — use run_js_script or run_command with /bin paths only.
+
+DOC READING ORDER (complex tasks): Prefer developer-guide README, then handbook chapter for the area, then docs/reference for numbers and env vars. Do not copy version tables into chat; link or cite paths.
+
+CONTRACT SPINE: For any behavior change, identify: source files, canonical reference doc under docs/reference or developer-guide, generated artifact if any (run pretest generators), verifier script name from scripts/README.md, and whether compatibility-matrix or CHANGELOG moves.
+
+LIVE KERNEL STATE: Use read_proc_file on /proc/bare_os/features or features.json and /proc/bare_os/capabilities.json. Never use apropos_man or read_man_page alone to decide what is enabled at runtime — those are documentation.
+
+GENERATED FILES: Do not hand-edit posix-dashboard, ctx-client-helper.generated.ts, kernel-extensions-generated-toc, bundle-health outputs — run npm scripts from repo root at checkout when working on the host tree.
+
+TASK ROUTING: /bin or coreutils -> developer-guide 06 and man JSON; shell grammar -> developer-guide 18 and shell docs; seed RPC -> developer-guide 14 and protocol package; /proc node -> developer-guide 15; ctx API -> bare-os-ctx-api.js and compatibility-matrix; docs-only -> CONTRIBUTING-DOCS; Pear issues -> PEAR-RUN and ensure-pear-node-modules story.
+
+ASK FIRST: Destructive deletes, bridge mutations (emit_host_notification, request_host_action), vault/identity exfil patterns, or widening HTTP allowlists — confirm with the user unless config already allows.
+
+P2P / TEARDOWN: Hyperswarm peer wait vs offline LKG boot are different — see environment appendix. When diagnosing replication, prefer runtime_diagnostic_bundle and read_proc allowlisted swarm files; closing order is swarm before drives when changing booter lifecycle code.
+
+WORKFLOW: Plan briefly, execute tools, verify with read_proc or logs, then task_complete. Before large edits state blast radius (packages, contracts, docs). Before task_complete, self-review: docs updated? generated regen? wrong runtime assumption?
+
+STOP CONDITIONS: If the same failing action repeats three times, stop and summarize evidence; do not loop blindly.
+
+TOOLS: Use verification_hints for suggested repo-root npm checks when the user describes changed paths (host checkout). Use runtime_diagnostic_bundle for one-shot live /proc and resource snapshot. Use read_skill for workflow skills under workspace/skills/.`
+
 /**
  * Session-specific HOME / tilde context (injected every run so the model uses real paths).
  * @param {Record<string, unknown>} ctx
@@ -6277,6 +6443,7 @@ async function bareOsRunAgentSession(ctx, argv0, task, runOpts) {
 
   let systemContent =
     BARE_AGENT_STATIC_SYSTEM +
+    BARE_AGENT_OPERATING_CONTRACT +
     '\n\n' +
     bareAgentSessionHomeBlock(ctx, home, paths) +
     '\n\n' +