typeclaw 0.9.0 → 0.9.2

package/src/channels/router.ts

@@ -11,6 +11,7 @@ import { createCommandRegistry } from '@/commands'
 import { CORE_PERMISSIONS, type PermissionService } from '@/permissions'
 import type { HookBus } from '@/plugin'
 import { extractClaimCode } from '@/role-claim'
+import type { Stream } from '@/stream'
 
 import { decideEngagement, grantStickyForReplyTargets, StickyLedger, type EngagementDecision } from './engagement'
 import {
@@ -505,6 +506,14 @@ export type CreateChannelRouterOptions = {
   // back over the same chat, or null to fall through to normal routing
   // when no pending claim window matches.
   claimHandler?: ClaimHandler
+  // Optional in-process Stream. When set, every inbound the router sees
+  // is published as a tagged broadcast (`kind: 'channel-inbound'`) so the
+  // `/inspect` WS endpoint can surface it live and `stream.scan()` can
+  // backfill it on subscribe. Decoupled from the routing decision: even
+  // permission-denied and role-claim inbounds publish, so the operator
+  // can diagnose silent drops from `typeclaw inspect` alone. Omitted in
+  // tests that don't care about inspect surfacing.
+  stream?: Stream
 }
 
 export type ClaimHandlerInput = {
@@ -539,6 +548,7 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
   const sessionIdleTimeoutMs = options.sessionIdleTimeoutMs ?? SESSION_IDLE_TIMEOUT_MS
   const permissions = options.permissions ?? GRANT_ALL_PERMISSIONS
   const claimHandler = options.claimHandler
+  const stream = options.stream
   const liveSessions = new Map<string, LiveSession>()
   const creating = new Map<string, Promise<LiveSession>>()
   const outboundCallbacks = new Map<ChannelKey['adapter'], Set<OutboundCallback>>()
@@ -713,7 +723,20 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
     const existing = liveSessions.get(keyId)
     if (existing && !existing.destroyed) {
       const idleMs = now() - existing.lastInboundAt
-      if (idleMs > SESSION_FRESHNESS_TTL_MS) {
+      // `lastInboundAt` is only bumped on engaged inbounds (see route()),
+      // so a session whose drain loop has been compiling a slow reply for
+      // 5+ minutes off a single inbound looks "idle" by this clock even
+      // though `session.prompt()` is mid-flight. Aborting that prompt to
+      // re-cold-start on the next user message wipes the in-flight work
+      // (observed against `openai-codex/gpt-5.5` in PR #359's incident:
+      // a 285s + 227s turn pair lost the second turn entirely to
+      // `tearDownLive` → `session.abort()` triggered by the user's
+      // follow-up at 5min idle). The `runIdleGc` path already skips
+      // draining sessions for the same reason; rollover must match.
+      // The skip is bounded: when the in-flight prompt completes or its
+      // own provider/transport timeout fires, `draining` clears and the
+      // next inbound's idle check picks up rollover normally.
+      if (idleMs > SESSION_FRESHNESS_TTL_MS && !existing.draining) {
         logger.info(`[channels] ${keyId}: stale-rollover (live: ${idleMs}ms idle)`)
         await tearDownLive(existing)
         liveSessions.delete(keyId)
@@ -1277,6 +1300,33 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
     }, wait)
   }
 
+  const publishInbound = (event: InboundMessage, decision: 'engage' | 'observe' | 'denied' | 'claim'): void => {
+    if (stream === undefined) return
+    try {
+      stream.publish({
+        target: { kind: 'broadcast' },
+        payload: {
+          kind: 'channel-inbound',
+          adapter: event.adapter,
+          workspace: event.workspace,
+          chat: event.chat,
+          thread: event.thread,
+          authorId: event.authorId,
+          authorName: event.authorName,
+          authorIsBot: event.authorIsBot,
+          isDm: event.isDm,
+          isBotMention: event.isBotMention,
+          text: event.text,
+          externalMessageId: event.externalMessageId,
+          ts: event.ts,
+          decision,
+        },
+      })
+    } catch (err) {
+      logger.warn(`[channels] inbound stream publish failed: ${err instanceof Error ? err.message : String(err)}`)
+    }
+  }
+
   const route = async (event: InboundMessage): Promise<void> => {
     const adapterConfig = options.configForAdapter(event.adapter)
     if (!adapterConfig) return
@@ -1303,6 +1353,7 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
         text: event.text,
       })
       if (outcome.kind !== 'fallthrough') {
+        publishInbound(event, 'claim')
         logger.info(
           `[channels] ${channelKeyId(key)}: claim ${outcome.kind} author=${event.authorId} id=${event.externalMessageId}`,
         )
@@ -1321,6 +1372,7 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
     }
 
     if (isChannelRespondDenied(event)) {
+      publishInbound(event, 'denied')
       logger.info(
         `[channels] ${channelKeyId(key)}: denied by permissions (channel.respond) author=${event.authorId} id=${event.externalMessageId}`,
       )
@@ -1388,6 +1440,7 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
     })
 
     if (decision === 'observe') {
+      publishInbound(event, 'observe')
       // Log every observe so an unanswered mention is diagnosable from logs
       // alone instead of "routed but no prompting" silence. The bracketed
       // shape mirrors `prompting batch=` so log scraping can pair them.
@@ -1396,6 +1449,8 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
       return
     }
 
+    publishInbound(event, 'engage')
+
     updateLoopGuard(live, event)
 
     enqueue(live, event)
@@ -1739,11 +1794,23 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
   const validateChannelTurn = async (live: LiveSession, successfulSendsBeforePrompt: number): Promise<void> => {
     if (live.successfulChannelSends > successfulSendsBeforePrompt) return
 
-    const assistantText = latestAssistantText(live.session)
-    if (assistantText === null) return
+    const candidate = recoverableAssistantText(live.session)
+    if (candidate === null) {
+      // Observability: previously a silent bail-out. The most common cause is a
+      // turn that ends mid-loop with NO assistant message at all (leaf is a
+      // session header / model_change / similar non-message entry, or a session
+      // that just started). Logged at debug-level info so operators can grep for
+      // unexpected silent turns; not warn-level because legitimate empty-state
+      // sessions hit this on every TUI-only check before the first user prompt.
+      logger.info(`[channels] ${live.keyId}: no recoverable assistant text in branch`)
+      return
+    }
+
+    const { text: assistantText, source } = candidate
 
-    if (isNoReplySignal(assistantText)) {
-      logger.info(`[channels] ${live.keyId} no_reply`)
+    if (endsWithNoReplySignal(assistantText)) {
+      const leakedReasoning = !isNoReplySignal(assistantText)
+      logger.info(`[channels] ${live.keyId} no_reply${leakedReasoning ? ' (with_leaked_reasoning)' : ''}`)
       return
     }
 
@@ -1754,8 +1821,23 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
       return
     }
 
+    if (isLikelyKimiChannelToolLeak(assistantText)) {
+      logger.warn(`[channels] ${live.keyId}: suppressed kimi_tool_call_leak text_len=${assistantText.length}`)
+      return
+    }
+
+    // `source` distinguishes the two recovery shapes for log triage:
+    //   - 'leaf': the assistant message IS the leaf (existing behavior; model
+    //     ended its turn with text but forgot to call channel_reply).
+    //   - 'pre-tool': the leaf is a toolResult (or other non-assistant entry)
+    //     and the assistant message lives upstream in the branch. This is the
+    //     Kimi-on-Fireworks `kimi-k2p6-turbo` failure mode where the post-tool
+    //     follow-up LLM call never produced a persisted assistant message, so
+    //     the model's pre-tool commentary is the only user-facing text we have.
+    //     Recovering it means the user gets *something* — strictly better than
+    //     the historical silent drop.
     logger.warn(
-      `[channels] ${live.keyId}: recovering assistant_text_without_channel_tool text_len=${assistantText.length}`,
+      `[channels] ${live.keyId}: recovering assistant_text_without_channel_tool source=${source} text_len=${assistantText.length}`,
     )
     const result = await send(
       {
@@ -2114,10 +2196,23 @@ function composeTurnPrompt(
       parts.push(formatAuthorLine(o.ts, o.authorId, o.authorName, o.authorIsBot, o.text))
     }
     parts.push('')
-    parts.push(batch.length === 1 ? '## Current message (addressed to you)' : '## Current messages (addressed to you)')
   }
-  for (const b of batch) {
-    parts.push(formatAuthorLine(b.ts, b.authorId, b.authorName, b.authorIsBot, b.text))
+  // Only emit the `## Current message(s)` header when there is at least one
+  // queued inbound to live under it. A reminder-only wakeup (subagent
+  // completion firing while the prompt queue is empty) used to print the
+  // header with zero lines underneath; persona-rich models read the empty
+  // header as "there must be a current message addressed to me" and
+  // hallucinated content to reply to. The header is now batch-gated; the
+  // reminder block above and any observed context still render normally.
+  if (batch.length > 0) {
+    if (observed.length > 0) {
+      parts.push(
+        batch.length === 1 ? '## Current message (addressed to you)' : '## Current messages (addressed to you)',
+      )
+    }
+    for (const b of batch) {
+      parts.push(formatAuthorLine(b.ts, b.authorId, b.authorName, b.authorIsBot, b.text))
+    }
   }
   return parts.join('\n')
 }
@@ -2287,12 +2382,67 @@ async function raceWithTimeout<T>(work: Promise<T>, ms: number, label: string):
   }
 }
 
-function latestAssistantText(session: AgentSession): string | null {
-  const entry = session.sessionManager.getLeafEntry()
-  if (entry?.type !== 'message') return null
-  if (entry.message.role !== 'assistant') return null
-  if (entry.message.stopReason !== 'stop') return null
-  return visibleAssistantText(entry.message)
+// Walks the session branch backward from the leaf to find a recoverable
+// assistant message — i.e., text the user should see but didn't, because the
+// model failed to call `channel_reply`/`channel_send` before its turn ended.
+//
+// Two recovery shapes:
+//
+//   - source: 'leaf'
+//     The leaf entry IS an assistant message with `stopReason === 'stop'`.
+//     The model finished its turn with visible text but never called a channel
+//     tool. Pre-existing behavior; this is what the historical
+//     `latestAssistantText` covered.
+//
+//   - source: 'pre-tool'
+//     The leaf is a `toolResult` and the immediately-prior assistant message
+//     has `stopReason === 'toolUse'` (it called the tool that produced this
+//     toolResult). The upstream pi-agent-core loop SHOULD have made a
+//     follow-up LLM call after the tool returned, but that call either never
+//     happened or produced no persisted message. Recovers the assistant's
+//     pre-tool commentary so the user gets *something* — observed against
+//     Fireworks' `accounts/fireworks/routers/kimi-k2p6-turbo` on 2026-05-26.
+//
+// Returns null when no recovery is appropriate:
+//   - No leaf, no messages in branch, branch is malformed
+//   - Leaf is an assistant with non-'stop' stopReason (e.g. mid-stream error)
+//     and is NOT preceded by a toolResult pattern — we don't recover partial
+//     errored output because it's typically a truncation, not a deliberate
+//     reply
+//   - Leaf is a user/system message (model hasn't responded yet)
+//
+// `visibleAssistantText` returning '' (empty string) is a valid recovery
+// target — the caller's downstream guards (`endsWithNoReplySignal('')` returns
+// true) handle the no-content case explicitly via the `no_reply` log.
+function recoverableAssistantText(session: AgentSession): { text: string; source: 'leaf' | 'pre-tool' } | null {
+  const leaf = session.sessionManager.getLeafEntry()
+  if (!leaf) return null
+
+  if (leaf.type === 'message' && leaf.message.role === 'assistant') {
+    if (leaf.message.stopReason !== 'stop') return null
+    return { text: visibleAssistantText(leaf.message), source: 'leaf' }
+  }
+
+  // Pre-tool recovery: the leaf must be a toolResult message, and walking
+  // back through parentId chain must land on an assistant message before any
+  // user message (otherwise we'd be recovering text from a turn the user
+  // already saw a reply to). Bounded walk with a depth guard so a malformed
+  // session can't infinite-loop.
+  if (!(leaf.type === 'message' && leaf.message.role === 'toolResult')) return null
+
+  let cursor: { parentId: string | null } | undefined = leaf
+  for (let depth = 0; depth < 32 && cursor?.parentId; depth++) {
+    const parent = session.sessionManager.getEntry(cursor.parentId)
+    if (!parent) return null
+    if (parent.type === 'message') {
+      if (parent.message.role === 'assistant') {
+        return { text: visibleAssistantText(parent.message), source: 'pre-tool' }
+      }
+      if (parent.message.role === 'user') return null
+    }
+    cursor = parent
+  }
+  return null
 }
 
 function visibleAssistantText(message: AssistantMessage): string {
@@ -2317,6 +2467,45 @@ export function isNoReplySignal(text: string): boolean {
   return false
 }
 
+// Looser sibling of isNoReplySignal, used ONLY by validateChannelTurn's
+// recovery path. Catches leaked-reasoning turns where the model produced
+// prose and then ended with the silent-turn token, e.g.
+//   "The user is laughing. ... I'll end with NO_REPLY.NO_REPLY"
+// Today those fall through to recovery and the entire reasoning paragraph
+// gets posted to the channel — the worst-possible outcome, since the leaked
+// prose is itself an admission that the model intended to stay silent.
+//
+// NOT shared with channel_send / channel_reply misuse guards: those need
+// strict literal match so a legitimate message like "set NO_REPLY=true in
+// the env" isn't rejected as a misuse of the silent-turn signal. Recovery
+// is a different question — by the time we get here the model already
+// failed to call the tool, and "ends in NO_REPLY" is strong evidence of
+// intent to stay silent, not of intent to send those bytes.
+//
+// Matches (returns true):
+//   "NO_REPLY"                        (strict)
+//   "(NO_REPLY)"                      (strict, parenthesized)
+//   "... I'll end with NO_REPLY"      (trailing token after whitespace)
+//   "... end with NO_REPLY."          (+ sentence punctuation)
+//   "... end with NO_REPLY.NO_REPLY"  (model-doubled terminator, glued)
+//   "... and stop. (NO_REPLY)"        (parenthesized at end)
+// Does not match (returns false):
+//   "NO_REPLY means do nothing"       (token at start, prose after)
+//   "the env var is NO_REPLY_MODE"    (substring, not whole token)
+//   "no reply needed"                 (case-sensitive on purpose)
+export function endsWithNoReplySignal(text: string): boolean {
+  if (isNoReplySignal(text)) return true
+  const trimmed = text.trim()
+  if (trimmed === '') return false
+  // Strip trailing sentence punctuation / closing brackets / whitespace, then
+  // check the last whitespace-or-punctuation-separated token. The leading
+  // boundary in the regex (`[\s.!?([]`) treats `.NO_REPLY` as a separate
+  // token from the preceding sentence, which covers the model-doubled
+  // `...NO_REPLY.NO_REPLY` shape.
+  const tail = trimmed.replace(/[.!?)\]\s]+$/, '')
+  return /(?:^|[\s.!?([])\(?NO_REPLY\)?$/.test(tail)
+}
+
 // Detects the upstream "empty response" debug sentinel: when the LLM ends a
 // turn with only a `thinking` block, some provider SDK paths (observed
 // against claude-opus-4-5 via pi-ai) fabricate a single text block whose
@@ -2342,6 +2531,62 @@ export function isUpstreamEmptyResponseSentinel(text: string): boolean {
   return trimmed.includes("'stop_reason'")
 }
 
+// Detects any Kimi-family tool-call delimiter token. Kimi-family deployments
+// emit tool calls inline in their native chat template using these tokens:
+//
+//   <|tool_calls_section_begin|>
+//     <|tool_call_begin|>functions.<name>:<idx><|tool_call_argument_begin|>{...}<|tool_call_end|>
+//   <|tool_calls_section_end|>
+//
+// (Source: https://github.com/MoonshotAI/Kimi-K2/blob/1b4022b/docs/tool_call_guidance.md;
+// the documented set is exactly five tokens — the section begin/end markers,
+// the per-call begin/end markers, and the argument-begin separator. There is
+// no `<|tool_call_argument_end|>`: arguments terminate at `<|tool_call_end|>`.)
+//
+// Production inference servers are expected to parse this format server-side
+// and translate it into OpenAI-shaped `choice.delta.tool_calls`. When the
+// translation breaks (observed against Fireworks' `kimi-k2p6-turbo` router on
+// 2026-05-24; vLLM had a similar class of leak fixed in
+// https://github.com/vllm-project/vllm/pull/38579), the raw tokens flow
+// through `choice.delta.content` instead. pi-ai's `openai-completions`
+// provider is vendor-neutral and has no Kimi-specific parser, so they land
+// verbatim in the assistant message's text content with `stopReason: 'stop'`.
+//
+// Used as a defense-in-depth check at the `channel_send` / `channel_reply`
+// tool boundary so a model that somehow passes raw delimiter text as the
+// message body is denied. NOT used directly by the recovery path in
+// `validateChannelTurn` — see `isLikelyKimiChannelToolLeak` below.
+const KIMI_TOOL_DELIMITER_RE = /<\|tool_calls_section_(?:begin|end)\|>|<\|tool_call_(?:begin|end|argument_begin)\|>/
+
+export function containsKimiToolDelimiter(text: string): boolean {
+  return KIMI_TOOL_DELIMITER_RE.test(text)
+}
+
+// Narrower predicate used by `validateChannelTurn` to decide whether to
+// suppress recovery of assistant text. Requires BOTH:
+//   (1) at least one Kimi tool-call delimiter token, AND
+//   (2) a recognizable channel-tool-call identifier (`channel_reply:N` or
+//       `channel_send:N`, with or without the `functions.` prefix).
+//
+// The two-signal rule narrows the false-positive surface to "the model was
+// trying to call a channel tool and the upstream parser failed". Bare-text
+// discussion of the Kimi protocol — e.g. the agent answering "explain Kimi's
+// tool-call format" with documentation-style prose containing `<|tool_call_begin|>`
+// — does NOT trigger suppression and reaches the user normally. The leak shape
+// observed in production (`channel_reply:0<|tool_call_argument_begin|>{...}<|tool_calls_section_end|>`)
+// satisfies both conditions trivially.
+//
+// The tool-name regex deliberately stays loose on the index suffix
+// (`channel_reply:0` / `channel_reply:1` / `channel_send:0` / ...): every
+// observed leak uses the canonical `functions.<name>:<idx>` shape, but partial
+// parsers may strip the `functions.` prefix before the leak surfaces.
+const KIMI_CHANNEL_TOOL_ID_RE = /(?:functions\.)?channel_(?:reply|send):\d+/
+
+export function isLikelyKimiChannelToolLeak(text: string): boolean {
+  if (!containsKimiToolDelimiter(text)) return false
+  return KIMI_CHANNEL_TOOL_ID_RE.test(text)
+}
+
 function describe(err: unknown): string {
   return err instanceof Error ? err.message : String(err)
 }

package/src/channels/schema.ts

@@ -19,7 +19,7 @@ const stickinessSchema = z.union([
   }),
 ])
 
-export const STICKY_DEFAULT_WINDOW_MS = 5 * 60 * 1000
+export const STICKY_DEFAULT_WINDOW_MS = 15 * 60 * 1000
 
 const engagementSchema = z
   .object({

package/src/cli/compose.ts

@@ -12,11 +12,12 @@ import {
   type ComposeDoctorReport,
 } from '@/compose'
 import { config } from '@/config'
+import { parseTailValue } from '@/container'
 import { formatJson, formatReport } from '@/doctor'
 
 import { formatComposeStatus } from './compose-status'
 import { formatComposeUsage, formatComposeUsageJson } from './compose-usage'
-import { c, spinner } from './ui'
+import { c, errorLine, spinner } from './ui'
 import { parseSince, parseUntil } from './usage-args'
 
 const startSub = defineCommand({
@@ -144,8 +145,23 @@ const logsSub = defineCommand({
       description: 'stream new log output as it arrives',
       default: false,
     },
+    tail: {
+      type: 'string',
+      alias: 'n',
+      description: 'number of lines to show from the end of each agent\'s logs (non-negative integer or "all")',
+    },
   },
   async run({ args }) {
+    let tail: string | undefined
+    if (args.tail !== undefined) {
+      const parsed = parseTailValue(args.tail)
+      if (!parsed.ok) {
+        console.error(errorLine(parsed.reason))
+        process.exit(2)
+      }
+      tail = parsed.value
+    }
+
     const controller = new AbortController()
     const onSig = (): void => controller.abort()
     process.once('SIGINT', onSig)
@@ -156,7 +172,12 @@ const logsSub = defineCommand({
       } else {
         console.log(c.dim('Showing logs for all agents.'))
       }
-      const result = await composeLogs({ rootCwd: process.cwd(), follow: args.follow, signal: controller.signal })
+      const result = await composeLogs({
+        rootCwd: process.cwd(),
+        follow: args.follow,
+        tail,
+        signal: controller.signal,
+      })
       if (result.agents.length === 0) {
         console.log(c.dim('No typeclaw agents found in immediate subdirectories of cwd.'))
         return

package/src/cli/logs.ts

@@ -1,6 +1,6 @@
 import { defineCommand } from 'citty'
 
-import { logs } from '@/container'
+import { logs, parseTailValue } from '@/container'
 import { findAgentDir } from '@/init'
 
 import { c, errorLine } from './ui'
@@ -17,17 +17,32 @@ export const logsCommand = defineCommand({
       description: 'stream new log output as it arrives',
       default: false,
     },
+    tail: {
+      type: 'string',
+      alias: 'n',
+      description: 'number of lines to show from the end of the logs (non-negative integer or "all")',
+    },
   },
   async run({ args }) {
     const cwd = findAgentDir(process.cwd()) ?? process.cwd()
 
+    let tail: string | undefined
+    if (args.tail !== undefined) {
+      const parsed = parseTailValue(args.tail)
+      if (!parsed.ok) {
+        console.error(errorLine(parsed.reason))
+        process.exit(2)
+      }
+      tail = parsed.value
+    }
+
     if (args.follow) {
       console.log(c.cyan('Streaming container logs...'))
     } else {
       console.log(c.dim('Showing container logs.'))
     }
 
-    const result = await logs({ cwd, follow: args.follow })
+    const result = await logs({ cwd, follow: args.follow, tail })
     if (!result.ok) {
       console.error(errorLine(result.reason))
       process.exit(1)

package/src/compose/logs.ts

@@ -1,4 +1,4 @@
-import { containerExists } from '@/container'
+import { buildDockerLogsCmd, containerExists } from '@/container'
 import { supportsColor } from '@/container/log-colors'
 import { makeLogTimestampReformatter, type TimestampReformatter } from '@/container/log-timestamps'
 import { getBun } from '@/container/shared'
@@ -8,6 +8,7 @@ import { discoverAgents, type AgentEntry } from './discover'
 export type ComposeLogsOptions = {
   rootCwd: string
   follow: boolean
+  tail?: string
   out?: NodeJS.WritableStream
   err?: NodeJS.WritableStream
   signal?: AbortSignal
@@ -66,6 +67,7 @@ export function makeLinePrefixer(
 export async function composeLogs({
   rootCwd,
   follow,
+  tail,
   out = process.stdout,
   err = process.stderr,
   signal,
@@ -93,9 +95,11 @@ export async function composeLogs({
   const useColor = supportsColor(out)
 
   const procs = attached.map((agent) => {
-    const cmd = follow
-      ? ['docker', 'logs', '--timestamps', '-f', agent.containerName]
-      : ['docker', 'logs', '--timestamps', agent.containerName]
+    const cmd = buildDockerLogsCmd({
+      containerName: agent.containerName,
+      follow,
+      ...(tail !== undefined ? { tail } : {}),
+    })
     const proc = bun.spawn({ cmd, stdout: 'pipe', stderr: 'pipe' })
     return { agent, proc }
   })

package/src/config/config.ts

@@ -121,6 +121,14 @@ const dockerfileObjectSchema = z.object({
   // time, not via version pins like apt. Default `false`; the bundled
   // `typeclaw-claude-code` skill prompts the user to opt in.
   claudeCode: z.boolean().default(false),
+  // `codexCli` is boolean-only (not an apt feature toggle): the upstream
+  // installer is the npm package `@openai/codex` which we install globally
+  // via `bun install -g`. Default `false`; the bundled `typeclaw-codex-cli`
+  // skill prompts the user to opt in. Mirrors the `claudeCode` toggle for
+  // OpenAI's Codex CLI (https://github.com/openai/codex) — same shape, same
+  // restart-required semantics, separate hook scripts (Codex uses
+  // hooks.json with a different event matcher than Claude Code).
+  codexCli: z.boolean().default(false),
   append: z.array(dockerfileLineSchema).default([]),
 })
 

package/src/container/index.ts

@@ -1,4 +1,4 @@
-export { logs, planLogs, type LogsPlan, type LogsResult } from './logs'
+export { buildDockerLogsCmd, logs, parseTailValue, planLogs, type LogsPlan, type LogsResult } from './logs'
 export { CONTAINER_PORT, TUI_TOKEN_LABEL, findFreePort, resolveHostPort, resolveTuiToken } from './port'
 export {
   requireContainerRunning,

package/src/container/logs.ts

@@ -5,6 +5,7 @@ import { containerExists, containerNameFromCwd, getBun } from './shared'
 export type LogsPlan = {
   containerName: string
   follow: boolean
+  tail?: string
 }
 
 export type LogsResult = { ok: true; containerName: string; exitCode: number } | { ok: false; reason: string }
@@ -12,6 +13,10 @@ export type LogsResult = { ok: true; containerName: string; exitCode: number } |
 export type LogsOptions = {
   cwd: string
   follow: boolean
+  // Forwarded to `docker logs --tail <value>`. Accepts a non-negative
+  // integer string or the sentinel `"all"`. When undefined, no `--tail`
+  // arg is added and docker's default ("all") applies.
+  tail?: string
   out?: NodeJS.WritableStream
   err?: NodeJS.WritableStream
   signal?: AbortSignal
@@ -23,6 +28,7 @@ export type LogsOptions = {
 export async function logs({
   cwd,
   follow,
+  tail,
   out = process.stdout,
   err = process.stderr,
   signal,
@@ -31,18 +37,14 @@ export async function logs({
   const bun = getBun()
   if (!bun) return { ok: false, reason: 'bun runtime not available' }
 
-  const { containerName } = planLogs(cwd, { follow })
+  const plan = planLogs(cwd, { follow, tail })
 
   try {
-    if (!(await containerExists(containerName))) {
-      return { ok: false, reason: `Container ${containerName} not found. Run \`typeclaw start\` first.` }
+    if (!(await containerExists(plan.containerName))) {
+      return { ok: false, reason: `Container ${plan.containerName} not found. Run \`typeclaw start\` first.` }
     }
 
-    const cmd = ['docker', 'logs', '--timestamps']
-    if (follow) cmd.push('-f')
-    cmd.push(containerName)
-
-    const proc = bun.spawn({ cmd, cwd, stdout: 'pipe', stderr: 'pipe' })
+    const proc = bun.spawn({ cmd: buildDockerLogsCmd(plan), cwd, stdout: 'pipe', stderr: 'pipe' })
 
     const onAbort = (): void => {
       try {
@@ -62,14 +64,39 @@ export async function logs({
     const exitCode = await proc.exited
     signal?.removeEventListener('abort', onAbort)
 
-    return { ok: true, containerName, exitCode }
+    return { ok: true, containerName: plan.containerName, exitCode }
   } catch (error) {
     return { ok: false, reason: error instanceof Error ? error.message : String(error) }
   }
 }
 
-export function planLogs(cwd: string, { follow }: { follow: boolean }): LogsPlan {
-  return { containerName: containerNameFromCwd(cwd), follow }
+export function planLogs(cwd: string, { follow, tail }: { follow: boolean; tail?: string }): LogsPlan {
+  return { containerName: containerNameFromCwd(cwd), follow, ...(tail !== undefined ? { tail } : {}) }
+}
+
+// Validate user-supplied `--tail` value. Mirrors `docker logs --tail`'s
+// accepted shape: either the sentinel `"all"` (case-insensitive) or a
+// non-negative integer.
+export function parseTailValue(raw: string): { ok: true; value: string } | { ok: false; reason: string } {
+  const trimmed = raw.trim()
+  if (trimmed.length === 0) return { ok: false, reason: '--tail requires a value (a non-negative integer or "all")' }
+  if (trimmed.toLowerCase() === 'all') return { ok: true, value: 'all' }
+  // Reject leading +, leading zeros (other than "0"), signs, decimals, and
+  // scientific notation up front so the user gets a clear error instead of
+  // docker's terse "invalid value" later.
+  if (!/^(?:0|[1-9]\d*)$/.test(trimmed)) {
+    return { ok: false, reason: `--tail expects a non-negative integer or "all", got ${JSON.stringify(raw)}` }
+  }
+  return { ok: true, value: trimmed }
+}
+
+// Exported so `compose/logs.ts` builds the exact same `docker logs` argv shape.
+export function buildDockerLogsCmd(plan: LogsPlan): string[] {
+  const cmd = ['docker', 'logs', '--timestamps']
+  if (plan.tail !== undefined) cmd.push('--tail', plan.tail)
+  if (plan.follow) cmd.push('-f')
+  cmd.push(plan.containerName)
+  return cmd
 }
 
 // Exported for `compose/logs.ts` so the multi-agent path reuses the same