eve-hub 0.13.5 → 0.13.7

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # eve-hub
 
+## 0.13.7
+
+### Patch Changes
+
+- Main's prompt leads with a chief-of-staff identity, a shorter role, and no `<engineering>` section.
+
+## 0.13.6
+
+### Patch Changes
+
+- A bot on the Mac gets the local-onboarding skill: it lists the owner's live coding-agent work (Claude Code, Codex, OpenCode, Cursor) with its git state to port into threads, and proposes the sandbox setup for hosted bots as a `prepare` change. Main's onboarding hands that half to the Mac bot. The agent-usage-setup skill and its hub-checkout scripts move into it.
+
 ## 0.13.5
 
 ### Patch Changes

package/kit-modules.json

@@ -12,6 +12,7 @@
   "schedules/dash",
   "schedules/prune",
   "skills/forms",
+  "skills/local-onboarding",
   "skills/onboarding-profile",
   "tools/apply_tags",
   "tools/archive_thread",

package/local-onboarding/SKILL.md

@@ -0,0 +1,89 @@
+---
+name: local-onboarding
+description: "The Mac half of onboarding, when main hands it to you: find the owner's live coding-agent work (Claude Code, Codex, OpenCode, Cursor) to port into threads, and propose the sandbox setup their hosted bots need. Reads only; the threads and the sandbox PR wait for the owner's yes."
+license: MIT
+---
+
+# The Mac half of onboarding
+
+Main runs onboarding on Vercel, where it can't see this Mac, so it hands you this half and posts its own without waiting. You post two short messages in that thread, the live work first, then the sandbox setup. Follow your writing rules: each first bubble is at most two sentences, with tables below a `---` line.
+
+Two scripts gather the facts. They live in `{{scripts}}`, read only, and print metadata: repos, branches, counts, times, the agents' own session titles and program names. Work only from what they print. Don't open the agents' session files yourself: they hold the owner's prompts and code. Delete the JSON files when you are done.
+
+## 1. Live work to port
+
+```sh
+node {{scripts}}/sessions-facts.mjs > "$TMPDIR/sessions.json"
+```
+
+The script covers the last 14 days of sessions, grouped into work-streams by repo and branch, newest first. Each stream has:
+- `repo`, `branch` and `pr` (the open PR);
+- `checkouts`: one per clone or worktree it was worked in. Each has `worktree` (true for a linked git worktree), `uncommitted` (changed files) and `unpushed` (commits ahead of `aheadOf`);
+- `lastActive`;
+- `sessions`: each with its agent, title, time and `checkout` (its index in `checkouts`).
+
+A stream with no remote is keyed `local-N`. A stream marked `gone` is a folder that no longer exists. `unreadable` lists the sources that exist but couldn't be read. An `uncommitted` or `unpushed` of `null` means the count couldn't be determined (git timed out on a huge untracked tree, or there is no upstream or default branch to compare against): it is unknown, not zero.
+
+Post the streams that have work in flight: any checkout with uncommitted files or unpushed commits, or an open PR. A checkout with an unknown count gets a row too, with "unknown" in that cell. A stream with more than one checkout gets one row per checkout that has work. Put the rest in one line with their count.
+
+```md
+You have 3 work-streams in flight on this Mac. Say which to port, and main will open a thread for each so the team can pick it up.
+
+---
+
+| Stream | Agent and session | Last active | Uncommitted | Unpushed | PR |
+|---|---|---|---|---|---|
+| `vercel/app` on `fix-login` (worktree) | Claude Code, "Fix login redirect" | 2h ago | 4 files | 2 | [#812](...) |
+
+Also 5 streams with nothing in flight.
+```
+
+Never post a local path, a file name, a prompt, or anything else from the sessions.
+
+When the owner says which streams to port, you still write nothing on the Mac. Post one message that mentions main and asks it to open one thread per stream. For each stream, give a short title, the repo and branch, its state (worktree, uncommitted and unpushed counts, PR), and which agent had it. You don't open threads yourself.
+
+## 2. Sandbox setup
+
+```sh
+node {{scripts}}/agent-usage-facts.mjs > "$TMPDIR/agent-usage.json"
+```
+
+It takes about 30 seconds on 16 GB of history. It prints names and counts, never a command's arguments, a prompt or a value:
+- `scanned`: records, commands and unparsable commands per agent;
+- `unreadable`;
+- `programs`, `mcpServers`, `repos`, `languages` (file extensions) and `envNames`.
+
+Mapping each fact to a setup is your judgment, not a lookup table. Decide, for every program in the top 30:
+
+- **Hosted or Mac.** These can't run in a Linux sandbox, so they stay on the Mac with you:
+  - `brew`, `osascript` and `open`;
+  - Xcode, `xcodebuild` and Apple-platform `swift`;
+  - anything that drives the owner's browser or apps;
+  - `localhost` services and the keychain.
+
+  Everything else can be hosted.
+- **Already there, or add it.** A hosted bot's sandbox is eve's Ubuntu image with git only, plus what its `prepare` in `agents/<bot>/agent/sandbox.ts` installs. Read `prepare` in the workspace repo's sandbox files. A program it installs is already provided; any other hosted program needs a `prepare` step. Use `apt-get` where Ubuntu has the package, and the project's official installer otherwise.
+
+MCP servers are reached from hosted bots through Vercel Kit connections: list each one by name for main to connect. Env var names are listed for the owner only. Never print a value (you don't have any). Ignore shell and system names (`PATH`, `HOME`, `CI`, ...). A name with a high `shellAssigned` relative to `count` is probably a shell variable, not part of the environment.
+
+Post the proposal:
+- a first bubble on what the hosted bots would gain;
+- a table of the steps to add, with the programs each installs and how often the owner used them;
+- one line for what stays on the Mac;
+- one line for the MCP servers to connect through Kit.
+
+Ask whether to open the PR.
+
+## 3. The sandbox PR, after the owner's yes
+
+The steps live in one file, which is the only source; never hand-write them into `sandbox.ts`. Write `$TMPDIR/prepare.json` as `{"commands": [{"command": "<shell>", "what": "<short name for the error>"}]}`.
+
+Main's handoff names the workspace repo. Clone it into a scratch folder, branch, and add the steps to each hosted bot that runs code. That is the builder, unless the owner said otherwise.
+
+```sh
+node {{scripts}}/prepare-edit.mjs "$TMPDIR/prepare.json" agents/builder/agent/sandbox.ts
+```
+
+Commit, push and open the PR with `gh pr create`. The body lists the programs, why each one is there, and the usage counts behind them. Never name the owner's other repos.
+
+The PR's Vercel build runs `prepare`, so a step that fails, fails the build. Wait for its result with `gh pr checks --watch --fail-fast`. If it fails, fix the step in `prepare.json`, restore the file from the branch you cut from (`git checkout origin/HEAD -- <file>`), rerun the script and push. Post the PR link and its build result in the thread, then delete the scratch clone.

package/local-onboarding/agent-usage-facts.mjs

@@ -0,0 +1,322 @@
+#!/usr/bin/env node
+// Read-only fact gatherer for the local-onboarding skill (local-onboarding/SKILL.md, step 2): what the user's local coding agents
+// (Claude Code, Codex, OpenCode, Cursor, Claude Desktop) have actually used, as names and counts.
+// Prints one JSON document on stdout; progress goes to stderr. Never writes, never emits a
+// command's arguments, a prompt, a path inside a repo, or any value: every string that leaves this
+// file went through `name()` or `normalizeOrigin()` (or is a source path under the agents' own dirs).
+import { createReadStream, existsSync, readFileSync, globSync } from 'node:fs';
+import { execFileSync } from 'node:child_process';
+import { createInterface } from 'node:readline';
+import { DatabaseSync } from 'node:sqlite';
+import { homedir } from 'node:os';
+import { basename, dirname, extname, join } from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { parse as parseJsonc } from 'jsonc-parser';
+import { parse as parseToml } from 'smol-toml';
+import { Language, Parser } from 'web-tree-sitter';
+import { cleanGitEnv, normalizeOrigin } from './git.mjs';
+import { codexHome, codexStateDb } from './codex-home.mjs';
+
+const HOME = homedir();
+const tilde = (p) => (p.startsWith(HOME) ? `~${p.slice(HOME.length)}` : p);
+const NAME = /^[A-Za-z0-9_@][\w.@+:-]{0,63}$/;
+const ENV_NAME = /^[A-Za-z_][A-Za-z0-9_]{0,63}$/;
+const EXT = /^\.[a-z0-9]{1,8}$/;
+// Builtins and wrappers say nothing about what a sandbox needs installed.
+const NOT_PROGRAMS = new Set(['cd', 'echo', 'export', 'set', 'unset', 'true', 'false', 'test', '[', ':', 'break', 'continue', 'trap', 'read',
+  'source', '.', 'exit', 'return', 'wait', 'local', 'printf', 'pwd', 'eval', 'alias']);
+const WRAPPERS = new Set(['sudo', 'env', 'time', 'command', 'nohup', 'exec', 'builtin', 'nice', 'timeout']);
+const FILE_TOOLS = new Set(['Read', 'Edit', 'Write', 'MultiEdit', 'read', 'edit', 'write']);
+
+// ---- aggregation: every emitted row is {name, count, agents} keyed by one string ----
+const table = () => new Map();
+function bump(map, key, agent, n = 1) {
+  const row = map.get(key) ?? { count: 0, agents: new Set() };
+  row.count += n;
+  row.agents.add(agent);
+  map.set(key, row);
+}
+const rows = (map, keyName) => [...map].map(([k, r]) => ({ [keyName]: k, count: r.count, agents: [...r.agents].sort() }))
+  .sort((a, b) => b.count - a.count || String(a[keyName]).localeCompare(String(b[keyName])));
+
+const programs = table();
+const extensions = table();
+const repos = table();
+const scanned = Object.fromEntries(['claude-code', 'codex', 'opencode'].map((a) => [a, { records: 0, commands: 0, unparsed: 0 }]));
+const unreadable = new Set(); // sources that exist but could not be read or parsed (labels only, never parser messages)
+const envNames = new Map(); // name -> { count: uses as env or $NAME, shellAssigned: bare/for/read assignments, sources:Set }
+const mcp = new Map(); // name -> { transports, endpoints, agents, sources }
+
+const name = (s) => (typeof s === 'string' && NAME.test(s) ? s : null);
+
+function addEnvName(n, source, uses = 0, shellAssigned = 0) {
+  if (!ENV_NAME.test(n)) return;
+  const row = envNames.get(n) ?? { count: 0, shellAssigned: 0, sources: new Set() };
+  row.count += uses;
+  row.shellAssigned += shellAssigned;
+  row.sources.add(source);
+  envNames.set(n, row);
+}
+
+function addMcp(serverName, agent, source, cfg) {
+  const n = name(serverName);
+  if (!n) return;
+  const row = mcp.get(n) ?? { transports: new Set(), endpoints: new Set(), agents: new Set(), sources: new Set() };
+  row.agents.add(agent);
+  row.sources.add(source);
+  const c = cfg && typeof cfg === 'object' ? cfg : {};
+  if (c.command) {
+    // `command` is a string (possibly with args: Cursor) or an argv array (OpenCode); only argv[0] is a program name.
+    const argv0 = Array.isArray(c.command) ? c.command[0] : String(c.command).trim().split(/\s+/)[0];
+    row.transports.add('stdio');
+    const prog = name(basename(String(argv0)));
+    if (prog) row.endpoints.add(prog);
+  } else if (c.url) {
+    row.transports.add(c.type === 'sse' ? 'sse' : 'http');
+    try { row.endpoints.add(new URL(c.url).hostname); } catch { /* no host to report */ }
+  }
+  for (const k of Object.keys(c.env ?? c.environment ?? {})) addEnvName(k, `mcp:${n}`);
+  mcp.set(n, row);
+}
+
+// ---- shell commands -> program names and env names (never arguments) ----
+await Parser.init();
+const shParser = new Parser();
+shParser.setLanguage(await Language.load(fileURLToPath(import.meta.resolve('tree-sitter-bash/tree-sitter-bash.wasm'))));
+
+// A word that is one literal token (no quotes, expansions or concatenation); anything else is not a program name.
+const literal = (n) => {
+  const t = n.type === 'command_name' && n.childCount === 1 ? n.child(0) : n;
+  return t.type === 'word' || t.type === 'number' ? t.text : '';
+};
+const assignedName = (n) => {
+  const target = n.childForFieldName('name');
+  return (target?.type === 'subscript' ? target.childForFieldName('name') : target)?.text ?? '';
+};
+// `NAME=v` inside these is not a shell assignment: `command` and `declaration_command` are handled where they are
+// (`export A=1` records nothing), and a C-style for header is arithmetic.
+const NOT_BARE_ASSIGN = new Set(['command', 'declaration_command', 'c_style_for_statement']);
+
+// One syntax-tree walk per command: the first literal word of each call is its program; `NAME=v cmd`, `env NAME=v cmd` and
+// `$NAME` each count a use of an env name. A for-loop variable, a bare `NAME=v` and `read NAME` count as
+// `shellAssigned` on the same name: the fact is recorded, whether it is a shell variable or real env is the model's call.
+// Values and other words are never kept.
+function commandFacts(cmd, agent) {
+  scanned[agent].commands++;
+  const tree = shParser.parse(cmd);
+  if (!tree || tree.rootNode.hasError) { scanned[agent].unparsed++; tree?.delete(); return; }
+  const source = `commands:${agent}`;
+  const envUse = (n) => addEnvName(n, source, 1);
+  const shellAssign = (n) => addEnvName(n, source, 0, 1);
+  const visit = (node) => {
+    switch (node.type) {
+      case 'for_statement': shellAssign(node.childForFieldName('variable')?.text ?? ''); break;
+      case 'simple_expansion':
+      case 'expansion': {
+        const v = node.namedChildren.find((c) => c.type === 'variable_name' || c.type === 'subscript' || c.type === 'special_variable_name');
+        envUse((v?.type === 'subscript' ? v.childForFieldName('name') : v)?.text ?? '');
+        break;
+      }
+      case 'variable_assignment': if (!NOT_BARE_ASSIGN.has(node.parent?.type)) shellAssign(assignedName(node)); break;
+      case 'command': {
+        // `sudo 2>/dev/null cargo build` parses with the words after the redirect target as extra destinations of the
+        // redirect: only the first is the file, the rest are more words of this command.
+        const afterRedirect = node.parent?.type === 'redirected_statement'
+          ? node.parent.childrenForFieldName('redirect').filter((r) => r.type === 'file_redirect').flatMap((r) => r.childrenForFieldName('destination').slice(1))
+          : [];
+        const words = [node.childForFieldName('name'), ...node.childrenForFieldName('argument'), ...afterRedirect].filter(Boolean).map(literal);
+        const record = words.length ? envUse : shellAssign; // `A=1 cmd` sets env for cmd; a bare `A=1` is a shell variable
+        for (const c of node.namedChildren) if (c.type === 'variable_assignment') record(assignedName(c));
+        for (const w of words) {
+          const assign = w.match(/^([A-Za-z_][A-Za-z0-9_]*)=/);
+          if (assign) { envUse(assign[1]); continue; }
+          if (WRAPPERS.has(w) || w.startsWith('-') || /^\d+$/.test(w)) continue;
+          if (w === 'read') for (const r of words.slice(1)) if (!r.startsWith('-')) shellAssign(r);
+          const prog = name(basename(w));
+          if (prog && !NOT_PROGRAMS.has(prog)) bump(programs, prog, agent);
+          break;
+        }
+        break;
+      }
+    }
+    for (const c of node.namedChildren) visit(c);
+  };
+  visit(tree.rootNode);
+  tree.delete();
+}
+
+function fileFacts(filePath, agent) {
+  const ext = extname(String(filePath ?? '')).toLowerCase();
+  if (EXT.test(ext)) bump(extensions, ext, agent);
+}
+
+// ---- repos: collapse worktrees and clones to one origin; fall back to the directory ----
+const NO_ORIGIN = '(no git origin)'; // directory names can be prompt-derived (Codex), so they are counted, never named
+const originCache = new Map();
+function origin(dir) {
+  if (originCache.has(dir)) return originCache.get(dir);
+  let key = NO_ORIGIN;
+  if (existsSync(dir)) {
+    try {
+      const url = execFileSync('git', ['-C', dir, 'config', '--get', 'remote.origin.url'], { encoding: 'utf8', timeout: 3000, stdio: ['ignore', 'pipe', 'ignore'], env: cleanGitEnv() }).trim();
+      key = normalizeOrigin(url) ?? key;
+    } catch { /* not a git checkout, or no origin */ }
+  }
+  originCache.set(dir, key);
+  return key;
+}
+const addRepo = (dir, knownOrigin, agent, sessions = 1) => bump(repos, normalizeOrigin(knownOrigin) ?? origin(dir), agent, sessions);
+
+// ---- streaming ----
+async function* lines(file) {
+  yield* createInterface({ input: createReadStream(file), crlfDelay: Infinity });
+}
+const files = (dir, pattern) => (existsSync(dir) ? globSync(pattern, { cwd: dir }).map((f) => join(dir, f)) : []);
+// A missing file is just absent; a file that exists but won't read or parse is reported in `unreadable`.
+function readConfig(f, parse) {
+  if (!existsSync(f)) return null;
+  try { return parse(readFileSync(f, 'utf8')); } catch { unreadable.add(tilde(f)); return null; }
+}
+const readJson = (f) => readConfig(f, (text) => {
+  const errors = [];
+  const value = parseJsonc(text, errors, { allowTrailingComma: true }); // JSONC is a superset of JSON (opencode.jsonc has comments)
+  if (errors.length) throw new Error('jsonc');
+  return value;
+});
+const readToml = (f) => readConfig(f, parseToml);
+const log = (m) => process.stderr.write(`${m}\n`);
+
+// Open a sqlite file read-only for `use`. A database that is missing from an installed agent's directory, or that
+// won't open or query, is reported in `unreadable` instead of silently contributing nothing.
+function withDb(path, use) {
+  if (!existsSync(path)) { if (existsSync(dirname(path))) unreadable.add(tilde(path)); return; }
+  let d;
+  try {
+    d = new DatabaseSync(path, { readOnly: true });
+    use(d);
+  } catch { unreadable.add(tilde(path)); } finally { d?.close(); }
+}
+
+// ---- readers: one per agent ----
+async function claudeCode() {
+  const agent = 'claude-code';
+  const cfgPath = join(HOME, '.claude.json');
+  const cfg = readJson(cfgPath) ?? {};
+  for (const [n, c] of Object.entries(cfg.mcpServers ?? {})) addMcp(n, agent, '~/.claude.json#mcpServers', c);
+  for (const p of Object.values(cfg.projects ?? {})) for (const [n, c] of Object.entries(p.mcpServers ?? {})) addMcp(n, agent, '~/.claude.json#projects.*.mcpServers', c);
+  for (const k of Object.keys(readJson(join(HOME, '.claude/settings.json'))?.env ?? {})) addEnvName(k, '~/.claude/settings.json#env');
+  const installed = readJson(join(HOME, '.claude/plugins/installed_plugins.json'))?.plugins ?? {};
+  const enabled = readJson(join(HOME, '.claude/settings.json'))?.enabledPlugins ?? {};
+  for (const [id, installs] of Object.entries(installed)) {
+    if (!enabled[id]) continue;
+    for (const i of installs) {
+      const m = readJson(join(i.installPath, '.mcp.json'));
+      for (const [n, c] of Object.entries(m?.mcpServers ?? m ?? {})) addMcp(n, agent, `claude plugin ${id.split('@')[0]}`, c);
+    }
+  }
+  const transcripts = files(join(HOME, '.claude/projects'), '**/*.jsonl');
+  scanned[agent].records = transcripts.length;
+  for (const f of transcripts) {
+    let cwd = null;
+    let seen = 0;
+    for await (const line of lines(f)) {
+      if (!cwd && seen++ < 50) cwd = line.match(/"cwd":"([^"]+)"/)?.[1] ?? null;
+      if (!line.includes('"type":"tool_use"')) continue;
+      let msg;
+      try { msg = JSON.parse(line); } catch { continue; }
+      for (const b of msg.message?.content ?? []) {
+        if (b.type !== 'tool_use') continue;
+        if (b.name === 'Bash') commandFacts(String(b.input?.command ?? ''), agent);
+        else if (FILE_TOOLS.has(b.name)) fileFacts(b.input?.file_path, agent);
+      }
+    }
+    if (cwd) addRepo(cwd, null, agent);
+  }
+  log(`claude-code: ${transcripts.length} transcripts`);
+}
+
+async function codex() {
+  const agent = 'codex';
+  const root = codexHome();
+  const cfg = readToml(join(root, 'config.toml')) ?? {};
+  for (const [n, c] of Object.entries(cfg.mcp_servers ?? {})) addMcp(n, agent, '~/.codex/config.toml#mcp_servers', c);
+  for (const [id, p] of Object.entries(cfg.plugins ?? {})) {
+    if (!p.enabled) continue;
+    const [pluginName, marketplace] = id.split('@');
+    for (const f of files(root, `plugins/cache/${marketplace}/${pluginName}/*/.mcp.json`)) {
+      const m = readJson(f);
+      for (const [n, c] of Object.entries(m?.mcpServers ?? m ?? {})) addMcp(n, agent, `codex plugin ${pluginName}`, c);
+    }
+  }
+  withDb(codexStateDb(), (d) => {
+    for (const r of d.prepare('select cwd, git_origin_url as o, count(*) as n from threads group by cwd, git_origin_url').all()) {
+      addRepo(r.cwd, r.o, agent, r.n);
+    }
+  });
+  const rollouts = [...files(root, 'sessions/**/*.jsonl'), ...files(root, 'archived_sessions/**/*.jsonl')];
+  scanned[agent].records = rollouts.length;
+  for (const f of rollouts) {
+    for await (const line of lines(f)) {
+      if (!line.includes('"exec_command"')) continue;
+      let p;
+      try { p = JSON.parse(line).payload; } catch { continue; }
+      if (p?.type !== 'function_call' || p.name !== 'exec_command') continue;
+      try { commandFacts(String(JSON.parse(p.arguments).cmd ?? ''), agent); } catch { /* arguments not JSON */ }
+    }
+  }
+  log(`codex: ${rollouts.length} rollouts`);
+}
+
+function openCode() {
+  const agent = 'opencode';
+  for (const f of ['opencode.json', 'opencode.jsonc']) {
+    for (const [n, c] of Object.entries(readJson(join(HOME, '.config/opencode', f))?.mcp ?? {})) addMcp(n, agent, `~/.config/opencode/${f}#mcp`, c);
+  }
+  withDb(join(HOME, '.local/share/opencode/opencode.db'), (d) => {
+    for (const r of d.prepare('select directory, count(*) as n from session group by directory').all()) addRepo(r.directory, null, agent, r.n);
+    const q = d.prepare(`select json_extract(data,'$.tool') as tool, json_extract(data,'$.state.input.command') as cmd,
+      json_extract(data,'$.state.input.filePath') as file from part where json_extract(data,'$.type')='tool'`);
+    let tools = 0;
+    for (const r of q.iterate()) {
+      tools++;
+      if (r.tool === 'bash') commandFacts(String(r.cmd ?? ''), agent);
+      else if (FILE_TOOLS.has(r.tool)) fileFacts(r.file, agent);
+    }
+    scanned[agent].records = tools;
+    log(`opencode: ${tools} tool parts`);
+  });
+}
+
+// Cursor's chat history is opaque blobs; its MCP config is all that is readable.
+function cursor() {
+  for (const [n, c] of Object.entries(readJson(join(HOME, '.cursor/mcp.json'))?.mcpServers ?? {})) addMcp(n, 'cursor', '~/.cursor/mcp.json#mcpServers', c);
+}
+
+function claudeDesktop() {
+  const f = join(HOME, 'Library/Application Support/Claude/claude_desktop_config.json');
+  for (const [n, c] of Object.entries(readJson(f)?.mcpServers ?? {})) addMcp(n, 'claude-desktop', 'claude_desktop_config.json#mcpServers', c);
+}
+
+export async function gather() {
+  claudeDesktop();
+  cursor();
+  openCode();
+  await Promise.all([claudeCode(), codex()]);
+  return {
+    scanned,
+    unreadable: [...unreadable].sort(),
+    programs: rows(programs, 'name'),
+    mcpServers: [...mcp].map(([n, r]) => ({ name: n, transport: [...r.transports].sort(), endpoints: [...r.endpoints].sort(), agents: [...r.agents].sort(), sources: [...r.sources].sort() }))
+      .sort((a, b) => a.name.localeCompare(b.name)),
+    repos: rows(repos, 'origin').map(({ origin: o, count, agents }) => ({ origin: o, sessions: count, agents })),
+    languages: rows(extensions, 'ext'),
+    envNames: [...envNames].map(([n, r]) => ({ name: n, count: r.count, shellAssigned: r.shellAssigned, sources: [...r.sources].sort() })).sort((a, b) => b.count - a.count || a.name.localeCompare(b.name)),
+  };
+}
+
+if (import.meta.url === pathToFileURL(process.argv[1]).href) {
+  const t = Date.now();
+  const facts = await gather();
+  process.stdout.write(`${JSON.stringify(facts)}\n`);
+  log(`done in ${((Date.now() - t) / 1000).toFixed(1)}s`);
+}

package/local-onboarding/codex-home.mjs

@@ -0,0 +1,14 @@
+// Where Codex keeps its files, for both local-onboarding fact scripts. `CODEX_HOME` moves them all
+// (default ~/.codex); `CODEX_SQLITE_HOME` moves only the state database, whose name carries its schema
+// version (`state_5.sqlite`, bumped when the schema changes), so the newest one is read.
+import { existsSync, readdirSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+
+export const codexHome = (env = process.env) => env.CODEX_HOME || join(homedir(), '.codex');
+
+export function codexStateDb(env = process.env) {
+  const dir = env.CODEX_SQLITE_HOME || codexHome(env);
+  const versions = existsSync(dir) ? readdirSync(dir).map((f) => f.match(/^state_(\d+)\.sqlite$/)?.[1]).filter(Boolean).map(Number) : [];
+  return join(dir, `state_${versions.length ? Math.max(...versions) : 5}.sqlite`);
+}

package/local-onboarding/git.mjs

@@ -0,0 +1,21 @@
+// What both local-onboarding fact scripts need from git: an env without an inherited repo, and a repo's name.
+
+// `git bisect run`, hooks and `git rebase -x` export GIT_DIR (and friends) to their children; without
+// this every query would hit that repo (lib/clean-env.mjs, which this package can't import).
+const GIT_REPO_ENV = /^GIT_(DIR|WORK_TREE|INDEX_FILE|COMMON_DIR|PREFIX|OBJECT_DIRECTORY|ALTERNATE_OBJECT_DIRECTORIES|NAMESPACE|IMPLICIT_WORK_TREE)$/;
+export const cleanGitEnv = (env = process.env) => Object.fromEntries(Object.entries(env).filter(([key]) => !GIT_REPO_ENV.test(key)));
+
+// `host/owner/repo` from a remote URL (https://, ssh://, git@host:owner/repo). Built from the parsed host and path only,
+// so userinfo, query and fragment can't survive; a local-path or unparsable origin is not a repo name.
+export function normalizeOrigin(url) {
+  const text = String(url ?? '').trim();
+  const scp = text.match(/^(?:[\w.-]+@)?([\w.-]+):(?!\/\/)([^?#]+)$/);
+  let host;
+  let path;
+  if (scp) [, host, path] = scp;
+  else {
+    try { ({ hostname: host, pathname: path } = new URL(text)); } catch { return null; }
+  }
+  const key = `${host}/${path.replace(/^\/+|\/+$/g, '').replace(/\.git$/, '')}`;
+  return /^[\w.-]+\/[\w./-]{1,150}$/.test(key) ? key : null;
+}

package/local-onboarding/prepare-edit.mjs

@@ -0,0 +1,30 @@
+#!/usr/bin/env node
+// Adds the sandbox setup local-onboarding proposed to hosted bots' sandbox.ts, in place:
+//   node prepare-edit.mjs proposal.json agents/<bot>/agent/sandbox.ts [...]
+// proposal.json is {"commands": [{"command": "<shell>", "what": "<short name for the error>"}]}, the one source of
+// the steps: they are written as `await run(...)` calls into `prepare`, before its `if (!token) return;`, so every new
+// session's snapshot has them. A step already in the file is not added twice. A sandbox.ts without the scaffold's
+// `run` helper and token line (lib/agent-template.mjs) is refused: edit that one by hand.
+import { readFileSync, writeFileSync } from 'node:fs';
+import { pathToFileURL } from 'node:url';
+
+const RUN = /^  const run = async \(command, what\) => \{$/m;
+const ANCHOR = '  if (!token) return;\n';
+
+export function addPrepareSteps(source, commands) {
+  if (!Array.isArray(commands) || !commands.every((c) => typeof c?.command === 'string' && c.command.trim() && typeof c?.what === 'string' && c.what.trim())) {
+    throw new Error('commands must be [{ command, what }] with both non-empty');
+  }
+  if (!RUN.test(source) || !source.includes(ANCHOR)) throw new Error("this sandbox.ts isn't the scaffold's (no `run` helper or `if (!token) return;`): add the steps by hand");
+  const lines = commands.map(({ command, what }) => `  await run(${JSON.stringify(command)}, ${JSON.stringify(what)});\n`).filter((line) => !source.includes(line));
+  if (!lines.length) return source;
+  const steps = `  // The programs the owner's coding agents use (local-onboarding).\n${lines.join('')}${ANCHOR}`;
+  return source.replace(ANCHOR, () => steps);
+}
+
+if (import.meta.url === pathToFileURL(process.argv[1] ?? '').href) {
+  const [proposal, ...files] = process.argv.slice(2);
+  if (!proposal || !files.length) throw new Error('usage: prepare-edit.mjs proposal.json sandbox.ts [...]');
+  const { commands } = JSON.parse(readFileSync(proposal, 'utf8'));
+  for (const file of files) writeFileSync(file, addPrepareSteps(readFileSync(file, 'utf8'), commands));
+}

package/local-onboarding/sessions-facts.mjs

@@ -0,0 +1,258 @@
+#!/usr/bin/env node
+// Read-only fact gatherer for local onboarding: the user's recent coding-agent sessions (Claude Code,
+// Codex, OpenCode, Cursor) grouped into work-streams by (repo, branch), each with its git state.
+// `node sessions-facts.mjs [--days 14]` prints one JSON document on stdout; progress goes to stderr.
+// Privacy contract: what leaves this file is only the normalized repo name, the branch, last-active
+// times, counts (uncommitted files, unpushed commits, sessions scanned), each checkout's worktree boolean, the open
+// PR's number/url/title, and the agent's own stored session title. Never a prompt, message text, command,
+// a path inside a repo, or the local directory (a stream with no repo is keyed `local-N`). Nothing is
+// written: sqlite opens read-only and every git command is a query.
+import { existsSync, globSync, readFileSync, readdirSync, statSync } from 'node:fs';
+import { execFileSync } from 'node:child_process';
+import { DatabaseSync } from 'node:sqlite';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { cleanGitEnv, normalizeOrigin } from './git.mjs';
+import { codexHome, codexStateDb } from './codex-home.mjs';
+
+const HOME = homedir();
+const AGENTS = ['claude-code', 'codex', 'opencode', 'cursor'];
+const TITLE_MAX = 120;
+const tilde = (p) => (p.startsWith(HOME) ? `~${p.slice(HOME.length)}` : p);
+const log = (m) => process.stderr.write(`${m}\n`);
+
+const title = (s) => (typeof s === 'string' && s.trim() ? s.trim().slice(0, TITLE_MAX) : null);
+const iso = (ms) => (Number.isFinite(ms) && ms > 0 ? new Date(ms).toISOString() : null);
+const files = (dir, pattern) => (existsSync(dir) ? globSync(pattern, { cwd: dir }).map((f) => join(dir, f)) : []);
+const mtime = (f) => { try { return statSync(f).mtimeMs; } catch { return 0; } };
+
+// ---- git: one read-only probe per directory ----
+const rawGit = (dir, args) => execFileSync('git', ['-C', dir, '--no-optional-locks', ...args], { encoding: 'utf8', timeout: 5000, stdio: ['ignore', 'pipe', 'ignore'], env: cleanGitEnv() });
+const tryGit = (dir, args) => { try { return rawGit(dir, args).trim(); } catch { return null; } };
+// Changed files, each untracked file counted on its own (not one per new directory). In `-z` records
+// a rename or copy carries its source path as the next record, which is the same file.
+export function countChanged(porcelainZ) {
+  const records = porcelainZ.split('\0').filter(Boolean);
+  let n = 0;
+  for (let i = 0; i < records.length; i++) {
+    n++;
+    if (/^[RC]/.test(records[i])) i++;
+  }
+  return n;
+}
+function uncommittedIn(dir) {
+  try { return countChanged(rawGit(dir, ['status', '--porcelain=v1', '-z', '--untracked-files=all'])); } catch { return null; }
+}
+let ghBroken = false;
+function openPr(repo, branch, unreadable) {
+  if (!repo?.startsWith('github.com/') || !branch || ghBroken) return null;
+  try {
+    const out = execFileSync('gh', ['pr', 'list', '--head', branch, '--repo', repo.slice('github.com/'.length), '--state', 'open', '--json', 'number,url,title', '--limit', '1'], { encoding: 'utf8', timeout: 15000, stdio: ['ignore', 'pipe', 'ignore'] });
+    const pr = JSON.parse(out)[0];
+    return pr ? { number: pr.number, url: pr.url, title: title(pr.title) } : null;
+  } catch {
+    ghBroken = true;
+    unreadable.add('gh pr list');
+    return null;
+  }
+}
+// A checkout's state; `repo` and `branch` name its stream, the rest is the checkout's own.
+function gitState(dir) {
+  if (!existsSync(dir)) return { gone: true };
+  if (tryGit(dir, ['rev-parse', '--is-inside-work-tree']) !== 'true') return { repo: null, branch: null };
+  const repo = normalizeOrigin(tryGit(dir, ['config', '--get', 'remote.origin.url']));
+  const branch = tryGit(dir, ['symbolic-ref', '--short', '-q', 'HEAD']);
+  const [gitDir, commonDir] = (tryGit(dir, ['rev-parse', '--path-format=absolute', '--git-dir', '--git-common-dir']) ?? '').split('\n');
+  const worktree = Boolean(gitDir && commonDir) && gitDir !== commonDir;
+  const uncommitted = uncommittedIn(dir);
+  let aheadOf = tryGit(dir, ['rev-parse', '--abbrev-ref', '--symbolic-full-name', '@{upstream}']) ? 'upstream' : null;
+  if (!aheadOf) {
+    const head = tryGit(dir, ['symbolic-ref', '-q', '--short', 'refs/remotes/origin/HEAD']);
+    if (head) aheadOf = head;
+  }
+  const count = aheadOf && tryGit(dir, ['rev-list', '--count', `${aheadOf === 'upstream' ? '@{upstream}' : aheadOf}..HEAD`]);
+  const unpushed = count === null || count === undefined ? null : Number(count);
+  return { repo, branch, checkout: { worktree, uncommitted, unpushed, aheadOf } };
+}
+
+// ---- readers: one per agent, each yielding {agent, dir, title, lastActive(ms)} ----
+function withDb(path, unreadable, use) {
+  if (!existsSync(path)) { if (existsSync(dirname(path))) unreadable.add(tilde(path)); return; }
+  let d;
+  try {
+    d = new DatabaseSync(path, { readOnly: true });
+    use(d);
+  } catch { unreadable.add(tilde(path)); } finally { d?.close(); }
+}
+const readJson = (f, unreadable) => {
+  if (!existsSync(f)) return null;
+  try { return JSON.parse(readFileSync(f, 'utf8')); } catch { unreadable.add(tilde(f)); return null; }
+};
+
+function* claudeCode(since, scanned, unreadable) {
+  const root = join(HOME, '.claude/projects');
+  for (const f of files(root, '**/*.jsonl')) {
+    if (f.includes('/subagents/')) continue;
+    scanned['claude-code']++;
+    if (mtime(f) < since) continue;
+    let dir = null;
+    let last = 0;
+    let custom = null;
+    let ai = null;
+    let summary = null;
+    let text;
+    // A project folder's name is the session's directory, so only the root is named.
+    try { text = readFileSync(f, 'utf8'); } catch { unreadable.add(tilde(root)); continue; }
+    for (const line of text.split('\n')) {
+      if (!line) continue;
+      let r;
+      try { r = JSON.parse(line); } catch { continue; }
+      if (!dir && typeof r.cwd === 'string') dir = r.cwd;
+      const t = Date.parse(r.timestamp);
+      if (t > last) last = t;
+      if (r.type === 'custom-title') custom = r.customTitle;
+      else if (r.type === 'ai-title') ai = r.aiTitle;
+      else if (r.type === 'summary') summary = r.summary;
+    }
+    last ||= mtime(f);
+    if (dir && last >= since) yield { agent: 'claude-code', dir, title: title(custom ?? ai ?? summary), lastActive: last };
+  }
+}
+
+function* codex(since, scanned, unreadable) {
+  const root = codexHome();
+  const seen = new Set();
+  const rows = [];
+  withDb(codexStateDb(), unreadable, (d) => {
+    for (const r of d.prepare('select * from threads').all()) {
+      if (r.archived || r.thread_source === 'subagent') continue;
+      const ms = r.updated_at_ms ?? (r.updated_at > 1e12 ? r.updated_at : r.updated_at * 1000);
+      // `title` is Codex's generated thread name; when it only mirrors the first prompt it is not a title.
+      const t = r.title && r.title !== r.first_user_message ? title(r.title) : null;
+      rows.push({ id: r.id, agent: 'codex', dir: r.cwd, title: t, lastActive: ms });
+    }
+  });
+  for (const r of rows) { seen.add(r.id); scanned.codex++; if (r.lastActive >= since) yield r; }
+  // Rollouts not indexed in the state db (older Codex, or a db that wouldn't open). First line is session_meta.
+  for (const f of files(root, 'sessions/**/*.jsonl')) {
+    const id = f.match(/rollout-.*-([0-9a-f-]{36})\.jsonl$/)?.[1];
+    if (id && seen.has(id)) continue;
+    scanned.codex++;
+    if (mtime(f) < since) continue;
+    let meta;
+    try { meta = JSON.parse(readFileSync(f, 'utf8').split('\n', 1)[0]); } catch { unreadable.add(tilde(f)); continue; }
+    if (meta?.type !== 'session_meta' || typeof meta.payload?.cwd !== 'string') continue;
+    yield { agent: 'codex', dir: meta.payload.cwd, title: null, lastActive: mtime(f) };
+  }
+}
+
+function* openCode(since, scanned, unreadable) {
+  const rows = [];
+  withDb(join(HOME, '.local/share/opencode/opencode.db'), unreadable, (d) => {
+    for (const r of d.prepare('select directory, title, time_updated from session where parent_id is null and time_archived is null').all()) {
+      rows.push({ agent: 'opencode', dir: r.directory, title: title(r.title), lastActive: r.time_updated });
+    }
+  });
+  for (const r of rows) { scanned.opencode++; if (r.lastActive >= since) yield r; }
+}
+
+const CURSOR_USER_DIRS = ['Library/Application Support/Cursor/User', '.config/Cursor/User'];
+function* cursor(since, scanned, unreadable) {
+  // cursor-agent CLI: one dir per chat with meta.json (cwd, times) and store.db (meta row "0": hex JSON with `name`).
+  for (const metaFile of files(join(HOME, '.cursor/chats'), '*/*/meta.json')) {
+    scanned.cursor++;
+    const meta = readJson(metaFile, unreadable);
+    if (!meta || meta.isSubagent || typeof meta.cwd !== 'string') continue;
+    const last = meta.updatedAtMs ?? meta.createdAtMs ?? mtime(metaFile);
+    if (last < since) continue;
+    let name = title(meta.title);
+    if (!name) {
+      withDb(join(dirname(metaFile), 'store.db'), unreadable, (d) => {
+        const v = d.prepare("select value from meta where key = '0'").get()?.value;
+        if (v) name = title(JSON.parse(Buffer.from(String(v), 'hex').toString('utf8')).name);
+      });
+    }
+    yield { agent: 'cursor', dir: meta.cwd, title: name, lastActive: last };
+  }
+  // Cursor IDE: each workspace dir names its folder; its state.vscdb lists the composers (chats) opened there.
+  for (const userDir of CURSOR_USER_DIRS) {
+    const storage = join(HOME, userDir, 'workspaceStorage');
+    if (!existsSync(storage)) continue;
+    for (const ws of readdirSync(storage)) {
+      const folder = readJson(join(storage, ws, 'workspace.json'), unreadable)?.folder;
+      if (typeof folder !== 'string' || !folder.startsWith('file://')) continue;
+      let dir;
+      try { dir = fileURLToPath(folder); } catch { continue; }
+      const composers = [];
+      withDb(join(storage, ws, 'state.vscdb'), unreadable, (d) => {
+        const v = d.prepare("select value from ItemTable where key = 'composer.composerData'").get()?.value;
+        if (v) composers.push(...(JSON.parse(String(v)).allComposers ?? []));
+      });
+      for (const c of composers) {
+        scanned.cursor++;
+        const last = c.lastUpdatedAt ?? c.createdAt;
+        if (last >= since) yield { agent: 'cursor', dir, title: title(c.name), lastActive: last };
+      }
+    }
+  }
+}
+
+// ---- gather: sessions -> work-streams keyed by (repo, branch), or an opaque local index ----
+// A stream keeps one entry per checkout it was worked in (two clones or worktrees can share a branch),
+// in order of first use, and each session names its checkout by index: no directory leaves the file.
+export function gather({ days = 14 } = {}) {
+  const since = Date.now() - days * 86400000;
+  const scanned = Object.fromEntries(AGENTS.map((a) => [a, 0]));
+  const unreadable = new Set();
+  const states = new Map();
+  const streams = new Map();
+  let locals = 0;
+  // A checkout is its work tree's root, so sessions in its subdirectories share it.
+  const roots = new Map();
+  const rootOf = (dir) => {
+    if (!roots.has(dir)) roots.set(dir, existsSync(dir) ? tryGit(dir, ['rev-parse', '--show-toplevel']) || dir : dir);
+    return roots.get(dir);
+  };
+  const stateOf = (root) => {
+    if (!states.has(root)) states.set(root, gitState(root));
+    return states.get(root);
+  };
+  for (const reader of [claudeCode, codex, openCode, cursor]) {
+    for (const s of reader(since, scanned, unreadable)) {
+      const root = rootOf(s.dir);
+      const state = stateOf(root);
+      const key = state.repo && state.branch ? `${state.repo}#${state.branch}` : `dir:${root}`;
+      if (!streams.has(key)) {
+        const local = !(state.repo && state.branch);
+        const head = state.gone ? { gone: true } : { repo: state.repo, branch: state.branch, pr: openPr(state.repo, state.branch, unreadable), checkouts: [] };
+        streams.set(key, { key: local ? `local-${++locals}` : key, ...head, dirs: [], lastActive: 0, sessions: [] });
+      }
+      const stream = streams.get(key);
+      let checkout;
+      if (state.checkout) {
+        checkout = stream.dirs.indexOf(root);
+        if (checkout < 0) {
+          checkout = stream.dirs.push(root) - 1;
+          stream.checkouts.push(state.checkout);
+        }
+      }
+      stream.sessions.push({ agent: s.agent, title: s.title, lastActive: iso(s.lastActive), ...(checkout === undefined ? {} : { checkout }) });
+      if (s.lastActive > stream.lastActive) stream.lastActive = s.lastActive;
+    }
+    log(`${reader.name}: done`);
+  }
+  const out = [...streams.values()].sort((a, b) => b.lastActive - a.lastActive).map(({ dirs, ...s }) => ({
+    ...s,
+    lastActive: iso(s.lastActive),
+    sessions: s.sessions.sort((a, b) => String(b.lastActive).localeCompare(String(a.lastActive))),
+  }));
+  return { days, generatedAt: new Date().toISOString(), scanned, unreadable: [...unreadable].sort(), streams: out };
+}
+
+if (import.meta.url === pathToFileURL(process.argv[1]).href) {
+  const i = process.argv.indexOf('--days');
+  const facts = gather({ days: i > 0 ? Number(process.argv[i + 1]) : 14 });
+  process.stdout.write(`${JSON.stringify(facts)}\n`);
+  log(`${facts.streams.length} streams`);
+}

package/main-instructions.mjs

@@ -1,6 +1,7 @@
 // A bot's system prompt, rendered from the kit's templates. Every section is wrapped in its own
 // tag, in this order: identity, team, execution, engineering, what_reaches_you, reaching_others,
-// writing, role, execution_context (the last one is execution-context.mjs). eve joins a bot's
+// writing, role, execution_context (the last one is execution-context.mjs); main's leaves out
+// engineering, since main never builds. eve joins a bot's
 // instruction sources with a blank line, flat instructions.{md,ts} first, then instructions/*
 // by file name, so the order is made in code: one source renders identity, the shared sections
 // and role together (botInstructions, mainInstructions), and instructions/execution-context.ts
@@ -51,8 +52,8 @@ export function splitRole(text, source = "role file") {
 
 // What eve joins: each source's content with a blank line between, and trims only the whole. So a
 // source ends at its closing tag, with no newline of its own.
-const assemble = ({ identity, role }, additions, options) =>
-  [section("identity", identity), workspaceProtocol(options), section("role", [role, ...additions].join("\n\n"))].join("\n\n");
+const assemble = ({ identity, role }, additions, shared, options) =>
+  [section("identity", identity), sections(shared, options), section("role", [role, ...additions].join("\n\n"))].join("\n\n");
 
 // A bot's own additions to its role: agents/<bot>/agent/role/*.md, by file name, inside <role>.
 // They can't sit in instructions/*.md: eve loads that folder itself, after execution-context.ts,
@@ -70,13 +71,15 @@ function additionsOf(bot, options) {
   return readdirSync(dir).filter((f) => f.endsWith(".md")).sort().map((f) => readFileSync(join(dir, f), "utf8").trim());
 }
 
-export const mainInstructions = (options) => assemble(splitRole(template(HEAD, options), HEAD), additionsOf("main", options), options);
+// Main never builds, so it goes without <engineering>.
+const MAIN_SHARED = SHARED.filter(([tag]) => tag !== ENGINEERING.slice(0, -3));
+export const mainInstructions = (options) => assemble(splitRole(template(HEAD, options), HEAD), additionsOf("main", options), MAIN_SHARED, options);
 
 // Every other bot: agents/<bot>/agent/role.md in the workspace.
 export { ROLE_DIR, ROLE_FILE };
 export function botInstructions(bot, options) {
   const file = join(findWorkspaceRoot(options), "agents", bot, "agent", ROLE_FILE);
-  return assemble(splitRole(readFileSync(file, "utf8"), file), additionsOf(bot, options), options);
+  return assemble(splitRole(readFileSync(file, "utf8"), file), additionsOf(bot, options), SHARED, options);
 }
 
 // The engineering section alone, for a subagent that doesn't carry the shared sections
@@ -85,4 +88,5 @@ export const engineeringPage = (options) => `${section("engineering", template(E
 
 // The shared sections, with no identity or role: what a bot whose instructions.md still holds
 // both gets appended (instructions/protocol.ts).
-export const workspaceProtocol = (options) => SHARED.map(([tag, file]) => section(tag, template(file, options))).join("\n\n");
+const sections = (shared, options) => shared.map(([tag, file]) => section(tag, template(file, options))).join("\n\n");
+export const workspaceProtocol = (options) => sections(SHARED, options);

package/onboarding/SKILL.md

@@ -8,6 +8,12 @@ license: MIT
 
 Two scripts gather facts (GitHub in your sandbox, Slack inside Kit); you write the profile and the schedule drafts from those facts alone. Nothing is posted to Slack and nothing is committed; the only write is the pull request in step 6, which the user approves by merging. The user sees one short message from you at the end (step 7), not one per step. If a step cannot finish, that message says which one and what the user must do; never write the profile as if every source had been read.
 
+## 0. Hand the Mac half to the bot on the Mac
+
+You run on Vercel and can't see the user's Mac. If `list_agents` shows a bot that runs `local`, post one message in this thread before step 1 that mentions it (the first one, if there are several) and asks it to run its local-onboarding skill. Name the workspace repo for its sandbox PR, or say there is none. Then go on with step 1 without waiting: its half arrives in this thread as its own posts.
+
+With no bot that runs `local`, skip this step and say nothing about a Mac.
+
 ## 1. Ask for Kit access, once
 
 Kit's tools are `request_access`, `request_status` and `execute`. Hosted, you reach them through the `vercel-kit` connection: `connection_execute({ connection: "vercel-kit", tool: "request_access", input: { ... } })`, and the same shape for the others. Everywhere below, "call `request_access`" means that.
@@ -119,6 +125,7 @@ Fix every line it prints and rerun until it prints nothing, then post the file's
 - Below it, the two tables, then the lines under them and nothing else:
   - The PR line. Without a repo, it says the drafts stay in the thread. If the PR's checks still fail after step 6, it says so and what failed, in place of "merging it turns them on".
   - One line per source you could not read or Kit grant the user declined: what was not read and what they must do.
+  - If you handed the Mac half over in step 0 and that bot hasn't posted yet, one line: its half hasn't reported yet, and if the Hub app is closed on their Mac, it runs once they open it.
 - Nothing else goes in: not the profile, the "Could not tell" section, counts, windows, or how the run went. Keep `profile.md`, and post it, or the part asked for, only when the user asks.
 
 Only the schedule files ever leave the thread.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "eve-hub",
-  "version": "0.13.5",
+  "version": "0.13.7",
   "license": "Apache-2.0",
   "description": "Bot-side code shared by every hub agent: registry tools, the roster hook, the eve channel, the host sandbox and browser, and model helpers.",
   "type": "module",
@@ -39,6 +39,10 @@
   },
   "dependencies": {
     "ai": "^7.0.137",
-    "jose": "^6.2.3"
+    "jose": "^6.2.3",
+    "jsonc-parser": "3.3.1",
+    "smol-toml": "^1.9.1",
+    "tree-sitter-bash": "0.25.1",
+    "web-tree-sitter": "0.27.1"
   }
 }

package/skills/local-onboarding.d.ts

@@ -0,0 +1,2 @@
+declare const _default: any;
+export default _default;

package/skills/local-onboarding.gen.mjs

@@ -0,0 +1,2 @@
+// Generated by scripts/build-onboarding.mjs from local-onboarding/SKILL.md. Do not edit.
+export default {"description":"The Mac half of onboarding, when main hands it to you: find the owner's live coding-agent work (Claude Code, Codex, OpenCode, Cursor) to port into threads, and propose the sandbox setup their hosted bots need. Reads only; the threads and the sandbox PR wait for the owner's yes.","markdown":"# The Mac half of onboarding\n\nMain runs onboarding on Vercel, where it can't see this Mac, so it hands you this half and posts its own without waiting. You post two short messages in that thread, the live work first, then the sandbox setup. Follow your writing rules: each first bubble is at most two sentences, with tables below a `---` line.\n\nTwo scripts gather the facts. They live in `{{scripts}}`, read only, and print metadata: repos, branches, counts, times, the agents' own session titles and program names. Work only from what they print. Don't open the agents' session files yourself: they hold the owner's prompts and code. Delete the JSON files when you are done.\n\n## 1. Live work to port\n\n```sh\nnode {{scripts}}/sessions-facts.mjs > \"$TMPDIR/sessions.json\"\n```\n\nThe script covers the last 14 days of sessions, grouped into work-streams by repo and branch, newest first. Each stream has:\n- `repo`, `branch` and `pr` (the open PR);\n- `checkouts`: one per clone or worktree it was worked in. Each has `worktree` (true for a linked git worktree), `uncommitted` (changed files) and `unpushed` (commits ahead of `aheadOf`);\n- `lastActive`;\n- `sessions`: each with its agent, title, time and `checkout` (its index in `checkouts`).\n\nA stream with no remote is keyed `local-N`. A stream marked `gone` is a folder that no longer exists. `unreadable` lists the sources that exist but couldn't be read. An `uncommitted` or `unpushed` of `null` means the count couldn't be determined (git timed out on a huge untracked tree, or there is no upstream or default branch to compare against): it is unknown, not zero.\n\nPost the streams that have work in flight: any checkout with uncommitted files or unpushed commits, or an open PR. A checkout with an unknown count gets a row too, with \"unknown\" in that cell. A stream with more than one checkout gets one row per checkout that has work. Put the rest in one line with their count.\n\n```md\nYou have 3 work-streams in flight on this Mac. Say which to port, and main will open a thread for each so the team can pick it up.\n\n---\n\n| Stream | Agent and session | Last active | Uncommitted | Unpushed | PR |\n|---|---|---|---|---|---|\n| `vercel/app` on `fix-login` (worktree) | Claude Code, \"Fix login redirect\" | 2h ago | 4 files | 2 | [#812](...) |\n\nAlso 5 streams with nothing in flight.\n```\n\nNever post a local path, a file name, a prompt, or anything else from the sessions.\n\nWhen the owner says which streams to port, you still write nothing on the Mac. Post one message that mentions main and asks it to open one thread per stream. For each stream, give a short title, the repo and branch, its state (worktree, uncommitted and unpushed counts, PR), and which agent had it. You don't open threads yourself.\n\n## 2. Sandbox setup\n\n```sh\nnode {{scripts}}/agent-usage-facts.mjs > \"$TMPDIR/agent-usage.json\"\n```\n\nIt takes about 30 seconds on 16 GB of history. It prints names and counts, never a command's arguments, a prompt or a value:\n- `scanned`: records, commands and unparsable commands per agent;\n- `unreadable`;\n- `programs`, `mcpServers`, `repos`, `languages` (file extensions) and `envNames`.\n\nMapping each fact to a setup is your judgment, not a lookup table. Decide, for every program in the top 30:\n\n- **Hosted or Mac.** These can't run in a Linux sandbox, so they stay on the Mac with you:\n  - `brew`, `osascript` and `open`;\n  - Xcode, `xcodebuild` and Apple-platform `swift`;\n  - anything that drives the owner's browser or apps;\n  - `localhost` services and the keychain.\n\n  Everything else can be hosted.\n- **Already there, or add it.** A hosted bot's sandbox is eve's Ubuntu image with git only, plus what its `prepare` in `agents/<bot>/agent/sandbox.ts` installs. Read `prepare` in the workspace repo's sandbox files. A program it installs is already provided; any other hosted program needs a `prepare` step. Use `apt-get` where Ubuntu has the package, and the project's official installer otherwise.\n\nMCP servers are reached from hosted bots through Vercel Kit connections: list each one by name for main to connect. Env var names are listed for the owner only. Never print a value (you don't have any). Ignore shell and system names (`PATH`, `HOME`, `CI`, ...). A name with a high `shellAssigned` relative to `count` is probably a shell variable, not part of the environment.\n\nPost the proposal:\n- a first bubble on what the hosted bots would gain;\n- a table of the steps to add, with the programs each installs and how often the owner used them;\n- one line for what stays on the Mac;\n- one line for the MCP servers to connect through Kit.\n\nAsk whether to open the PR.\n\n## 3. The sandbox PR, after the owner's yes\n\nThe steps live in one file, which is the only source; never hand-write them into `sandbox.ts`. Write `$TMPDIR/prepare.json` as `{\"commands\": [{\"command\": \"<shell>\", \"what\": \"<short name for the error>\"}]}`.\n\nMain's handoff names the workspace repo. Clone it into a scratch folder, branch, and add the steps to each hosted bot that runs code. That is the builder, unless the owner said otherwise.\n\n```sh\nnode {{scripts}}/prepare-edit.mjs \"$TMPDIR/prepare.json\" agents/builder/agent/sandbox.ts\n```\n\nCommit, push and open the PR with `gh pr create`. The body lists the programs, why each one is there, and the usage counts behind them. Never name the owner's other repos.\n\nThe PR's Vercel build runs `prepare`, so a step that fails, fails the build. Wait for its result with `gh pr checks --watch --fail-fast`. If it fails, fix the step in `prepare.json`, restore the file from the branch you cut from (`git checkout origin/HEAD -- <file>`), rerun the script and push. Post the PR link and its build result in the thread, then delete the scratch clone.\n"};

package/skills/local-onboarding.js

@@ -0,0 +1,9 @@
+import { dirname, join } from "node:path";
+import { defineSkill } from "eve/skills";
+import { templatesDir } from "../main-instructions.mjs";
+import skill from "./local-onboarding.gen.mjs";
+// The local-onboarding skill: local-onboarding/SKILL.md, embedded at build time
+// (scripts/build-onboarding.mjs). Its scripts run from the installed kit, beside
+// the dependencies agent-usage-facts.mjs imports.
+const scripts = join(dirname(templatesDir()), "local-onboarding");
+export default defineSkill({ ...skill, markdown: skill.markdown.replaceAll("{{scripts}}", scripts) });

package/skills/onboarding-profile.gen.mjs

@@ -1,2 +1,2 @@
 // Generated by scripts/build-onboarding.mjs from onboarding/SKILL.md. Do not edit.
-export default {"description":"Right after sign-in: ask for the Kit access you need, then work out who the user is and what to focus on from their recent Slack and GitHub, and draft schedules that keep them on track. Reads only; the one write is a pull request the user approves by merging.","markdown":"# Profile the user from Slack and GitHub\n\nTwo scripts gather facts (GitHub in your sandbox, Slack inside Kit); you write the profile and the schedule drafts from those facts alone. Nothing is posted to Slack and nothing is committed; the only write is the pull request in step 6, which the user approves by merging. The user sees one short message from you at the end (step 7), not one per step. If a step cannot finish, that message says which one and what the user must do; never write the profile as if every source had been read.\n\n## 1. Ask for Kit access, once\n\nKit's tools are `request_access`, `request_status` and `execute`. Hosted, you reach them through the `vercel-kit` connection: `connection_execute({ connection: \"vercel-kit\", tool: \"request_access\", input: { ... } })`, and the same shape for the others. Everywhere below, \"call `request_access`\" means that.\n\nSlack goes through the user's Kit connection. Before any fetch, ask for everything the run reads in one request:\n\n```\nrequest_access({ service: \"slack\", reads: true, reason: \"Read your recent channel messages, mentions and threads to write your onboarding profile\" })\n```\n\n- `approved`: go on.\n- `pending` (or `connection_required`): tell the user, in one sentence, that Slack access is waiting, with the `approveUrl`; then `request_status({ request })` until they decide. Do not start step 3 before it is approved. If they decline, the final message says the Slack half was not read.\n\nGitHub does not use Kit: it uses `gh` in your sandbox (step 2). If `gh auth status` fails, the final message says GitHub was not read.\n\n## 2. GitHub facts\n\nCall the `onboarding_scripts` tool once: it writes the skill's scripts into your sandbox at `/tmp/onboarding-skill/` and returns that directory.\n\n```sh\nnode /tmp/onboarding-skill/github-facts.mjs > /tmp/onboarding-skill/github-facts.json\n```\n\nIt prints one JSON document: `counts` (merged PRs, open PRs, review requests, assigned issues, mentions never replied to, PRs reviewed), `repos` (merged, reviewed, open and lines changed per repo), item lists (`merged`, `open`, `reviewRequested`, `assignedIssues`, `unansweredMentions`; `total` is the full count, `items` the newest 150), `teams`, and `codeowners` lines naming the user or their teams. Open PRs carry `draft`, `reviewDecision`, `mergeable` and `checks`. `author:@me` includes PRs the user's bots open under their login. `unreadable` lists a source that could not be read.\n\n## 3. Slack facts\n\nRun the script in \"The Slack script\" below with Kit's `execute`: pass it as the script, unchanged. It runs inside Kit, so no raw message reaches you; it returns one JSON document in about 10 seconds.\n\n- A `ratelimited` error means Slack's search limit (about 20 a minute; the script makes at most 19). Wait 70 seconds (`sleep 70`) and run it again unchanged, up to five times.\n- A `suspended` result whose output says `consent_required` is a pause, not an error: tell the user in one sentence that the Slack read is waiting, with its `approveUrl`; `request_status({ request })` until they decide; then `execute({ run })` continues the same run (settled steps are not repeated).\n- An `output` with `refused` means Slack answered `missing_scope` (or another refusal) to a call, so no facts were read: `refused.needed` names the scope the user's Slack connection lacks (`refused.provided` what it has). Do not continue. Call `request_access({ service: \"slack\", capability: \"search_messages\", reason })`: if it returns an `approveUrl`, give it to the user; otherwise tell them to reconnect Slack in Kit allowing `refused.needed`. The final message says the Slack half was not read and names the scope.\n- Any other error goes to the user in the final message. Never continue with fewer facts, and never retry around a refusal.\n- Save the run's `output` as `/tmp/onboarding-skill/slack-facts.json` (the checker reads it).\n- `window`: the last 30 days. Slack search allows 15 pages of 100 here, so a very active account is covered only back to `own.oldest` (`newestOnly: true`); state that window in the profile.\n- `own`: messages per channel, thread replies, recent snippets. `mentions`: `replied` means the user posted later in the same thread; `unanswered` means they did not. A mention older than what was read with no reply among it (`notJudged`) is unknown, not unanswered. `mentions.capped` means the search found more mentions (`searchTotal`) than the three pages read: say so in \"Could not tell\". Reactions are not read (the Slack grant has no `reactions:read`): say so in \"Could not tell\". `memberships`: channels the user is in.\n- DMs and group DMs are never searched. Every list item carries a permalink (`url`); a snippet that looked like a secret is `[withheld]`.\n\n## 4. Write the profile and drafts\n\nWrite the profile to `/tmp/onboarding-skill/profile.md`. It names the user's repos and colleagues, so it is posted only in this thread and never committed.\n\nAnswer, in the user's terms:\n\n- What they have shipped, what they own, what they are responsible for.\n- What people tag them for, and what they write about.\n- What they have missed: unanswered mentions, requested reviews, stale or conflicted PRs.\n- Which open GitHub work-streams to close (stale, conflicted, superseded) and which to focus on.\n\nRules:\n\n- Judge; the scripts only counted. No scoring formula and no thresholds from code: say why in a sentence.\n- Every list item cites at least one permalink that appears in the facts, and no URL appears that isn't in the facts. State counts as the facts give them, with the window.\n- Don't quote messages beyond the snippets, and don't name people beyond what a claim needs.\n- Add a \"Could not tell\" section: every `unreadable` source, `notJudged` mentions, that reactions were not read, the Slack window, a Kit grant the user declined.\n\nFor each recurring need you found (a morning pass over unanswered mentions, a weekly stale-PR pass), write one draft to `/tmp/onboarding-skill/schedules/<bot>/<id>.md` for an existing bot of your workspace:\n\n```md\n---\ncron: \"0 9 * * 1-5\"\n---\n\nThe prompt the bot runs.\n```\n\n`cron` is five fields in UTC on a hosted deploy. Each draft says in its prompt which facts it reads and what it reports.\n\n## 5. Check\n\n```sh\nnode /tmp/onboarding-skill/check-report.mjs --profile /tmp/onboarding-skill/profile.md --facts /tmp/onboarding-skill/github-facts.json /tmp/onboarding-skill/slack-facts.json\n```\n\nFix every line it prints and rerun until it prints nothing. Then delete the two facts files.\n\n## 6. Open the pull request, if the workspace has a repo\n\nWhen the workspace is backed by a GitHub repo, open one PR on it that adds only the schedule drafts, as `agents/<bot>/agent/schedules/<id>.md`, and nothing from the profile (`gh pr create`). The user merging it is their approval; the deploy that follows is what makes the schedules run. The PR's checks include the deploy's build, which rejects a bad cron or a bot that does not exist: watch them (`gh pr checks`), fix the draft and push again until they pass, and say in the message if they do not. Without a repo the drafts stay in the thread and the message says so.\n\n## 7. Post one short message to the user\n\nThe user reads it cold, often only its first line (your writing rules). Write it to `/tmp/onboarding-skill/post.md` in this shape, load the forms skill for the tables, and check it:\n\n```md\nOne line on who they are and what they own, then the one thing to do first.\n\n---\n\n| Act on first | Why | Link |\n|---|---|---|\n(three rows, each linking a permalink from the facts)\n\n| Schedule | Bot | When | What it reports |\n|---|---|---|---|\n(one row per draft)\n\nThe drafts are in [this PR](...): merging it turns them on.\n(one line per source not read or grant declined: what was not read and what to do)\n```\n\n```sh\nnode /tmp/onboarding-skill/check-report.mjs --post /tmp/onboarding-skill/post.md\n```\n\nFix every line it prints and rerun until it prints nothing, then post the file's text in this thread.\n\n- The first bubble, everything above `---`, is at most two sentences.\n- Below it, the two tables, then the lines under them and nothing else:\n  - The PR line. Without a repo, it says the drafts stay in the thread. If the PR's checks still fail after step 6, it says so and what failed, in place of \"merging it turns them on\".\n  - One line per source you could not read or Kit grant the user declined: what was not read and what they must do.\n- Nothing else goes in: not the profile, the \"Could not tell\" section, counts, windows, or how the run went. Keep `profile.md`, and post it, or the part asked for, only when the user asks.\n\nOnly the schedule files ever leave the thread.\n\n## The Slack script\n\n```js\n// Facts about the signed-in user's recent Slack channel activity. Counts, permalinks and short snippets only.\n// Searches exclude DMs and group DMs (-is:dm) so none is ever read. Slack allows about 20 searches a minute: this\n// script makes at most 19, so on a ratelimited error wait a minute and run it again unchanged.\n// The .slice(0, n) before each .map is not redundant: callscript counts worst-case calls from it (200 max).\nconst DAYS = 30;\nconst after = new Date(Date.now() - (DAYS + 1) * 86400000).slice(0, 10);\nconst auth = await slack.auth_test();\nconst me = auth.user_id;\nconst ownPages = await Promise.all([1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15].slice(0, 15).map(page => slack.search_messages({ query: `from:<@${me}> after:${after} -is:dm`, count: 100, page, sort: \"timestamp\", sort_dir: \"desc\" })));\nconst mentionPages = await Promise.all([1, 2, 3].slice(0, 3).map(page => slack.search_messages({ query: `<@${me}> after:${after} -is:dm`, count: 100, page, sort: \"timestamp\", sort_dir: \"desc\" })));\nconst member = await slack.users_conversations({ types: \"public_channel,private_channel\", limit: 200, exclude_archived: true });\nconst refused = [auth, ...ownPages, ...mentionPages, member].filter(r => r.ok === false);\nif (refused.length > 0) {\n  return { refused: { error: refused[0].error, needed: refused[0].needed ?? null, provided: refused[0].provided ?? null, calls: refused.length } };\n}\nconst channels = Object.entries(Object.groupBy(ownPages.flatMap(r => r.messages.matches).filter(m => m.user === me && !m.channel.is_im && !m.channel.is_mpim), m => m.channel.id)).map(e => ({ id: e[0], channel: e[1][0].channel.name, count: e[1].length, threadReplies: e[1].filter(m => m.permalink.includes(\"thread_ts=\") && !m.permalink.includes(`thread_ts=${m.ts}`)).length, oldest: e[1][e[1].length - 1].ts, recent: e[1].slice(0, 2).map(m => ({ url: m.permalink, ts: m.ts, text: m.text.split(\"\\n\").join(\" \").split(\" \").some(t => t.length >= 20 && [\"xoxb-\", \"xoxp-\", \"xoxa-\", \"xoxs-\", \"xoxe\", \"sk-\", \"ghp_\", \"gho_\", \"ghu_\", \"ghs_\", \"ghr_\", \"github_pat_\", \"vck_\", \"AKIA\", \"eyJ\"].some(p => t.includes(p))) ? \"[withheld]\" : m.text.split(\"\\n\").join(\" \").slice(0, 160) })) })).sort((a, b) => b.count - a.count);\nconst total = channels.reduce((n, c) => n + c.count, 0);\nconst threadReplies = channels.reduce((n, c) => n + c.threadReplies, 0);\nconst mentioned = mentionPages.flatMap(r => r.messages.matches).filter(m => m.user !== me && !m.channel.is_im && !m.channel.is_mpim).map(m => ({ url: m.permalink, ts: m.ts, author: m.username, channel: m.channel.id, name: m.channel.name, thread: m.permalink.includes(\"thread_ts=\") ? m.permalink.split(\"thread_ts=\")[1].split(\"&\")[0] : m.ts, text: m.text.split(\"\\n\").join(\" \").split(\" \").some(t => t.length >= 20 && [\"xoxb-\", \"xoxp-\", \"xoxa-\", \"xoxs-\", \"xoxe\", \"sk-\", \"ghp_\", \"gho_\", \"ghu_\", \"ghs_\", \"ghr_\", \"github_pat_\", \"vck_\", \"AKIA\", \"eyJ\"].some(p => t.includes(p))) ? \"[withheld]\" : m.text.split(\"\\n\").join(\" \").slice(0, 160) }));\nconst ownMessages = ownPages.flatMap(r => r.messages.matches).filter(m => m.user === me && !m.channel.is_im && !m.channel.is_mpim);\nconst lastOwn = Object.fromEntries(Object.entries(Object.groupBy(ownMessages, m => `${m.channel.id}:${m.permalink.includes(\"thread_ts=\") ? m.permalink.split(\"thread_ts=\")[1].split(\"&\")[0] : m.ts}`)).map(e => [e[0], e[1].reduce((t, m) => Math.max(t, Number(m.ts)), 0)]));\nconst oldestOwn = channels.length ? channels.reduce((t, c) => Math.min(t, Number(c.oldest)), Number(channels[0].oldest)) : 0;\nconst newestOnly = ownPages[0].messages.paging.pages > ownPages.length;\nconst known = mentioned.map(m => ({ ...m, replied: (lastOwn[`${m.channel}:${m.thread}`] ?? 0) > Number(m.ts) }));\nconst judged = known.filter(m => m.replied || !newestOnly || Number(m.ts) >= oldestOwn);\nconst open = judged.filter(m => !m.replied);\nreturn {\n  me: { id: me, name: auth.user },\n  window: { days: DAYS, after, searchTotal: ownPages[0].messages.paging.total, pagesTotal: ownPages[0].messages.paging.pages, pagesRead: ownPages.length, newestOnly },\n  scope: \"public and private channels; DMs and group DMs are dropped before counting\",\n  own: {\n    total,\n    threadReplies,\n    topLevel: total - threadReplies,\n    oldest: channels.length ? oldestOwn : null,\n    channelCount: channels.length,\n    channels: channels.slice(0, 25).map(c => ({ id: c.id, channel: c.channel, count: c.count, threadReplies: c.threadReplies, recent: c.recent }))\n  },\n  mentions: {\n    searchTotal: mentionPages[0].messages.paging.total,\n    pagesTotal: mentionPages[0].messages.paging.pages,\n    pagesRead: mentionPages.length,\n    capped: mentionPages[0].messages.paging.pages > mentionPages.length,\n    found: mentioned.length,\n    judged: judged.length,\n    notJudged: mentioned.length - judged.length,\n    replied: judged.length - open.length,\n    unanswered: open.length,\n    unansweredItems: open.slice(0, 20).map(m => ({ url: m.url, channel: m.name, author: m.author, ts: m.ts, text: m.text })),\n    basis: \"replied = the user posted later in the same thread; reactions are not read (the token lacks reactions:read); a mention not yet answered in a thread may have been answered elsewhere\"\n  },\n  memberships: { count: member.channels.length, names: member.channels.map(c => c.name).sort(), more: Boolean(member.response_metadata?.next_cursor) }\n};\n```\n"};
+export default {"description":"Right after sign-in: ask for the Kit access you need, then work out who the user is and what to focus on from their recent Slack and GitHub, and draft schedules that keep them on track. Reads only; the one write is a pull request the user approves by merging.","markdown":"# Profile the user from Slack and GitHub\n\nTwo scripts gather facts (GitHub in your sandbox, Slack inside Kit); you write the profile and the schedule drafts from those facts alone. Nothing is posted to Slack and nothing is committed; the only write is the pull request in step 6, which the user approves by merging. The user sees one short message from you at the end (step 7), not one per step. If a step cannot finish, that message says which one and what the user must do; never write the profile as if every source had been read.\n\n## 0. Hand the Mac half to the bot on the Mac\n\nYou run on Vercel and can't see the user's Mac. If `list_agents` shows a bot that runs `local`, post one message in this thread before step 1 that mentions it (the first one, if there are several) and asks it to run its local-onboarding skill. Name the workspace repo for its sandbox PR, or say there is none. Then go on with step 1 without waiting: its half arrives in this thread as its own posts.\n\nWith no bot that runs `local`, skip this step and say nothing about a Mac.\n\n## 1. Ask for Kit access, once\n\nKit's tools are `request_access`, `request_status` and `execute`. Hosted, you reach them through the `vercel-kit` connection: `connection_execute({ connection: \"vercel-kit\", tool: \"request_access\", input: { ... } })`, and the same shape for the others. Everywhere below, \"call `request_access`\" means that.\n\nSlack goes through the user's Kit connection. Before any fetch, ask for everything the run reads in one request:\n\n```\nrequest_access({ service: \"slack\", reads: true, reason: \"Read your recent channel messages, mentions and threads to write your onboarding profile\" })\n```\n\n- `approved`: go on.\n- `pending` (or `connection_required`): tell the user, in one sentence, that Slack access is waiting, with the `approveUrl`; then `request_status({ request })` until they decide. Do not start step 3 before it is approved. If they decline, the final message says the Slack half was not read.\n\nGitHub does not use Kit: it uses `gh` in your sandbox (step 2). If `gh auth status` fails, the final message says GitHub was not read.\n\n## 2. GitHub facts\n\nCall the `onboarding_scripts` tool once: it writes the skill's scripts into your sandbox at `/tmp/onboarding-skill/` and returns that directory.\n\n```sh\nnode /tmp/onboarding-skill/github-facts.mjs > /tmp/onboarding-skill/github-facts.json\n```\n\nIt prints one JSON document: `counts` (merged PRs, open PRs, review requests, assigned issues, mentions never replied to, PRs reviewed), `repos` (merged, reviewed, open and lines changed per repo), item lists (`merged`, `open`, `reviewRequested`, `assignedIssues`, `unansweredMentions`; `total` is the full count, `items` the newest 150), `teams`, and `codeowners` lines naming the user or their teams. Open PRs carry `draft`, `reviewDecision`, `mergeable` and `checks`. `author:@me` includes PRs the user's bots open under their login. `unreadable` lists a source that could not be read.\n\n## 3. Slack facts\n\nRun the script in \"The Slack script\" below with Kit's `execute`: pass it as the script, unchanged. It runs inside Kit, so no raw message reaches you; it returns one JSON document in about 10 seconds.\n\n- A `ratelimited` error means Slack's search limit (about 20 a minute; the script makes at most 19). Wait 70 seconds (`sleep 70`) and run it again unchanged, up to five times.\n- A `suspended` result whose output says `consent_required` is a pause, not an error: tell the user in one sentence that the Slack read is waiting, with its `approveUrl`; `request_status({ request })` until they decide; then `execute({ run })` continues the same run (settled steps are not repeated).\n- An `output` with `refused` means Slack answered `missing_scope` (or another refusal) to a call, so no facts were read: `refused.needed` names the scope the user's Slack connection lacks (`refused.provided` what it has). Do not continue. Call `request_access({ service: \"slack\", capability: \"search_messages\", reason })`: if it returns an `approveUrl`, give it to the user; otherwise tell them to reconnect Slack in Kit allowing `refused.needed`. The final message says the Slack half was not read and names the scope.\n- Any other error goes to the user in the final message. Never continue with fewer facts, and never retry around a refusal.\n- Save the run's `output` as `/tmp/onboarding-skill/slack-facts.json` (the checker reads it).\n- `window`: the last 30 days. Slack search allows 15 pages of 100 here, so a very active account is covered only back to `own.oldest` (`newestOnly: true`); state that window in the profile.\n- `own`: messages per channel, thread replies, recent snippets. `mentions`: `replied` means the user posted later in the same thread; `unanswered` means they did not. A mention older than what was read with no reply among it (`notJudged`) is unknown, not unanswered. `mentions.capped` means the search found more mentions (`searchTotal`) than the three pages read: say so in \"Could not tell\". Reactions are not read (the Slack grant has no `reactions:read`): say so in \"Could not tell\". `memberships`: channels the user is in.\n- DMs and group DMs are never searched. Every list item carries a permalink (`url`); a snippet that looked like a secret is `[withheld]`.\n\n## 4. Write the profile and drafts\n\nWrite the profile to `/tmp/onboarding-skill/profile.md`. It names the user's repos and colleagues, so it is posted only in this thread and never committed.\n\nAnswer, in the user's terms:\n\n- What they have shipped, what they own, what they are responsible for.\n- What people tag them for, and what they write about.\n- What they have missed: unanswered mentions, requested reviews, stale or conflicted PRs.\n- Which open GitHub work-streams to close (stale, conflicted, superseded) and which to focus on.\n\nRules:\n\n- Judge; the scripts only counted. No scoring formula and no thresholds from code: say why in a sentence.\n- Every list item cites at least one permalink that appears in the facts, and no URL appears that isn't in the facts. State counts as the facts give them, with the window.\n- Don't quote messages beyond the snippets, and don't name people beyond what a claim needs.\n- Add a \"Could not tell\" section: every `unreadable` source, `notJudged` mentions, that reactions were not read, the Slack window, a Kit grant the user declined.\n\nFor each recurring need you found (a morning pass over unanswered mentions, a weekly stale-PR pass), write one draft to `/tmp/onboarding-skill/schedules/<bot>/<id>.md` for an existing bot of your workspace:\n\n```md\n---\ncron: \"0 9 * * 1-5\"\n---\n\nThe prompt the bot runs.\n```\n\n`cron` is five fields in UTC on a hosted deploy. Each draft says in its prompt which facts it reads and what it reports.\n\n## 5. Check\n\n```sh\nnode /tmp/onboarding-skill/check-report.mjs --profile /tmp/onboarding-skill/profile.md --facts /tmp/onboarding-skill/github-facts.json /tmp/onboarding-skill/slack-facts.json\n```\n\nFix every line it prints and rerun until it prints nothing. Then delete the two facts files.\n\n## 6. Open the pull request, if the workspace has a repo\n\nWhen the workspace is backed by a GitHub repo, open one PR on it that adds only the schedule drafts, as `agents/<bot>/agent/schedules/<id>.md`, and nothing from the profile (`gh pr create`). The user merging it is their approval; the deploy that follows is what makes the schedules run. The PR's checks include the deploy's build, which rejects a bad cron or a bot that does not exist: watch them (`gh pr checks`), fix the draft and push again until they pass, and say in the message if they do not. Without a repo the drafts stay in the thread and the message says so.\n\n## 7. Post one short message to the user\n\nThe user reads it cold, often only its first line (your writing rules). Write it to `/tmp/onboarding-skill/post.md` in this shape, load the forms skill for the tables, and check it:\n\n```md\nOne line on who they are and what they own, then the one thing to do first.\n\n---\n\n| Act on first | Why | Link |\n|---|---|---|\n(three rows, each linking a permalink from the facts)\n\n| Schedule | Bot | When | What it reports |\n|---|---|---|---|\n(one row per draft)\n\nThe drafts are in [this PR](...): merging it turns them on.\n(one line per source not read or grant declined: what was not read and what to do)\n```\n\n```sh\nnode /tmp/onboarding-skill/check-report.mjs --post /tmp/onboarding-skill/post.md\n```\n\nFix every line it prints and rerun until it prints nothing, then post the file's text in this thread.\n\n- The first bubble, everything above `---`, is at most two sentences.\n- Below it, the two tables, then the lines under them and nothing else:\n  - The PR line. Without a repo, it says the drafts stay in the thread. If the PR's checks still fail after step 6, it says so and what failed, in place of \"merging it turns them on\".\n  - One line per source you could not read or Kit grant the user declined: what was not read and what they must do.\n  - If you handed the Mac half over in step 0 and that bot hasn't posted yet, one line: its half hasn't reported yet, and if the Hub app is closed on their Mac, it runs once they open it.\n- Nothing else goes in: not the profile, the \"Could not tell\" section, counts, windows, or how the run went. Keep `profile.md`, and post it, or the part asked for, only when the user asks.\n\nOnly the schedule files ever leave the thread.\n\n## The Slack script\n\n```js\n// Facts about the signed-in user's recent Slack channel activity. Counts, permalinks and short snippets only.\n// Searches exclude DMs and group DMs (-is:dm) so none is ever read. Slack allows about 20 searches a minute: this\n// script makes at most 19, so on a ratelimited error wait a minute and run it again unchanged.\n// The .slice(0, n) before each .map is not redundant: callscript counts worst-case calls from it (200 max).\nconst DAYS = 30;\nconst after = new Date(Date.now() - (DAYS + 1) * 86400000).slice(0, 10);\nconst auth = await slack.auth_test();\nconst me = auth.user_id;\nconst ownPages = await Promise.all([1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15].slice(0, 15).map(page => slack.search_messages({ query: `from:<@${me}> after:${after} -is:dm`, count: 100, page, sort: \"timestamp\", sort_dir: \"desc\" })));\nconst mentionPages = await Promise.all([1, 2, 3].slice(0, 3).map(page => slack.search_messages({ query: `<@${me}> after:${after} -is:dm`, count: 100, page, sort: \"timestamp\", sort_dir: \"desc\" })));\nconst member = await slack.users_conversations({ types: \"public_channel,private_channel\", limit: 200, exclude_archived: true });\nconst refused = [auth, ...ownPages, ...mentionPages, member].filter(r => r.ok === false);\nif (refused.length > 0) {\n  return { refused: { error: refused[0].error, needed: refused[0].needed ?? null, provided: refused[0].provided ?? null, calls: refused.length } };\n}\nconst channels = Object.entries(Object.groupBy(ownPages.flatMap(r => r.messages.matches).filter(m => m.user === me && !m.channel.is_im && !m.channel.is_mpim), m => m.channel.id)).map(e => ({ id: e[0], channel: e[1][0].channel.name, count: e[1].length, threadReplies: e[1].filter(m => m.permalink.includes(\"thread_ts=\") && !m.permalink.includes(`thread_ts=${m.ts}`)).length, oldest: e[1][e[1].length - 1].ts, recent: e[1].slice(0, 2).map(m => ({ url: m.permalink, ts: m.ts, text: m.text.split(\"\\n\").join(\" \").split(\" \").some(t => t.length >= 20 && [\"xoxb-\", \"xoxp-\", \"xoxa-\", \"xoxs-\", \"xoxe\", \"sk-\", \"ghp_\", \"gho_\", \"ghu_\", \"ghs_\", \"ghr_\", \"github_pat_\", \"vck_\", \"AKIA\", \"eyJ\"].some(p => t.includes(p))) ? \"[withheld]\" : m.text.split(\"\\n\").join(\" \").slice(0, 160) })) })).sort((a, b) => b.count - a.count);\nconst total = channels.reduce((n, c) => n + c.count, 0);\nconst threadReplies = channels.reduce((n, c) => n + c.threadReplies, 0);\nconst mentioned = mentionPages.flatMap(r => r.messages.matches).filter(m => m.user !== me && !m.channel.is_im && !m.channel.is_mpim).map(m => ({ url: m.permalink, ts: m.ts, author: m.username, channel: m.channel.id, name: m.channel.name, thread: m.permalink.includes(\"thread_ts=\") ? m.permalink.split(\"thread_ts=\")[1].split(\"&\")[0] : m.ts, text: m.text.split(\"\\n\").join(\" \").split(\" \").some(t => t.length >= 20 && [\"xoxb-\", \"xoxp-\", \"xoxa-\", \"xoxs-\", \"xoxe\", \"sk-\", \"ghp_\", \"gho_\", \"ghu_\", \"ghs_\", \"ghr_\", \"github_pat_\", \"vck_\", \"AKIA\", \"eyJ\"].some(p => t.includes(p))) ? \"[withheld]\" : m.text.split(\"\\n\").join(\" \").slice(0, 160) }));\nconst ownMessages = ownPages.flatMap(r => r.messages.matches).filter(m => m.user === me && !m.channel.is_im && !m.channel.is_mpim);\nconst lastOwn = Object.fromEntries(Object.entries(Object.groupBy(ownMessages, m => `${m.channel.id}:${m.permalink.includes(\"thread_ts=\") ? m.permalink.split(\"thread_ts=\")[1].split(\"&\")[0] : m.ts}`)).map(e => [e[0], e[1].reduce((t, m) => Math.max(t, Number(m.ts)), 0)]));\nconst oldestOwn = channels.length ? channels.reduce((t, c) => Math.min(t, Number(c.oldest)), Number(channels[0].oldest)) : 0;\nconst newestOnly = ownPages[0].messages.paging.pages > ownPages.length;\nconst known = mentioned.map(m => ({ ...m, replied: (lastOwn[`${m.channel}:${m.thread}`] ?? 0) > Number(m.ts) }));\nconst judged = known.filter(m => m.replied || !newestOnly || Number(m.ts) >= oldestOwn);\nconst open = judged.filter(m => !m.replied);\nreturn {\n  me: { id: me, name: auth.user },\n  window: { days: DAYS, after, searchTotal: ownPages[0].messages.paging.total, pagesTotal: ownPages[0].messages.paging.pages, pagesRead: ownPages.length, newestOnly },\n  scope: \"public and private channels; DMs and group DMs are dropped before counting\",\n  own: {\n    total,\n    threadReplies,\n    topLevel: total - threadReplies,\n    oldest: channels.length ? oldestOwn : null,\n    channelCount: channels.length,\n    channels: channels.slice(0, 25).map(c => ({ id: c.id, channel: c.channel, count: c.count, threadReplies: c.threadReplies, recent: c.recent }))\n  },\n  mentions: {\n    searchTotal: mentionPages[0].messages.paging.total,\n    pagesTotal: mentionPages[0].messages.paging.pages,\n    pagesRead: mentionPages.length,\n    capped: mentionPages[0].messages.paging.pages > mentionPages.length,\n    found: mentioned.length,\n    judged: judged.length,\n    notJudged: mentioned.length - judged.length,\n    replied: judged.length - open.length,\n    unanswered: open.length,\n    unansweredItems: open.slice(0, 20).map(m => ({ url: m.url, channel: m.name, author: m.author, ts: m.ts, text: m.text })),\n    basis: \"replied = the user posted later in the same thread; reactions are not read (the token lacks reactions:read); a mention not yet answered in a thread may have been answered elsewhere\"\n  },\n  memberships: { count: member.channels.length, names: member.channels.map(c => c.name).sort(), more: Boolean(member.response_metadata?.next_cursor) }\n};\n```\n"};

package/stubs.mjs

@@ -18,6 +18,7 @@ export const KIT_FILES = {
   "tools/list_agents.ts": ["The team right now: kind, place, tools, models, who's busy."],
   "tools/post_message.ts": ["Post into an existing thread or a bot's DM; with `status`, report the thread's phase."],
   "skills/forms.ts": ["The forms skill (packages/agent-kit/forms/SKILL.md): how to draw a flow, sequence, chart or ask the app renders."],
+  "skills/local-onboarding.ts": ["The local-onboarding skill (packages/agent-kit/local-onboarding/SKILL.md): the Mac half of onboarding, the live work to port and the sandbox setup."],
 };
 
 // main, the orchestrator: the shared files (the same channel as every bot),

package/team.mjs

@@ -66,7 +66,7 @@ export function teamModel({ agents, humans = [], tools = {} }) {
 
 // fixed text: what each kind owns, never does, and why
 const KIND_TEXT = {
-  coordinator: { owns: "the human's ask end to end: scopes it, opens one thread per unit of work, routes it, and keeps it from stalling", never: "builds or reviews, because a coordinator inside one task stops watching the others" },
+  coordinator: { owns: "the human's ask end to end, as their chief of staff: scopes it, routes it to the bot that fits, clears what blocks it and drives it to done", never: "builds or reviews, because a coordinator inside one task stops watching the others" },
   planner: { owns: "the brief: research, the plan, the real-path test, the deploy boundary", never: "builds, because a plan written to fit code already written stops being a check on it" },
   builder: { owns: "its branch, from first push to landing: building, proving it on the real path, fixing review findings, and landing once the human approves", never: "reviews its own work or merges without the human's approval, because the author is the worst judge of their own change" },
   reviewer: { owns: "the verdict: whether the change is the right one, not only whether it matches its plan", never: "edits, pushes or merges the change under review, because a reviewer who fixes it stops being an independent check" },

package/templates/execution-context-hosted-main.md

@@ -1,3 +1,3 @@
 - **Team.** `create_agent` takes `runsOn` (`hosted` or `local`) and commits the new bot to the workspace repository; it joins with the next deployment, and a `local` bot then runs on the owner's Mac. `remove_agent` commits the bot's removal to the same repository (its files and roster entry, nothing else), and the bot goes with the next deployment, when its DM and schedule threads are archived. If nobody on the team covers the work well, ask the human before going on.
 - **Memory.** Add an entry as your Memory section says, by committing the file to the workspace repository (see Changing it above). With no repository, write nothing and tell the human to link one first.
-- **Schedules.** Your `dash` schedule runs every 8 minutes: it classifies the threads that changed into the Dash and rewrites track summaries that have news, without PR data (a function has no `gh`). `compact` is deployed but finds nothing to compact until hosted sessions record their last model call. `prune` is not deployed: it cleans the hub machine's disk.
+- **Schedules.** Your `dash` schedule runs every 8 minutes: it classifies the threads that changed into the Dash and rewrites track summaries that have news, without PR data (a function has no `gh`).

package/templates/main-instructions.md

@@ -1,20 +1,14 @@
-You are **main**, the human's long-lived partner and the team's coordinator. The human talks to you first. You own each ask end to end: scope it, open one thread per unit of work, hand it to the bot whose role fits, and keep it from stalling until it lands. You don't do a thread's work yourself, because a coordinator inside one task stops watching the others; answer directly only quick questions you can settle from what you already know.
+You are **main**, the human's chief of staff. The human talks to you first, and you make sure what they ask for gets done. You scope it, put the right bot on it, and stay on it across turns and threads until it lands. A quick question you can settle from what you already know ("where is X?") you answer directly, without opening a thread. You are relentless. You work long stretches without being prodded. When something blocks a bot (a missing grant, an answer only the human has, a bot going in circles), you clear it yourself, put the right bot on it, or get it from the one person who can. Every turn, you look for the next step that moves something forward. You work between the bots that do the work, never as one of them: you don't build or review, because a chief of staff inside one task stops watching the others.
 
-**Route by fit.** Send each piece of work straight to the bot whose role fits it; there is no fixed pipeline. Plan first only when the scope is unclear, the parts are many or the risk is real: then the planner. A clear fix, a bug or a small change goes straight to a builder of that kind. A bot busy in another thread can still start here now, so route to the best fit; between two equal fits, pick the idle one.
+**Take the ask.** First look for an open thread on the same work (`list_threads`) and continue there. Otherwise, `create_thread` with a `path` and an `issueType` already in use. A path is `project/track`: reuse the area's path, and start a new one only for a new effort, named for the feature. The thread's first message mentions only the bot who starts. It gives the goal, the constraints, what done looks like, and "validate with the human" when the scope needs their yes. Building waits for that yes. Route by fit: unclear scope, many parts or real risk go to the planner, and a clear, small change goes straight to a builder of that kind. A thread the human starts reaches you untitled: file it with one `update_thread`, then route it inside that thread. Tell the human in one or two lines what you opened and who's on it.
 
-**Opening work.**
-- Before opening a thread, look for an open one on the same work (`list_threads`) and continue there.
-- Every thread sits on a **path**, `project/track` (e.g. `web/checkout/cart`): the project, then the feature or effort inside it, which spans many threads and PRs. Reuse the path for the thread's area; start a new one only for a new effort, named for the feature, never the task. Merge near-duplicates with `move_path`. A path the human set by hand stays.
-- `create_thread` takes the `path` and an `issueType` (reuse the ones in use). Its first message mentions only the bot who starts, with the goal, the constraints, what done looks like, and "validate with the human" when sign-off is needed. Don't prescribe who comes after; bots hand off by role.
-- When the human starts a thread themselves, it reaches you untitled and already is the work: file it with one `update_thread` (title, path, issue type, summary), then route it inside that thread.
-- Then tell the human in 1–3 lines what you opened and who's on it.
+**Drive it to done.** Every turn, look for what is stalled and what you can move:
+- **A bot is waiting on a grant, an answer or another bot:** get it what it needs.
+- **A PR has had no push or verdict for an hour:** steer its bot with narrower instructions (`post_message` with `policy: "steer"`, or `"abort"` to replace its turn), or hand the PR to an idle builder of the same kind.
+- **Something needs the human:** bring them only the decision, in one line with your recommendation, and act on everything else.
+- **Cross-thread chores (merge, rebase, close out, restart):** post in each owning thread to the bot that built it. Never collect them into one bot or your own session.
+- **A builder reports a merge sha:** archive the thread (`archive_thread`) in that turn.
 
-**Summaries.** Your `dash` schedule keeps track summaries current. Give a thread a summary (`set_summary`, `thread:<id>`) once its opening ask no longer describes it. In a track chat (a thread the human opens from a track page to ask about it), answer from the track's threads, PRs and summary; when a question turns into work, post it in the thread that owns it or open one, and link it.
+**Keep the workspace legible.** Give a thread a summary (`set_summary`) once its opening ask no longer describes it. Keep tags tidy with `tag_threads` and `apply_tags`, and say in one line what changed. On the Dash, the hub sets ready, and a deferral the human made stays. Tags and paths the human set stay too. In a track chat, answer from that track's threads, PRs and summary, and post new work in the thread that owns it.
 
-**Keep work moving.** On every Dash tick, check open PRs and bots waiting on tasks. A PR with no push or verdict for an hour while its owner waits: steer that bot with narrower instructions (`post_message` with `policy: "steer"`, or `"abort"` to replace its turn), or hand the PR to an idle builder of the same kind, and tell the human in one line. Cross-thread chores (merge, rebase, close out, restart) fan out: post in each owning thread and mention the bot that built it, because the owner lands its own branch; never collect several threads' work into one bot or your own session. When a builder reports a merge sha for approved work, archive the thread (`archive_thread`) in that turn.
-
-**The Dash** is the human's view of open threads in four lanes: needs-you (theirs to act or decide), ready (set by the hub when the reviewer's latest verdict is ship at the current head; you can't write it), running, and fyi. Never undo a deferral the human made. The Dash only reports: it never nudges bots, merges or posts.
-
-**Tags.** Thread tags group the human's sidebar, and keeping them tidy is yours: retag a thread whose tag no longer fits what it's doing, merge near-duplicates and one-offs, and name any tag that reads wrong title-cased. Read what threads actually did (`tag_threads` vocabulary, `read_thread`), then `apply_tags`; say in a line what changed. Stage a big pass with `tag_threads` propose only when the human asked to review it first. Tags the human set stay unless they ask.
-
-**Memory.** When the human states a preference that should outlast the task, write it as an entry in the workspace repo: `memory/<id>.md` for every bot (naming no bot), or `agents/<bot>/memory/<id>.md` for one. Front matter `id`, `status: active`, `since`, `evidence` (`[thr_…/msg_…]`), then the rule in at most 3 lines. A replaced entry gets `status: superseded` and `superseded_by`, never a rewrite. Keep `memory/human.md` (who the human is and how they work) current the same way.
+**Memory.** A preference that should outlast the task becomes `memory/<id>.md` (every bot) or `agents/<bot>/memory/<id>.md` (one bot). It has front matter `id`, `status: active`, `since` and `evidence` (`[thr_…/msg_…]`), then the rule in at most 3 lines. A replaced entry gets `status: superseded` and `superseded_by`, never a rewrite. Keep `memory/human.md` (who the human is and how they work) current the same way.