typeclaw 0.34.1 → 0.35.1

package/src/sandbox/availability.ts

@@ -138,6 +138,27 @@ export function _resetRealProcProbeCacheForTests(): void {
 // future bwrap flag change, would turn this strategy into a secret leak. So we
 // PROBE it directly before ever selecting it — plant a real secret in a sibling
 // process's env and assert the sandbox cannot read it back.
+// The probe has THREE outcomes, not two — collapsing them to a boolean is what
+// caused the silent-degrade bug this verdict type fixes. 'safe'/'unsafe' are definitive capability
+// facts (the userns block held / a leak was observed); 'inconclusive' is a
+// transient local failure (probe timeout under CPU/IO contention, sentinel dying
+// mid-probe, a bwrap startup hiccup) that proves NOTHING about the host. A caller
+// deciding the /proc strategy must tell these apart: an inconclusive probe must
+// trigger a RETRY, never a fall-through to tmpfs that breaks the whole bash call
+// on a host that is actually capable. 'unsafe' must still fail closed with no
+// retry. canBindProcSafely() keeps the old boolean shape for callers that only
+// need "is proc-bind selectable right now"; getProcBindSafetyVerdict() exposes
+// the third state for the retry-owning strategy resolver.
+export type ProcBindSafetyVerdict = 'safe' | 'unsafe' | 'inconclusive'
+
+// Only DEFINITIVE verdicts are process-global facts worth caching. Caching
+// 'inconclusive' (i.e. its boolean `false`) would PERMANENTLY disable proc-bind
+// for the process — a single slow first bash call would silently break every
+// later bunx until container restart (the exact "works after restart" symptom
+// this whole machinery exists to kill). So the cache type structurally excludes
+// it.
+type CacheableProcBindSafetyVerdict = Exclude<ProcBindSafetyVerdict, 'inconclusive'>
+
 // Keyed by resolved bwrapPath, like ensureBwrapAvailable: the safety answer is a
 // fact about a SPECIFIC bwrap binary, so a caller pinning a non-default path
 // (tests, or a future deployment) must re-probe rather than inherit the default
@@ -145,19 +166,21 @@ export function _resetRealProcProbeCacheForTests(): void {
 // concurrent first callers for one path share a single probe. Both cached
 // process-globally (the answer is a per-container capability fact). Not abortable
 // (see canMountRealProc).
-const procBindProbeCache = new Map<string, boolean>()
-const procBindProbeInFlight = new Map<string, Promise<boolean>>()
-
-// `safe` is the answer; `cacheable` is false for INCONCLUSIVE outcomes (a probe
-// timeout under load, or the sentinel dying mid-probe). Those are transient
-// failure modes, not capability facts, so caching their `safe=false` would
-// PERMANENTLY disable proc-bind for the process — a single slow first bash call
-// would silently break every later bunx until container restart (the exact
-// "works after restart" symptom this whole fix exists to kill). Only a probe that
-// ran to a verdict (definitively safe OR definitively leaking) is cached.
-type ProcBindProbe = { safe: boolean; cacheable: boolean }
+const procBindProbeCache = new Map<string, CacheableProcBindSafetyVerdict>()
+const procBindProbeInFlight = new Map<string, Promise<ProcBindSafetyVerdict>>()
 
-export function canBindProcSafely(options?: { bwrapPath?: string }): Promise<boolean> {
+// `verdict` is the answer; only definitive verdicts are `cacheable`. INCONCLUSIVE
+// outcomes (a probe timeout under load, or the sentinel dying mid-probe) are
+// transient failure modes, not capability facts — see the cache rationale above.
+type ProcBindProbe =
+  | { verdict: CacheableProcBindSafetyVerdict; cacheable: true }
+  | { verdict: 'inconclusive'; cacheable: false }
+
+// The three-state probe, deduped + cached like canBindProcSafely. The strategy
+// resolver (resolveProcStrategy in plugin-tools.ts) consumes this so it can RETRY
+// an 'inconclusive' result before degrading the bash call to tmpfs, while still
+// failing closed on 'unsafe'.
+export function getProcBindSafetyVerdict(options?: { bwrapPath?: string }): Promise<ProcBindSafetyVerdict> {
   const bwrap = options?.bwrapPath ?? 'bwrap'
   const cached = procBindProbeCache.get(bwrap)
   if (cached !== undefined) return Promise.resolve(cached)
@@ -165,9 +188,9 @@ export function canBindProcSafely(options?: { bwrapPath?: string }): Promise<boo
   if (existing !== undefined) return existing
 
   const promise = probeProcBind(bwrap)
-    .then(({ safe, cacheable }) => {
-      if (cacheable) procBindProbeCache.set(bwrap, safe)
-      return safe
+    .then(({ verdict, cacheable }) => {
+      if (cacheable) procBindProbeCache.set(bwrap, verdict)
+      return verdict
     })
     .finally(() => {
       procBindProbeInFlight.delete(bwrap)
@@ -176,9 +199,53 @@ export function canBindProcSafely(options?: { bwrapPath?: string }): Promise<boo
   return promise
 }
 
+// Boolean convenience wrapper: 'safe' is the ONLY verdict that makes proc-bind
+// selectable. 'unsafe' AND 'inconclusive' both map to false — callers that only
+// take a boolean (and do not own a retry budget) must fail closed on either.
+// Derives from the deduped verdict probe, so concurrent callers still share one
+// spawn even though this wrapper's own promise identity differs per call.
+export function canBindProcSafely(options?: { bwrapPath?: string }): Promise<boolean> {
+  return getProcBindSafetyVerdict(options).then((verdict) => verdict === 'safe')
+}
+
+// Default backoff between proc-bind safety re-probes, in ms. Array length = retry
+// count (2 retries after the initial attempt = 3 probes total). The probe is
+// normally sub-ms; it only returns 'inconclusive' under transient CPU/IO
+// contention (e.g. a boot-time storm of concurrent LLM calls saturating the box
+// and tripping the probe's own timeout), so a short staggered wait lets the spike
+// pass before re-proving.
+export const PROC_BIND_RETRY_BACKOFF_MS = [250, 1_000] as const
+
+// proc-bind selection must distinguish "definitely unavailable" from "couldn't
+// verify right now". A DEFINITIVE verdict is final: 'safe'→true; a real userns
+// leak ('unsafe')→false with NO retry. Only an 'inconclusive' verdict (transient
+// probe failure that proves nothing about the host) is retried, because degrading
+// the bash call to tmpfs over a transient hiccup is what silently broke
+// external-package runs on capable hosts. 'inconclusive' is never cached
+// (see the cache type), so each retry re-probes from scratch. After the backoff
+// budget is exhausted we fail CLOSED — an unverified leak-block is never treated
+// as safe. Pure and dependency-injected (probe + sleep) so the retry policy is
+// unit-testable without spawning processes; production passes
+// getProcBindSafetyVerdict and Bun.sleep.
+export async function resolveProcBindSafetyWithRetry(
+  probe: () => Promise<ProcBindSafetyVerdict>,
+  sleep: (ms: number) => Promise<void>,
+  backoffMs: readonly number[] = PROC_BIND_RETRY_BACKOFF_MS,
+): Promise<boolean> {
+  for (let attempt = 0; ; attempt++) {
+    const verdict = await probe()
+    if (verdict === 'safe') return true
+    if (verdict === 'unsafe') return false
+
+    const backoff = backoffMs[attempt]
+    if (backoff === undefined) return false
+    await sleep(backoff)
+  }
+}
+
 const PROC_BIND_PROBE_SECRET = 'TYPECLAW_PROCBIND_PROBE_SECRET'
 
-const INCONCLUSIVE: ProcBindProbe = { safe: false, cacheable: false }
+const INCONCLUSIVE: ProcBindProbe = { verdict: 'inconclusive', cacheable: false }
 
 async function probeProcBind(bwrap: string): Promise<ProcBindProbe> {
   // The sentinel must model the REAL threat geometry: the agent runtime holds
@@ -277,13 +344,13 @@ async function probeProcBind(bwrap: string): Promise<ProcBindProbe> {
     // "non-zero" — a non-zero exit also covers script setup failures (a bwrap that
     // started but couldn't read /proc/self/fd), bwrap startup failures (missing
     // lib, transient mount EBUSY → bwrap's own exit), and an external SIGKILL.
-    // Caching any of those transient failures as a definitive safe=false would
+    // Caching any of those transient failures as a definitive 'unsafe' would
     // PERMANENTLY disable proc-bind — the same cache-poisoning class as the
     // timeout bug. So only the script's two designated codes are cacheable:
     // PROC_BIND_SAFE (clean run, every open blocked) and PROC_BIND_LEAK (an open
     // SUCCEEDED — a real leak). Setup failures use PROC_BIND_SETUP_FAILED, and any
     // other code (bwrap startup, signals, 127) is treated as inconclusive.
-    if (proc.exitCode === PROC_BIND_LEAK) return { safe: false, cacheable: true }
+    if (proc.exitCode === PROC_BIND_LEAK) return { verdict: 'unsafe', cacheable: true }
     if (proc.exitCode !== PROC_BIND_SAFE) return INCONCLUSIVE
     // Final liveness: the in-sandbox blocked-open assertions are only meaningful
     // if the sentinel was alive throughout. Re-read its MARKER from the PARENT —
@@ -293,12 +360,13 @@ async function probeProcBind(bwrap: string): Promise<ProcBindProbe> {
     // kernel liveness, so this marker re-read is the stronger postcondition. A
     // failure here means the sentinel vanished mid-probe → inconclusive.
     if (!(await parentReadsSentinelMarker(sentinelPid))) return INCONCLUSIVE
-    return { safe: true, cacheable: true }
+    return { verdict: 'safe', cacheable: true }
   } catch {
     return INCONCLUSIVE
   } finally {
     try {
       sentinel?.kill()
+      await sentinel?.exited.catch(() => {})
     } catch {
       // killing an already-exited sentinel can throw on some runtimes; cleanup
       // must never propagate out of the probe.

package/src/sandbox/build.ts

@@ -1,3 +1,5 @@
+import { posix } from 'node:path'
+
 import { SandboxPolicyError } from './errors'
 import {
   DEFAULT_SANDBOX_ENV,
@@ -8,6 +10,8 @@ import {
 } from './policy'
 import { formatCommand } from './quote'
 
+const { dirname } = posix
+
 export type SandboxedCommand = {
   argv: string[]
   commandString: string
@@ -163,9 +167,11 @@ function buildArgv(command: string, policy: SandboxPolicy): string[] {
     appendMount(argv, mount)
   }
 
+  appendWritableRoot(argv, policy)
   appendMasks(argv, policy)
   appendWritable(argv, policy)
   appendProtected(argv, policy)
+  appendSymlinks(argv, policy)
 
   if (policy.cwd !== undefined) {
     argv.push('--chdir', policy.cwd)
@@ -175,6 +181,15 @@ function buildArgv(command: string, policy: SandboxPolicy): string[] {
   return argv
 }
 
+// Renders BEFORE appendMasks so the broad RW root is overridden by the secret
+// masks and protected re-binds that follow (last-op-wins). See
+// SandboxWritableRootPolicy for the full ordering contract.
+function appendWritableRoot(argv: string[], policy: SandboxPolicy): void {
+  if (policy.writableRoot !== undefined) {
+    argv.push('--bind', policy.writableRoot.dir, policy.writableRoot.dir)
+  }
+}
+
 function appendMasks(argv: string[], policy: SandboxPolicy): void {
   for (const dir of policy.masks?.dirs ?? []) {
     argv.push('--tmpfs', dir)
@@ -202,6 +217,18 @@ function appendProtected(argv: string[], policy: SandboxPolicy): void {
   }
 }
 
+// Rendered after every bind (incl. the /tmp session bind in policy.mounts) so
+// last-op-wins keeps the symlink: a `/tmp/.foo` dest emitted before the /tmp
+// bind would be erased by it. `--dir` ensures the symlink's parent exists inside
+// the jail (the sandbox HOME dir may not be present after --clearenv tmpfs
+// scaffolding); `--symlink TARGET DEST` then creates `dest -> target`.
+function appendSymlinks(argv: string[], policy: SandboxPolicy): void {
+  for (const link of policy.symlinks ?? []) {
+    argv.push('--dir', dirname(link.dest))
+    argv.push('--symlink', link.target, link.dest)
+  }
+}
+
 function appendMount(argv: string[], mount: SandboxMount): void {
   switch (mount.type) {
     case 'ro-bind':

package/src/sandbox/index.ts

@@ -4,19 +4,27 @@ export {
   canBindProcSafely,
   canMountRealProc,
   ensureBwrapAvailable,
+  getProcBindSafetyVerdict,
+  PROC_BIND_RETRY_BACKOFF_MS,
+  resolveProcBindSafetyWithRetry,
   resolveProcSelfExe,
+  type ProcBindSafetyVerdict,
   _resetBwrapAvailabilityCacheForTests,
   _resetProcBindProbeCacheForTests,
   _resetRealProcProbeCacheForTests,
 } from './availability'
 export { resolveHiddenPaths, type HiddenPaths } from './hidden-paths'
 export {
+  resolvePackageInstallZones,
   resolveProtectedZones,
   resolveWritableZones,
   subtractMasked,
+  type PackageInstallZones,
   type ProtectedZones,
   type WritableZones,
 } from './writable-zones'
+export { resolveSandboxSymlinks, type SandboxSymlinkSpec } from './symlinks'
+export { isPackageInstallCommand } from './package-install'
 export { ensureSessionTmpDir, isUnderTmp, mapVirtualTmpPath, SESSION_TMP_ROOT, sessionTmpDir } from './session-tmp'
 export { formatCommand, shellQuote } from './quote'
 export { SandboxPolicyError, SandboxUnavailableError } from './errors'
@@ -30,5 +38,7 @@ export {
   type SandboxProcessPolicy,
   type SandboxProcStrategy,
   type SandboxProtectedPolicy,
+  type SandboxSymlinkOp,
   type SandboxWritablePolicy,
+  type SandboxWritableRootPolicy,
 } from './policy'

package/src/sandbox/package-install.ts

@@ -0,0 +1,23 @@
+// Recognizes the narrow command class that earns the package-install sandbox
+// mode (RW project root). Deliberately conservative: a single standalone local
+// `bun add` / `bun install` / `bun i` with NO shell metacharacters, chaining,
+// redirects, or substitution. Anything fancier (`bun add x && rm -rf …`,
+// `bun add x; curl …`, a subshell, a pipe) falls back to the default ro-root
+// jail so the broad RW root can never be piggybacked onto an attacker-controlled
+// second command. Global installs (`-g` / `--global`) are excluded — the
+// bun-hygiene guard already blocks them and they write outside the jail anyway.
+const SHELL_METACHARACTERS = /[;&|`$()<>\\\n\r{}!*?[\]"']/
+
+const GLOBAL_FLAG = /^(-g|--global)$/
+
+export function isPackageInstallCommand(command: string): boolean {
+  if (SHELL_METACHARACTERS.test(command)) return false
+
+  const words = command.trim().split(/\s+/)
+  if (words[0] !== 'bun') return false
+
+  const subcommand = words[1]
+  if (subcommand !== 'add' && subcommand !== 'install' && subcommand !== 'i') return false
+
+  return !words.some((word) => GLOBAL_FLAG.test(word))
+}

package/src/sandbox/policy.ts

@@ -83,6 +83,35 @@ export type SandboxProtectedPolicy = {
   files?: string[]
 }
 
+// Symlinks recreated INSIDE the jail so a CLI that reads a fixed path (e.g.
+// `$HOME/.metabase-cli`) resolves to a writable target under /agent. `dest` is
+// the symlink location resolved against the SANDBOX HOME (/tmp), `target` is the
+// absolute /agent path it points at. Rendered last (after the /tmp bind and all
+// writable binds) so last-op-wins keeps the symlink — a `/tmp/...` dest emitted
+// before the /tmp bind would be erased by it.
+export type SandboxSymlinkOp = {
+  target: string
+  dest: string
+}
+
+// A single RW bind of the project root, used ONLY by the package-install path
+// (recognized standalone `bun add`/`bun install` commands). `bun add` writes
+// node_modules/ AND a temp lockfile (`bun.lock.NNN.tmp`, atomically renamed)
+// directly under the root, so a file-level RW bind of `bun.lock` alone is
+// insufficient — Bun needs DIRECTORY write to create its temp file. The default
+// ro-root + narrow carve-out model can't express that, so this widens the root
+// to RW for that command class only.
+//
+// CRITICAL ordering: unlike `writable` (rendered AFTER masks), `writableRoot`
+// renders BEFORE masks so the broad RW root does not re-expose secrets. With
+// last-op-wins the chain is: ro-bind root → writableRoot (RW root) → masks
+// (re-hide .env/secrets.json/private dirs) → protected (re-RO node_modules/typeclaw,
+// packages, .agents/skills, .git/hooks, .git/config). Everything stays hidden or
+// EROFS except the dirs a dependency install legitimately needs to write.
+export type SandboxWritableRootPolicy = {
+  dir: string
+}
+
 export type SandboxPolicy = {
   bwrapPath?: string
   cwd?: string
@@ -95,9 +124,11 @@ export type SandboxPolicy = {
   // the builder stays pure.
   procSelfExe?: string
   mounts?: SandboxMount[]
+  writableRoot?: SandboxWritableRootPolicy
   masks?: SandboxMaskPolicy
   writable?: SandboxWritablePolicy
   protected?: SandboxProtectedPolicy
+  symlinks?: SandboxSymlinkOp[]
   network?: SandboxNetwork
   env?: SandboxEnvPolicy
   commandFilter?: SandboxCommandFilter

package/src/sandbox/symlinks.ts

@@ -0,0 +1,34 @@
+import { posix } from 'node:path'
+
+import type { SandboxSymlinkOp } from './policy'
+
+const { isAbsolute, join, normalize } = posix
+
+export type SandboxSymlinkSpec = {
+  from: string
+  to: string
+}
+
+// Resolves config `sandbox.symlinks` into the in-jail `--symlink` ops the bwrap
+// builder consumes. `from` is the symlink LOCATION: a `~/`-prefixed `from` is
+// expanded against the SANDBOX HOME (`/tmp`, where the per-session tmp dir is
+// bound), NOT the container's real `/root` — inside the jail a CLI reading
+// `$HOME/.foo` looks under `/tmp`, so the symlink must live there. An absolute
+// `from` is used verbatim. `to` is resolved to the absolute /agent path the
+// symlink points at. Container paths are always POSIX, so this uses posix path
+// ops regardless of the dev-stage host OS.
+export function resolveSandboxSymlinks(
+  agentDir: string,
+  specs: readonly SandboxSymlinkSpec[],
+  sandboxHome: string,
+): SandboxSymlinkOp[] {
+  return specs.map((spec) => ({
+    target: join(agentDir, spec.to),
+    dest: resolveSymlinkDest(spec.from, sandboxHome),
+  }))
+}
+
+function resolveSymlinkDest(from: string, home: string): string {
+  if (from.startsWith('~/')) return join(home, from.slice(2))
+  return isAbsolute(from) ? normalize(from) : join(home, from)
+}

package/src/sandbox/writable-zones.ts

@@ -1,4 +1,4 @@
-import { lstat, mkdir, readFile, writeFile } from 'node:fs/promises'
+import { lstat, mkdir, readdir, readFile, realpath, writeFile } from 'node:fs/promises'
 import path, { isAbsolute, join, resolve } from 'node:path'
 
 export type WritableZones = {
@@ -35,6 +35,25 @@ export type ProtectedZones = {
 // exactly that escalation.
 const WRITABLE_DIRS = ['workspace', 'public', 'mounts', '.git'] as const
 
+// SECURITY: configured writable paths (`sandbox.writablePaths`) may NOT resolve
+// onto these. `.git` carries the hook/config escalation surface; `.env` and
+// `secrets.json` are the credential files; `sessions`/`memory` are the agent's
+// private surface (masked from low-trust roles by hidden-paths); `.typeclaw`
+// holds system-managed home persistence; `node_modules` is executable
+// dependency code. Granting blanket RW to any of these via config would defeat
+// the very guards the narrow built-in set exists to preserve. The agent root
+// itself is also rejected (a writablePaths of '' or '.') — an RW bind of the
+// whole tree erases the read-only confinement wholesale.
+const FORBIDDEN_WRITABLE_ROOTS = [
+  '.git',
+  '.env',
+  'secrets.json',
+  'sessions',
+  'memory',
+  '.typeclaw',
+  'node_modules',
+] as const
+
 const PROTECTED_GIT_DIRS = ['.git/hooks'] as const
 const PROTECTED_GIT_FILES = ['.git/config'] as const
 
@@ -54,16 +73,157 @@ const WRITABLE_ROOT_FILES = [
 // 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(
+//
+// `configuredWritablePaths` are operator-chosen agent-relative dirs from
+// `sandbox.writablePaths`. They join the built-in dirs through the SAME
+// existence + symlink filter, plus the extra guardrails in
+// `resolveConfiguredWritableDirs`: each must resolve inside agentDir and must
+// not land on a forbidden root. A path that fails any check is dropped, never
+// throws — a stale config should degrade the one bad entry, not abort sandboxing.
+export async function resolveWritableZones(
+  agentDir: string,
+  configuredWritablePaths: readonly string[] = [],
+): Promise<WritableZones> {
+  const builtinDirs = await collectExisting(
     WRITABLE_DIRS.map((d) => join(agentDir, d)),
     'dir',
   )
+  const configuredDirs = await resolveConfiguredWritableDirs(agentDir, configuredWritablePaths)
   const files = await collectExisting(
     WRITABLE_ROOT_FILES.map((f) => join(agentDir, f)),
     'file',
   )
-  return { dirs, files }
+  return { dirs: dedupe([...builtinDirs, ...configuredDirs]), files }
+}
+
+// SECURITY: validation is on the REAL path, not the lexical one. A lexical-only
+// check (resolve + isInside) is bypassable by a symlinked INTERMEDIATE component:
+// with `/agent/alias -> /tmp/outside` (or `-> /agent/sessions`) and a config of
+// `alias/sub`, the lexical path `/agent/alias/sub` passes isInside and the
+// forbidden-root check, while the bwrap `--bind` follows the ancestor symlink to
+// write outside /agent (or onto a forbidden root). The zone-root lstat alone
+// can't see it — lstat of the final component follows ancestor symlinks. So we
+// realpath BOTH the candidate and agentDir (+ the forbidden roots) and validate
+// the resolved targets. A path whose real form escapes agentDir or lands on a
+// real forbidden root is dropped. realpath also rejects the final component
+// being a symlink (its real target is re-checked), subsuming the prior lstat.
+async function resolveConfiguredWritableDirs(agentDir: string, configured: readonly string[]): Promise<string[]> {
+  const realAgentDir = await realpathOrUndefined(agentDir)
+  if (realAgentDir === undefined) return []
+  const realForbidden = await resolveRealForbiddenRoots(agentDir)
+
+  const accepted: string[] = []
+  for (const rel of configured) {
+    const absolute = resolve(agentDir, rel)
+    // Cheap lexical pre-filter: reject obvious escapes before touching the disk.
+    if (absolute === agentDir || !isInside(agentDir, absolute)) continue
+    const real = await realpathOrUndefined(absolute)
+    if (real === undefined) continue
+    if (!(await isRealEntry(real, 'dir'))) continue
+    if (real === realAgentDir || !isInside(realAgentDir, real)) continue
+    if (realForbidden.some((root) => real === root || isInside(root, real))) continue
+    // Bind the lexical (caller-facing) path; bwrap resolves it to `real` itself.
+    accepted.push(absolute)
+  }
+  return accepted
+}
+
+async function resolveRealForbiddenRoots(agentDir: string): Promise<string[]> {
+  const resolved: string[] = []
+  for (const root of FORBIDDEN_WRITABLE_ROOTS) {
+    const real = await realpathOrUndefined(join(agentDir, root))
+    if (real !== undefined) resolved.push(real)
+  }
+  return resolved
+}
+
+async function realpathOrUndefined(target: string): Promise<string | undefined> {
+  try {
+    return await realpath(target)
+  } catch {
+    return undefined
+  }
+}
+
+function dedupe(values: string[]): string[] {
+  return [...new Set(values)]
+}
+
+export type PackageInstallZones = {
+  root: string
+  protected: ProtectedZones
+}
+
+// SECURITY: the package-install RW root is governed by an ALLOWLIST, not a
+// denylist. `bun add` writes exactly these and nothing else: `node_modules/`
+// (deps), `package.json` + `bun.lock` (manifest + lockfile, plus the temp
+// lockfile created in the root DIR). The scratch zones (`workspace`, `public`,
+// `mounts`) stay writable to match the normal jail. EVERY other existing root
+// entry is RO-bound, so a denylist of "executable/runtime-sensitive" paths is
+// not needed — it would be unbounded (any file the unsandboxed runtime reads or
+// execs, including `src/`/`scripts/` in dev-mode agents where typeclaw is a
+// file:/link: dep, the agent's own lifecycle scripts, and prompt-source files)
+// and fails OPEN for any root entry not yet listed. An allowlist fails CLOSED.
+const PACKAGE_INSTALL_WRITABLE_DIRS = ['node_modules', 'workspace', 'public', 'mounts'] as const
+const PACKAGE_INSTALL_WRITABLE_FILES = ['package.json', 'bun.lock'] as const
+
+// Resolves the jail layout for a recognized standalone dependency install
+// (`bun add` / `bun install`). The RW root lets bun create node_modules/ and its
+// temp lockfile (`bun.lock.NNN.tmp`, renamed) — a file-level bind of `bun.lock`
+// alone cannot, since the temp file needs DIRECTORY write. Pre-creates an empty
+// node_modules/ so the dir exists before the RW root bind. Then RO-binds every
+// EXISTING root entry not in the writable allowlist (readdir enumeration, so a
+// new file like `src/` or a planted `cron.json` is covered without a hardcoded
+// list), plus `node_modules/typeclaw` (the live/symlinked runtime, nested under
+// the writable node_modules) and the whole `.git` (a `bun add` never needs git,
+// so RO-binding it wholesale is simpler and safer than the hooks/config carve-out
+// — it closes the hook / core.hooksPath escalation by construction).
+//
+// SECURITY: rejects a symlink at agentDir, at any install-touched path
+// (node_modules, package.json, bun.lock), and at every RO-bind source — an RW
+// root or an RO bind that follows a symlink would write/read outside the jail.
+// The secret/private masks render AFTER this protected set (subtractMasked in
+// applyBashSandbox drops any protected entry a mask already hides), so .env /
+// secrets.json / memory / sessions stay hidden, not merely RO.
+export async function resolvePackageInstallZones(agentDir: string): Promise<PackageInstallZones> {
+  await assertNotSymlink(agentDir)
+  await mkdir(join(agentDir, 'node_modules'), { recursive: true })
+  for (const rel of ['node_modules', ...PACKAGE_INSTALL_WRITABLE_FILES] as const) {
+    const target = join(agentDir, rel)
+    if (await exists(target)) await assertNotSymlink(target)
+  }
+
+  const writable = new Set<string>([...PACKAGE_INSTALL_WRITABLE_DIRS, ...PACKAGE_INSTALL_WRITABLE_FILES])
+  const dirs: string[] = []
+  const files: string[] = []
+  for (const entry of await readdir(agentDir, { withFileTypes: true })) {
+    if (writable.has(entry.name)) continue
+    // A symlinked root entry is skipped, not RO-bound: an RO bind follows it to
+    // an outside target. Skipping leaves it under the RW root — but it is the
+    // agent's OWN symlink under its OWN root, contained by the agent-folder bind
+    // and the always-on kernel invariants, the same residual the default jail
+    // accepts for symlinks pointing outside /agent.
+    if (entry.isSymbolicLink()) continue
+    const target = join(agentDir, entry.name)
+    if (entry.isDirectory()) dirs.push(target)
+    else if (entry.isFile()) files.push(target)
+  }
+
+  // node_modules itself is writable (deps land there), but the runtime under it
+  // must not be — RO-bind it nested, last-op-wins over the writable node_modules.
+  const runtime = join(agentDir, 'node_modules', 'typeclaw')
+  if (await isRealEntry(runtime, 'dir')) dirs.push(runtime)
+
+  return { root: agentDir, protected: { dirs: dedupe(dirs), files: dedupe(files) } }
+}
+
+async function exists(target: string): Promise<boolean> {
+  try {
+    await lstat(target)
+    return true
+  } catch {
+    return false
+  }
 }
 
 // Read-only re-protections rendered on top of the writable .git bind. Unlike

package/src/server/index.ts

@@ -1265,6 +1265,10 @@ function handleInspectMessage(
     ws.close()
     return
   }
+  if (msg.type === 'ping') {
+    sendInspect(ws, { type: 'pong', id: msg.id })
+    return
+  }
   if (msg.type !== 'subscribe' || typeof msg.sessionId !== 'string' || msg.sessionId === '') {
     sendInspect(ws, { type: 'error', message: 'invalid inspect subscription' })
     ws.close()
@@ -1314,7 +1318,7 @@ function handleInspectMessage(
     })
   }
 
-  sendInspect(ws, { type: 'subscribed', sessionId: msg.sessionId, sessionLive: live !== undefined })
+  sendInspect(ws, { type: 'subscribed', sessionId: msg.sessionId, sessionLive: live !== undefined, supportsPing: true })
 }
 
 function extractJobId(target: StreamMessage['target']): string {

package/src/shared/protocol.ts

@@ -44,16 +44,22 @@ export type TunnelLogsServerMessage =
   | { type: 'error'; message: string }
   | { type: 'end' }
 
-export type InspectClientMessage = {
-  type: 'subscribe'
-  sessionId: string
-  // sinceMs is a wall-clock cutoff for backfilling broadcasts from the
-  // in-process Stream ring buffer. The client uses Date.now() - duration;
-  // omit to skip broadcast backfill. AgentSession events are NEVER
-  // backfilled (the session's pi-coding-agent subscribe API delivers
-  // future events only).
-  sinceMs?: number
-}
+export type InspectClientMessage =
+  | {
+      type: 'subscribe'
+      sessionId: string
+      // sinceMs is a wall-clock cutoff for backfilling broadcasts from the
+      // in-process Stream ring buffer. The client uses Date.now() - duration;
+      // omit to skip broadcast backfill. AgentSession events are NEVER
+      // backfilled (the session's pi-coding-agent subscribe API delivers
+      // future events only).
+      sinceMs?: number
+    }
+  // Steady-state liveness probe echoed back as a pong. A live tail is
+  // legitimately quiet for long stretches, so absence of inbound frames cannot
+  // distinguish "idle" from "dead"; a missed pong can. Guards a wedged
+  // WebSocket that stays ESTABLISHED yet never fires 'close'/'error'.
+  | { type: 'ping'; id: number }
 
 export type InspectFramePayload =
   | { kind: 'text_delta'; sessionId: string; delta: string }
@@ -123,9 +129,14 @@ export type InspectFramePayload =
     }
 
 export type InspectServerMessage =
-  | { type: 'subscribed'; sessionId: string; sessionLive: boolean }
+  // supportsPing is the heartbeat capability flag. A pre-heartbeat server omits
+  // it; the client must treat its absence as "no ping support" and never send a
+  // ping (an old server answers an unknown ping with an error + close, killing
+  // the tail). Strict opt-in: only an explicit true arms round-trip probing.
+  | { type: 'subscribed'; sessionId: string; sessionLive: boolean; supportsPing?: true }
   | { type: 'frame'; ts: number; payload: InspectFramePayload }
   | { type: 'error'; message: string }
+  | { type: 'pong'; id: number }
 
 export type ClientMessage =
   | { type: 'prompt'; text: string; delivery?: PromptDelivery }