typeclaw 0.31.1 → 0.32.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "typeclaw",
-  "version": "0.31.1",
+  "version": "0.32.1",
   "homepage": "https://github.com/typeclaw/typeclaw#readme",
   "bugs": {
     "url": "https://github.com/typeclaw/typeclaw/issues"

package/scripts/verify-procbind-sandbox.sh

@@ -0,0 +1,61 @@
+#!/usr/bin/env bash
+# Manual acceptance check for the default 'proc-bind' sandbox strategy
+# (src/sandbox/build.ts). Not a unit test: it needs a Linux container with bwrap,
+# which the macOS dev host cannot provide, so it lives here as an operator-
+# runnable script instead of a skipIf-everywhere test.
+#
+# The point of proc-bind is that it needs NEITHER `unshare --mount-proc` NOR
+# CAP_SYS_ADMIN — so this runs WITHOUT --cap-add (unlike verify-realproc-sandbox).
+# It proves two properties of `bwrap --unshare-all … --ro-bind /proc /proc`:
+#   1. An external package runner (bunx) runs to completion (no Bun "NotDir").
+#   2. A secret in a sibling process's environment is UNREADABLE from the sandbox
+#      (the --unshare-all child userns blocks cross-userns /proc/<pid>/environ).
+# The signal boundary (kill/ptrace fail EPERM across the userns) is a corollary
+# of the same userns isolation property (2) proves, so it is not re-tested here.
+#
+# Usage: scripts/verify-procbind-sandbox.sh [image]
+#   image defaults to ghcr.io/typeclaw/typeclaw-base:<version-from-package.json>
+set -euo pipefail
+
+IMAGE="${1:-}"
+if [ -z "$IMAGE" ]; then
+  version="$(node -p "require('./package.json').version" 2>/dev/null || echo latest)"
+  IMAGE="ghcr.io/typeclaw/typeclaw-base:${version}"
+fi
+
+secret="TYPECLAW_PROCBIND_LEAK_CANARY_$$"
+
+inner='
+echo "=== bunx via proc-bind sandbox (no CAP_SYS_ADMIN) ==="
+bunx cowsay "proc-bind ok" 2>&1 | tail -6
+echo "bunx exit=$?"
+echo "=== leak scan (sandbox must NOT read the canary holders env) ==="
+found=0
+for f in /proc/[0-9]*/environ; do
+  if tr "\0" "\n" < "$f" 2>/dev/null | grep -q "CANARY_TOKEN"; then
+    echo "LEAK:$f"; found=1
+  fi
+done
+if [ $found -eq 0 ]; then echo "NO_LEAK_CONFIRMED"; else echo "LEAK_DETECTED"; exit 1; fi
+echo "=== self /proc must be usable (the property that makes bunx work) ==="
+test -r /proc/self/fd && test -r /proc/self/maps && echo "SELF_PROC_OK" || { echo "SELF_PROC_MISSING"; exit 1; }
+'
+inner="${inner//CANARY_TOKEN/$secret}"
+
+# The proc-bind argv shape mirrors buildArgv() in src/sandbox/build.ts. Keep in
+# sync if that helper changes. Note: NO `unshare` prefix and NO --cap-add below.
+runner="
+env CANARY=${secret} sleep 120 &
+bwrap --unshare-all \
+      --new-session --die-with-parent --clearenv \
+      --setenv PATH /usr/local/bin:/usr/bin:/bin --setenv HOME /tmp --setenv LANG C.UTF-8 \
+      --ro-bind /usr /usr --ro-bind /etc /etc --dev /dev --tmpfs /tmp \
+      --ro-bind-try /bin /bin --ro-bind-try /sbin /sbin --ro-bind-try /lib /lib --ro-bind-try /lib64 /lib64 \
+      --share-net \
+      --ro-bind /proc /proc \
+      bash -c '$inner'
+"
+
+echo "Image: $IMAGE"
+docker run --rm --security-opt seccomp=unconfined \
+  -e "CANARY=${secret}" "$IMAGE" bash -c "$runner"

package/src/agent/multimodal/look-at.ts

@@ -89,8 +89,10 @@ export function createChannelLookAtTool(router: ChannelRouter, origin: ChannelLo
     name: 'look_at_channel_attachment',
     label: 'Look at channel attachment',
     description:
-      'View an image attached to the current inbound channel message. Inbound messages show ' +
-      '`[<Platform> attachment #N: <kind> <metadata>]`; pass `N` as `attachment_id`. Do not invent ids.',
+      'View an image attached to a channel message. Inbound messages show ' +
+      '`[<Platform> attachment #N: <kind> <metadata>]`; pass `N` as `attachment_id`. Do not invent ids. ' +
+      'Images on the CURRENT inbound resolve directly; for one from an EARLIER message, call channel_history ' +
+      'first to make it resolvable by the same id.',
     parameters: Type.Object({
       attachment_id: Type.Integer({
         description: 'The number N from the inbound `[<Platform> attachment #N: ...]` placeholder.',
@@ -106,10 +108,10 @@ export function createChannelLookAtTool(router: ChannelRouter, origin: ChannelLo
         const validIds = router.listInboundAttachmentIds(origin)
         const validMsg =
           validIds.length === 0
-            ? 'no attachments are present in the current turn'
-            : `valid attachment_ids in this turn: ${validIds.join(', ')}`
+            ? 'no attachments are resolvable right now'
+            : `resolvable attachment_ids: ${validIds.join(', ')}`
         return errorResult(
-          `no attachment with id=${params.attachment_id} in this turn (${validMsg}). Do not call look_at_channel_attachment for attachments that do not appear in the inbound message — they do not exist.`,
+          `no attachment with id=${params.attachment_id} (${validMsg}). For an attachment from an earlier message, call channel_history first to make it resolvable; otherwise do not invent ids that are not in the inbound message.`,
           { count: 0, prompt: params.prompt },
         )
       }

package/src/agent/plugin-tools.ts

@@ -37,6 +37,8 @@ import type {
 } from '@/plugin'
 import {
   buildSandboxedCommand,
+  canBindProcSafely,
+  canMountRealProc,
   ensureBwrapAvailable,
   ensureSessionTmpDir,
   mapVirtualTmpPath,
@@ -44,6 +46,7 @@ import {
   resolveProcSelfExe,
   resolveProtectedZones,
   resolveWritableZones,
+  type SandboxProcStrategy,
   subtractMasked,
 } from '@/sandbox'
 
@@ -599,17 +602,7 @@ async function applyBashSandbox(
   // bwrap does --clearenv, so the overlay must be re-introduced via env.set or
   // it would never reach the sandboxed process (the non-sandboxed spawnHook
   // path does not run when the command is rewritten to a bwrap invocation).
-  // 'real-proc' gives a sandboxed JS package runner a working /proc/self/{fd,
-  // maps} so `bunx`/`bun add`/`bun run <pkg>` stop aborting with Bun's NotDir.
-  // Opt-in (default 'tmpfs') because it makes start.ts grant the container
-  // CAP_SYS_ADMIN at boot. Read from the boot-time `config` snapshot, NOT live
-  // getConfig(): sandbox.realProc is restart-required, and the strategy MUST
-  // track the boot-time capability. A `typeclaw reload` that flips realProc to
-  // true would otherwise make this emit `unshare --mount-proc` in a container
-  // booted WITHOUT CAP_SYS_ADMIN, so the mount fails instead of the old tmpfs
-  // strategy holding until restart. `config` never changes on reload.
-  // procSelfExe is only consumed by the 'tmpfs' branch.
-  const realProc = config.sandbox.realProc
+  const proc = await resolveProcStrategy()
   const { commandString } = buildSandboxedCommand(command, {
     mounts: [
       { type: 'ro-bind', source: agentDir, dest: agentDir },
@@ -620,13 +613,55 @@ async function applyBashSandbox(
     protected: protectedZones,
     network: 'inherit',
     cwd: agentDir,
-    proc: realProc ? 'real-proc' : 'tmpfs',
+    proc,
     procSelfExe: resolveProcSelfExe(),
     ...(envOverlay !== undefined ? { env: { set: envOverlay } } : {}),
   })
   mutableArgs.command = commandString
 }
 
+// Picks the /proc strategy for a sandboxed bash call. The branch order is:
+// 'real-proc' ONLY when the operator explicitly opted in (sandbox.realProc) AND
+// the kernel permits the mount (canMountRealProc) — it adds PID isolation but
+// needs CAP_SYS_ADMIN (unshare --mount-proc), so it is a deliberate, narrow
+// opt-in; else 'proc-bind' (--ro-bind /proc, NO CAP_SYS_ADMIN) when its userns
+// leak-block is verified safe (canBindProcSafely); else 'tmpfs'. Because
+// sandbox.realProc DEFAULTS FALSE, the first branch is normally skipped and
+// proc-bind is the de-facto default — which is the point: the common path needs
+// no broad outer capability. 'tmpfs' is the last-resort degraded mode where
+// external packages can't run; reached only when BOTH probes fail (e.g. a kernel
+// that would leak cross-userns environ — proc-bind fails closed there).
+//
+// Read from the boot-time `config` snapshot, NOT live getConfig(): sandbox is
+// restart-required, and the strategy MUST track the boot-time CAP_SYS_ADMIN
+// grant. A `typeclaw reload` flipping realProc would otherwise emit `unshare
+// --mount-proc` in a container booted WITHOUT the cap (or vice versa). Both
+// probes are cached process-globally, so this resolves to one spawn per
+// container lifetime regardless of how many bash calls hit it.
+async function resolveProcStrategy(): Promise<SandboxProcStrategy> {
+  if (config.sandbox.realProc && (await canMountRealProc())) return 'real-proc'
+  if (await canBindProcSafely()) return 'proc-bind'
+  // Degraded last resort: no working /proc strategy. External package runners
+  // (bunx/bun add/bun run <pkg-bin>) will fail with Bun's opaque "NotDir" because
+  // /proc/self/{fd,maps} are absent. Warn once so an operator on such an exotic
+  // host (no usable user namespaces at all) gets a diagnostic instead of the bare
+  // Bun error. Not gated on parsing the command — that heuristic is fragile (see
+  // PR #696); this is a strategy-level notice, fail-closed and command-agnostic.
+  warnTmpfsProcFallbackOnce()
+  return 'tmpfs'
+}
+
+let tmpfsProcFallbackWarned = false
+function warnTmpfsProcFallbackOnce(): void {
+  if (tmpfsProcFallbackWarned) return
+  tmpfsProcFallbackWarned = true
+  console.warn(
+    '[sandbox] degraded /proc mode: neither real-proc nor proc-bind is available on this host, ' +
+      'so sandboxed external package runners (bunx / bun add / bun run <pkg-bin>) will fail. ' +
+      'This needs a runtime with working user namespaces.',
+  )
+}
+
 // The builtin file tools that take a single filesystem `path` arg. For a
 // sandboxed role they all run UNSANDBOXED in the main process (only bash is
 // bwrap-wrapped), so each must apply the same /tmp -> session-dir mapping that

package/src/agent/session-origin.ts

@@ -129,14 +129,34 @@ type PlatformInfo = {
   // the call would no-op. Keep in sync with the adapters that call
   // `router.registerReaction` (github, slack-bot, discord-bot today).
   supportsReactions: boolean
+  // Whether this adapter's OutboundCallback accepts file attachments. Gates the
+  // "ship a researcher report as a PDF by default" prompt guidance: a report is
+  // only worth converting to a downloadable file on channels that can actually
+  // receive one. GitHub's outbound callback hard-rejects attachments
+  // (`github-bot-does-not-support-attachments` in adapters/github/outbound.ts),
+  // so a PDF nudge there would train the model toward a call that always fails;
+  // the other four upload files (Slack `uploadFile`, Discord `uploadFile`,
+  // Telegram `sendDocument`, KakaoTalk `sendAttachment`). Keep in sync with the
+  // adapters' outbound callbacks.
+  supportsAttachments: boolean
 }
 
 const PLATFORM_INFO: Record<AdapterId, PlatformInfo> = {
-  'slack-bot': { displayName: 'Slack', mentionMode: 'angle-id', supportsReactions: true },
-  'discord-bot': { displayName: 'Discord', mentionMode: 'angle-id', supportsReactions: true },
-  github: { displayName: 'GitHub', mentionMode: 'at-username', supportsReactions: true },
-  'telegram-bot': { displayName: 'Telegram', mentionMode: 'at-username', supportsReactions: false },
-  kakaotalk: { displayName: 'KakaoTalk', mentionMode: 'alias', supportsReactions: false },
+  'slack-bot': { displayName: 'Slack', mentionMode: 'angle-id', supportsReactions: true, supportsAttachments: true },
+  'discord-bot': {
+    displayName: 'Discord',
+    mentionMode: 'angle-id',
+    supportsReactions: true,
+    supportsAttachments: true,
+  },
+  github: { displayName: 'GitHub', mentionMode: 'at-username', supportsReactions: true, supportsAttachments: false },
+  'telegram-bot': {
+    displayName: 'Telegram',
+    mentionMode: 'at-username',
+    supportsReactions: false,
+    supportsAttachments: true,
+  },
+  kakaotalk: { displayName: 'KakaoTalk', mentionMode: 'alias', supportsReactions: false, supportsAttachments: true },
 }
 
 function getPlatformInfo(adapter: AdapterId): PlatformInfo {
@@ -461,6 +481,7 @@ function renderChannelOrigin(
     "matching the channel's `allow` rules are accepted (the tool returns",
     '`{ ok: false }` otherwise).',
     '',
+    ...renderResearchReportDeliveryGuidance(platformInfo),
     ...renderMentionGuidance(platformInfo, origin.participants ?? [], now, origin.self),
   )
 
@@ -496,6 +517,36 @@ function renderMembershipSummary(
   return `This channel has approximately ${total} members (about ${membership.humans} humans, ${membership.bots} bots — the bot count is approximate, the full member list was not enumerated because it exceeds the 50-member cap). The 10 most recent speakers are listed below.`
 }
 
+// The `researcher` subagent always hands back a markdown report file
+// (`research-<slug>.md`) and is itself read-only — it cannot produce the PDF.
+// Whoever delivers that report to a channel is the one who decides the format,
+// and on a channel that accepts file uploads the right default for a multi-page
+// research report is a downloadable PDF, not a wall of raw markdown dumped into
+// chat. This block makes that the default ONLY where it is actionable: gated on
+// `supportsAttachments` so GitHub (whose outbound callback rejects attachments)
+// never gets a nudge toward a `channel_send` call that would fail.
+function renderResearchReportDeliveryGuidance(platformInfo: PlatformInfo): string[] {
+  if (!platformInfo.supportsAttachments) return []
+  return [
+    `**Ship reports as a PDF by default.** ${platformInfo.displayName} accepts file`,
+    'attachments. When the user asks for a report, document, brief, or "the report"',
+    '— or a `researcher` subagent hands you a `research-<slug>.md` file path in its',
+    '`<report>` block — convert that markdown to a PDF with the `typeclaw-markdown-pdf`',
+    'skill and deliver it with `channel_send({ ..., attachments: [{ path, filename }] })`,',
+    'with a one- or two-line summary as the message text. A `researcher` `<summary>`',
+    'is a teaser, NOT the deliverable: the deliverable is the report file rendered to',
+    'PDF. Never build the PDF with an ad-hoc library (jsPDF, pdfkit, a raw-text dump) —',
+    'that yields unrendered markdown and mojibake; the skill is the only correct path.',
+    "For CJK (Korean/Japanese/Chinese) reports, follow that skill's CJK font gate —",
+    'never ship a tofu-rendered PDF; ask before enabling the opt-in `cjkFonts`.',
+    'A downloadable file is what a human wants for a multi-page report; do not paste',
+    'the full markdown into chat, and do not attach the raw `.md` when asked for a',
+    'report or PDF. Send inline plain text only if the caller explicitly asked for it,',
+    'or the content is short enough that a file would be overkill.',
+    '',
+  ]
+}
+
 function renderMentionGuidance(
   platformInfo: PlatformInfo,
   participants: readonly ChannelParticipant[],

package/src/agent/system-prompt.ts

@@ -59,6 +59,12 @@ For any multi-step or long-running task, maintain a todo list with \`todo_write\
 
 Do not narrate routine, low-risk tool calls. Just call the tool. Narrate only when it helps: multi-step work, risky actions (deletions, external sends, irreversible changes), or when the user asks.
 
+## Delivering reports and documents
+
+When the user asks for a *report*, *document*, *brief*, *PDF*, or asks you to *send/show/attach/export* a generated result — anything where the deliverable is a file a human would download, print, or forward — produce a polished file, not a wall of text pasted into chat and not a one-line summary that drops the substance. A summary (yours or a subagent's) is a pointer to the deliverable, never the deliverable itself; when the user asked for the report, ship the report.
+
+To turn Markdown into a PDF, use the bundled \`typeclaw-markdown-pdf\` skill — it is the only supported path and it renders Markdown properly (headings, lists, tables). **Never** hand-roll a PDF with an ad-hoc library (jsPDF, pdfkit, a canvas text dump, a headless-browser raw-text print): those produce unrendered raw \`##\`/\`**\` markup and mojibake for non-Latin text. CJK fonts are opt-in, so for Korean/Japanese/Chinese reports follow that skill's CJK gate — never ship a tofu-rendered PDF; ask before enabling opt-in CJK fonts. If a request is plainly satisfied by inline chat — a short answer, a snippet, a quick explanation — stay inline; this rule is for explicit document deliverables, not for every long reply.
+
 ## Long-running and interactive shell work
 
 Foreground \`bash\` blocks your turn until exit, so a command that runs for minutes or waits for input (dev server, REPL, watcher, \`docker compose up\`, interactive installer) freezes the conversation. \`tmux\` is in the container — run such programs detached so your turn stays free:

package/src/agent/tools/channel-fetch-attachment.ts

@@ -37,11 +37,12 @@ export function createChannelFetchAttachmentTool({
     name: 'channel_fetch_attachment',
     label: 'Channel Fetch Attachment',
     description:
-      'Download a file the user attached to the current inbound channel message and save it to disk. Inbound channel ' +
+      'Download a file attached to a channel message and save it to disk. Inbound channel ' +
       'messages with attachments show `[<Platform> attachment #N: <kind> <metadata>]` in the text. Pass `N` as ' +
-      '`attachment_id`; do not invent ids that are not present in the inbound message. The router validates the id ' +
-      'against the current turn and resolves the private platform ref itself. On success returns the absolute path ' +
-      'of the saved file plus its detected mimetype and size.',
+      '`attachment_id`; do not invent ids that are not present in the message. The router resolves the private ' +
+      'platform ref itself. Attachments on the CURRENT inbound message resolve directly; for one from an EARLIER ' +
+      'message, call channel_history first (it makes those attachments resolvable by the same id). On success ' +
+      'returns the absolute path of the saved file plus its detected mimetype and size.',
     parameters: Type.Object({
       attachment_id: Type.Integer({
         description:
@@ -75,10 +76,10 @@ export function createChannelFetchAttachmentTool({
         })
         const validMsg =
           validIds.length === 0
-            ? 'no attachments are present in the current turn'
-            : `valid attachment_ids in this turn: ${validIds.join(', ')}`
+            ? 'no attachments are resolvable right now'
+            : `resolvable attachment_ids: ${validIds.join(', ')}`
         return errorResult(
-          `no attachment with id=${params.attachment_id} in this turn (${validMsg}). Do not call channel_fetch_attachment for attachments that do not appear in the inbound message — they do not exist.`,
+          `no attachment with id=${params.attachment_id} (${validMsg}). For an attachment from an earlier message, call channel_history first to make it resolvable; otherwise do not invent ids that are not in the inbound message.`,
         )
       }
       if (found.ref === '') {

package/src/agent/tools/channel-history.ts

@@ -94,6 +94,8 @@ export function createChannelHistoryTool({
         }
       }
 
+      router.registerHistoryAttachments(origin, result.messages)
+
       const rendered = renderMessages(result.messages)
       const cursorLine =
         result.nextCursor !== undefined

package/src/bundled-plugins/github-cli-auth/gh-command.ts

@@ -37,12 +37,14 @@ type GhSegmentDecision =
 
 const COMPOSITION_REASON =
   'A repo-targeting `gh` command receives a minted GitHub App token in its process ' +
-  'environment, so it must run as a single bare `gh` command — no pipes, `;`, `&&`, ' +
-  '`||`, `&`, newlines, redirections, command/process substitution, subshells, heredocs, ' +
-  'or unquoted `$` expansion (any sibling process or expansion would inherit the token ' +
-  'and could exfiltrate it). jq/JSON metacharacters are fine INSIDE single quotes, e.g. ' +
-  "`gh api repos/o/r --jq '.[] | {id}'`. To feed JSON to `gh api`, write it to a temp " +
-  'file and use `gh api --input <file>`.'
+  'environment, so it must run as a single bare `gh` command — no `;`, `&&`, `||`, `&`, ' +
+  'newlines, redirections, command/process substitution, subshells, heredocs, or unquoted ' +
+  '`$` expansion (any sibling process or expansion would inherit the token and could ' +
+  'exfiltrate it). One exception is allowed: a trailing reader pipeline `gh … | <reader>` ' +
+  'where every downstream stage is a stdin-only reader (`jq`, `cat`, `wc`, `sort`, `uniq`) ' +
+  'with no file operand — e.g. `gh api repos/o/r | jq .`. jq/JSON metacharacters are also ' +
+  "fine INSIDE single quotes, e.g. `gh api repos/o/r --jq '.[] | {id}'`. To feed JSON to " +
+  '`gh api`, write it to a temp file and use `gh api --input <file>`.'
 
 // Shell-active metacharacters that, OUTSIDE single quotes, either spawn another
 // process sharing the shell env (where the minted GH_TOKEN lives) or expand
@@ -140,15 +142,267 @@ export function analyzeGhCommand(command: string): GhCommandDecision {
   const owners = new Set(repoSlugs.map((slug) => slug.split('/')[0]))
   if (owners.size > 1) return { kind: 'block', reason: MULTI_OWNER_REASON }
 
-  // We would inject a token. Enforce the single-bare-`gh` shape: the token
-  // lands in the shell's env, so any sibling/upstream/downstream process or
-  // shell expansion would inherit it.
-  if (!isSingleBareGhCommand(command)) return { kind: 'block', reason: COMPOSITION_REASON }
+  const repoSlug = repoSlugs[0] as string
 
-  if (stripRepoFlag) {
-    return { kind: 'inject', repoSlug: repoSlugs[0] as string, rewrittenCommand: stripRepoFlagFromCommand(command) }
+  // We would inject a token. The token lands in the shell env, so any sibling/
+  // upstream/downstream process or shell expansion would inherit it. The single-
+  // bare-`gh` shape is the safe baseline; a trailing reader pipeline (`gh | jq`)
+  // is the one exception we allow, under strict conditions (see analyzeReaderPipeline).
+  if (isSingleBareGhCommand(command)) {
+    if (stripRepoFlag) return { kind: 'inject', repoSlug, rewrittenCommand: stripRepoFlagFromCommand(command) }
+    return { kind: 'inject', repoSlug }
   }
-  return { kind: 'inject', repoSlug: repoSlugs[0] as string }
+
+  const piped = analyzeReaderPipeline(command, stripRepoFlag)
+  if (piped !== null) return { kind: 'inject', repoSlug, rewrittenCommand: piped }
+
+  return { kind: 'block', reason: COMPOSITION_REASON }
+}
+
+// stdin-only readers whose only sink is stdout (back to the agent, who already
+// has gh's output) — they cannot open their own network/file/process sink, so a
+// `gh <repo> | <reader>` pipeline cannot exfiltrate the minted token to a third
+// party. EXCLUDED on purpose: awk (system()/getline|cmd/inet), sed (GNU `e`
+// shell-exec), tee/xargs (write/spawn), less (`!cmd`), and grep/head/tail (their
+// file-operand forms are too easy to abuse and not worth the parser risk yet).
+const READER_ALLOWLIST = new Set(['jq', 'cat', 'wc', 'sort', 'uniq'])
+
+// STRICT per-command flag allowlists. We allow ONLY flags known to be pure
+// stdin-shaping (no file/program operand). This is allow-known-good, not
+// deny-known-bad: coreutils exposes file reads AND code execution as FLAGS, not
+// just operands — `wc --files0-from=F` and `sort --files0-from=F` open a file
+// with no positional, and `sort --compress-program=PROG` execs a helper. Any
+// such flag would let a downstream "reader" open `/proc/<pid>/environ` and
+// recover the sibling token. So an unrecognized flag REJECTS the whole stage.
+// jq is excluded here (its filter is a positional, handled separately).
+const READER_BOOLEAN_FLAGS: Record<string, ReadonlySet<string>> = {
+  cat: new Set(['-n', '--number', '-b', '--number-nonblank', '-s', '--squeeze-blank', '-A', '--show-all', '-E', '-T']),
+  wc: new Set(['-l', '--lines', '-c', '--bytes', '-m', '--chars', '-w', '--words', '-L', '--max-line-length']),
+  sort: new Set(['-r', '--reverse', '-n', '--numeric-sort', '-u', '--unique', '-f', '--ignore-case', '-b', '-g', '-h']),
+  uniq: new Set(['-c', '--count', '-d', '--repeated', '-u', '--unique', '-i', '--ignore-case']),
+}
+
+// jq is validated allow-known-good, exactly like the coreutils readers: only
+// known stdin-shaping flags pass; anything else rejects the stage. Exact-token
+// deny-listing was unsound — `-f/proc/self/environ`, `-L/proc`, and clustered
+// `-rf/proc/...` short forms slipped past a `Set.has(token)` check and reopened
+// the file-read path. jq accepts NO `--flag=value` form (value flags take the
+// value as a SEPARATE token), so long flags are matched as whole tokens.
+
+// Safe boolean LONG flags: output/parse shaping only, no value, no file/module.
+const JQ_SAFE_BOOLEAN_LONG = new Set([
+  '--raw-output',
+  '--raw-output0',
+  '--compact-output',
+  '--slurp',
+  '--null-input',
+  '--exit-status',
+  '--ascii-output',
+  '--sort-keys',
+  '--raw-input',
+  '--join-output',
+  '--color-output',
+  '--monochrome-output',
+  '--binary',
+  '--tab',
+  '--unbuffered',
+  '--stream',
+  '--stream-errors',
+  '--seq',
+])
+
+// Safe LONG flags that consume a fixed number of FOLLOWING tokens, none a file:
+// --arg/--argjson take 2 (name, value), --indent takes 1 (a number).
+const JQ_SAFE_VALUE_LONG: Record<string, number> = {
+  '--arg': 2,
+  '--argjson': 2,
+  '--indent': 1,
+}
+
+// Safe boolean SHORT flags (single chars). A clustered short token like `-rc`
+// is allowed iff EVERY char is in this set. `f` (filter-from-file) and `L`
+// (module path) are the fatal ones — and any unknown char also rejects.
+const JQ_SAFE_BOOLEAN_SHORT = new Set(['r', 'c', 's', 'n', 'e', 'a', 'S', 'R', 'j', 'C', 'M', 'b'])
+
+// A reader stage is safe only if it is an allowlisted command using ONLY its
+// known stdin-shaping flags, with no file operand. Backslashes are rejected
+// outright: our tokenizer does not model shell backslash escaping, so a
+// `jq \--from-file=…` would be seen as a harmless positional here but reach bash
+// as the forbidden flag — an allowlist-bypass. Rejecting `\` closes that gap.
+function isStdinOnlyReaderStage(stage: string): boolean {
+  if (containsShellActiveMetachar(stage)) return false
+  if (stage.includes('\\')) return false
+  const tokens = splitStageTokens(stage)
+  const cmd = tokens[0]
+  if (cmd === undefined || !READER_ALLOWLIST.has(cmd)) return false
+
+  if (cmd === 'jq') return isStdinOnlyJqStage(tokens)
+
+  const allowedFlags = READER_BOOLEAN_FLAGS[cmd]
+  if (allowedFlags === undefined) return false
+  for (let i = 1; i < tokens.length; i++) {
+    const tok = tokens[i] as string
+    if (!tok.startsWith('-')) return false
+    if (!allowedFlags.has(tok)) return false
+  }
+  return true
+}
+
+// jq must run pure-stdin: only known stdin-shaping flags, and EXACTLY one
+// positional (the filter). A second positional is an input FILE jq would open
+// (`jq . /proc/self/environ` reads that file), so it is rejected. The filter is
+// additionally screened for `import`/`include`, which load modules from jq's
+// default search path even without `-L` — another file-read vector.
+function isStdinOnlyJqStage(tokens: readonly string[]): boolean {
+  let sawFilter = false
+  for (let i = 1; i < tokens.length; i++) {
+    const tok = tokens[i] as string
+    if (tok === '--') return false
+    if (tok.startsWith('--')) {
+      if (JQ_SAFE_BOOLEAN_LONG.has(tok)) continue
+      const consume = JQ_SAFE_VALUE_LONG[tok]
+      if (consume === undefined) return false
+      i += consume
+      continue
+    }
+    if (tok.startsWith('-') && tok.length > 1) {
+      for (const ch of tok.slice(1)) {
+        if (!JQ_SAFE_BOOLEAN_SHORT.has(ch)) return false
+      }
+      continue
+    }
+    if (sawFilter) return false
+    sawFilter = true
+    if (jqFilterLoadsModules(tok)) return false
+  }
+  return true
+}
+
+// jq `import`/`include` directives pull a module file from the search path, a
+// file-read vector that `-L` rejection alone does not cover (the default path
+// still applies). Match them as leading directives in the untrusted filter.
+function jqFilterLoadsModules(filter: string): boolean {
+  return /(^|[;\s])(import|include)\s/.test(filter)
+}
+
+// Splits a single bare `gh ... | reader | reader` pipeline into its stages on
+// TOP-LEVEL `|` only (quote-aware, so a `|` inside a single-quoted jq filter is
+// not a stage boundary), rewriting each downstream reader to run under
+// `/usr/bin/env -u GH_TOKEN`. Returns the rewritten command, or null if the
+// shape is not a leading-`gh` + allowlisted-stdin-readers pipeline. Absolute
+// `/usr/bin/env` (not bare `env`) so the strip can't be defeated by a PATH-
+// shadowed `env`; a missing binary exits 127, failing closed.
+function analyzeReaderPipeline(command: string, stripRepoFlag: boolean): string | null {
+  const stages = splitTopLevelPipeStages(command)
+  if (stages === null || stages.length < 2) return null
+
+  const ghStage = (stages[0] as string).trim()
+  if (!isSingleBareGhCommand(ghStage)) return null
+
+  for (let i = 1; i < stages.length; i++) {
+    if (!isStdinOnlyReaderStage((stages[i] as string).trim())) return null
+  }
+
+  const rewrittenGh = stripRepoFlag ? stripRepoFlagFromCommand(ghStage) : ghStage
+  const rewrittenReaders = stages.slice(1).map((s) => `/usr/bin/env -u GH_TOKEN ${s.trim()}`)
+  return [rewrittenGh, ...rewrittenReaders].join(' | ')
+}
+
+// Quote-aware split on top-level `|`. Returns null if any OTHER shell-active
+// metachar appears outside single quotes (`;` `&` `<` `>` backtick `$` `(` `)`
+// `{` `}` newline) or if a `||`/`|&` is seen — those are not simple pipelines.
+function splitTopLevelPipeStages(command: string): string[] | null {
+  const stages: string[] = []
+  let current = ''
+  let quote: '"' | "'" | null = null
+  for (let i = 0; i < command.length; i++) {
+    const ch = command[i] as string
+    if (quote === "'") {
+      if (ch === "'") quote = null
+      current += ch
+      continue
+    }
+    if (quote === '"') {
+      if (ch === '$' || ch === '`') return null
+      if (ch === '"') quote = null
+      current += ch
+      continue
+    }
+    if (ch === "'" || ch === '"') {
+      quote = ch
+      current += ch
+      continue
+    }
+    if (ch === '|') {
+      const next = command[i + 1]
+      if (next === '|' || next === '&') return null
+      stages.push(current)
+      current = ''
+      continue
+    }
+    if (SHELL_ACTIVE_METACHARS.has(ch) && ch !== '|') return null
+    current += ch
+  }
+  if (quote !== null) return null
+  stages.push(current)
+  return stages
+}
+
+function containsShellActiveMetachar(stage: string): boolean {
+  let quote: '"' | "'" | null = null
+  for (let i = 0; i < stage.length; i++) {
+    const ch = stage[i] as string
+    if (quote === "'") {
+      if (ch === "'") quote = null
+      continue
+    }
+    if (quote === '"') {
+      if (ch === '$' || ch === '`') return true
+      if (ch === '"') quote = null
+      continue
+    }
+    if (ch === "'" || ch === '"') {
+      quote = ch
+      continue
+    }
+    if (SHELL_ACTIVE_METACHARS.has(ch)) return true
+  }
+  return false
+}
+
+// Whitespace-splits a single stage into argv-ish tokens, stripping surrounding
+// quotes so a quoted filter like `'.[] | {id}'` becomes one token. Quote-aware
+// so whitespace inside quotes does not split.
+function splitStageTokens(stage: string): string[] {
+  const tokens: string[] = []
+  let current = ''
+  let has = false
+  let quote: '"' | "'" | null = null
+  for (let i = 0; i < stage.length; i++) {
+    const ch = stage[i] as string
+    if (quote !== null) {
+      if (ch === quote) quote = null
+      else current += ch
+      continue
+    }
+    if (ch === "'" || ch === '"') {
+      quote = ch
+      has = true
+      continue
+    }
+    if (ch === ' ' || ch === '\t') {
+      if (has) {
+        tokens.push(current)
+        current = ''
+        has = false
+      }
+      continue
+    }
+    current += ch
+    has = true
+  }
+  if (has) tokens.push(current)
+  return tokens
 }
 
 // Removes an unquoted `-R`/`--repo` flag (and its repo-slug value) from a single