typeclaw 0.23.0 → 0.24.0

package/src/channels/schema.ts

@@ -131,11 +131,26 @@ export const DEFAULT_GITHUB_EVENT_ALLOWLIST = [
   'pull_request_review.submitted',
 ] as const
 
+// Which pull_request webhook action triggers an agent code review. The two
+// event values are GitHub's bare PR action names (the `pull_request.` event
+// prefix is implied by this field living under the review config); `off` is the
+// disable sentinel, matching the `engagement.stickiness: 'off'` convention:
+//   - 'review_requested' — review only when the bot is requested (default)
+//   - 'opened'           — review every PR as soon as it opens
+//   - 'off'              — disable code review entirely
+export const GITHUB_REVIEW_ON_VALUES = ['review_requested', 'opened', 'off'] as const
+
+export type GithubReviewOn = (typeof GITHUB_REVIEW_ON_VALUES)[number]
+
+export const DEFAULT_GITHUB_REVIEW_ON: GithubReviewOn = 'review_requested'
+
 // PR-review policy knobs. Grouped under `review` so future toggles
-// (`requestChanges`, auto-review-on-request, severity thresholds) cluster
-// here instead of flattening onto the channel root.
+// (`requestChanges`, severity thresholds) cluster here instead of flattening
+// onto the channel root.
+//
+// `on` gates which pull_request action triggers a code review (see values above).
 //
-// `approve` gates whether the agent may submit a formal review with
+// `approve` gates *whether* the agent may submit a formal review with
 // `event: APPROVE`. When `false`, the adapter appends an operator-policy note
 // to inbounds and the `typeclaw-channel-github` skill downgrades an `approve`
 // verdict to a `COMMENT` review (findings still posted, no formal approval).
@@ -144,9 +159,10 @@ export const DEFAULT_GITHUB_EVENT_ALLOWLIST = [
 // temp file the command interceptor never sees.
 const githubReviewSchema = z
   .object({
+    on: z.enum(GITHUB_REVIEW_ON_VALUES).default(DEFAULT_GITHUB_REVIEW_ON),
     approve: z.boolean().default(true),
   })
-  .default({ approve: true })
+  .default({ on: DEFAULT_GITHUB_REVIEW_ON, approve: true })
 
 const githubChannelSchema = adapterSchema.extend({
   // Optional now (PR 2): when omitted and a `tunnels[]` entry with

package/src/channels/types.ts

@@ -52,6 +52,9 @@ export type InboundMessage = {
   chat: string
   thread: string | null
   text: string
+  // Prompt-only context for replied-to / quoted / linked messages. Kept out
+  // of `text` so the engagement gate sees only the human-authored body.
+  referenceContext?: InboundReferenceContext
   // Non-text attachments the user sent on this inbound. Empty / omitted
   // when the message is text-only. The router carries these through to
   // the live session's promptQueue/contextBuffer so channel tools can
@@ -94,6 +97,15 @@ export type InboundMessage = {
   // means "unknown" — the formatter renders such lines without a
   // timestamp prefix instead of stamping them with the wrong clock.
   ts: number
+  // Platform-native anchor for showing a typing/status indicator, kept
+  // SEPARATE from `thread` on purpose: `thread` drives reply threading,
+  // this drives ONLY the typing surface. Slack's `assistant.threads.
+  // setStatus` (the bot's only typing signal) requires a real message ts
+  // even in a flat DM, where `thread` is null because replies stay top-
+  // level. The classifier sets this to the inbound message ts for DMs so
+  // the status can render without forcing the reply into a thread. Omitted
+  // for non-DM inbounds, where the typing path falls back to `thread`.
+  typingThread?: string
   // Opaque, adapter-owned handle for the entity an emoji reaction would
   // attach to. The classifier stamps it because only there is the platform-
   // side target type still known (GitHub: issue body vs issue-comment vs
@@ -183,6 +195,10 @@ export type OutboundMessage = {
   // `uploadFile` does not accept a content body or a thread id, see the
   // adapter for the workaround details.
   attachments?: OutboundAttachment[]
+  // Typing-only anchor (see InboundMessage.typingThread), stamped by the
+  // router from the live session so the adapter can CLEAR the status after a
+  // flat DM send — where `thread` is null and would otherwise no-op the clear.
+  typingThread?: string
   // Set by the router (native render mode + anchor fired) so an adapter can
   // reply to the inbound it answers. Telegram/Discord consume `externalMessageId`;
   // `quote`-mode adapters never see this (the router prepends the blockquote into
@@ -207,6 +223,11 @@ export type QuoteAnchorSource = {
   text: string
 }
 
+export type InboundReferenceContext = {
+  kind: 'reply' | 'quote' | 'link'
+  sources: readonly QuoteAnchorSource[]
+}
+
 export type SendErrorCode =
   | 'duplicate'
   | 'turn-cap'
@@ -224,6 +245,10 @@ export type TypingTarget = {
   workspace: string
   chat: string
   thread?: string | null
+  // Typing-only anchor (see InboundMessage.typingThread). An adapter whose
+  // typing surface needs a message ts even when `thread` is null (Slack DMs)
+  // reads this first and falls back to `thread`. Never used for reply routing.
+  typingThread?: string
   // 'tick' is the heartbeat fired during debouncing/generation; adapters
   // should set the indicator visible. 'stop' is fired exactly once when the
   // router decides the turn is over (drain finally, /stop command, or
@@ -280,6 +305,7 @@ export type ChannelHistoryMessage = {
   authorId: string
   authorName: string
   text: string
+  referenceContext?: InboundReferenceContext
   attachments?: readonly InboundAttachment[]
   ts: number
   isBot: boolean
@@ -314,6 +340,48 @@ export type FetchAttachmentResult =
 
 export type FetchAttachmentCallback = (args: FetchAttachmentArgs) => Promise<FetchAttachmentResult>
 
+// A request to resolve (close out) a review-comment thread the bot itself
+// opened, after the author addressed it. Adapter-specific: only the github
+// adapter registers a resolver today. The router carries the request through
+// to that resolver, which is responsible for the platform-side authorship
+// check — `resolveReviewThread` MUST only close a thread whose root comment
+// the bot authored, never a human reviewer's thread. The address fields below
+// are the same ones a `channel_reply` origin carries: `workspace` is the repo
+// slug `owner/name`, `chat` is `pr:<N>`, and `rootCommentId` is the numeric id
+// of the thread's root comment (the `thread` value the inbound carried).
+export type ReviewThreadResolveRequest = {
+  adapter: AdapterId
+  workspace: string
+  chat: string
+  rootCommentId: string
+}
+
+// `already-resolved` is a success-shaped no-op: the thread was closed before we
+// got here (a duplicate turn, a manual resolve), so the desired end state holds
+// and the caller should treat it like `ok: true`. `not-author` is a hard
+// refusal: the root comment is not the bot's, so resolving would erase a
+// human's open question — the caller must NOT proceed as if it closed the loop.
+//
+// `no-match` is the ONLY non-blocking failure: the PR's threads listed cleanly
+// but none is rooted at this comment (already deleted, or the wrong target),
+// so there is genuinely nothing to close and an acknowledgement may still post.
+// Every other code is a hard failure — `not-found` here means an HTTP 404 from
+// the API (a real problem, e.g. wrong repo/PR), NOT "no such thread"; a caller
+// must treat it as blocking so it never claims a thread is settled on a failed
+// or misdirected lookup.
+export type ReviewThreadResolveResult =
+  | { ok: true; alreadyResolved?: boolean }
+  | {
+      ok: false
+      error: string
+      code?: 'not-author' | 'no-match' | 'not-found' | 'unsupported' | 'permission-denied' | 'transient'
+    }
+
+// Registered per-adapter on the ChannelRouter, last-write-wins like the
+// self-identity resolver (one bot account per adapter). Adapters that do not
+// support review threads never register one; the router answers `unsupported`.
+export type ReviewThreadResolver = (req: ReviewThreadResolveRequest) => Promise<ReviewThreadResolveResult>
+
 export function channelKeyId(key: ChannelKey): string {
   return `${key.adapter}:${key.workspace}:${key.chat}:${key.thread ?? ''}`
 }

package/src/cli/inspect-controller.ts

@@ -14,6 +14,8 @@ export type EscController = {
   dispose: () => void
 }
 
+const QUIT_KEY = 0x71
+
 export function createEscController({ debounceMs }: { debounceMs: number }): EscController {
   let currentCtrl: AbortController | null = null
   let pendingEsc: ReturnType<typeof setTimeout> | null = null
@@ -111,6 +113,11 @@ export function createTailScope(opts: { debounceMs: number; input?: RawInput; pr
 
   const onData = (chunk: Buffer): void => {
     if (esc === null) return
+    if (chunk[0] === QUIT_KEY) {
+      // q mirrors dreams' quit key and is symmetric with Ctrl-C in live tail.
+      settle('exit')
+      return
+    }
     const { sigint } = esc.onChunk(chunk)
     if (sigint) settle('exit')
   }

package/src/cli/inspect.ts

@@ -58,6 +58,7 @@ export const inspectCommand = defineCommand({
       selectSession: (sessions, selectOpts) => clackSelect(sessions, selectOpts?.initialSessionId),
       ...(liveSource !== undefined ? { liveSource } : {}),
       createTailScope: () => createTailScope({ debounceMs: ESC_DEBOUNCE_MS }),
+      ...(interactive ? { interactive: true } : {}),
       ...(liveHint !== undefined ? { liveHint } : {}),
       stdout: (line) => process.stdout.write(`${line}\n`),
       stderr: (line) => process.stderr.write(`${line}\n`),
@@ -93,7 +94,7 @@ async function buildLiveSource(cwd: string): Promise<LiveSourceFactory | undefin
 }
 
 function escHintLine(color: boolean): string {
-  const text = '(press esc to return to session list)'
+  const text = '(esc to return to session list · q to quit)'
   return color ? `\u001b[2m${text}\u001b[0m` : text
 }
 

package/src/commands/index.ts

@@ -25,6 +25,13 @@ export type Command<Context> = {
   description: string
   permission?: CommandPermission
   requiresLiveSession?: boolean
+  // Resolve an existing live session into the handler context WITHOUT failing
+  // when none exists (distinct from `requiresLiveSession`, which aborts the
+  // command if no session is live). Used by /restart: it must bounce the
+  // container even from a cold channel, but when a session IS live it needs
+  // that session's identity to write a resume handoff. Ignored when
+  // `requiresLiveSession` is true (that path already resolves the session).
+  wantsLiveSession?: boolean
   handler: CommandHandler<Context>
 }
 
@@ -42,6 +49,7 @@ export type CommandInfo = {
   description: string
   permission: CommandPermission
   requiresLiveSession: boolean
+  wantsLiveSession: boolean
 }
 
 export type CommandResult =
@@ -74,6 +82,7 @@ export function createCommandRegistry<Context>(commands: readonly Command<Contex
     description: command.description,
     permission: command.permission ?? 'session.control',
     requiresLiveSession: command.requiresLiveSession ?? true,
+    wantsLiveSession: command.wantsLiveSession ?? false,
   })
 
   return {

package/src/init/gitignore.ts

@@ -32,16 +32,19 @@ auth.json
 node_modules/
 packages/*/node_modules/
 workspace/
+public/
 mounts/
 Dockerfile
 .DS_Store
 
 # System-managed: gitignored by default so the agent never stages them by hand,
-# but TypeClaw force-commits them on its own schedule (sessions/ via auto-backup,
-# memory/ via the dreaming subagent). Treat them as runtime-owned, not agent-owned.
+# but TypeClaw force-commits them on its own schedule (sessions/ + todo/ via
+# auto-backup, memory/ via the dreaming subagent). Treat them as runtime-owned,
+# not agent-owned.
 sessions/
 memory/
 channels/
+todo/
 `
 }
 

package/src/inspect/index.ts

@@ -34,6 +34,7 @@ export type RunInspectOptions = {
   // caller's loop inspects its own scope intent to tell back from exit.
   signal?: AbortSignal
   liveHint?: string
+  interactive?: boolean
 }
 
 export type SelectSessionOptions = {
@@ -81,6 +82,7 @@ export async function runInspect(opts: RunInspectOptions): Promise<RunInspectRes
     ...(opts.liveSource !== undefined ? { liveSource: opts.liveSource } : {}),
     ...(opts.signal !== undefined ? { signal: opts.signal } : {}),
     ...(opts.liveHint !== undefined ? { liveHint: opts.liveHint } : {}),
+    ...(opts.interactive === true ? { interactive: true } : {}),
   })
   if (streamResult.escToPicker) return { ok: true, exitCode: 0, escToPicker: true }
   return { ok: true, exitCode: 0 }
@@ -146,6 +148,7 @@ async function streamSession(opts: {
   liveSource?: LiveSourceFactory
   signal?: AbortSignal
   liveHint?: string
+  interactive?: boolean
 }): Promise<{ escToPicker: boolean }> {
   if (!opts.json) writeHeader(opts.summary, opts.color, opts.stdout)
   const emit = (event: InspectEvent): void => {
@@ -167,6 +170,18 @@ async function streamSession(opts: {
 
   if (opts.liveSource === undefined) {
     if (!opts.json) opts.stdout('─── end of transcript ───')
+    // Already aborted during replay (user pressed esc/q): honor it, don't lose the keystroke.
+    if (aborted()) return { escToPicker: true }
+    // Interactive replay-only: hold a stable viewer like `dreams` instead of
+    // bouncing straight back to the picker. Block until the tail scope aborts
+    // (esc → back, q/ctrl-c → exit). Never block without a signal (non-TTY has
+    // no listener and would hang) or in json/non-interactive mode (scriptability).
+    if (opts.interactive === true && !opts.json && opts.signal !== undefined) {
+      if (opts.liveHint !== undefined && opts.liveHint !== '') {
+        opts.stdout(divider(opts.color, opts.liveHint))
+      }
+      await waitForAbort(opts.signal)
+    }
     return { escToPicker: aborted() }
   }
 
@@ -208,6 +223,13 @@ function divider(color: boolean, text: string): string {
   return text
 }
 
+export async function waitForAbort(signal: AbortSignal): Promise<void> {
+  if (signal.aborted) return
+  await new Promise<void>((resolve) => {
+    signal.addEventListener('abort', () => resolve(), { once: true })
+  })
+}
+
 function writeHeader(summary: SessionSummary, color: boolean, stdout: (line: string) => void): void {
   const id = shortSessionId(summary.sessionId)
   const label = summary.origin === null ? '(unknown origin)' : originLabel(summary.origin)

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}`
     },
   })
@@ -434,6 +453,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 +533,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,7 @@ function buildArgv(command: string, policy: SandboxPolicy): string[] {
   }
 
   appendMasks(argv, policy)
+  appendWritable(argv, policy)
 
   if (policy.cwd !== undefined) {
     argv.push('--chdir', policy.cwd)
@@ -128,6 +129,15 @@ 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 appendMount(argv: string[], mount: SandboxMount): void {
   switch (mount.type) {
     case 'ro-bind':

package/src/sandbox/index.ts

@@ -1,6 +1,7 @@
 export { buildSandboxedCommand, type SandboxedCommand } from './build'
 export { ensureBwrapAvailable, _resetBwrapAvailabilityCacheForTests } from './availability'
 export { resolveHiddenPaths, type HiddenPaths } from './hidden-paths'
+export { resolveWritableZones, subtractMasked, type WritableZones } from './writable-zones'
 export { formatCommand, shellQuote } from './quote'
 export { SandboxPolicyError, SandboxUnavailableError } from './errors'
 export {
@@ -12,4 +13,5 @@ export {
   type SandboxPolicy,
   type SandboxProcessPolicy,
   type SandboxProcStrategy,
+  type SandboxWritablePolicy,
 } from './policy'

package/src/sandbox/policy.ts

@@ -37,11 +37,21 @@ 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[]
+}
+
 export type SandboxPolicy = {
   bwrapPath?: string
   cwd?: string
   mounts?: SandboxMount[]
   masks?: SandboxMaskPolicy
+  writable?: SandboxWritablePolicy
   network?: SandboxNetwork
   env?: SandboxEnvPolicy
   commandFilter?: SandboxCommandFilter

package/src/sandbox/writable-zones.ts

@@ -0,0 +1,78 @@
+import { lstat } from 'node:fs/promises'
+import path, { join } from 'node:path'
+
+export type WritableZones = {
+  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.
+const WRITABLE_DIRS = ['workspace', 'public', 'mounts'] 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 }
+}
+
+// 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
+  }
+}