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' +

kernel/etc/bare-os/posix_utilities.json

@@ -1,7 +1,7 @@
 {
   "schema": 2,
   "profileId": "bare-os-posix-like",
-  "generatedAt": "2026-04-27T04:38:35.670Z",
+  "generatedAt": "2026-04-27T04:58:54.649Z",
   "note": "Sparse POSIX Issue 7 coverage hints for /bin utilities. Omitted command names are not yet profiled here.",
   "commandIndex": [
     {
@@ -20,10 +20,6 @@
       "name": "awk",
       "tier": "tier1_bin"
     },
-    {
-      "name": "bare-sshd",
-      "tier": "tier1_bin"
-    },
     {
       "name": "baresay",
       "tier": "tier1_bin"

kernel/lib/bare/shell-completion.json

@@ -1,6 +1,6 @@
 {
   "schema": 1,
-  "atMs": 1777264715669,
+  "atMs": 1777265934648,
   "commands": [
     "agent",
     "appctl",

kernel/share/agent-workspace/AGENTS.md

@@ -6,6 +6,14 @@
 2. Load latest MEMORY.md + today's memory/YYYY-MM-DD.md
 3. Execute BOOTSTRAP.md tasks
 
+## Plan → execute → verify → report
+
+For non-trivial work: state a short plan, use tools (prefer runtime_diagnostic_bundle over guessing live state), verify with read_proc_file or logs, then task_complete with a confidence note (what was verified vs assumed).
+
+## Blast radius
+
+Before multi-file edits, note packages, contracts, generated artifacts, and doc trees that must move together (see developer-guide README cheat sheet).
+
 ## Security & Scope Rules (NEVER violate)
 
 - Only operate inside approved Hyperdrives (system + personal).

kernel/share/agent-workspace/MEMORY.md

@@ -1,3 +1,14 @@
 # MEMORY.md - Long-term Learned Knowledge
 
 (Agent appends distilled insights here over time)
+
+## Structured ledger (optional)
+
+Append short bullets under dated headings:
+
+- FACT — durable repo or env truth (cite path).
+- CHECK — verifier or npm script that proved something.
+- RISK — unresolved assumption or flaky area.
+- HANDOFF — what the next session should read first.
+
+Daily detail can go in `memory/YYYY-MM-DD.md`; keep MEMORY.md as the rolling summary.

kernel/share/agent-workspace/PROMPT.md

@@ -23,3 +23,15 @@ Disable reasoning/process output with `edit_agent_config` (`show_reasoning=false
 ## /xai-debug
 
 Validate xAI compatibility settings, stream behavior, reasoning summary visibility, and tool-call handling. Recommend `reasoning_mode=trace` when summaries are absent.
+
+## /verify-hints
+
+Pass `verification_hints` with the paths or topic you are about to edit (host checkout) to list suggested npm/node checks before leaving the agent.
+
+## /diag-bundle
+
+Run `runtime_diagnostic_bundle` once for live `/proc` and resource snapshot before deep P2P or booter debugging.
+
+## Multi-agent handoff (human or tools)
+
+Split work: one pass for repo/doc scout (read_skill + read_man_page), one for verification hints and smallest test lane, one for summarizing risks. Hand off structured JSON notes in MEMORY.md rather than repeating full logs.

kernel/share/agent-workspace/TOOLS.md

@@ -47,3 +47,14 @@ The agent has access to modular **skills** under `~/.agent/workspace/skills/` (a
 - A **compact** list of skill ids + short descriptions is included in the system prompt.
 - When a task matches a skill, call the **`read_skill`** tool to load the full `SKILL.md`, then follow it exactly.
 - Prefer using skills over reinventing workflows.
+
+## Host-checkout helpers (git workspace on the machine)
+
+When the user is editing the Bare OS repo on the host (not only inside this guest):
+
+- **`verification_hints`** — suggests `npm run …` / `node scripts/verify-*.mjs` from topic keywords or paths; does not run them here.
+- At the repo root, **`npm run agent:path-hints`** takes path arguments; **`npm run agent:holepunch-index`** dumps a JSON index of local `holepunchto_repos` packages.
+
+## One-shot diagnostics
+
+- **`runtime_diagnostic_bundle`** — ctx API version, resource snapshot if available, and all allowlisted `/proc/bare_os/*` snapshots that exist (bounded).

kernel/share/agent-workspace/skills/bareos-code-change/SKILL.md

@@ -0,0 +1,22 @@
+---
+name: bareos-code-change
+description: Generic Bare OS change — contract spine, docs, checks, parity before touching code.
+tags: [bare-os, workflow, governance]
+requires: [read_skill, read_proc_file, verification_hints]
+---
+
+# bareos-code-change
+
+## Before edits
+
+1. Identify contract spine: reference doc under docs/reference or developer-guide, generators in scripts/README.md, verifier names.
+2. Run read_proc_file on /proc/bare_os/features and capabilities.json if behavior depends on runtime bits.
+3. If working from a git checkout on the host, call verification_hints with paths you will touch.
+
+## After edits (host checkout)
+
+Run the smallest check that covers your change; escalate to npm run pretest before push.
+
+## Never
+
+Hand-edit *.generated.ts, posix-dashboard.md, or kernel-extensions-generated-toc without running generators.

kernel/share/agent-workspace/skills/coreutils-command-change/SKILL.md

@@ -0,0 +1,17 @@
+---
+name: coreutils-command-change
+description: /bin utilities — commands.mjs, build, man JSON, BARE_OS_BIN_API pragma, parity.
+tags: [coreutils, bin, man]
+requires: [read_man_page, verification_hints]
+---
+
+# coreutils-command-change
+
+## Flow
+
+1. packages/bare-os-coreutils/lib/commands.mjs and src/<cmd>.js
+2. man/pages/<cmd>.json
+3. npm run build -w bare-os-coreutils
+4. node scripts/verify-man-coverage.mjs and verify-kernel-seeder-parity when kernel/bin updated
+
+See developer-guide/16-how-to-add-bin-utility.md and 06-extending-bin-coreutils.md.

kernel/share/agent-workspace/skills/ctx-api-change/SKILL.md

@@ -0,0 +1,19 @@
+---
+name: ctx-api-change
+description: ctx API semver, types, compatibility matrix, feature bits alignment.
+tags: [ctx, api, semver]
+requires: [read_proc_file, verification_hints]
+---
+
+# ctx-api-change
+
+## Touch list
+
+- packages/bare-os-booter/lib/bare-os-ctx-api.js
+- packages/bare-os-booter/lib/bare-os-ctx.d.ts
+- docs/reference/compatibility-matrix.md
+- packages/bare-os-booter/CHANGELOG.md
+
+## Checks
+
+verification_hints with paths under bare-os-booter; run verify-ctx-api-feature-bits and verify-ctx-dts from repo root.

kernel/share/agent-workspace/skills/docs-contract-update/SKILL.md

@@ -0,0 +1,10 @@
+---
+name: docs-contract-update
+description: Documentation changes — canonical source first, link env appendix, pretest generators.
+tags: [docs, contributing]
+requires: [read_man_page]
+---
+
+# docs-contract-update
+
+Follow docs/CONTRIBUTING-DOCS.md: relative links, Mermaid rules, no task lists in normative docs. Version tables live in compatibility-matrix and environment appendix — link, do not duplicate. After edits run npm run pretest or verify-doc-links.

kernel/share/agent-workspace/skills/holepunch-local-mirror/SKILL.md

@@ -0,0 +1,14 @@
+---
+name: holepunch-local-mirror
+description: Ground Holepunch APIs in local holepunchto_repos clones before inventing usage.
+tags: [holepunch, hypercore, pear, upstream]
+requires: [read_skill]
+---
+
+# holepunch-local-mirror
+
+Default clone root: ~/dev/pearcli/holepunch-repos/holepunchto_repos (or BARE_OS_HOLEPUNCH_CLONES_ROOT).
+
+For API questions: open that repo’s package.json exports, README, lib/, and test/. Cite paths. On host checkout run npm run agent:holepunch-index > /tmp/index.json for a full package list.
+
+Tier-1 stacks: hypercore, corestore, hyperdrive, hyperswarm, hyperdht, protomux, pear, pear-runtime, bare-runtime, bare-* shims.

kernel/share/agent-workspace/skills/hyperdrive-replication/SKILL.md

@@ -0,0 +1,22 @@
+---
+name: hyperdrive-replication
+description: Hyperdrive replication, MBR, swarm disk — read protocol docs and Holepunch hyperdrive first.
+tags: [hyperdrive, p2p, replication]
+requires: [read_man_page, read_proc_file, runtime_diagnostic_bundle]
+---
+
+# hyperdrive-replication
+
+## Read first (repo)
+
+- handbook/03-protocol-and-disk.md
+- docs/reference/package-bare-os-protocol.md
+- docs/reference/architecture-data-flow.md
+
+## Local mirror
+
+Use holepunchto_repos/hyperdrive and related packages for API examples; cite file paths when adapting code.
+
+## Live state
+
+runtime_diagnostic_bundle plus read_proc allowlisted swarm files; compare with Hyperswarm teardown order in docs/reference/hyperswarm-protomux-teardown.md.

kernel/share/agent-workspace/skills/pear-runtime-debug/SKILL.md

@@ -0,0 +1,17 @@
+---
+name: pear-runtime-debug
+description: Pear dev runs, hoisted node_modules, BARE_OS_PEAR_* — isolate from Node-only booter runs.
+tags: [pear, runtime, booter]
+requires: [read_man_page, runtime_diagnostic_bundle]
+---
+
+# pear-runtime-debug
+
+## Read
+
+- docs/PEAR-RUN.md
+- users-manual/03-running-seeder-and-booter.md (ensure-pear-node-modules, npm run os:seeder / os:booter from repo root)
+
+## Debug
+
+Compare pear run --dev with node index.js when bugs are Pear-only. runtime_diagnostic_bundle for live proc snapshot.

kernel/share/agent-workspace/skills/proc-node-change/SKILL.md

@@ -0,0 +1,10 @@
+---
+name: proc-node-change
+description: Add or change /proc/bare_os nodes — VFS, schema, privacy, tests.
+tags: [proc, vfs, schema]
+requires: [read_skill, read_proc_file]
+---
+
+# proc-node-change
+
+Follow developer-guide/15-how-to-add-proc-node.md end to end: booter wiring, snapshot shape, schema under docs/schemas when applicable, redact secrets, add tests in bare-os-booter where appropriate.

kernel/share/agent-workspace/skills/protomux-channel/SKILL.md

@@ -0,0 +1,19 @@
+---
+name: protomux-channel
+description: Protomux channels and compact-encoding messages — align with bare-os-protocol and teardown order.
+tags: [protomux, protocol, wire]
+requires: [read_man_page, read_proc_file]
+---
+
+# protomux-channel
+
+## Read first
+
+- packages/bare-os-protocol/lib/channel.js
+- packages/bare-os-protocol/lib/messages.js
+- docs/reference/package-bare-os-protocol.md
+
+## Rules
+
+- Channel name and message IDs must match seed channel setup.
+- Teardown: swarm before drives when touching booter lifecycle (see hyperswarm-protomux-teardown.md).

kernel/share/agent-workspace/skills/seed-rpc-change/SKILL.md

@@ -0,0 +1,17 @@
+---
+name: seed-rpc-change
+description: Seed RPC registry and channel handlers — no drift from seed-rpc-methods.js.
+tags: [seed-rpc, protocol, rpc]
+requires: [read_man_page, verification_hints]
+---
+
+# seed-rpc-change
+
+## Order
+
+1. packages/bare-os-protocol/lib/seed-rpc-methods.js
+2. packages/bare-os-protocol/lib/channel.js
+3. Seeder and booter call sites
+4. Protocol tests and docs/reference/package-bare-os-protocol.md
+
+Run npm run test -w bare-os-protocol and capability contract verifiers after edits.

kernel/share/agent-workspace/skills/shell-grammar-change/SKILL.md

@@ -0,0 +1,10 @@
+---
+name: shell-grammar-change
+description: Shell tokenizer/parser — grammar-first, fixtures, shell roadmap docs.
+tags: [shell, grammar, posix]
+requires: [read_man_page, verification_hints]
+---
+
+# shell-grammar-change
+
+Read developer-guide/18-how-to-add-shell-grammar-feature.md. Update docs/reference/shell-grammar.md, shell-unsupported-behavior.md, shell-troubleshooting.md when semantics change. Run test:shell-fast and verify:shell-roadmap when applicable.