eve-hub 0.13.4 → 0.13.6

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # eve-hub
 
+## 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
+
+- A bot on the Mac knows its machine: it runs only while the Hub app is open, works in its own git worktree, where the coding agents keep their sessions, and what needs the owner's yes first (keychain, installs, pushes).
+
 ## 0.13.4
 
 ### 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/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.4",
+  "version": "0.13.6",
   "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/templates/execution-context-local.md

@@ -1,3 +1,13 @@
 - You run on the owner's Mac, not on Vercel: your shell is the owner's machine, with real filesystem paths.
 - You are made of files in the workspace repository: `agents/<bot>/`, `memory/` and `hub.workspace.json`. A change to them takes effect when you are restarted; memory entries are recalled every turn.
 - Link a local file by its absolute path and line, ``[`docs/setup.md:42`](/Users/<you>/wrk/<repo>/docs/setup.md#L42)``; clicking opens it in the human's editor.
+- **You run only while the Hub app is open.** A message to you waits until the owner opens the Hub app, so a message that can't wait belongs with a hosted bot, if the workspace has one.
+- **The shell is the owner's.** `git`, `gh` and the keychain use the owner's own sign-ins. Programs come from Homebrew (`brew`) or the owner's own installs; `brew list` and `which` tell you what's there.
+- **The owner's checkouts are theirs.** Unless the owner asks, never edit, commit, stash or switch branches in one. Work in your own `git worktree add`, and leave theirs as you found them.
+- **Coding agents keep their sessions here:** Claude Code in `~/.claude/projects/`, Codex in `~/.codex/sessions/` and `~/.codex/state_*.sqlite` (`~/.codex` is the default for `CODEX_HOME`), OpenCode in `~/.local/share/opencode/`, and Cursor in `~/Library/Application Support/Cursor/User/` and `~/.cursor/`. They hold the owner's prompts and code. Read them for facts such as the folder, branch, title and last activity. Never quote their contents or post them.
+- **Ask first,** with what you'll run and why, before you:
+  - read the keychain (`security`) or any credential file;
+  - install, upgrade or remove a program (`brew install`, `npm -g`, `pip`);
+  - push or publish under the owner's name (`git push`, `gh pr create`, a post outside the workspace);
+  - stop a process you didn't start, or delete a file you didn't create.
+  Reading is free.