lazyclaw 6.3.0 → 6.4.0

package/sandbox/spawn.mjs

@@ -0,0 +1,144 @@
+// sandbox/spawn.mjs — unified spawn dispatcher + auto-confiner.
+//
+// Bridges the docker-spec shim (used by mas/tools/bash.mjs and
+// providers/{claude,codex,gemini}_cli.mjs via sandbox.mjs) with the v5
+// confiner backend. Today only docker specs and null are handled by the
+// docker.mjs spawnSandboxed; this module adds {kind:'local', confiner:...}
+// support by wrapping the child argv via a confiner module.
+//
+// CAPABILITY-ONLY: no caller passes a local spec yet, so null and docker
+// paths are byte-identical to docker.mjs's spawnSandboxed and there is zero
+// behaviour change. The default-OFF posture is unchanged.
+
+import { spawn, spawnSync } from 'node:child_process';
+import { buildDockerArgs } from './docker.mjs';
+import { SandboxError } from './base.mjs';
+import * as seatbelt from './confiners/seatbelt.mjs';
+import * as bubblewrap from './confiners/bubblewrap.mjs';
+import * as firejail from './confiners/firejail.mjs';
+import * as landlock from './confiners/landlock.mjs';
+
+const CONFINERS = { seatbelt, bubblewrap, firejail, landlock };
+
+// Process-wide memo of the real-probe result, keyed by platform. Auto-confiner
+// selection sits on a hot path (every confined child spawn), so we avoid
+// repeated execFileSync probes. The memo is bypassed when an explicit `avail`
+// override is supplied (tests need a fresh evaluation per call).
+const _probeMemo = new Map();
+
+/**
+ * Pick the best available confiner for a platform.
+ *
+ * @param {{platform?: string, avail?: {seatbelt?: boolean, bubblewrap?: boolean, firejail?: boolean}}} [opts]
+ * @returns {'seatbelt'|'bubblewrap'|'firejail'|'none'}
+ *   Never returns 'landlock' — it is fail-closed (available() === false).
+ */
+export function pickAvailableConfiner({ platform = process.platform, avail } = {}) {
+  const probe = avail
+    ? () => avail
+    : () => _probeAvailability(platform);
+  const a = probe();
+  if (platform === 'darwin') {
+    return a.seatbelt ? 'seatbelt' : 'none';
+  }
+  if (platform === 'linux') {
+    if (a.bubblewrap) return 'bubblewrap';
+    if (a.firejail) return 'firejail';
+    return 'none';
+  }
+  return 'none';
+}
+
+function _probeAvailability(platform) {
+  if (_probeMemo.has(platform)) return _probeMemo.get(platform);
+  const a = {
+    seatbelt: seatbelt.available({ platform }),
+    bubblewrap: bubblewrap.available(),
+    firejail: firejail.available(),
+  };
+  _probeMemo.set(platform, a);
+  return a;
+}
+
+/**
+ * Build the WRAPPED argv for a {kind:'local'} spec WITHOUT spawning, so it is
+ * unit-testable.
+ *
+ * @param {{kind:'local', confiner?: string} & Record<string, unknown>} spec
+ * @param {string} bin
+ * @param {string[]} args
+ * @returns {string[]} the wrapped argv ([bin, ...args] when confiner is none)
+ */
+export function buildLocalArgv(spec, bin, args) {
+  const requested = spec.confiner === 'auto'
+    ? pickAvailableConfiner()
+    : (spec.confiner || 'none');
+  if (requested === 'none') return [bin, ...args];
+  const mod = CONFINERS[requested];
+  if (!mod) {
+    throw new SandboxError(`unknown confiner "${requested}"`, 'SANDBOX_BAD_CONFINER');
+  }
+  // landlock is fail-closed: its buildArgv throws. Do NOT special-case it.
+  return mod.buildArgv([bin, ...args], spec);
+}
+
+/**
+ * Spawn a child under the requested sandbox spec.
+ *
+ *  - null          → bare spawn (byte-identical to docker.mjs today)
+ *  - kind 'docker' → spawn('docker', buildDockerArgs(...)) (byte-identical)
+ *  - kind 'local'  → wrap argv via confiner, then spawn the wrapper
+ *  - anything else → SANDBOX_UNSUPPORTED
+ *
+ * @param {object|null} spec
+ * @param {string} bin
+ * @param {string[]} args
+ * @param {object} [spawnOpts]
+ * @returns {import('node:child_process').ChildProcess}
+ */
+export function spawnSandboxed(spec, bin, args, spawnOpts = {}) {
+  if (!spec) return spawn(bin, args, spawnOpts);
+  if (spec.kind === 'docker') {
+    const dockerArgs = buildDockerArgs(spec, [bin, ...args], { cwd: spawnOpts.cwd });
+    return spawn('docker', dockerArgs, spawnOpts);
+  }
+  if (spec.kind === 'local') {
+    const wrapped = buildLocalArgv(spec, bin, args);
+    return spawn(wrapped[0], wrapped.slice(1), spawnOpts);
+  }
+  throw new SandboxError(
+    `spawnSandboxed shim handles docker+local only; got "${spec.kind}"`,
+    'SANDBOX_UNSUPPORTED',
+  );
+}
+
+/**
+ * Synchronous mirror of {@link spawnSandboxed} for callers that shell out via
+ * spawnSync (e.g. mas/tools/git.mjs). Same kind handling, just sync:
+ *
+ *  - null          → bare spawnSync (byte-identical to a plain spawnSync)
+ *  - kind 'docker' → spawnSync('docker', buildDockerArgs(...)) (byte-identical)
+ *  - kind 'local'  → wrap argv via confiner, then spawnSync the wrapper
+ *  - anything else → SANDBOX_UNSUPPORTED
+ *
+ * @param {object|null} spec
+ * @param {string} bin
+ * @param {string[]} args
+ * @param {object} [spawnOpts]
+ * @returns {import('node:child_process').SpawnSyncReturns<string>}
+ */
+export function spawnSyncSandboxed(spec, bin, args, spawnOpts = {}) {
+  if (!spec) return spawnSync(bin, args, spawnOpts);
+  if (spec.kind === 'docker') {
+    const dockerArgs = buildDockerArgs(spec, [bin, ...args], { cwd: spawnOpts.cwd });
+    return spawnSync('docker', dockerArgs, spawnOpts);
+  }
+  if (spec.kind === 'local') {
+    const wrapped = buildLocalArgv(spec, bin, args);
+    return spawnSync(wrapped[0], wrapped.slice(1), spawnOpts);
+  }
+  throw new SandboxError(
+    `spawnSyncSandboxed shim handles docker+local only; got "${spec.kind}"`,
+    'SANDBOX_UNSUPPORTED',
+  );
+}

package/sandbox.mjs

@@ -6,6 +6,10 @@
 export {
   parseSandboxSpec,
   buildDockerArgs,
-  spawnSandboxed,
 } from './sandbox/docker.mjs';
+// spawnSandboxed now comes from the unified dispatcher, which adds
+// {kind:'local'} confiner support on top of the byte-identical null/docker
+// paths. bash.mjs + the 3 CLI providers import it via this shim, so they
+// transparently get the upgraded dispatcher.
+export { spawnSandboxed, spawnSyncSandboxed } from './sandbox/spawn.mjs';
 export { SandboxError } from './sandbox/base.mjs';

package/scripts/loop-worker.mjs

@@ -64,10 +64,15 @@ const sessions = await import(path.join(REPO_ROOT, 'sessions.mjs'));
 const loopEngine = await import(path.join(REPO_ROOT, 'loop-engine.mjs'));
 const registryUrl = path.join(REPO_ROOT, 'providers', 'registry.mjs');
 const { PROVIDERS } = await import(registryUrl);
+const { readConfig, _resolveAuthKey } = await import(path.join(REPO_ROOT, 'lib', 'config.mjs'));
 
 const cfgDir = process.env.LAZYCLAW_CONFIG_DIR || loops.defaultConfigDir();
 const sessionId = args['session-existing'] || `loop:${loopId}`;
 
+// Resolve the auth key the SAME way the foreground loop does — the worker used
+// process.env.LAZYCLAW_API_KEY||'' and so failed auth against anthropic/openai.
+const cfg = readConfig();
+
 const provName = args.provider || 'mock';
 const prov = PROVIDERS[provName];
 if (!prov) {
@@ -111,7 +116,7 @@ async function sendOnce(messages, signal) {
   }
   let acc = '';
   for await (const chunk of prov.sendMessage(messages, {
-    apiKey: process.env.LAZYCLAW_API_KEY || '',
+    apiKey: _resolveAuthKey(cfg, provName),
     model: args.model,
     signal,
   })) {
@@ -144,6 +149,24 @@ const onIteration = ({ i, max: m, reply }) => {
   }, cfgDir);
 };
 
+// Honour --use-memory / --recall exactly like the foreground loop: rebuild a
+// system message from core/recall memory before each iteration. The detach
+// path forwards the flags now (buildDetachArgv); without this the worker would
+// see them and still ignore them.
+const memMod = (args['use-memory'] || args.recall) ? await import(path.join(REPO_ROOT, 'memory.mjs')) : null;
+const buildSystem = memMod ? (() => {
+  const parts = [];
+  if (args['use-memory']) {
+    const core = memMod.loadCore(cfgDir);
+    if (core && core.trim()) parts.push(core);
+  }
+  if (args.recall) {
+    const text = memMod.recall(String(args.recall), { topN: 3 }, cfgDir);
+    if (text && text.trim()) parts.push(text);
+  }
+  return parts.join('\n\n---\n\n');
+}) : null;
+
 try {
   const result = await loopEngine.runLoop({
     prompt: args.prompt || '',
@@ -154,6 +177,7 @@ try {
     persist,
     onIteration,
     signal: ac.signal,
+    buildSystem,
   });
   if (!terminating) {
     const finalStatus = result.stoppedBy === 'abort' ? 'killed' : 'completed';

package/skills/channel-style.md

@@ -0,0 +1,20 @@
+---
+description: Format replies for messaging channels (Slack, Telegram, Discord). Short messages, no heavy markdown, mobile-readable.
+created_by: starter
+version: 1
+---
+
+# Channel-friendly formatting
+
+Your reply will be read in a chat app (Slack, Telegram, Discord, Matrix), often on a phone. Format for that surface, not for a terminal or a wiki.
+
+## Rules
+
+- Keep messages short: lead with the answer, aim under ~120 words. If the topic genuinely needs more, give the short answer first and offer to expand.
+- No `#` headings and no horizontal rules — most chat apps render them as literal text or oversized noise. Use **bold** for the one key phrase instead.
+- Bullets: at most one level deep, 5-6 items max. Numbered lists only for true sequences.
+- Code: inline backticks for identifiers, fenced blocks only for runnable snippets ≤15 lines. Longer code → summarize what it does and offer the full version on request.
+- No tables — they collapse on mobile clients. Use `label: value` lines instead.
+- Links: bare URL or `<url|text>`-style only if the channel supports it; never markdown `[text](url)` on Slack.
+- One question per message when you need input — multi-part questionnaires get half-answered.
+- Emoji: at most one, and only when it carries tone the words don't.

package/skills/code-review.md

@@ -0,0 +1,33 @@
+---
+description: Structured code review. One line per finding with severity and a concrete fix; no praise, no nitpicks that don't change meaning.
+created_by: starter
+version: 1
+---
+
+# Code review
+
+Review the code or diff the user provides. Output findings, not commentary.
+
+## Output format
+
+One line per finding:
+
+```
+<file>:<line> <SEVERITY>: <problem>. <concrete fix>.
+```
+
+Severities, in the order findings should appear:
+
+- **BLOCKER** — bugs, data loss, security holes, broken builds. Must fix before merge.
+- **MAJOR** — correctness risks, missing error handling, race conditions, leaks.
+- **MINOR** — readability, naming, dead code, missed simplification.
+
+End with a one-line verdict: `verdict: <ship | fix blockers first | needs rework> (<n> findings)`.
+
+## Rules
+
+- Every finding names a location and a fix. "This could be better" is not a finding.
+- Check, in priority order: correctness → security (injection, path traversal, secrets in code/logs) → error handling (swallowed exceptions, missing timeouts) → concurrency → resource cleanup → API misuse → readability.
+- Skip pure formatting nits unless they change meaning — a formatter owns those.
+- No praise padding. If the code is fine, say `verdict: ship (0 findings)` and stop.
+- If you can't see enough context to judge a line, say what file/definition you'd need — don't guess.

package/skills/commit-message.md

@@ -0,0 +1,30 @@
+---
+description: Write Conventional Commits messages from a diff or change description. Subject ≤50 chars, body explains why.
+created_by: starter
+version: 1
+---
+
+# Commit message writer
+
+Given a diff, a `git status`, or a description of a change, produce a commit message in Conventional Commits format.
+
+## Format
+
+```
+<type>(<scope>): <subject>
+
+<body — only when the why isn't obvious from the subject>
+```
+
+- `type`: one of `feat` `fix` `docs` `refactor` `test` `chore` `perf` `style` `build` `ci`.
+- `scope`: the subsystem touched (directory or module name), omit if the change is global.
+- `subject`: imperative mood ("add", not "added"/"adds"), no trailing period, ≤50 characters.
+- `body`: wrap at 72 chars. Explain **why** the change was made and any non-obvious consequence. Never narrate the diff line by line — the diff already shows the what.
+
+## Rules
+
+- One logical change per message. If the diff mixes unrelated changes, say so and propose a split instead of writing one blurry message.
+- Breaking change → add a `BREAKING CHANGE:` footer describing the migration.
+- Reference issues in the footer (`Fixes #123`), not the subject.
+- No emoji, no marketing language, no "various fixes".
+- Output the message in a code block, ready to paste — nothing else unless asked.

package/skills/concise.md

@@ -0,0 +1,24 @@
+---
+description: Terse, high-signal replies. Cut filler and hedging, keep every technical fact. Good default for chat and channels.
+created_by: starter
+version: 1
+---
+
+# Concise replies
+
+Answer with maximum signal per token. The reader is busy; respect that.
+
+## Rules
+
+- Lead with the answer or outcome. Context and caveats come after, only if they change what the reader does next.
+- Drop filler ("basically", "just", "as you can see"), pleasantries, and restatements of the question.
+- No hedging chains. One qualifier max, and only when uncertainty is real — then say what would resolve it.
+- Prefer a short sentence over a bullet, a bullet over a paragraph, a table only for genuinely tabular data.
+- Code, commands, errors, and identifiers stay exact and complete — never compress those.
+- If the honest answer is "I don't know", say it in one line and state what's needed to find out.
+
+## Length budget
+
+- Simple question → 1-3 sentences.
+- How-to → numbered steps, one line each.
+- Anything longer than ~150 words: stop and ask yourself which half the reader can live without.

package/skills/debug-coach.md

@@ -0,0 +1,25 @@
+---
+description: Systematic debugging discipline — reproduce, isolate, hypothesize, verify. No guess-and-patch fixes.
+created_by: starter
+version: 1
+---
+
+# Debug coach
+
+When the user reports a bug, error, or unexpected behavior, work the problem systematically instead of pattern-matching to the first plausible fix.
+
+## Method
+
+1. **Reproduce** — pin down the exact failing input, command, and error text. If it can't be reproduced, that's the first problem to solve.
+2. **Read the error** — the actual message, the actual stack frame, the actual line. Quote it back exactly; most bugs are solved here.
+3. **Isolate** — bisect: which half of the pipeline is the failure in? Repeat until the broken unit is small enough to reason about. Recent changes (`git diff`, `git log`) are prime suspects.
+4. **Hypothesize, then verify** — state one specific cause and the observation that would confirm or kill it (a log line, a debugger value, a minimal repro). Check it before touching code.
+5. **Fix the cause, not the symptom** — a `try/catch` around the crash site or a sleep before the race is a symptom patch. Say so explicitly if a workaround is all that's feasible now.
+6. **Prove it** — re-run the original failing case, and add a regression test when there's a test suite to put it in.
+
+## Rules
+
+- Never claim "fixed" without re-running the failing case and showing the result.
+- One hypothesis at a time. Shotgunning five changes at once destroys the evidence.
+- If two fixes in a row haven't worked, stop and question the diagnosis — the bug is upstream of where you're looking.
+- Ask for the full error output and environment (versions, OS, config) when they're missing; don't reconstruct them from imagination.

package/skills/explain.md

@@ -0,0 +1,24 @@
+---
+description: Explain code or concepts clearly — start from what it does, then how, calibrated to the reader's level.
+created_by: starter
+version: 1
+---
+
+# Explainer
+
+When asked to explain code, an error, a concept, or a design, teach it — don't just describe it.
+
+## Method
+
+1. **What it does, in one sentence** — purpose before mechanics. "This debounces the search input" beats a line-by-line tour.
+2. **How it works** — walk the key path in execution order. Name the 2-3 load-bearing pieces and skip the boilerplate.
+3. **Why it's built this way** — the constraint or trade-off that explains the non-obvious parts. If a simpler way exists, mention it.
+4. **Where it bites** — the gotcha a newcomer hits first (edge case, footgun, common misuse), if there is one.
+
+## Rules
+
+- Calibrate to the reader: if their question shows expertise, skip fundamentals; if it doesn't, define terms on first use with a concrete example.
+- Use a runnable mini-example over an abstract description when one fits in ≤10 lines.
+- Analogies are seasoning, not the meal — one good one max, then back to the real thing.
+- Don't explain what wasn't asked. A question about one function is not an invitation to tour the codebase.
+- If the honest explanation is "this code is confusing because it's doing two unrelated things", say that.

package/skills/korean.md

@@ -0,0 +1,25 @@
+---
+description: Respond in Korean; keep code, commands, logs, and identifiers in English. 한국어 응답, 기술 용어는 원문 유지.
+created_by: starter
+version: 1
+---
+
+# Korean responses (한국어 응답)
+
+Respond in Korean. The user reads Korean fastest, but works in an English-language technical stack.
+
+## Rules
+
+- 답변 본문은 한국어로 작성한다.
+- Code, shell commands, file paths, error messages, variable/function names, API fields: keep in English, verbatim. Never translate an error message — the user needs to grep for it.
+- Established technical terms stay in English when the English term is what practitioners actually say (e.g. "race condition", "merge conflict"). Don't force awkward translations.
+- 존댓말(해요체) 기본. 과도한 격식이나 번역투("~하는 것이 가능합니다")는 피하고 자연스러운 한국어로.
+- Code comments and commit messages: English, unless the user asks otherwise.
+
+## Example
+
+> `useEffect` 의존성 배열에 `user.id`가 빠져서 stale closure가 생깁니다. 아래처럼 고치세요:
+>
+> ```js
+> useEffect(() => { fetchProfile(user.id); }, [user.id]);
+> ```

package/skills/summarize.md

@@ -0,0 +1,33 @@
+---
+description: Digest long content (threads, docs, logs, transcripts) into TL;DR, key points, and action items with owners.
+created_by: starter
+version: 1
+---
+
+# Summarizer
+
+Turn long input — a thread, document, meeting transcript, log dump, or article — into a digest the reader can act on in under a minute.
+
+## Output shape
+
+```
+TL;DR: <one sentence — the single thing to know>
+
+Key points:
+- <3-7 bullets, each a standalone fact or decision>
+
+Action items:        (only if the input contains or implies any)
+- <who> — <what> — <by when, if stated>
+
+Open questions:      (only if real unresolved items exist)
+- <question>
+```
+
+## Rules
+
+- The TL;DR is the conclusion, not the topic. "Deploy is blocked on the cert renewal" — not "This thread discusses deployment."
+- Preserve decisions, numbers, dates, names, and commitments exactly. These are the facts people come back to verify.
+- Attribute contested claims ("X argues…, Y counters…") instead of flattening disagreement into false consensus.
+- Drop greetings, repetition, and back-and-forth that didn't change the outcome.
+- If the input is too truncated or ambiguous to summarize faithfully, say what's missing instead of papering over it.
+- Match the input's language (Korean input → Korean summary), keeping technical terms as-is.

package/skills.mjs

@@ -27,6 +27,13 @@ const SKILL_EXT = '.md';
 // that want to be explicit.
 const _indexCache = new Map();  // cfgDir → { mtimeMs, skills, index }
 
+// Per-skill BODY cache, keyed by `${cfgDir}::${name}` → { mtimeMs, body }.
+// composeSystemPrompt calls loadSkill once per requested skill on every
+// POST /agent reply, so an unchanged skill .md used to be re-read from disk
+// each turn. Keyed by file mtime so a live edit (or installSkill rewrite)
+// busts the entry; install/removeSkill also clear it explicitly.
+const _bodyCache = new Map();
+
 export function _invalidateSkillsCache(configDir = defaultConfigDir()) {
   _indexCache.delete(configDir);
 }
@@ -152,8 +159,15 @@ export function skillsIndex(configDir = defaultConfigDir()) {
 
 export function loadSkill(name, configDir = defaultConfigDir()) {
   const p = skillPath(name, configDir);
-  if (!fs.existsSync(p)) throw new Error(`skill not found: ${name}`);
-  return fs.readFileSync(p, 'utf8');
+  let mtimeMs;
+  try { mtimeMs = fs.statSync(p).mtimeMs; }
+  catch { throw new Error(`skill not found: ${name}`); }
+  const key = `${configDir}::${name}`;
+  const hit = _bodyCache.get(key);
+  if (hit && hit.mtimeMs === mtimeMs) return hit.body;
+  const body = fs.readFileSync(p, 'utf8');
+  _bodyCache.set(key, { mtimeMs, body });
+  return body;
 }
 
 export function installSkill(name, content, configDir = defaultConfigDir()) {
@@ -161,6 +175,7 @@ export function installSkill(name, content, configDir = defaultConfigDir()) {
   fs.mkdirSync(path.dirname(p), { recursive: true });
   fs.writeFileSync(p, content);
   _invalidateSkillsCache(configDir);
+  _bodyCache.delete(`${configDir}::${name}`);
   return p;
 }
 
@@ -168,6 +183,13 @@ export function removeSkill(name, configDir = defaultConfigDir()) {
   const p = skillPath(name, configDir);
   if (fs.existsSync(p)) fs.unlinkSync(p);
   _invalidateSkillsCache(configDir);
+  _bodyCache.delete(`${configDir}::${name}`);
+  // Drop the skill's FTS row too — unlinking the .md left a stale, still
+  // recallable index row. Lazy + best-effort so better-sqlite3 stays off the
+  // skills hot path and a delete hiccup never throws out of removeSkill.
+  import('./mas/index_db.mjs')
+    .then((idx) => { try { idx.deleteSkill(name, configDir); } catch { /* best-effort */ } })
+    .catch(() => { /* index unavailable */ });
 }
 
 export function skillExists(name, configDir = defaultConfigDir()) {

package/skills_curator.mjs

@@ -287,6 +287,12 @@ function moveToArchive(name, configDir, archivedAtMs) {
       throw err;
     }
   }
+  // Archiving must also drop the skill's FTS row, or a 90-day-idle skill stays
+  // recallable forever. Lazy + best-effort (keeps better-sqlite3 off the curate
+  // hot path; an index hiccup never fails the archival move).
+  import('./mas/index_db.mjs')
+    .then((idx) => { try { idx.deleteSkill(name, configDir); } catch { /* best-effort */ } })
+    .catch(() => { /* index unavailable */ });
   return dest;
 }
 

package/skills_install.mjs

@@ -28,6 +28,7 @@ import os from 'node:os';
 import path from 'node:path';
 import { spawn } from 'node:child_process';
 import { Readable } from 'node:stream';
+import { sanitizeSkillBody, neutralizeRoleLabels } from './mas/redact.mjs';
 
 const GITHUB_SPEC = /^([\w.-]+)\/([\w.-]+)(?:@([^:]+))?(?::(.+))?$/;
 const SKILL_EXT = '.md';
@@ -213,8 +214,15 @@ export function installPickedSkills(picked, configDir, opts = {}) {
       skipped.push({ name, reason: 'exists', dst });
       continue;
     }
-    fs.copyFileSync(f.abs, dst);
-    installed.push({ name, src: f.relative, dst, bytes: fs.statSync(dst).size });
+    // A remote skill body is injected into other agents' system prompts, so
+    // sanitize it on the way in — same pass the synth path uses (redact
+    // secrets, defang the [[TASK_DONE]] router marker, strip control chars,
+    // cap size) PLUS neutralize forged role labels ([System]/[User]) since
+    // remote content is fully untrusted. No code is executed either way.
+    const raw = fs.readFileSync(f.abs, 'utf8');
+    const clean = sanitizeSkillBody(neutralizeRoleLabels(raw));
+    fs.writeFileSync(dst, clean);
+    installed.push({ name, src: f.relative, dst, bytes: Buffer.byteLength(clean, 'utf8'), sanitized: clean !== raw });
   }
   return { installed, skipped };
 }

package/tasks.mjs

@@ -15,7 +15,12 @@ import crypto from 'node:crypto';
 import { getTeam } from './teams.mjs';
 
 const TASKS_DIRNAME = 'tasks';
-export const VALID_STATUSES = ['pending', 'running', 'done', 'failed', 'abandoned'];
+// 'paused' is a resumable terminal state: a router turn that stopped on the
+// turn budget or went idle (no agent had more to do) lands here — it didn't
+// fail, and `task tick <id>` resumes it (the router flips it back to 'running'
+// for the next turn). Distinct from 'failed' (error), 'abandoned' (explicit
+// abort), and 'done' (completed).
+export const VALID_STATUSES = ['pending', 'running', 'done', 'failed', 'abandoned', 'paused'];
 
 export class TaskError extends Error {
   constructor(message, code) {

package/teams.mjs

@@ -98,6 +98,7 @@ export function registerTeam({ name, displayName, agents = [], lead = null, slac
     slackChannel: String(slackChannel || ''),
   };
   writeAtomic(p, data);
+  _invalidateTeamIndex(configDir);
   return data;
 }
 
@@ -133,6 +134,7 @@ export function patchTeam(name, patch, configDir = defaultConfigDir()) {
   if (patch.agents !== undefined) next.agents = [...new Set(patch.agents)];
   validateAgentRefs(next.agents, next.lead, configDir);
   writeAtomic(teamPath(name, configDir), next);
+  _invalidateTeamIndex(configDir);
   return next;
 }
 
@@ -142,6 +144,7 @@ export function removeTeam(name, configDir = defaultConfigDir()) {
     throw new TeamError(`no team "${name}"`, 'TEAM_NO_TEAM');
   }
   fs.unlinkSync(p);
+  _invalidateTeamIndex(configDir);
   return { name, removed: true };
 }
 
@@ -197,3 +200,78 @@ export function parseListFlag(raw) {
   if (s === '') return [];
   return s.split(',').map(x => x.trim()).filter(Boolean);
 }
+
+// Build the team's org tree for the dashboard: a nested { agent, children[] }
+// rooted at team.lead. A member nests under its `manager` when that manager is
+// also a team member; otherwise (no manager, or a manager outside the team) it
+// attaches directly under the lead, so the result is always a single tree.
+//
+// @param {{lead:string, agents:string[]}} team
+// @param {Record<string, object>} agentsById  name → agent record
+export function teamTree(team, agentsById = {}) {
+  const lead = team && team.lead;
+  if (!lead) return null;
+  const memberNames = new Set((team.agents || []));
+  const byManager = new Map(); // manager name → child names
+  for (const n of memberNames) {
+    if (n === lead) continue;
+    const rec = agentsById[n];
+    const mgr = rec && rec.manager && memberNames.has(rec.manager) && rec.manager !== n
+      ? rec.manager
+      : lead;
+    if (!byManager.has(mgr)) byManager.set(mgr, []);
+    byManager.get(mgr).push(n);
+  }
+  const build = (name, seen) => {
+    if (seen.has(name)) return null; // cycle guard (defensive — register/patch reject cycles)
+    const next = new Set(seen).add(name);
+    const node = { agent: agentsById[name] || { name }, children: [] };
+    for (const child of (byManager.get(name) || []).sort()) {
+      const c = build(child, next);
+      if (c) node.children.push(c);
+    }
+    return node;
+  };
+  return build(lead, new Set());
+}
+
+// Find the team bound to an inbound channel id (team.slackChannel), or null.
+// Used by the daemon to auto-route a Slack message to a team's multi-agent loop.
+export function teamForChannel(teams, channel) {
+  if (!channel) return null;
+  const c = String(channel);
+  return (teams || []).find((t) => t && t.slackChannel && String(t.slackChannel) === c) || null;
+}
+
+// slackChannel→team index, keyed by configDir and the teams/ dir mtime. Every
+// inbound Slack message used to re-scan the whole teams/ directory (readdir + N
+// JSON.parse) just to find one channel's team; this builds the lookup once and
+// reuses it until the directory changes. register/patch/removeTeam invalidate
+// explicitly (deterministic), and the dir-mtime key also catches manual edits.
+const _channelIndex = new Map();  // configDir → { mtimeMs, byChannel: Map<channel, team> }
+
+export function _invalidateTeamIndex(configDir = defaultConfigDir()) {
+  _channelIndex.delete(configDir);
+}
+
+// O(1) channel→team lookup for the inbound hot path. Returns null when no team
+// is bound to the channel (or there is no teams/ directory yet).
+export function teamForChannelCached(channel, configDir = defaultConfigDir()) {
+  if (!channel) return null;
+  const dir = teamsDir(configDir);
+  let mtimeMs = 0;
+  try { mtimeMs = fs.statSync(dir).mtimeMs; }
+  catch { return null; }  // no teams dir → no team bound to anything
+  const cached = _channelIndex.get(configDir);
+  let byChannel;
+  if (cached && cached.mtimeMs === mtimeMs) {
+    byChannel = cached.byChannel;
+  } else {
+    byChannel = new Map();
+    for (const t of listTeams(configDir)) {
+      if (t && t.slackChannel) byChannel.set(String(t.slackChannel), t);
+    }
+    _channelIndex.set(configDir, { mtimeMs, byChannel });
+  }
+  return byChannel.get(String(channel)) || null;
+}