typeclaw 0.16.0 → 0.18.0

package/src/init/run-owner-claim.ts

@@ -43,7 +43,7 @@ export async function runOwnerClaim({ url, configuredChannels }: RunOwnerClaimOp
     initialValue: true,
   })
   if (isCancel(proceed) || proceed === false) {
-    log.info(`Skipping. Run ${c.bold('typeclaw role claim')} later when you're ready.`)
+    warnMuteUntilClaimed()
     return
   }
 
@@ -78,9 +78,27 @@ export async function runOwnerClaim({ url, configuredChannels }: RunOwnerClaimOp
   }
   if (result.kind === 'error') {
     s.stop(c.red(`Claim failed: ${result.payload.reason}`))
-    log.info(`You can retry with ${c.bold('typeclaw role claim')} anytime.`)
+    warnMuteUntilClaimed()
     return
   }
   s.stop(c.yellow(`Claim timed out — no DM received within the window.`))
-  log.info(`Run ${c.bold('typeclaw role claim')} when you're ready.`)
+  warnMuteUntilClaimed()
+}
+
+// Printed on every path that finishes init WITHOUT a successful owner claim.
+// Since the scoped-by-default change removed the `member: ["*"]` seeding, an
+// unclaimed chat agent resolves every inbound to `guest` and drops it — the
+// agent answers no one. This is a footgun unless the operator is told plainly,
+// so the warning is loud and names the exact recovery command.
+function warnMuteUntilClaimed(): void {
+  note(
+    [
+      `Your agent will respond to ${c.bold('no one')} until you claim the owner role —`,
+      `every inbound message is currently dropped.`,
+      '',
+      `Run ${c.bold('typeclaw role claim')} to pair yourself, then grant others`,
+      `with the agent (ask it: "respond to <user>") or by editing typeclaw.json#roles.`,
+    ].join('\n'),
+    c.yellow('Heads up: agent is muted'),
+  )
 }

package/src/permissions/builtins.ts

@@ -10,6 +10,12 @@ export const BUILTIN_ROLE_NAMES: readonly BuiltinRoleName[] = ['owner', 'trusted
 // set at boot via expandOwnerWildcard.
 export const CORE_PERMISSIONS = {
   channelRespond: 'channel.respond',
+  // Distinct from channelRespond so a respond-capable guest cannot abort
+  // other speakers' sessions. The /stop command (both the text-prefix and
+  // native-slash paths in the router) gates on this, not on channelRespond:
+  // an operator may grant guest channelRespond to let strangers drive masked
+  // turns, but session lifecycle control stays member-and-up.
+  sessionControl: 'session.control',
   cronSchedule: 'cron.schedule',
   cronModify: 'cron.modify',
   subagentSpawn: 'subagent.spawn',
@@ -17,10 +23,11 @@ export const CORE_PERMISSIONS = {
   subagentOutput: 'subagent.output',
   subagentSpawnOperator: 'subagent.spawn.operator',
   // Phrased as capabilities to SEE, not to hide, so the role tower stays
-  // monotonic (a higher tier sees a strict superset of a lower tier) and the
-  // empty-permission guest is the fail-safe floor. resolveHiddenPaths masks
-  // whatever the resolved role lacks: fsSeePrivate gates workspace/+memory/+
-  // sessions/, fsSeeSecrets gates .env+secrets.json.
+  // monotonic (a higher tier sees a strict superset of a lower tier).
+  // resolveHiddenPaths masks whatever the resolved role lacks: fsSeePrivate
+  // gates workspace/+memory/+sessions/, fsSeeSecrets gates .env+secrets.json.
+  // The fail-safe floor is the undefined origin (see has() in
+  // permissions.ts), not the guest role, which is now grantable.
   fsSeePrivate: 'fs.see.private',
   fsSeeSecrets: 'fs.see.secrets',
 } as const
@@ -62,6 +69,7 @@ export const BUILTIN_ROLES: Readonly<Record<BuiltinRoleName, BuiltinRoleSpec>> =
     match: [{ kind: 'tui' }],
     permissions: [
       CORE_PERMISSIONS.channelRespond,
+      CORE_PERMISSIONS.sessionControl,
       CORE_PERMISSIONS.cronSchedule,
       CORE_PERMISSIONS.cronModify,
       CORE_PERMISSIONS.subagentSpawn,
@@ -80,6 +88,7 @@ export const BUILTIN_ROLES: Readonly<Record<BuiltinRoleName, BuiltinRoleSpec>> =
     match: [],
     permissions: [
       CORE_PERMISSIONS.channelRespond,
+      CORE_PERMISSIONS.sessionControl,
       CORE_PERMISSIONS.cronSchedule,
       CORE_PERMISSIONS.subagentSpawn,
       CORE_PERMISSIONS.subagentCancel,
@@ -95,6 +104,7 @@ export const BUILTIN_ROLES: Readonly<Record<BuiltinRoleName, BuiltinRoleSpec>> =
     match: [],
     permissions: [
       CORE_PERMISSIONS.channelRespond,
+      CORE_PERMISSIONS.sessionControl,
       CORE_PERMISSIONS.subagentSpawn,
       CORE_PERMISSIONS.subagentCancel,
       CORE_PERMISSIONS.subagentOutput,

package/src/permissions/grant.ts

@@ -1,6 +1,9 @@
 import { existsSync, readFileSync, renameSync, unlinkSync, writeFileSync } from 'node:fs'
 import { join } from 'node:path'
 
+import { commitSystemFileSync } from '@/git/system-commit'
+
+import { BUILTIN_ROLES, isBuiltinRoleName } from './builtins'
 import { parseMatchRule } from './match-rule'
 
 // Appends `rule` to `typeclaw.json#roles.<name>.match`, creating the role
@@ -23,15 +26,97 @@ export type GrantOptions = {
   matchRule: string
 }
 
+export type GrantPermissionOptions = {
+  cwd: string
+  roleName: string
+  permission: string
+}
+
 export function grantRole(opts: GrantOptions): GrantResult {
   const validation = parseMatchRule(opts.matchRule)
   if (!validation.ok) {
     return { ok: false, reason: `invalid match rule '${opts.matchRule}': ${validation.error}` }
   }
 
-  const path = join(opts.cwd, CONFIG_FILE)
+  const loaded = loadConfigObject(opts.cwd, opts.roleName)
+  if (!loaded.ok) return loaded
+
+  const { obj, roles, role } = loaded
+  const existingMatch = Array.isArray(role.match) ? [...(role.match as unknown[])] : []
+
+  // Dedup by exact string equality — match rules canonicalize during load,
+  // and a literal duplicate in the file is a noise source the schema doesn't
+  // currently dedupe for us.
+  if (existingMatch.includes(opts.matchRule)) {
+    return { ok: true, added: false }
+  }
+
+  role.match = [...existingMatch, opts.matchRule]
+  roles[opts.roleName] = role
+  obj.roles = roles
+
+  const written = writeConfigObject(opts.cwd, obj)
+  if (!written.ok) return written
+
+  // Best-effort commit so a claimed role survives a fresh clone/rebuild — a
+  // failing commit leaves the on-disk grant intact (history, not correctness).
+  // Subject stays neutral: every grantRole caller hits this, not just claim.
+  commitSystemFileSync(opts.cwd, CONFIG_FILE, `${CONFIG_FILE}: grant ${opts.roleName} role`)
+
+  return written
+}
+
+// Appends `permission` to `typeclaw.json#roles.<name>.permissions`. For a
+// built-in role with no explicit `permissions[]`, the runtime treats the
+// field as "use built-in defaults" (see resolveOne in permissions.ts), so a
+// naive write of `[permission]` would NARROW the role to a single capability,
+// silently dropping its defaults. We materialize the current effective set
+// (explicit field if present, else the built-in default list) and append to
+// THAT, preserving every existing capability. Idempotent: a permission the
+// role already holds is a no-op.
+//
+// NOTE: `roles.permissions` is `restart-required` (FIELD_EFFECTS); the write
+// lands on disk but does not take effect until the next container restart.
+// Callers must surface that to the operator.
+export function grantRolePermission(opts: GrantPermissionOptions): GrantResult {
+  const loaded = loadConfigObject(opts.cwd, opts.roleName)
+  if (!loaded.ok) return loaded
+
+  const { obj, roles, role } = loaded
+  const effective = effectivePermissions(opts.roleName, role)
+
+  if (effective.includes(opts.permission)) {
+    return { ok: true, added: false }
+  }
+
+  role.permissions = [...effective, opts.permission]
+  roles[opts.roleName] = role
+  obj.roles = roles
+
+  return writeConfigObject(opts.cwd, obj)
+}
+
+function effectivePermissions(roleName: string, role: Record<string, unknown>): string[] {
+  if (Array.isArray(role.permissions)) {
+    return role.permissions.filter((p): p is string => typeof p === 'string')
+  }
+  if (isBuiltinRoleName(roleName)) {
+    return [...BUILTIN_ROLES[roleName].permissions]
+  }
+  return []
+}
+
+type LoadedConfig = {
+  ok: true
+  obj: Record<string, unknown>
+  roles: Record<string, unknown>
+  role: Record<string, unknown>
+}
+
+function loadConfigObject(cwd: string, roleName: string): LoadedConfig | { ok: false; reason: string } {
+  const path = join(cwd, CONFIG_FILE)
   if (!existsSync(path)) {
-    return { ok: false, reason: `${CONFIG_FILE} not found at ${opts.cwd}` }
+    return { ok: false, reason: `${CONFIG_FILE} not found at ${cwd}` }
   }
 
   let raw: string
@@ -54,26 +139,17 @@ export function grantRole(opts: GrantOptions): GrantResult {
 
   const obj = json as Record<string, unknown>
   const roles = isPlainObject(obj.roles) ? { ...obj.roles } : {}
-  const role = isPlainObject(roles[opts.roleName]) ? { ...(roles[opts.roleName] as Record<string, unknown>) } : {}
-  const existingMatch = Array.isArray(role.match) ? [...(role.match as unknown[])] : []
-
-  // Dedup by exact string equality — match rules canonicalize during load,
-  // and a literal duplicate in the file is a noise source the schema doesn't
-  // currently dedupe for us.
-  if (existingMatch.includes(opts.matchRule)) {
-    return { ok: true, added: false }
-  }
-
-  role.match = [...existingMatch, opts.matchRule]
-  roles[opts.roleName] = role
-  obj.roles = roles
+  const role = isPlainObject(roles[roleName]) ? { ...(roles[roleName] as Record<string, unknown>) } : {}
+  return { ok: true, obj, roles, role }
+}
 
+function writeConfigObject(cwd: string, obj: Record<string, unknown>): GrantResult {
+  const path = join(cwd, CONFIG_FILE)
   try {
     writeAtomic(path, `${JSON.stringify(obj, null, 2)}\n`)
   } catch (error) {
     return { ok: false, reason: `failed to write ${CONFIG_FILE}: ${describeError(error)}` }
   }
-
   return { ok: true, added: true }
 }
 

package/src/permissions/index.ts

@@ -24,6 +24,12 @@ export {
   type PermissionService,
   type UnknownPermissionWarning,
 } from './permissions'
-export { grantRole, type GrantOptions, type GrantResult } from './grant'
-export { matchesOrigin, type MatchableOrigin } from './resolve'
+export {
+  grantRole,
+  grantRolePermission,
+  type GrantOptions,
+  type GrantPermissionOptions,
+  type GrantResult,
+} from './grant'
+export { matchesOrigin, isDmChannelOrigin, type MatchableOrigin } from './resolve'
 export { MATCH_RULE_JSON_SCHEMA_PATTERN, rolesConfigSchema, type RoleConfig, type RolesConfig } from './schema'

package/src/permissions/permissions.ts

@@ -141,6 +141,15 @@ export function createPermissionService(opts: CreatePermissionServiceOptions = {
 
   return {
     has(origin, permission) {
+      // Fail-safe floor: an undefined origin holds nothing, regardless of
+      // role permissions. Previously this floor was implicit in `guest`
+      // being empty; now `guest` is grantable (an operator may grant it
+      // `channel.respond`), so the floor must live on the no-actor input
+      // instead. Keeps every downstream `has(maybeUndefined, ...)` check
+      // (bypass tiers, fs.see.*, subagent spawn) closed even after a guest
+      // grant. resolveRole/describe still report 'guest' for audit/display;
+      // only authorization is forced closed.
+      if (origin === undefined) return false
       const roleName = resolveRole(origin)
       const role = byName.get(roleName)
       if (!role) return false

package/src/permissions/resolve.ts

@@ -79,3 +79,13 @@ function matchesBucket(
   if (platform === 'telegram') return origin.workspace === 'dm' || origin.workspace.startsWith('@')
   return false
 }
+
+// True only for a 1:1 direct-message channel origin (a two-participant
+// conversation: the principal + the bot). Reuses the same per-adapter
+// workspace markers as the `dm` match-rule bucket. A DM is the only channel
+// shape with no third-party content buffered into a turn, so role-grant tools
+// treat an owner/trusted DM as injection-equivalent to the TUI; group/open
+// channels never qualify.
+export function isDmChannelOrigin(origin: { adapter: AdapterId; workspace: string }): boolean {
+  return matchesBucket('dm', { kind: 'channel', adapter: origin.adapter, workspace: origin.workspace, chat: '' })
+}

package/src/role-claim/index.ts

@@ -10,6 +10,7 @@ export {
   type CreateClaimControllerOptions,
 } from './controller'
 export { formatClaimMatchRule, type PartialChannelOrigin } from './match-rule'
+export { reloadAfterClaim, type ReloadAfterClaimOptions, type ReloadAfterClaimResult } from './reload-after-claim'
 export {
   createPendingClaimRegistry,
   type ClaimResult,

package/src/role-claim/reload-after-claim.ts

@@ -0,0 +1,34 @@
+import { requestReload, type ReloadResult } from '@/reload'
+
+export interface ReloadAfterClaimOptions {
+  url: string
+  reload?: (opts: { url: string; scope: string }) => Promise<ReloadResult[]>
+}
+
+export type ReloadAfterClaimResult = { ok: true; results: ReloadResult[] } | { ok: false; reason: string }
+
+// Best-effort by contract: the role is already persisted to typeclaw.json by
+// the time a claim completes, so a reload failure here must NOT fail the claim.
+// Callers surface the reason but keep the claim successful.
+export async function reloadAfterClaim(opts: ReloadAfterClaimOptions): Promise<ReloadAfterClaimResult> {
+  const reload = opts.reload ?? requestReload
+  let results: ReloadResult[]
+  try {
+    results = await reload({ url: opts.url, scope: 'config' })
+  } catch (err) {
+    return { ok: false, reason: err instanceof Error ? err.message : String(err) }
+  }
+
+  // requestReload resolves even when the server reports a per-scope failure, so
+  // an exception-free call is not proof the config actually reloaded. Surface
+  // any failed scope (and an empty result, which means nothing reloaded) as a
+  // failure so the caller can tell the user to reload manually.
+  const failed = results.filter((r) => !r.ok)
+  if (failed.length > 0) {
+    return { ok: false, reason: failed.map((r) => `${r.scope}: ${r.reason}`).join('; ') }
+  }
+  if (results.length === 0) {
+    return { ok: false, reason: 'no reloadable config scope responded' }
+  }
+  return { ok: true, results }
+}

package/src/run/channel-session-factory.ts

@@ -7,7 +7,7 @@ import type { CreateSessionForSubagent, SubagentRegistry } from '@/agent/subagen
 import { capJsonlFileInPlace } from '@/bundled-plugins/tool-result-cap/cap-jsonl'
 import type { CapOptions } from '@/bundled-plugins/tool-result-cap/cap-result'
 import type { CreateSessionForChannel, ChannelRouter } from '@/channels'
-import type { PermissionService } from '@/permissions'
+import type { PermissionService, RolesConfig } from '@/permissions'
 import type { ReloadRegistry } from '@/reload'
 import type { SessionFactory } from '@/sessions'
 import type { Stream } from '@/stream'
@@ -47,6 +47,10 @@ export type BuildChannelSessionFactoryDeps = {
   // the production wiring can plumb in pluginsLoaded.permissions while tests
   // (or stand-alone callers) keep the previous no-annotation behavior.
   permissions?: PermissionService
+  // Re-reads roles from disk for the grant_role tool's hot-reload (reload then
+  // read, not an in-memory snapshot). Forwarded to createSession; the tool only
+  // mounts when permissions is also present.
+  reloadRoles?: () => RolesConfig | undefined
   // Test seam: lets a fake stand in for the agent session creator so tests
   // can assert exactly which CreateSessionOptions the factory builds without
   // needing a live LLM, plugin runtime, or session manager on disk.
@@ -124,6 +128,7 @@ export function buildChannelSessionFactory(deps: BuildChannelSessionFactoryDeps)
       ...(deps.containerName !== undefined ? { containerName: deps.containerName } : {}),
       ...(deps.runtimeVersion !== undefined ? { runtimeVersion: deps.runtimeVersion } : {}),
       ...(deps.permissions !== undefined ? { permissions: deps.permissions } : {}),
+      ...(deps.reloadRoles !== undefined ? { reloadRoles: deps.reloadRoles } : {}),
       ...(deps.liveSubagentRegistry !== undefined ? { liveSubagentRegistry: deps.liveSubagentRegistry } : {}),
       ...(deps.subagentRegistry !== undefined ? { subagentRegistry: deps.subagentRegistry } : {}),
       ...(deps.getCreateSessionForSubagent !== undefined

package/src/run/index.ts

@@ -24,7 +24,7 @@ import {
   type SubagentCompletionBridge,
 } from '@/channels'
 import { createTunnelBridge, type TunnelBridge } from '@/channels/tunnel-bridge'
-import { createConfigReloadable, getConfig, loadConfigSync, loadPluginConfigsSync } from '@/config'
+import { createConfigReloadable, getConfig, loadConfigSync, loadPluginConfigsSync, reloadConfig } from '@/config'
 import {
   type CronConsumer,
   type CronJob,
@@ -150,6 +150,7 @@ export async function startAgent({
     createConfigReloadable({
       cwd,
       permissions: pluginsLoaded.permissions,
+      onRolesChanged: () => channelManager.router.tearDownAllLive(),
       skipMountValidation: containerName !== undefined,
     }),
   )
@@ -244,6 +245,7 @@ export async function startAgent({
       getChannelRouter: () => channelManager.router,
       rehydrateCapOptions: resolveCapOptionsFromConfig(pluginConfigsByName['tool-result-cap']),
       permissions: pluginsLoaded.permissions,
+      reloadRoles: () => reloadRolesFromDisk(cwd),
       liveSubagentRegistry,
       liveSessionRegistry,
       subagentRegistry: pluginRuntime.get().subagents,
@@ -369,6 +371,7 @@ export async function startAgent({
             runtimeVersion: runtimeVersionOpt.runtimeVersion,
             containerName: containerNameOpt.containerName,
             sessionFactory,
+            channelRouter: channelManager.router,
           }),
         subagent: (subName: string, payload?: unknown) =>
           dispatchSpawnSubagent(subName, payload, {
@@ -583,6 +586,7 @@ export async function startAgent({
       containerName,
       outbound,
       sessionFactory,
+      channelRouter: channelManager.router,
     })
 
   const server = createServer({
@@ -688,6 +692,21 @@ async function disposeMaterializedSkills(pluginRuntime: PluginRuntime): Promise<
   await Promise.allSettled(all.map((m) => m.dispose()))
 }
 
+// grant_role's hot-reload hook: reload the live config FROM DISK (grantRole
+// wrote typeclaw.json directly, bypassing the in-memory snapshot) and return
+// the fresh roles for permissions.replaceRoles. Mirrors the config reloadable's
+// reload-then-read order. Falls back to the current snapshot if the just-written
+// file fails to parse — the on-disk write still stands and the next reload picks
+// it up; replaceRoles with stale roles is no worse than not reloading.
+function reloadRolesFromDisk(cwd: string): ReturnType<typeof getConfig>['roles'] {
+  try {
+    reloadConfig(cwd)
+  } catch {
+    // keep the current pointer; see above
+  }
+  return getConfig().roles
+}
+
 async function startScheduler({
   cwd,
   loadCron,

package/src/sandbox/build.ts

@@ -65,6 +65,38 @@ function buildArgv(command: string, policy: SandboxPolicy): string[] {
 
   argv.push('--ro-bind', '/usr', '/usr', '--ro-bind', '/etc', '/etc', '--dev', '/dev', '--tmpfs', '/tmp')
 
+  // Recreate the usr-merge root symlinks that --ro-bind /usr does NOT bring
+  // along. On the Debian base (oven/bun:1-slim) /bin /sbin /lib /lib64 are
+  // root-level symlinks into /usr; binding /usr exposes /usr/bin etc. but the
+  // root entries themselves are absent in the sandbox. That breaks every
+  // ABSOLUTE-path reference the kernel resolves WITHOUT consulting PATH:
+  //   - ELF interpreter (the dynamic loader) baked into PT_INTERP:
+  //     /lib/ld-linux-aarch64.so.1 (arm64) or /lib64/ld-linux-x86-64.so.2
+  //     (amd64). Missing it makes bwrap report "execvp bash: No such file or
+  //     directory" — the missing file is the loader, not bash.
+  //   - shebang lines: /bin/sh and /bin/bash are the most common interpreters
+  //     on earth; a script with "#!/bin/sh" fails "cannot execute: required
+  //     file not found" without /bin, even though /usr/bin/sh exists, because
+  //     the shebang path is literal and skips PATH.
+  // --ro-bind-try, not --ro-bind: the set is arch- and base-dependent (arm64
+  // oven/bun:1-slim ships /lib but no /lib64), and a hard bind of an absent
+  // source aborts bwrap. -try binds each only when present, keeping this
+  // builder pure (no host filesystem probe) and correct across arches/bases.
+  argv.push(
+    '--ro-bind-try',
+    '/bin',
+    '/bin',
+    '--ro-bind-try',
+    '/sbin',
+    '/sbin',
+    '--ro-bind-try',
+    '/lib',
+    '/lib',
+    '--ro-bind-try',
+    '/lib64',
+    '/lib64',
+  )
+
   if ((policy.proc ?? 'tmpfs') === 'tmpfs') {
     // --tmpfs /proc, never --proc /proc (OrbStack's kernel blocks
     // mount("proc",...) from user namespaces) and never --dev-bind /proc /proc

package/src/secrets/schema.ts

@@ -49,7 +49,6 @@ const githubAppAuthSchema = z.object({
   type: z.literal('app'),
   appId: z.number().int().positive(),
   privateKey: secretFieldSchema,
-  installationId: z.number().int().positive().optional(),
 })
 
 const githubChannelSchema = z.object({

package/src/server/command-runner.ts

@@ -5,6 +5,7 @@ import {
   type CreateSessionResult,
   type SessionOrigin,
 } from '@/agent'
+import type { ChannelRouter } from '@/channels/router'
 import type { PermissionService } from '@/permissions'
 import type {
   CommandExecResult,
@@ -44,6 +45,14 @@ export type CommandRunnerOptions = {
   // `SessionManager.inMemory()` and never persist usage — see
   // `runPromptForCommand` below.
   sessionFactory: SessionFactory
+  // Channel router threaded into every `ctx.prompt` session so the model can
+  // call `channel_send`. Without this, `buildChannelTools` (src/agent/index.ts)
+  // receives `undefined` and emits no channel tools — a plugin command or cron
+  // handler told to post to a channel then has no tool to do it and falls back
+  // to flailing bash loops. The cron `prompt` path already passes
+  // `channelManager.router` via `createSessionForCron`; this is the matching
+  // wire for the handler/command path.
+  channelRouter: ChannelRouter | undefined
 }
 
 type CommandHandle = {
@@ -182,6 +191,7 @@ export function createCommandRunner(opts: CommandRunnerOptions): CommandRunner {
               permissions: opts.permissions,
               signal: abortController.signal,
               sessionFactory: opts.sessionFactory,
+              channelRouter: opts.channelRouter,
             }),
           subagent: (subName, payload) =>
             opts.spawnSubagent(subName, payload, {
@@ -363,6 +373,9 @@ export async function runPromptForCommand(args: {
   // cron `prompt` path uses in src/run/index.ts. Passing in-memory here
   // regresses `typeclaw usage` (see CommandRunnerOptions.sessionFactory).
   sessionFactory: SessionFactory
+  // See CommandRunnerOptions.channelRouter. Threaded to createSessionWithDispose
+  // so the spawned session exposes `channel_send`.
+  channelRouter?: ChannelRouter
   // Test seam for the agent-session boundary. Production passes the real
   // `createSessionWithDispose`; tests inject a fake to verify wiring
   // (specifically: the sessionManager handed off must be persisted, not
@@ -388,6 +401,7 @@ export async function runPromptForCommand(args: {
       sessionId,
       agentDir: args.agentDir,
     },
+    ...(args.channelRouter !== undefined ? { channelRouter: args.channelRouter } : {}),
     ...(args.runtimeVersion !== undefined ? { runtimeVersion: args.runtimeVersion } : {}),
     ...(args.containerName !== undefined ? { containerName: args.containerName } : {}),
   })

package/src/skills/typeclaw-channel-github/SKILL.md

@@ -63,7 +63,11 @@ Why delegate: the `reviewer` subagent runs on the `deep` model profile, loads a
    </review>
    ```
 
-4. **Translate findings into a `gh api` review payload.** Each `<finding>` with `severity` of `blocker`, `concern`, or `nit` and a `location="path:line"` becomes one entry in `comments[]`. Compose the inline `body` from the reviewer's `<issue>` + `<evidence>` + `<suggestion>` — preserve the reviewer's wording, do not paraphrase. Findings whose `location` is `general` (no file:line anchor) go into the top-level review `body` instead. **Skip `praise` findings when building `comments[]`** — they are not actionable, and inline praise comments are exactly the noise the reviewer is supposed to filter out at the source; if you want to surface them, weave them into the top-level review `body` alongside the summary. Map the reviewer's `<verdict>` to the GitHub `event`:
+4. **Translate findings into a `gh api` review payload.** Each `<finding>` with `severity` of `blocker`, `concern`, or `nit` and a `location="path:line"` becomes one entry in `comments[]`. Compose the inline `body` from the reviewer's `<issue>` + `<evidence>` + `<suggestion>` — preserve the reviewer's wording, do not paraphrase. Findings whose `location` is `general` (no file:line anchor) go into the top-level review `body` instead. **Skip `praise` findings when building `comments[]`** — they are not actionable, and inline praise comments are exactly the noise the reviewer is supposed to filter out at the source; if you want to surface them, weave them into the top-level review `body` alongside the summary.
+
+   **The verdict and the inline comments are independent. The verdict sets only the `event` field; it never decides whether you post `comments[]`.** Whenever there is at least one actionable finding (`blocker`/`concern`/`nit`) with a `location="path:line"`, you MUST submit a formal review via `POST /pulls/<N>/reviews` carrying those findings in `comments[]` — including when the verdict is `approve`. An `approve` with three nits is still a formal `APPROVE` review with three inline comments, **not** a plain approval and **not** a flattened summary posted as a top-level comment. Collapsing inline findings into a single `channel_reply` or issue comment loses the line anchors the reviewer worked to produce — that is the exact failure mode this step exists to prevent.
+
+   Map the reviewer's `<verdict>` to the GitHub `event`:
 
    | Reviewer verdict  | GitHub `event`    |
    | ----------------- | ----------------- |
@@ -88,13 +92,21 @@ Why delegate: the `reviewer` subagent runs on the `deep` model profile, loads a
 
    **Always use `--input -` with a quoted heredoc (`<<'JSON'`) for review bodies.** Do **not** use `-f body=...` or `-F 'comments[][body]=...'`: those go through shell argument parsing, so backticks (\`) trigger command substitution and have to be backslash-escaped, which leaks the literal `\` into the rendered comment. The quoted heredoc passes the JSON through untouched — backticks, newlines, and `${...}` all survive verbatim. The same applies to any other `gh api` POST whose body contains backticks, embedded newlines, or shell metacharacters.
 
-5. **Post a one-line summary with `channel_reply`** so the conversation has a human-readable trace pointing at the review (e.g., "Posted review on PR #N: <verdict>, N findings.").
+5. **Verify the review actually landed before announcing it.** The `gh api` call can fail silently from the model's perspective — a permission denial, a bad `line` anchor, or a malformed payload returns an error you must not paper over. After submitting, confirm the review exists:
+
+   ```sh
+   gh api /repos/owner/repo/pulls/<N>/reviews --jq '.[-1] | {id, state, user: .user.login}'
+   ```
+
+   The returned `id`/`state` is your proof the formal review posted. If the call errored or the review is absent, do **not** fall back to a top-level `channel_reply` that _claims_ a review was posted — fix the payload (most often a `line` that isn't part of the diff; re-anchor it or move that finding to the top-level `body`) and resubmit. A trace reply that says "Posted review" when no review exists is worse than silence.
+
+6. **End the turn with `skip_response`, not a trace reply.** The formal review from step 4 already landed _in this PR_ — it carries the summary, the verdict, and the inline comments. A `channel_reply` here does **not** go to a separate operator channel; on GitHub it posts another public comment on the same PR. A one-line "Posted review on PR #N: …" narrated into the PR thread is meta-commentary addressed to a phantom operator, and it reads absurdly next to the review it claims to point at. So once step 5 confirms the review exists, call `skip_response({ reason: "review posted via gh api" })` to close the turn silently. Only fall back to `channel_reply` when there was **no** formal review to post — the zero-actionable-findings branches in Rules below already use `channel_reply`/issue comments _as_ the substantive reply.
 
 ### Rules
 
 - **Always delegate to the `reviewer` subagent.** Do not perform the review craft yourself. The reviewer is the source of truth for severity, evidence quality, and what counts as a finding. Your job is mechanics: spawn, wait, translate, post.
 - **Trust the verdict.** Use the GitHub `event` mapped from the reviewer's `<verdict>`. Do not upgrade `comment` → `APPROVE` to seem agreeable, and do not downgrade `request-changes` → `COMMENT` to soften the tone. The reviewer chose deliberately.
-- **No actionable findings → no inline review post.** A finding is "actionable" if its severity is `blocker`, `concern`, or `nit`. If the reviewer returns zero actionable findings:
+- **No actionable findings → no inline review post.** A finding is "actionable" if its severity is `blocker`, `concern`, or `nit`. This branch applies **only when the actionable count is exactly zero** — if there is even one actionable finding with a line anchor, follow step 4 and submit a formal review with `comments[]` regardless of verdict. When the reviewer returns zero actionable findings:
   - `approve` verdict → post a plain `APPROVE` with the `<summary>` as the review body (no `comments[]` array).
   - `comment` verdict → post the summary as a top-level PR comment via `gh api -X POST /repos/.../issues/<N>/comments` instead of submitting an empty review.
   - `request-changes` verdict → submit `REQUEST_CHANGES` with the `<summary>` as the review body and no `comments[]` array. This combination is rare (the reviewer's contract says `request-changes` requires at least one blocker or load-bearing concern), so if it happens, faithfully encode the verdict and trust the reviewer's reasoning is in the summary.

package/src/skills/typeclaw-permissions/SKILL.md

@@ -42,11 +42,19 @@ When the runtime knows your permissions, it prepends a block under your `## Sess
 Role: `member`. Permissions: `channel.respond`.
 ```
 
-The block renders for cron / channel / subagent sessions. For TUI sessions, the block is omitted because TUI always resolves to `owner` under severity-then-declaration ordering (built-in `owner.match` includes `tui` and is appended-to, never replaced, by user config — and `owner` is walked first). If you don't see the block in a TUI session, treat yourself as `owner`.
+This concrete role/permissions block renders for **cron and subagent** sessions, which have a single fixed actor. For TUI sessions the block is omitted because TUI always resolves to `owner` under severity-then-declaration ordering (built-in `owner.match` includes `tui` and is appended-to, never replaced, by user config — and `owner` is walked first). If you don't see the block in a TUI session, treat yourself as `owner`.
 
-**The role line reflects the session at creation time.** For channel sessions, the speaker on subsequent turns may resolve to a different role; the runtime updates that internally for tool gating (the channel router and the security plugin re-resolve on each turn), but the system prompt is not regenerated mid-session. If the user asks "what role am I right now in this channel", read `typeclaw.json` `roles` and match their author id against `match[]` yourself — do not parrot the system-prompt line as if it always applied.
+**Channel sessions are different.** A channel session is keyed by chat/thread, not by author, so it can see many speakers with different roles. It does NOT print one concrete role; instead the block is a policy reminder:
 
-**The permission list is exhaustive at session-creation time** for the resolved role. If a permission you expect isn't listed there, the role doesn't carry it — adding it requires editing `roles.<role>.permissions[]` and restarting.
+```
+## Your role in this session
+
+This is a channel conversation that may include multiple speakers...
+```
+
+For each user turn, the current speaker's effective role is delivered in the turn context as a `<your-role authority="current-speaker">…</your-role>` tag (omitted for `owner`, the unconstrained default). **That per-turn tag is authoritative for the current message and overrides any role implied by the system prompt.** If the user asks "what role am I right now in this channel", read the `<your-role>` tag on the current turn (or, if absent, treat them as `owner`); do not consult a session-creation role line — channel sessions no longer carry one.
+
+**The permission list (cron/subagent block) is exhaustive at session-creation time** for the resolved role. If a permission you expect isn't listed there, the role doesn't carry it — adding it requires editing `roles.<role>.permissions[]` and restarting.
 
 ## The match-rule DSL
 

package/src/skills/typeclaw-skills/SKILL.md

@@ -5,7 +5,9 @@ description: Use this skill whenever the user asks you to install, find, list, u
 
 # typeclaw-skills
 
-You operate inside an agent folder. Skills — markdown files with YAML frontmatter — are how this folder teaches you new procedures, conventions, and APIs without changing your code. The runtime discovers them on session start, parses each `SKILL.md`'s frontmatter, and surfaces the `name` + `description` to you so you can decide when to read the body. **You do not import or invoke skills; you read them when their description matches the current request.**
+You operate inside an agent folder. Skills — markdown files with YAML frontmatter — are how this folder teaches you new procedures, conventions, and APIs without changing your code. The runtime discovers them on session start, parses each `SKILL.md`'s frontmatter, and surfaces the `name` + `description` (plus an absolute `<location>` path) to you in the `<available_skills>` section so you can decide when to read the body. **You do not import or invoke skills; you load one by `read`-ing the `SKILL.md` at the exact `<location>` path that section gives you.**
+
+**Never construct or guess a skill's path.** Use the `<location>` verbatim. Do not assume a layout like `node_modules/typeclaw/src/skills/<name>/SKILL.md` — bundled skills resolve through the installed package, user skills live under `.agents/skills/`, and muscle-memory skills under `memory/skills/`. If a skill you expect is not listed in `<available_skills>`, it is not a file-based skill and has no `SKILL.md` to read — stop looking on disk. (Subagent-only skills loaded via the `load_skill` tool, e.g. the `reviewer` subagent's `code-review`, are never files.)
 
 This skill exists so you (a) understand which skills you can edit and which you must not, (b) can install new skills cleanly when the user asks, and (c) can author your own skills without colliding with the rest of the system.