typeclaw 0.23.0 → 0.25.0

package/src/run/index.ts

@@ -4,6 +4,7 @@ import { createSession, createSessionWithDispose } from '@/agent'
 import { LiveSessionRegistry } from '@/agent/live-sessions'
 import { LiveSubagentRegistry } from '@/agent/live-subagents'
 import { requestContainerRestart } from '@/agent/restart'
+import { consumeRestartHandoff } from '@/agent/restart-handoff'
 import type { SessionOrigin } from '@/agent/session-origin'
 import {
   awaitWithSubagentTimeout,
@@ -16,6 +17,7 @@ import {
   type SubagentRegistry,
   type SubagentShared,
 } from '@/agent/subagents'
+import { clearTodosForOrigin } from '@/agent/todo/continuation-wiring'
 import { resolveCapOptionsFromConfig } from '@/bundled-plugins/tool-result-cap'
 import {
   createChannelManager,
@@ -282,14 +284,31 @@ export async function startAgent({
     // `typeclaw run` outside Docker), the handler reports that instead of the
     // command resolving as unknown, which would make the advertised contract
     // depend on the runtime environment.
-    onRestart: async (): Promise<string> => {
+    onRestart: async (ctx): Promise<string> => {
       if (containerName === undefined) {
         return 'Restart is unavailable: this agent is not running inside a typeclaw container.'
       }
-      // No originatingSessionId/stream/handoff: a channel-invoked restart must
-      // not write a resume hint or fire the "I'm back" broadcast that a TUI
-      // restart does (issue #291 scoping — only TUI origins resume).
-      const result = await requestContainerRestart({ containerName })
+      // When the /restart command resolved a live channel session, ctx carries
+      // its identity: pass stream + session id/file + channel handoffOrigin so
+      // the dying container appends the `typeclaw.restart-self` entry (via the
+      // broadcast) and writes a channel-origin handoff. On the next boot the
+      // channel resume path reopens that exact conversation. With no live
+      // session (cold channel / native slash), ctx is undefined and the
+      // container just bounces — the next inbound resumes pending todos.
+      const result = await requestContainerRestart({
+        containerName,
+        ...(ctx !== undefined
+          ? {
+              stream,
+              agentDir: cwd,
+              originatingSessionId: ctx.originatingSessionId,
+              ...(ctx.originatingSessionFile !== undefined
+                ? { originatingSessionFile: ctx.originatingSessionFile }
+                : {}),
+              handoffOrigin: ctx.handoffOrigin,
+            }
+          : {}),
+      })
       return result.ok ? 'Restart scheduled; the container will bounce shortly.' : `Restart denied: ${result.reason}`
     },
   })
@@ -328,6 +347,20 @@ export async function startAgent({
           ...(entry.pluginSubagent.customTools ? { customTools: entry.pluginSubagent.customTools } : {}),
           toolNamePrefix: `__plugin_${entry.pluginName}_${entry.subagentName}`,
         },
+        // Orchestration wiring is opt-in per subagent (canSpawnSubagents) so
+        // only operator/reviewer can delegate; explorer/scout/etc. stay leaves.
+        // The same liveSubagentRegistry instance is shared, but
+        // subagent_output/subagent_cancel scope by the caller's session (see
+        // authorizeLiveSubagentAccess) and spawn_subagent caps the chain at
+        // MAX_SUBAGENT_DEPTH. createSessionForSubagent self-references so a
+        // nested spawn re-enters this same factory.
+        ...(entry.pluginSubagent.canSpawnSubagents === true
+          ? {
+              liveSubagentRegistry,
+              subagentRegistry: snap.subagents,
+              createSessionForSubagent,
+            }
+          : {}),
         ...(entry.pluginSubagent.profile !== undefined ? { profile: entry.pluginSubagent.profile } : {}),
         ...(entry.pluginSubagent.toolResultBudget !== undefined
           ? { toolResultBudget: entry.pluginSubagent.toolResultBudget }
@@ -434,6 +467,13 @@ export async function startAgent({
         // marker so the audit trail records "user edited cron.json".
         scheduledByOrigin: (job.scheduledByOrigin as SessionOrigin | undefined) ?? { kind: 'config-file' },
       }
+      // Cron todos are per-fire ephemeral by default: each scheduled run starts
+      // with a clean list so an incomplete item from a prior fire cannot
+      // resurrect indefinitely on every tick. (A future opt-in could carry them
+      // forward; until then, clearing is the safe default.)
+      await clearTodosForOrigin(cwd, cronOrigin).catch((err) =>
+        console.error(`[cron] ${job.id}: clear todos failed: ${err instanceof Error ? err.message : String(err)}`),
+      )
       const session = await createSession({
         reloadRegistry,
         sessionManager,
@@ -507,8 +547,37 @@ export async function startAgent({
   })
 
   reloadRegistry.register(createChannelsReloadable({ manager: channelManager }))
+
+  // Two-phase channel restart-resume around adapter startup, to close the race
+  // where an adapter starts receiving before the resume claims the handoff:
+  //   1. Claim the channel handoff and RESERVE the originating key BEFORE
+  //      channelManager.start(). The reservation installs a per-key gate, so an
+  //      inbound that arrives the instant an adapter connects coalesces onto the
+  //      resume instead of stale-rolling the mapping or creating a rival session.
+  //   2. start() the adapters (registers outbound callbacks the wake reply needs).
+  //   3. resume() the reservation: reopen the exact session and enqueue the wake
+  //      — skipped automatically if a real inbound already coalesced in (2)→(3).
+  // Claims ONLY channel handoffs; tui handoffs are left on disk (peek-then-delete
+  // never removes an unclaimed handoff) for the websocket open handler to claim.
+  // Best-effort throughout: any failure leaves the todo to resume on the next inbound.
+  let restartReservation: ReturnType<typeof channelManager.router.reserveRestartHandoff> = null
+  try {
+    const handoff = await consumeRestartHandoff(cwd, { accept: (h) => h.origin.kind === 'channel' })
+    if (handoff !== null) restartReservation = channelManager.router.reserveRestartHandoff(handoff)
+  } catch (err) {
+    console.warn(`[run] channel restart-resume reserve failed: ${err instanceof Error ? err.message : err}`)
+  }
+
   await channelManager.start()
 
+  if (restartReservation !== null) {
+    try {
+      await restartReservation.resume()
+    } catch (err) {
+      console.warn(`[run] channel restart-resume failed: ${err instanceof Error ? err.message : err}`)
+    }
+  }
+
   // Captured separately from setSpawnSubagent so both the plugin context and
   // the plugin-command runner can dispatch through the same path. The setter
   // returns void, so without this local binding we couldn't reuse the fn.

package/src/sandbox/build.ts

@@ -110,6 +110,8 @@ function buildArgv(command: string, policy: SandboxPolicy): string[] {
   }
 
   appendMasks(argv, policy)
+  appendWritable(argv, policy)
+  appendProtected(argv, policy)
 
   if (policy.cwd !== undefined) {
     argv.push('--chdir', policy.cwd)
@@ -128,6 +130,24 @@ function appendMasks(argv: string[], policy: SandboxPolicy): void {
   }
 }
 
+function appendWritable(argv: string[], policy: SandboxPolicy): void {
+  for (const dir of policy.writable?.dirs ?? []) {
+    argv.push('--bind', dir, dir)
+  }
+  for (const file of policy.writable?.files ?? []) {
+    argv.push('--bind', file, file)
+  }
+}
+
+function appendProtected(argv: string[], policy: SandboxPolicy): void {
+  for (const dir of policy.protected?.dirs ?? []) {
+    argv.push('--ro-bind', dir, dir)
+  }
+  for (const file of policy.protected?.files ?? []) {
+    argv.push('--ro-bind', file, file)
+  }
+}
+
 function appendMount(argv: string[], mount: SandboxMount): void {
   switch (mount.type) {
     case 'ro-bind':

package/src/sandbox/index.ts

@@ -1,6 +1,14 @@
 export { buildSandboxedCommand, type SandboxedCommand } from './build'
 export { ensureBwrapAvailable, _resetBwrapAvailabilityCacheForTests } from './availability'
 export { resolveHiddenPaths, type HiddenPaths } from './hidden-paths'
+export {
+  resolveProtectedZones,
+  resolveWritableZones,
+  subtractMasked,
+  type ProtectedZones,
+  type WritableZones,
+} from './writable-zones'
+export { ensureSessionTmpDir, isUnderTmp, mapVirtualTmpPath, SESSION_TMP_ROOT, sessionTmpDir } from './session-tmp'
 export { formatCommand, shellQuote } from './quote'
 export { SandboxPolicyError, SandboxUnavailableError } from './errors'
 export {
@@ -12,4 +20,6 @@ export {
   type SandboxPolicy,
   type SandboxProcessPolicy,
   type SandboxProcStrategy,
+  type SandboxProtectedPolicy,
+  type SandboxWritablePolicy,
 } from './policy'

package/src/sandbox/policy.ts

@@ -37,11 +37,33 @@ export type SandboxMaskPolicy = {
   files?: string[]
 }
 
+// Writable carve-outs re-exposed on top of a read-only project root AND its
+// masks. Rendered last so "last op wins" makes these the only RW paths: an RW
+// bind here overrides the broad --ro-bind parent, while anything not listed
+// stays read-only (EROFS) or masked.
+export type SandboxWritablePolicy = {
+  dirs?: string[]
+  files?: string[]
+}
+
+// Read-only re-protections carved back out of a writable parent. MUST render
+// after `writable` so bwrap's last-op-wins keeps these EROFS despite the parent
+// RW bind. Load-bearing: `.git` is writable so members can commit, but
+// `.git/hooks` and `.git/config` stay RO here — otherwise a low-trust role
+// plants a hook or sets core.hooksPath and gets code execution in the
+// unsandboxed runtime git ops (backup/dreaming) that share the same .git.
+export type SandboxProtectedPolicy = {
+  dirs?: string[]
+  files?: string[]
+}
+
 export type SandboxPolicy = {
   bwrapPath?: string
   cwd?: string
   mounts?: SandboxMount[]
   masks?: SandboxMaskPolicy
+  writable?: SandboxWritablePolicy
+  protected?: SandboxProtectedPolicy
   network?: SandboxNetwork
   env?: SandboxEnvPolicy
   commandFilter?: SandboxCommandFilter

package/src/sandbox/session-tmp.ts

@@ -0,0 +1,43 @@
+import { mkdir } from 'node:fs/promises'
+import { isAbsolute, join, relative, resolve } from 'node:path'
+
+// Per-session scratch lives on the REAL container /tmp, namespaced by session id.
+// It sits OUTSIDE the agent folder on purpose: the agent folder's `sessions/` is
+// force-committed by typeclaw, and scratch must never be committed. The real
+// /tmp is ephemeral (dies with the container) and already the natural home for
+// throwaway files, so a per-session subdir of it gives `/tmp` semantics without
+// either sharing the whole container /tmp into a sandboxed role or persisting
+// anything into the project surface.
+export const SESSION_TMP_ROOT = '/tmp/typeclaw-session'
+
+export function sessionTmpDir(sessionId: string): string {
+  return join(SESSION_TMP_ROOT, sessionId)
+}
+
+export async function ensureSessionTmpDir(sessionId: string): Promise<string> {
+  const dir = sessionTmpDir(sessionId)
+  await mkdir(dir, { recursive: true, mode: 0o700 })
+  return dir
+}
+
+export function isUnderTmp(agentDir: string, rawPath: string): boolean {
+  const resolved = resolve(agentDir, rawPath)
+  return resolved === '/tmp' || isInside('/tmp', resolved)
+}
+
+// Maps a model-facing /tmp path to its per-session backing path. Returns
+// undefined when the path is not under /tmp (caller leaves it untouched). The
+// model keeps writing/reading `/tmp/foo`; only the on-disk target moves to
+// `<SESSION_TMP_ROOT>/<sid>/foo`, which is the same dir bwrap binds over `/tmp`
+// for the sandboxed bash that reads it back.
+export function mapVirtualTmpPath(agentDir: string, sessionId: string, rawPath: string): string | undefined {
+  const resolved = resolve(agentDir, rawPath)
+  if (resolved !== '/tmp' && !isInside('/tmp', resolved)) return undefined
+  const rel = relative('/tmp', resolved)
+  return rel === '' ? sessionTmpDir(sessionId) : join(sessionTmpDir(sessionId), rel)
+}
+
+function isInside(parent: string, child: string): boolean {
+  const rel = relative(parent, child)
+  return rel !== '' && !rel.startsWith('..') && !isAbsolute(rel)
+}

package/src/sandbox/writable-zones.ts

@@ -0,0 +1,178 @@
+import { lstat, mkdir, readFile, writeFile } from 'node:fs/promises'
+import path, { isAbsolute, join, resolve } from 'node:path'
+
+export type WritableZones = {
+  dirs: string[]
+  files: string[]
+}
+
+export type ProtectedZones = {
+  dirs: string[]
+  files: string[]
+}
+
+// SECURITY: a blanket RW bind is coarser than the write/edit guards, so this set
+// is deliberately NARROWER than the write/edit allowlist — only genuinely
+// free-write scratch zones. `.agents/skills` and `packages` are excluded: the
+// former is validated (SKILL.md shape, name, frontmatter) by the skillAuthoring
+// guard and the latter holds executable plugin code; bash must not get blanket
+// RW to either. Skill authoring and package writes go through the guarded
+// write/edit tool only.
+// `.git` is writable so a member can `git add`/`git commit` their own edits.
+// This is the AGENT'S OWN repo, not a shared/upstream one, so writing history
+// is not a privilege boundary: a low-trust role staging a tracked path it
+// cannot edit in the worktree (e.g. via `git update-index --cacheinfo` plumbing)
+// only writes the agent's own history — content the backup runner already
+// force-commits on idle regardless. So we deliberately do NOT try to confine
+// commit *content* to the worktree write-allowlist; that boundary governs the
+// working tree, not the object database.
+//
+// The one thing writable `.git` must NOT grant is code execution in the
+// UNSANDBOXED runtime (backup/dreaming commit the same .git out of band): a
+// planted `.git/hooks/*` or a `core.hooksPath` in `.git/config` would fire there
+// as a higher-privilege process. resolveProtectedZones re-binds `.git/hooks` and
+// `.git/config` read-only (after the writable .git bind, last-op-wins) to close
+// exactly that escalation.
+const WRITABLE_DIRS = ['workspace', 'public', 'mounts', '.git'] as const
+
+const PROTECTED_GIT_DIRS = ['.git/hooks'] as const
+const PROTECTED_GIT_FILES = ['.git/config'] as const
+
+// Bash may EDIT these when present; creating a MISSING root file goes through
+// write/edit (bwrap cannot RW-bind a non-existent source without pre-creating it).
+const WRITABLE_ROOT_FILES = [
+  'AGENTS.md',
+  'IDENTITY.md',
+  'SOUL.md',
+  'USER.md',
+  'cron.json',
+  'package.json',
+  'typeclaw.json',
+] as const
+
+// SECURITY: the symlink rejection is load-bearing. An RW bind follows symlinks,
+// so a `workspace -> /etc` symlink at a zone root would grant write access to an
+// outside path. (Symlinks INSIDE a real zone are already safe — the kernel
+// resolves them to the read-only parent mount.)
+export async function resolveWritableZones(agentDir: string): Promise<WritableZones> {
+  const dirs = await collectExisting(
+    WRITABLE_DIRS.map((d) => join(agentDir, d)),
+    'dir',
+  )
+  const files = await collectExisting(
+    WRITABLE_ROOT_FILES.map((f) => join(agentDir, f)),
+    'file',
+  )
+  return { dirs, files }
+}
+
+// Read-only re-protections rendered on top of the writable .git bind. Unlike
+// the writable resolvers, this MUST NOT drop absent entries: .git is writable,
+// so a path absent at jail-build time would otherwise be CREATED by sandboxed
+// bash (e.g. a planted .git/hooks/pre-commit) and then executed by the
+// unsandboxed runtime git ops. So we ensure each protected path exists first,
+// then always RO-bind it — a read-only bind of a real dir blocks creating
+// children inside it (EROFS), and a read-only bind of config keeps its real
+// content readable (commits need user.name/email) while blocking mutation.
+//
+// We also resolve the effective core.hooksPath from the real (about-to-be-RO)
+// config: if it already points at a writable location (e.g. workspace/hooks),
+// the .git/hooks RO-bind alone would not cover it, so that dir is protected too.
+export async function resolveProtectedZones(agentDir: string): Promise<ProtectedZones> {
+  const dirs: string[] = []
+  for (const rel of PROTECTED_GIT_DIRS) {
+    dirs.push(await ensureProtectedDir(join(agentDir, rel)))
+  }
+  const files: string[] = []
+  for (const rel of PROTECTED_GIT_FILES) {
+    files.push(await ensureProtectedFile(join(agentDir, rel)))
+  }
+
+  const hooksPathDir = await resolveEffectiveHooksPath(agentDir)
+  if (hooksPathDir !== undefined && !dirs.includes(hooksPathDir)) {
+    dirs.push(await ensureProtectedDir(hooksPathDir))
+  }
+
+  return { dirs, files }
+}
+
+// Fail closed: a symlink at a protected path would make the RO bind follow it
+// elsewhere, so reject it rather than silently protect the wrong target.
+async function ensureProtectedDir(target: string): Promise<string> {
+  await mkdir(target, { recursive: true })
+  await assertNotSymlink(target)
+  return target
+}
+
+async function ensureProtectedFile(target: string): Promise<string> {
+  if (!(await isRealEntry(target, 'file'))) {
+    try {
+      await writeFile(target, '', { flag: 'wx' })
+    } catch {
+      // Lost a race (or it appeared); the symlink check below still guards it.
+    }
+  }
+  await assertNotSymlink(target)
+  return target
+}
+
+async function assertNotSymlink(target: string): Promise<void> {
+  const stats = await lstat(target)
+  if (stats.isSymbolicLink()) {
+    throw new Error(`sandbox: refusing to protect symlinked path ${target}`)
+  }
+}
+
+// Reads core.hooksPath straight from .git/config text (the file is about to be
+// RO-bound, so its content is the trusted baseline). Returns the resolved
+// absolute dir only when it lands inside agentDir — an outside path is not
+// writable by the jail and a relative path resolves against the repo root, per
+// gitconfig semantics.
+async function resolveEffectiveHooksPath(agentDir: string): Promise<string | undefined> {
+  let text: string
+  try {
+    text = await readFile(join(agentDir, '.git', 'config'), 'utf8')
+  } catch {
+    return undefined
+  }
+  const match = text.match(/^\s*hooksPath\s*=\s*(.+?)\s*$/m)
+  if (match === null) return undefined
+  const raw = match[1]?.trim()
+  if (raw === undefined || raw.length === 0) return undefined
+  const resolved = isAbsolute(raw) ? resolve(raw) : resolve(agentDir, raw)
+  return isInside(agentDir, resolved) ? resolved : undefined
+}
+
+// SECURITY: a writable RW bind renders AFTER the masks and last-op-wins, so an
+// RW bind on a masked path would re-expose the real (hidden) directory. Drop any
+// writable zone that is, or is nested under, a masked path so the confidentiality
+// boundary survives — e.g. a guest's masked `workspace/` is never re-exposed RW.
+export function subtractMasked(writable: WritableZones, masked: { dirs: string[]; files: string[] }): WritableZones {
+  const maskedDirs = masked.dirs
+  const isMasked = (target: string): boolean =>
+    masked.files.includes(target) || maskedDirs.some((dir) => target === dir || isInside(dir, target))
+  return {
+    dirs: writable.dirs.filter((dir) => !isMasked(dir)),
+    files: writable.files.filter((file) => !isMasked(file)),
+  }
+}
+
+function isInside(parent: string, child: string): boolean {
+  const relative = path.relative(parent, child)
+  return relative !== '' && !relative.startsWith('..') && !path.isAbsolute(relative)
+}
+
+async function collectExisting(paths: string[], kind: 'dir' | 'file'): Promise<string[]> {
+  const checks = await Promise.all(paths.map((p) => isRealEntry(p, kind)))
+  return paths.filter((_, i) => checks[i])
+}
+
+async function isRealEntry(path: string, kind: 'dir' | 'file'): Promise<boolean> {
+  try {
+    const stats = await lstat(path)
+    if (stats.isSymbolicLink()) return false
+    return kind === 'dir' ? stats.isDirectory() : stats.isFile()
+  } catch {
+    return false
+  }
+}

package/src/server/command-runner.ts

@@ -389,7 +389,7 @@ export async function runPromptForCommand(args: {
   // Mirrors src/agent/multimodal/look-at.ts: spawn a session, prompt, capture
   // the final assistant text, dispose. Unlike look-at we want the FULL agent
   // toolset (no `tools: []` / `customTools: []` overrides) so the model can
-  // call channel_send, websearch, etc. The system prompt is composed from
+  // call channel_send, web_search, etc. The system prompt is composed from
   // the agent folder's IDENTITY/SOUL/MEMORY files via the default resource
   // loader (no `systemPromptOverride`).
   const snapshot = args.runtime.get()