typeclaw 0.48.10 → 0.48.11

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (33) hide show
  1. package/package.json +1 -1
  2. package/scripts/apparmor/typeclaw-bwrap +43 -0
  3. package/scripts/verify-apparmor-signals.sh +161 -0
  4. package/scripts/verify-mask-fd-sandbox.sh +86 -16
  5. package/src/agent/live-subagents.ts +98 -0
  6. package/src/agent/session-origin.ts +5 -1
  7. package/src/agent/tools/channel-reply.ts +30 -2
  8. package/src/agent/tools/channel-send.ts +19 -2
  9. package/src/agent/tools/spawn-subagent.ts +37 -1
  10. package/src/bundled-plugins/github-cli-auth/index.ts +1 -0
  11. package/src/channels/adapters/github/inbound.ts +195 -25
  12. package/src/channels/adapters/github/index.ts +16 -18
  13. package/src/channels/adapters/github/reconcile-cooldown-store.ts +15 -1
  14. package/src/channels/adapters/github/recover-failed-deliveries.ts +7 -2
  15. package/src/channels/adapters/github/review-submitter.ts +28 -0
  16. package/src/channels/github-repo.ts +11 -0
  17. package/src/channels/github-review-verdict-coordinator.ts +179 -29
  18. package/src/channels/github-verdict-activity.ts +10 -6
  19. package/src/channels/manager.ts +9 -0
  20. package/src/channels/persistence.ts +28 -2
  21. package/src/channels/router.ts +284 -61
  22. package/src/channels/schema.ts +18 -0
  23. package/src/channels/types.ts +1 -0
  24. package/src/config/config.ts +9 -1
  25. package/src/container/start.ts +33 -24
  26. package/src/doctor/apparmor.ts +101 -0
  27. package/src/doctor/checks.ts +2 -0
  28. package/src/init/dockerfile.ts +7 -6
  29. package/src/init/windows-dev-link.ts +34 -2
  30. package/src/run/index.ts +1 -0
  31. package/src/sandbox/availability.ts +7 -5
  32. package/src/skills/typeclaw-channel-github/SKILL.md +4 -2
  33. package/typeclaw.schema.json +7 -0
@@ -185,6 +185,7 @@ export const DEFAULT_GITHUB_EVENT_ALLOWLIST = [
185
185
  'discussion_comment.created',
186
186
  'issues.opened',
187
187
  'pull_request.opened',
188
+ 'pull_request.converted_to_draft',
188
189
  'pull_request.ready_for_review',
189
190
  'pull_request.review_requested',
190
191
  'pull_request.review_request_removed',
@@ -234,6 +235,22 @@ const GITHUB_EVENT_ALLOWLIST_V3 = [
234
235
  'discussion.created',
235
236
  'pull_request_review.submitted',
236
237
  ] as const
238
+ // - v4: added synchronize (the default just before converted_to_draft was
239
+ // added). Snapshotted here so configs seeded with the pre-draft-abort
240
+ // default unfreeze and re-track the new default.
241
+ const GITHUB_EVENT_ALLOWLIST_V4 = [
242
+ 'issue_comment.created',
243
+ 'pull_request_review_comment.created',
244
+ 'discussion_comment.created',
245
+ 'issues.opened',
246
+ 'pull_request.opened',
247
+ 'pull_request.ready_for_review',
248
+ 'pull_request.review_requested',
249
+ 'pull_request.review_request_removed',
250
+ 'pull_request.synchronize',
251
+ 'discussion.created',
252
+ 'pull_request_review.submitted',
253
+ ] as const
237
254
 
238
255
  // Every event-allowlist that `channel add` / `init` has ever seeded verbatim
239
256
  // into typeclaw.json, oldest first, current default last. The legacy-shape
@@ -246,6 +263,7 @@ export const SEEDED_GITHUB_EVENT_ALLOWLISTS: readonly (readonly string[])[] = [
246
263
  GITHUB_EVENT_ALLOWLIST_V1,
247
264
  GITHUB_EVENT_ALLOWLIST_V2,
248
265
  GITHUB_EVENT_ALLOWLIST_V3,
266
+ GITHUB_EVENT_ALLOWLIST_V4,
249
267
  DEFAULT_GITHUB_EVENT_ALLOWLIST,
250
268
  ]
251
269
 
@@ -59,6 +59,7 @@ export type GithubReviewThreadCloseout = {
59
59
  workspace: string
60
60
  prNumber: number
61
61
  rootCommentId: string
62
+ deferUntil?: { kind: 'review-state-unknown'; expiresAt: number }
62
63
  }
63
64
 
64
65
  export type InboundMessage = {
@@ -480,13 +480,21 @@ export const symlinkSchema = z.object({
480
480
 
481
481
  export type SandboxSymlink = z.infer<typeof symlinkSchema>
482
482
 
483
+ // Docker treats the profile as one argument, but keeping the value to the
484
+ // kernel profile-name alphabet prevents whitespace or option-like text from
485
+ // turning a hand-edited config into ambiguous docker argv.
486
+ const apparmorProfileSchema = z
487
+ .string()
488
+ .regex(/^[A-Za-z0-9_.-]+$/, 'AppArmor profile must be non-empty and contain only letters, digits, _, ., or -')
489
+
483
490
  export const sandboxSchema = z
484
491
  .object({
492
+ apparmorProfile: apparmorProfileSchema.default('unconfined'),
485
493
  realProc: z.boolean().default(false),
486
494
  writablePaths: z.array(relativeAgentPathSchema).default([]),
487
495
  symlinks: z.array(symlinkSchema).default([]),
488
496
  })
489
- .default({ realProc: false, writablePaths: [], symlinks: [] })
497
+ .default({ apparmorProfile: 'unconfined', realProc: false, writablePaths: [], symlinks: [] })
490
498
 
491
499
  export type SandboxConfig = z.infer<typeof sandboxSchema>
492
500
 
@@ -870,21 +870,28 @@ export async function planStart({
870
870
  // Operators must `typeclaw restart` (removes and recreates), not
871
871
  // `docker restart` (reuses the old HostConfig).
872
872
  //
873
- // `seccomp=unconfined` lets `bwrap(1)` (installed in baseline; see
874
- // BASELINE_APT_PACKAGES in src/init/dockerfile.ts) create user/pid/mount
875
- // namespaces from inside the container. Docker's default seccomp profile
876
- // rejects `unshare(CLONE_NEWUSER)` and `clone(CLONE_NEWUSER)` for
877
- // non-privileged containers, which is the right default for multi-tenant
878
- // hosts (Kubernetes nodes, CI runners) but wrong for typeclaw: the outer
879
- // container is a single-tenant trust boundary — the user trusts everything
880
- // inside it equally, the .env and agent folder are already mounted in —
881
- // so the multi-tenant protections seccomp adds are not load-bearing for
882
- // typeclaw's threat model. The per-tool sandbox bwrap builds for subagents
883
- // IS the real boundary against prompt-injected commands; that boundary is
884
- // what `--security-opt seccomp=unconfined` exists to enable. See
885
- // `docs/internals/sandbox.mdx` for the full rationale including why
886
- // `--cap-add=SYS_ADMIN` was rejected as an alternative (narrower in
887
- // syscalls but strictly worse in capability semantics).
873
+ // These two security options are a load-bearing pair for `bwrap(1)`
874
+ // (installed in baseline; see BASELINE_APT_PACKAGES in
875
+ // src/init/dockerfile.ts). Docker's default seccomp profile rejects the
876
+ // namespace syscalls, while moby's docker-default AppArmor profile has an
877
+ // explicit `deny mount,` rule that rejects bwrap's opening
878
+ // mount(NULL, "/", MS_SLAVE|MS_REC). Selecting `apparmor=unconfined` removes
879
+ // that mount denial; it selects a profile, it does NOT grant a capability.
880
+ // On stock Ubuntu 23.10+ the host's `unprivileged_userns` catch-all then
881
+ // denies bwrap's /proc/<pid>/uid_map write when
882
+ // kernel.apparmor_restrict_unprivileged_userns=1. The complete path there is
883
+ // the shipped host-loaded `typeclaw-bwrap` profile plus
884
+ // sandbox.apparmorProfile="typeclaw-bwrap"; doctor reports the exact install
885
+ // and restart commands.
886
+ //
887
+ // CAP_SYS_ADMIN is not an alternative: the entrypoint drops to the host's
888
+ // non-root UID with an empty capability set, so Docker's --cap-add grant is
889
+ // void in the production process. These outer defaults are appropriate
890
+ // because the container is a single-tenant trust boundary — the user trusts
891
+ // everything inside it equally, and the .env and agent folder are already
892
+ // mounted in. Seccomp/AppArmor's multi-tenant protections are therefore not
893
+ // load-bearing for this threat model; the per-tool bwrap sandbox is the real
894
+ // boundary against prompt-injected commands. See docs/internals/sandbox.mdx.
888
895
  const runArgs = [
889
896
  'run',
890
897
  '-d',
@@ -894,6 +901,8 @@ export async function planStart({
894
901
  '--shm-size=2g',
895
902
  '--security-opt',
896
903
  'seccomp=unconfined',
904
+ '--security-opt',
905
+ `apparmor=${cfg.sandbox.apparmorProfile}`,
897
906
  '-p',
898
907
  `${publishHost}:${hostPort}:${CONTAINER_PORT}`,
899
908
  ]
@@ -919,17 +928,17 @@ export async function planStart({
919
928
  // sandbox.realProc (default FALSE) opts into the per-tool bwrap sandbox's
920
929
  // 'real-proc' strategy (src/sandbox/build.ts), which prefixes the sandbox with
921
930
  // `unshare --pid --fork --mount --mount-proc`. Mounting a fresh procfs for the
922
- // new PID namespace needs real CAP_SYS_ADMIN — seccomp=unconfined alone is not
923
- // enough (it only unblocks the unshare/clone SYSCALLS; the kernel still
924
- // rejects mount(2) of proc without the capability). So the grant is gated on
925
- // the flag and is OFF by default: external-package execution (`bunx agent-*`)
931
+ // new PID namespace needs real CAP_SYS_ADMIN, so the Docker grant remains
932
+ // gated on the flag and is OFF by default. The entrypoint's production
933
+ // non-root UID clears that cap before the agent starts today, and the runtime
934
+ // capability probe consequently falls back to proc-bind. External-package
935
+ // execution (`bunx agent-*`)
926
936
  // no longer needs it — the default 'proc-bind' strategy gives the runner real
927
937
  // /proc without any outer capability (see docs/internals/sandbox.mdx). Setting
928
- // realProc:true adds the stricter PID-isolation posture at the cost of this
929
- // broad "new root" grant. The container-side strategy resolution still probes
930
- // whether the mount actually works (canMountRealProc) and falls back to
931
- // proc-bind on runtimes where the cap is a no-op (e.g. OrbStack), so this grant
932
- // is necessary-but-not-sufficient by design. Placed before the image tag (like
938
+ // realProc:true requests the stricter PID-isolation posture. The
939
+ // container-side strategy resolution probes whether the mount actually works
940
+ // (canMountRealProc) and falls back to proc-bind when the cap is absent or the
941
+ // runtime rejects the mount (e.g. OrbStack). Placed before the image tag (like
933
942
  // --cap-add=NET_ADMIN) so docker applies it at run time.
934
943
  if (cfg.sandbox.realProc) {
935
944
  runArgs.push('--cap-add=SYS_ADMIN')
@@ -0,0 +1,101 @@
1
+ import { readFile } from 'node:fs/promises'
2
+
3
+ import { loadConfigSync } from '@/config'
4
+
5
+ import type { CheckResult, DoctorCheck } from './types'
6
+
7
+ const APPARMOR_ENABLED_PATH = '/sys/module/apparmor/parameters/enabled'
8
+ const RESTRICT_UNPRIVILEGED_USERNS_PATH = '/proc/sys/kernel/apparmor_restrict_unprivileged_userns'
9
+
10
+ const SHIPPED_PROFILE = 'typeclaw-bwrap'
11
+ const DOCKER_DEFAULT_PROFILE = 'docker-default'
12
+
13
+ const INSTALL_SHIPPED_PROFILE_FIX =
14
+ 'Install the shipped scripts/apparmor/typeclaw-bwrap profile as /etc/apparmor.d/typeclaw-bwrap, run `sudo apparmor_parser -r -W /etc/apparmor.d/typeclaw-bwrap`, set `sandbox.apparmorProfile` to `typeclaw-bwrap`, then run `typeclaw restart`.'
15
+
16
+ export type ApparmorSandboxDeps = {
17
+ readHostFile?: (path: string) => Promise<string | null>
18
+ loadApparmorProfile?: (cwd: string) => string
19
+ }
20
+
21
+ export function apparmorSandbox(deps: ApparmorSandboxDeps = {}): DoctorCheck {
22
+ const readHostFile = deps.readHostFile ?? safeReadHostFile
23
+ const loadApparmorProfile = deps.loadApparmorProfile ?? ((cwd) => loadConfigSync(cwd).sandbox.apparmorProfile)
24
+
25
+ return {
26
+ name: 'container.apparmor-bwrap',
27
+ category: 'container',
28
+ description: 'host AppArmor permits the per-tool bwrap sandbox',
29
+ applies: (ctx) => ctx.hasAgentFolder,
30
+ async run(ctx) {
31
+ const [enabled, restricted] = await Promise.all([
32
+ readHostFile(APPARMOR_ENABLED_PATH),
33
+ readHostFile(RESTRICT_UNPRIVILEGED_USERNS_PATH),
34
+ ])
35
+ if (enabled?.trim() !== 'Y') {
36
+ return { status: 'ok', message: 'host AppArmor is not enabled; no container profile applies' }
37
+ }
38
+
39
+ let profile: string
40
+ try {
41
+ profile = loadApparmorProfile(ctx.cwd)
42
+ } catch {
43
+ return { status: 'ok', message: 'AppArmor profile check deferred until typeclaw.json is valid' }
44
+ }
45
+ return classifyProfile(profile, restricted?.trim() === '1')
46
+ },
47
+ }
48
+ }
49
+
50
+ // Profile FIRST, host sysctl second. docker-default's `deny mount,` rejects
51
+ // bwrap's opening mount(NULL, "/", MS_SLAVE|MS_REC) on any AppArmor-enabled
52
+ // host, so gating that verdict on kernel.apparmor_restrict_unprivileged_userns
53
+ // would report a dead bash surface as healthy. Only the `unconfined` verdict
54
+ // actually depends on the sysctl.
55
+ function classifyProfile(profile: string, restrictedUserns: boolean): CheckResult {
56
+ if (profile === SHIPPED_PROFILE) {
57
+ return { status: 'ok', message: `sandbox uses the shipped ${SHIPPED_PROFILE} AppArmor profile` }
58
+ }
59
+
60
+ // `error`, not `warning`: an unavailable sandbox makes every model bash call
61
+ // throw SandboxUnavailableError (src/sandbox/availability.ts) — the surface is
62
+ // dead, not degraded.
63
+ if (profile === DOCKER_DEFAULT_PROFILE) {
64
+ return {
65
+ status: 'error',
66
+ message: `AppArmor profile ${DOCKER_DEFAULT_PROFILE} denies the mount that sandboxed bash needs, so every bash call fails`,
67
+ fix: { description: INSTALL_SHIPPED_PROFILE_FIX },
68
+ }
69
+ }
70
+
71
+ if (profile === 'unconfined') {
72
+ if (!restrictedUserns) {
73
+ return { status: 'ok', message: 'host AppArmor does not require a custom bwrap profile' }
74
+ }
75
+ return {
76
+ status: 'error',
77
+ message:
78
+ 'stock Ubuntu AppArmor blocks the user namespace required by sandboxed bash when sandbox.apparmorProfile is unconfined',
79
+ fix: { description: INSTALL_SHIPPED_PROFILE_FIX },
80
+ }
81
+ }
82
+
83
+ // A deliberate operator-authored profile. Doctor cannot read
84
+ // /sys/kernel/security/apparmor/profiles unprivileged, so it can neither
85
+ // confirm nor refute this one — say so rather than assert it works.
86
+ return {
87
+ status: 'info',
88
+ message: `sandbox uses custom AppArmor profile ${profile}; typeclaw cannot verify it permits userns, mount, and signal delivery`,
89
+ details: [
90
+ `Compare it against the shipped ${SHIPPED_PROFILE} profile, and run scripts/verify-apparmor-signals.sh against this host to confirm cancellation and container stop/restart still work.`,
91
+ ],
92
+ }
93
+ }
94
+
95
+ async function safeReadHostFile(path: string): Promise<string | null> {
96
+ try {
97
+ return await readFile(path, 'utf8')
98
+ } catch {
99
+ return null
100
+ }
101
+ }
@@ -22,6 +22,7 @@ import { detectMissingDeps } from '@/init/ensure-deps'
22
22
  import { buildGitignore, GITIGNORE_FILE } from '@/init/gitignore'
23
23
  import { detectWsl, isWindows, isWindowsDriveMount, type WslInfo } from '@/shared'
24
24
 
25
+ import { apparmorSandbox } from './apparmor'
25
26
  import { buildChannelChecks } from './channel-checks'
26
27
  import { agentFileOwnership, type FileOwnershipDeps } from './file-ownership'
27
28
  import { buildOperationalIncidentChecks } from './operational-incidents'
@@ -40,6 +41,7 @@ export function buildStaticChecks(opts: { dockerExec?: DockerExec } & FileOwners
40
41
  agentFolderGitRepo(),
41
42
  agentFileOwnership(opts),
42
43
  configValid(),
44
+ apparmorSandbox(),
43
45
  hostdHomeWritable(),
44
46
  wslDriveMount(),
45
47
  windowsSecretPerms(),
@@ -56,12 +56,13 @@ export type BuildDockerfileOptions = {
56
56
  // agent author. See `src/sandbox/` for the bwrap command builder, and
57
57
  // `docs/internals/sandbox.mdx` for why bwrap is the right
58
58
  // shape for per-call isolation inside an already-containerized agent. The
59
- // outer container's `--security-opt seccomp=unconfined` (added in the same
60
- // commit as this line; see `src/container/start.ts:planStart`) is what lets
61
- // bwrap create user/pid/mount namespaces from inside Docker. Without that
62
- // flag the seccomp default profile blocks `unshare(CLONE_NEWUSER)` and bwrap
63
- // fails at startup. The two changes are load-bearing together — do not drop
64
- // one without the other.
59
+ // outer container's `seccomp=unconfined` plus configured AppArmor profile
60
+ // (see `src/container/start.ts:planStart`) let bwrap create user/pid/mount
61
+ // namespaces from inside Docker. Docker's seccomp default blocks userns and
62
+ // docker-default AppArmor explicitly denies mount; on stock Ubuntu 23.10+ the
63
+ // operator must load the shipped typeclaw-bwrap profile because the host's
64
+ // unprivileged_userns catch-all also denies uid_map writes to unconfined
65
+ // processes. The package, options, and host profile are load-bearing together.
65
66
  //
66
67
  // `jq` is in baseline (not behind a toggle) so it is available to the
67
68
  // per-tool bwrap sandbox that wraps agent bash calls. The sandbox only
@@ -47,9 +47,41 @@ export async function linkWindowsDevTypeclaw(
47
47
  ): Promise<string | null> {
48
48
  const platform = options.platform ?? process.platform
49
49
  if (!isWindows(platform)) return null
50
+ const env = options.env ?? process.env
50
51
  const runLink = options.runBunLink ?? defaultRunBunLink
51
- await runLink(typeclawRoot)
52
- return resolveBunLinkedPackage(TYPECLAW_DEP, options.env ?? process.env) ?? typeclawRoot
52
+ try {
53
+ await runLink(typeclawRoot)
54
+ } catch (error) {
55
+ // `bun link` is not idempotent on Windows. It deletes any existing
56
+ // <globalDir>/node_modules/<name> entry and then creates the junction, but
57
+ // the delete is best-effort (its error is discarded) and the pair is not
58
+ // atomic — so a junction that resists deletion, or a second `bun link`
59
+ // racing the first, dies on EEXIST. Re-running `typeclaw init` from a dev
60
+ // checkout then aborts on a step that had nothing left to do. Swallow the
61
+ // failure ONLY when the end state we wanted is already true: the global
62
+ // entry resolves to THIS checkout. An entry pointing at a different
63
+ // checkout, or no entry at all, still propagates, so a link that genuinely
64
+ // failed is never mistaken for a success.
65
+ if (!isLinkedTo(typeclawRoot, env)) throw error
66
+ }
67
+ return resolveBunLinkedPackage(TYPECLAW_DEP, env) ?? typeclawRoot
68
+ }
69
+
70
+ function isLinkedTo(typeclawRoot: string, env: NodeJS.ProcessEnv): boolean {
71
+ const linked = resolveBunLinkedPackage(TYPECLAW_DEP, env)
72
+ if (linked === null) return false
73
+ // Both sides are realpath'd so a junction target compares equal to the
74
+ // checkout path we were handed, and case-folded because Windows paths are
75
+ // case-insensitive while the two resolutions need not agree on casing.
76
+ return linked.toLowerCase() === canonicalize(typeclawRoot).toLowerCase()
77
+ }
78
+
79
+ function canonicalize(path: string): string {
80
+ try {
81
+ return realpathSync(path)
82
+ } catch {
83
+ return path
84
+ }
53
85
  }
54
86
 
55
87
  async function defaultRunBunLink(cwd: string): Promise<void> {
package/src/run/index.ts CHANGED
@@ -504,6 +504,7 @@ async function startAgentRuntime(
504
504
  .list({ parentSessionId: sessionId })
505
505
  .filter((child) => child.status === 'running' && child.background === true)
506
506
  .map((child) => child.subagentName),
507
+ cancelRunningSubagentsByWorkKey: (workKey, reason) => liveSubagentRegistry.cancelRunningByWorkKey(workKey, reason),
507
508
  onReload: async () => {
508
509
  const { results } = await reloadAllNonDestructive()
509
510
  return formatChannelReloadSummary(results)
@@ -64,11 +64,13 @@ export function _resetBwrapAvailabilityCacheForTests(): void {
64
64
  // --mount --mount-proc`, which mounts a fresh procfs in a new PID namespace.
65
65
  // That mount needs REAL CAP_SYS_ADMIN. `typeclaw start` grants the container
66
66
  // `--cap-add=SYS_ADMIN` when sandbox.realProc is on, but the grant is a no-op
67
- // on runtimes that virtualize or strip caps: rootless Docker (userns-capped
68
- // caps), gVisor/runsc (caps never reach the host kernel), Docker Desktop
69
- // Enhanced Container Isolation (intercepts mount), and AppArmor-enforcing
70
- // hosts (Ubuntu 24.04+ restricts unprivileged userns even with the cap). On
71
- // those the `unshare` fails fast with "Operation not permitted" (exit != 0)
67
+ // on runtimes that virtualize or strip caps: the production entrypoint's
68
+ // non-root UID (empty cap set), rootless Docker (userns-capped caps),
69
+ // gVisor/runsc (caps never reach the host kernel), and Docker Desktop Enhanced
70
+ // Container Isolation (intercepts mount). AppArmor hosts need the configured
71
+ // host-loaded profile before bwrap reaches this strategy probe; selecting
72
+ // apparmor=unconfined alone is insufficient on stock Ubuntu 23.10+. On
73
+ // unsupported runtimes `unshare` fails fast with "Operation not permitted"
72
74
  // before bwrap runs. Probing once at the first sandboxed bash call lets the
73
75
  // consumer fall back to the '--tmpfs /proc' strategy instead of failing every
74
76
  // low-trust bash call — restoring the pre-realProc behavior on unsupported
@@ -117,7 +117,7 @@ The `reviewer` subagent is the analyst; you are the integration layer between it
117
117
 
118
118
  **The reviewer's `<review>` block is the only source of the verdict and the findings.** You do not review the PR yourself. Between spawning the reviewer and reading its result you do **no analysis of this PR** — do not run `gh pr diff`, do not read the changed files to form an opinion, do not draft a verdict. The reviewer runs on the `deep` model precisely so this judgment is not yours to make on the parent model. If you analyze the diff and post your own assessment while the reviewer is still running, you will post one verdict now and the reviewer's (often different) verdict when it completes — **two contradictory reviews on the same PR**, the exact failure this flow exists to prevent. Wait for the reviewer; post what it returns; nothing before that.
119
119
 
120
- **Reply-triggered re-review carrier rule.** Obey the session-origin carrier status before delegating. If you are not the carrier, do not spawn a reviewer or publish findings anywhere; once the carrier's verdict lands, close out only your own thread.
120
+ **Reply-triggered re-review carrier rule.** Obey the session-origin carrier status before delegating. If you are not the carrier, do not spawn a reviewer or publish findings anywhere; stay silent with `skip_response` while waiting, then close out only your own thread once the carrier's verdict lands. A "waiting for the verdict" status comment is process narration, not useful review feedback.
121
121
 
122
122
  **HARD RULE — a review with actionable findings is a formal review, never a flat comment.** If the reviewer returns **one or more** actionable findings (`blocker`/`concern`/`nit`), the ONLY acceptable way to deliver them is a formal review via `POST /pulls/<N>/reviews` (step 4) — `REQUEST_CHANGES`, `COMMENT`, or `APPROVE` per the verdict, with the line-anchored findings in `comments[]`. You may **never** flatten those findings into a `channel_reply` or a top-level issue comment, **even when** the `gh api` call fails. A 422 means an anchor is wrong (almost always a `line` not in the diff): re-anchor it or move that one finding into the top-level review `body`, then resubmit the formal review — do **not** abandon the formal review and post prose instead. A flat "## Review … two blockers" comment is a bug, not a fallback: it strands the findings without line anchors and is the exact failure this rule exists to prevent. The flat/issue-comment path is reserved for the **zero-actionable-findings** branch only (see below). **Narrow exception:** when `post_github_review` finds that this bot's identical `CHANGES_REQUESTED` verdict is already effective, the tool itself converts the redundant submission into one substantive root PR comment while the existing formal block remains authoritative. This is a successful tool-managed fallback, not permission to replace a failed or invalid formal review manually. **That conversion fires at most once per pull request per head.** If another session already landed it — a sibling thread session of the same PR is the usual case — your call is denied outright instead, and the denial says the prior verdict is still live. That denial is final: the findings for this head have already been published by the sibling, so **stand down and close out only your own thread**. Do not re-post them as a `channel_reply`, a top-level comment, or a reply in your thread; the HARD RULE above applies with full force to this case. If you genuinely cannot land a formal review after fixing anchors, say so plainly and post nothing that claims a review happened — silence beats a false receipt.
123
123
 
@@ -189,7 +189,7 @@ The `reviewer` subagent is the analyst; you are the integration layer between it
189
189
 
190
190
  **Operator approval policy.** If the inbound carries a note that PR approval is disabled (`channels.github.review.approve: false` — the adapter appends "Operator policy: PR approval is disabled for this agent" to the message), you must **not** submit an `APPROVE`. Map an `approve` verdict to `COMMENT` instead: post the same `<summary>` and all inline `comments[]` as a `COMMENT` review, just without the formal approval. `request-changes` and `comment` verdicts are unaffected (they never approve). Absent that note, approval is enabled and the table above applies unchanged.
191
191
 
192
- **Re-review.** On a reply-triggered re-review round, obey the session-origin carrier status. If you are **not** the carrier, do not spawn a reviewer, do not publish findings anywhere, and close out only your own thread once the carrier's verdict lands. If step 1 established this is a re-review (an unresolved blocking obligation of yours — a formal `CHANGES_REQUESTED` **or** an unretracted flat-comment blocker), the result MUST clear or re-assert that block. The only top-level-comment exception is the tool-managed duplicate fallback described above: the existing identical `CHANGES_REQUESTED` already re-asserts the formal block, so the new summary/findings may be added as one root comment without posting another blocking review — once per head. If a sibling session already landed that comment, your attempt is denied and the block stands re-asserted by both the formal review and the sibling's comment; discharge your obligation by closing out your own thread, not by publishing again. The clearing mechanics depend on which form the prior block took:
192
+ **Re-review.** On a reply-triggered re-review round, obey the session-origin carrier status. If you are **not** the carrier, do not spawn a reviewer or publish findings anywhere; stay silent with `skip_response` while waiting, then close out only your own thread in one participant-facing message once the carrier's verdict lands. Never narrate the carrier, round, session, verdict registration, or sticky state into the PR. If step 1 established this is a re-review (an unresolved blocking obligation of yours — a formal `CHANGES_REQUESTED` **or** an unretracted flat-comment blocker), the result MUST clear or re-assert that block. The only top-level-comment exception is the tool-managed duplicate fallback described above: the existing identical `CHANGES_REQUESTED` already re-asserts the formal block, so the new summary/findings may be added as one root comment without posting another blocking review — once per head. If a sibling session already landed that comment, your attempt is denied and the block stands re-asserted by both the formal review and the sibling's comment; discharge your obligation by closing out your own thread, not by publishing again. The clearing mechanics depend on which form the prior block took:
193
193
  - **Prior block was a formal `CHANGES_REQUESTED`.** It is sticky: **only** a fresh `APPROVE` from you, or a dismissal of your prior review, clears it. A plain issue comment does **not** clear it, and — critically — **neither does a `COMMENT` review.**
194
194
  - **Prior block was a flat comment** (no formal `CHANGES_REQUESTED` exists). There is no sticky GitHub state to clear, but the obligation is still yours to discharge as a **formal** review so the verdict finally lands as review state: submit `APPROVE` (resolved, approval enabled) or `REQUEST_CHANGES` (not resolved). Do not discharge a flat-comment block with another flat comment — that re-strands the verdict, the original bug.
195
195
 
@@ -242,6 +242,8 @@ The bundled `agent-browser` is **not** for PR reviews — `gh api` is faster and
242
242
 
243
243
  A review you posted leaves inline comment threads open on the PR. When one of **your** threads is addressed — the author pushed a fix, or replied that they handled it — close it out by **resolving the thread**. Leaving it open after the concern is settled reads as if you never noticed; a resolved thread is the signal that the loop is closed.
244
244
 
245
+ **No process narration.** A PR participant needs the technical outcome, not your coordination machinery. While another carrier is working, stay silent with `skip_response`; do not post that you are waiting or will clean up later. Once actionable, use one participant-facing message: acknowledge and resolve if addressed, or state the specific technical reason it remains open.
246
+
245
247
  **The base principle: whoever opened the thread closes it.** Resolve only threads whose root comment **you** authored. Never resolve a human reviewer's thread on your behalf — that erases their open question. The thread you can resolve is the one you started; the inbound that brings you here is a **review-thread reply on `pr:N` with `thread` set**, replying inside a thread you opened.
246
248
 
247
249
  > **Thread cleanup is not the same as discharging a PR-level block.** Resolving an inline thread closes that one thread; it carries **no** review state and does **not** clear a PR-level blocking obligation (a sticky `CHANGES_REQUESTED`, or a flat blocker you authored on the PR conversation). Those are two separate duties. If triage #1 found a live PR-level block, that inbound is a **re-review** and the PR review flow wins over this section — you owe a formal `APPROVE`/`REQUEST_CHANGES`, and resolving threads (or a chat ✅) must **not** be your final response. Reach this section only for a thread-scoped reply on a PR where you owe no PR-level verdict (triage #1 came back clean). When in doubt, re-run triage #1 first.
@@ -1020,6 +1020,7 @@
1020
1020
  "discussion_comment.created",
1021
1021
  "issues.opened",
1022
1022
  "pull_request.opened",
1023
+ "pull_request.converted_to_draft",
1023
1024
  "pull_request.ready_for_review",
1024
1025
  "pull_request.review_requested",
1025
1026
  "pull_request.review_request_removed",
@@ -2567,12 +2568,18 @@
2567
2568
  },
2568
2569
  "sandbox": {
2569
2570
  "default": {
2571
+ "apparmorProfile": "unconfined",
2570
2572
  "realProc": false,
2571
2573
  "writablePaths": [],
2572
2574
  "symlinks": []
2573
2575
  },
2574
2576
  "type": "object",
2575
2577
  "properties": {
2578
+ "apparmorProfile": {
2579
+ "default": "unconfined",
2580
+ "type": "string",
2581
+ "pattern": "^[A-Za-z0-9_.-]+$"
2582
+ },
2576
2583
  "realProc": {
2577
2584
  "default": false,
2578
2585
  "type": "boolean"