typeclaw 0.37.4 → 0.37.6

package/src/channels/router.ts

@@ -24,6 +24,7 @@ import type { HookBus } from '@/plugin'
 import { extractClaimCode } from '@/role-claim'
 import type { Stream } from '@/stream'
 
+import { extractMentionedUserIds } from './adapters/mention-hints'
 import { formatChannelCommandHelp } from './commands'
 import { detectContinuationWillingness } from './continuation-willingness'
 import {
@@ -111,13 +112,18 @@ export const TYPING_HEARTBEAT_MS = 8000
 // turns a temporary status into a permanent-looking artifact.
 //
 // The cap is measured from `live.typingStartedAt`, which is refreshed by
-// two signals of life (see `bumpTypingActivity`):
+// these signals of life (see `bumpTypingActivity`):
 //   1. Each new `drain()` iteration (a new turn is starting).
 //   2. Each `tool_execution_end` from the agent session (a tool just
 //      completed — the prompt is progressing, not stuck).
-// A 2-minute bash command that emits no intermediate events still trips
-// the cap, but a chatty agent running long tools stays under it
-// indefinitely. The cap exists to catch *silence*, not duration.
+//   3. Each streaming token (`message_update` carrying a `text_delta` or
+//      `thinking_delta`) — the model is actively generating, even on a
+//      pure-text reply that calls no tools.
+// Signal 3 is what keeps a long conversational reply (no tool calls, just
+// minutes of streamed text or extended thinking) under the cap: without it,
+// such a turn emits no `tool_execution_end` and the indicator was paused
+// mid-generation. A genuinely stuck model call — no tokens, no tools — still
+// trips the cap. The cap exists to catch *silence*, not duration.
 export const MAX_TYPING_HEARTBEAT_MS = 2 * 60 * 1000
 
 // Idle GC: a LiveSession whose `lastInboundAt` is older than
@@ -260,6 +266,28 @@ export const EMPTY_TURN_RETRY_NUDGE = [
 // drop so the human is never left staring at dead air after a degenerate turn.
 export const EMPTY_TURN_FALLBACK_TEXT =
   "⚠️ I got stuck putting together a reply and couldn't finish. Could you rephrase or try again?"
+// Distinct from EMPTY_TURN_RETRY_NUDGE: that one diagnoses budget exhaustion
+// ("ran out of output budget"), which is FALSE for a clean `stop` with empty
+// text. This nudge names the real failure — a turn that ended sending nothing
+// to a message addressed to the agent in a one-on-one conversation — and steers
+// the model to either answer or record the silence explicitly (skip_response /
+// NO_REPLY) rather than ending empty again.
+export const COLD_START_REPLY_NUDGE = [
+  '---',
+  '**[SYSTEM MESSAGE — not from a human]**',
+  '',
+  'Your previous turn ended without sending anything, but the last message was',
+  'addressed to you in a direct, one-on-one conversation — ending silent there',
+  'reads as ignoring the person. This is an automated signal from the channel',
+  'router, not a message from anyone in the chat. **Do not acknowledge or reply',
+  'to this notice itself.**',
+  '',
+  'Answer the last user message now via your channel reply tool. If you truly',
+  'have nothing to add, call `skip_response({ reason })` (preferred) or end with',
+  'exactly `NO_REPLY` so the silence is recorded — do not just end empty.',
+  '',
+  '---',
+].join('\n')
 // At most one continuation nudge per logical turn. Stricter than the empty-turn
 // retry budget (2) because the turn ALREADY delivered a user-facing reply — this
 // is a one-shot correction offer, not recovery from no output.
@@ -579,6 +607,11 @@ type LiveSession = {
   typingStartedAt: number
   typingTimedOut: boolean
   typingStopPromise: Promise<void> | null
+  // True only while `live.session.prompt()` is actively running. Gates the
+  // deferred typing revival: a revival queued behind an in-flight cap-trip
+  // 'stop' must NOT re-arm the heartbeat once the prompt has finished, or it
+  // leaks a timer that fires past the turn's end.
+  promptInFlight: boolean
   lastInboundAt: number
   // Transcript-file size (bytes) captured immediately after cold-start, before
   // any user turn — a proxy for the fixed base-context rebuild cost (rendered
@@ -772,6 +805,20 @@ type LiveSession = {
   // decision used, so the prompt nudge and sticky suppression agree on
   // "is this a multi-human group". Read by composeTurnPrompt().
   multiHumanGroup: boolean
+  // True when this live session was born from a cold-start (no persisted
+  // session existed — first contact or a stale-rollover after long idle), as
+  // opposed to rehydrating an existing session. Combined with `turnSeq === 0`
+  // it pinpoints the very first prompt of a freshly woken session.
+  createdFromColdStart: boolean
+  // Set in route() when the FIRST turn of a cold-start session engages via the
+  // solo-human "answer everything" fallback (not an explicit mention/reply/DM,
+  // not a multi-human group). Read by validateChannelTurn: a BARE-EMPTY stop on
+  // such a turn is a model whiff on a direct one-on-one question, not deliberate
+  // silence, so it earns an empty-turn retry instead of a silent no_reply.
+  // Recomputed on every engage, so it self-clears once turnSeq leaves the first
+  // turn; explicit NO_REPLY / skip_response and any turn that already sent stay
+  // on the historical silent path.
+  coldStartSoloFallbackTurnActive: boolean
   membershipFetch: Promise<MembershipCount | null> | null
   // Provider soft-error (`stopReason: 'error'`) captured during the current
   // turn, deferred to turn-end. Upstream surfaces transient errors (e.g.
@@ -1631,6 +1678,7 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
         typingStartedAt: 0,
         typingTimedOut: false,
         typingStopPromise: null,
+        promptInFlight: false,
         lastInboundAt: now(),
         baseContextBytes: 0,
         firstUnprocessedAt: 0,
@@ -1673,6 +1721,8 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
         consecutiveEngagedPeerBotTurns: 0,
         loopGuardActive: false,
         multiHumanGroup: false,
+        createdFromColdStart: isColdStart,
+        coldStartSoloFallbackTurnActive: false,
         membershipFetch,
         pendingProviderError: null,
         destroyed: false,
@@ -1886,10 +1936,70 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
     live.typingStartedAt = now()
   }
 
+  // Re-arm a heartbeat that the silence cap already stopped. PR #930 made
+  // streamed deltas refresh the clock, but only via `bumpTypingActivity`,
+  // which no-ops once `typingTimer` is null. So a turn that goes silent for
+  // >MAX_TYPING_HEARTBEAT_MS (a long single tool call, a slow provider, an
+  // extended-thinking phase that emits no deltas) trips the cap, and the
+  // delta/tool signals that arrive afterwards can no longer revive it —
+  // `startTypingHeartbeat` short-circuits on `typingTimedOut`, which only
+  // resets at the next drain() iteration (i.e. never, within one long turn).
+  // Reviving here lets demonstrable progress after a timeout bring the
+  // indicator back. The revival is gated on streamed activity ONLY, never on
+  // a new inbound (a later inbound during the same in-flight turn must stay
+  // silenced — see the matching router test).
+  //
+  // On Slack this is the visible bug: its `'stop'` phase sends a permanent
+  // empty-string `setStatus` clear that does not auto-expire, so a tripped
+  // indicator stays gone. Discord/Telegram mask the same defect because their
+  // native indicators auto-expire and self-heal on the next tick.
+  const reviveTypingActivity = (live: LiveSession): void => {
+    if (live.destroyed) return
+    if (!live.typingTimedOut) {
+      bumpTypingActivity(live)
+      return
+    }
+    // A `'stop'` clear may still be in flight. Starting a new heartbeat now
+    // would short-circuit on the non-null `typingStopPromise` (losing the
+    // revival), and firing a fresh `'tick'` before Slack's empty-string clear
+    // lands would let the clear wipe the just-revived status. Defer until the
+    // stop settles so the new `'tick'` is ordered strictly after the clear.
+    const stopPromise = live.typingStopPromise
+    if (stopPromise) {
+      void stopPromise.catch(() => undefined).then(() => restartTypingAfterTimeout(live))
+      return
+    }
+    restartTypingAfterTimeout(live)
+  }
+
+  const restartTypingAfterTimeout = (live: LiveSession): void => {
+    // Re-checked after the awaited stop:
+    //  - `destroyed`: the session may have been torn down.
+    //  - `!typingTimedOut`: an earlier queued revival already cleared the flag
+    //    and re-armed (so this one is a no-op — no double interval/tick).
+    //  - `!promptInFlight`: the prompt finished while the cap-trip 'stop' was
+    //    still in flight. A revival queued by a late delta would otherwise
+    //    re-arm a heartbeat after generation ended — a timer nothing stops
+    //    (drain()'s turn-end stop already ran with `typingTimer === null`).
+    //    `draining` is too coarse: it stays true through the turn-end hook tail
+    //    (turn-end/idle/todos) after `prompt()` returns, so a revival running
+    //    in that window would still leak. Gate on active generation instead.
+    if (live.destroyed || !live.promptInFlight || !live.typingTimedOut) return
+    live.typingTimedOut = false
+    startTypingHeartbeat(live)
+  }
+
   const subscribeTypingActivity = (session: AgentSession, live: LiveSession): (() => void) => {
     return session.subscribe((event) => {
-      if (event.type !== 'tool_execution_end') return
-      bumpTypingActivity(live)
+      if (event.type === 'tool_execution_end') {
+        reviveTypingActivity(live)
+        return
+      }
+      if (event.type !== 'message_update') return
+      const streamed = event.assistantMessageEvent.type
+      if (streamed === 'text_delta' || streamed === 'thinking_delta') {
+        reviveTypingActivity(live)
+      }
     })
   }
 
@@ -2287,6 +2397,7 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
         const isRealUserTurn = batch.length > 0
         const retrievalContext = await fireSessionTurnStart(live, composeRetrievalQuery(batch))
         const promptText = retrievalContext.results.length > 0 ? `${text}\n\n${retrievalContext.results}` : text
+        live.promptInFlight = true
         try {
           await live.session.prompt(promptText)
           await validateChannelTurn(live, successfulSendsBeforePrompt)
@@ -2298,6 +2409,7 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
           live.lastSentText.clear()
           live.lastSendLeafId = null
         } finally {
+          live.promptInFlight = false
           const sentReplyThisTurn = live.successfulChannelSends > successfulSendsBeforePrompt
           if (sentReplyThisTurn) dropEngageReactionsAfterReply(live, engageAddPromises)
           const emptyTurnRetryQueued = live.emptyTurnRetries > emptyTurnRetriesBeforePrompt
@@ -2557,7 +2669,8 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
 
     const membership = await membershipForEngagement(live)
 
-    live.multiHumanGroup = isMultiHumanGroup(event.isDm, countEffectiveHumans(live.participants, membership, now()))
+    const effectiveHumans = countEffectiveHumans(live.participants, membership, now())
+    live.multiHumanGroup = isMultiHumanGroup(event.isDm, effectiveHumans)
 
     const decision: EngagementDecision = decideEngagement({
       message: event,
@@ -2583,6 +2696,22 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
 
     publishInbound(event, 'engage', live.sessionId)
 
+    // Arm cold-start bare-empty recovery only for the exact incident shape: the
+    // FIRST prompt (`turnSeq === 0`) of a freshly cold-started session that
+    // engaged via the solo-human answer-everything fallback — a lone human, no
+    // explicit mention/reply/DM, not a multi-human group. Recomputed on every
+    // engage so it self-clears once the first turn advances `turnSeq`; explicit
+    // address (mention/reply/DM) keeps the historical silent-on-empty path.
+    live.coldStartSoloFallbackTurnActive =
+      live.createdFromColdStart &&
+      live.turnSeq === 0 &&
+      effectiveHumans <= 1 &&
+      !event.authorIsBot &&
+      !event.isDm &&
+      !event.isBotMention &&
+      event.replyToBotMessageId === null &&
+      !live.multiHumanGroup
+
     const engageReaction = autoReactOnEngage(event)
 
     updateLoopGuard(live, event)
@@ -3320,11 +3449,21 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
       const disengagedThisTurn = live.disengagedTurn !== null && live.disengagedTurn === live.turnSeq
       const adapterConfig = options.configForAdapter(msg.adapter)
       if (adapterConfig && !disengagedThisTurn) {
-        const targetIds = Array.from(
-          live.currentTurnAuthorIds.size > 0 ? live.currentTurnAuthorIds : live.lastTurnAuthorIds,
-        )
-        if (targetIds.length > 0) {
-          grantStickyForReplyTargets(stickyLedger, keyId, targetIds, adapterConfig.engagement, now())
+        const targets = new Set(live.currentTurnAuthorIds.size > 0 ? live.currentTurnAuthorIds : live.lastTurnAuthorIds)
+        // A user the agent addresses by @-mention is a reply target too: their
+        // next message answers us without re-mentioning the bot. Granting them
+        // sticky closes the gap where the agent asks "<@U123> can you confirm?"
+        // and that user's plain reply was observed until they re-pinged.
+        // Self-mentions (e.g. a quoted inbound) are excluded — we credit the
+        // OTHERS we addressed, not ourselves.
+        if (text !== undefined) {
+          const selfId = resolveSelfIdentity(live.key)?.id
+          for (const id of extractMentionedUserIds(msg.adapter, text)) {
+            if (id !== selfId) targets.add(id)
+          }
+        }
+        if (targets.size > 0) {
+          grantStickyForReplyTargets(stickyLedger, keyId, Array.from(targets), adapterConfig.engagement, now())
         }
       }
       const turnCount = live.consecutiveSends.get(sendKey) ?? 0
@@ -3597,6 +3736,36 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
     let assistantText = candidateText
 
     if (endsWithNoReplySignal(assistantText)) {
+      // A BARE-EMPTY stop (no visible text, not an explicit NO_REPLY token) on
+      // the armed cold-start solo-human fallback turn is the production "dropped
+      // the owner's first question" shape — a model whiff on a direct one-on-one
+      // question, not a deliberate decline. Give it the bounded empty-turn retry
+      // with a dedicated nudge; on exhaustion post the visible fallback so the
+      // human is never stranded on silence. Gated hard so deliberate silence
+      // still stays silent: explicit NO_REPLY (non-empty trim), any turn that
+      // already sent (successfulChannelSends moved), a queued fresh inbound (the
+      // next drain answers it), and every turn outside the armed cold-start solo
+      // path all fall through to the historical no_reply below.
+      if (
+        assistantText.trim() === '' &&
+        source === 'leaf' &&
+        live.coldStartSoloFallbackTurnActive &&
+        live.currentTurnAuthorId !== null &&
+        live.successfulChannelSends === successfulSendsBeforePrompt &&
+        live.promptQueue.length === 0
+      ) {
+        if (live.emptyTurnRetries < MAX_EMPTY_TURN_RETRIES) {
+          live.emptyTurnRetries++
+          logger.warn(
+            `[channels] ${live.keyId} empty_turn_retry attempt=${live.emptyTurnRetries}/${MAX_EMPTY_TURN_RETRIES} ` +
+              `cause=cold_start_solo_bare_empty`,
+          )
+          live.pendingSystemReminders.push(COLD_START_REPLY_NUDGE)
+          return
+        }
+        await postEmptyTurnFallback('cold_start_solo_bare_empty_retries_exhausted')
+        return
+      }
       const leakedReasoning = !isNoReplySignal(assistantText)
       logger.info(`[channels] ${live.keyId} no_reply${leakedReasoning ? ' (with_leaked_reasoning)' : ''}`)
       return

package/src/cli/compose.ts

@@ -325,7 +325,8 @@ function makeBoard(header: string): Board {
 function formatStartDone<T extends { alreadyRunning?: boolean; hostPort: number }>(result: AgentResult<T>): string {
   if (!result.ok) return `${c.red('✖')} ${c.red('failed:')} ${result.reason}`
   const verb = result.data.alreadyRunning ? 'already running' : 'started'
-  return `${c.green('✔')} ${verb} on host port ${c.cyan(String(result.data.hostPort))}`
+  const head = `${c.green('✔')} ${verb} on host port ${c.cyan(String(result.data.hostPort))}`
+  return appendWarnings(head, result.warnings)
 }
 
 function formatStopDone<T extends { running: boolean }>(result: AgentResult<T>): string {
@@ -336,7 +337,15 @@ function formatStopDone<T extends { running: boolean }>(result: AgentResult<T>):
 
 function formatRestartDone<T extends { start: { hostPort: number } }>(result: AgentResult<T>): string {
   if (!result.ok) return `${c.red('✖')} ${c.red('failed:')} ${result.reason}`
-  return `${c.green('✔')} restarted on host port ${c.cyan(String(result.data.start.hostPort))}`
+  const head = `${c.green('✔')} restarted on host port ${c.cyan(String(result.data.start.hostPort))}`
+  return appendWarnings(head, result.warnings)
+}
+
+// Surface non-fatal validateConfig warnings under the per-agent compose status
+// line so compose start/restart don't silently drop what `typeclaw start` prints.
+function appendWarnings(head: string, warnings: string[] | undefined): string {
+  if (warnings === undefined || warnings.length === 0) return head
+  return [head, ...warnings.map((w) => `  ${c.yellow('⚠')} ${w}`)].join('\n')
 }
 
 function emitComposeDoctor(report: ComposeDoctorReport, opts: { verbose: boolean; json: boolean }): void {

package/src/cli/dreams.ts

@@ -1,9 +1,9 @@
 import { defineCommand } from 'citty'
 
 import { type DreamEntry, renderListRow, runDreams, type ViewAction } from '@/dreams'
-import { findAgentDir } from '@/init'
 
 import { createEscController } from './inspect-controller'
+import { requireAgentDir } from './require-agent-dir'
 import { c, cancel, errorLine, isCancel, prepareStdinForClack } from './ui'
 
 const ESC_DEBOUNCE_MS = 50
@@ -31,7 +31,7 @@ export const dreamsCommand = defineCommand({
     },
   },
   async run({ args }) {
-    const cwd = findAgentDir(process.cwd()) ?? process.cwd()
+    const cwd = requireAgentDir()
     const color = useColor()
     const limit = parseLimit(args.limit)
     const interactive = isInteractive() && args.json !== true

package/src/cli/inspect.ts

@@ -1,7 +1,6 @@
 import { defineCommand } from 'citty'
 
 import { requireContainerRunning, resolveHostPort, resolveTuiToken } from '@/container'
-import { findAgentDir } from '@/init'
 import {
   fetchLiveSessions,
   listViewerItems,
@@ -20,6 +19,7 @@ import {
 import { originLabel, shortSessionId } from '@/inspect/label'
 
 import { createTailScope } from './inspect-controller'
+import { requireAgentDir } from './require-agent-dir'
 import { cancel, c, errorLine, isCancel, prepareStdinForClack } from './ui'
 
 const ESC_DEBOUNCE_MS = 50
@@ -51,7 +51,7 @@ export const inspectCommand = defineCommand({
     },
   },
   async run({ args }) {
-    const cwd = findAgentDir(process.cwd()) ?? process.cwd()
+    const cwd = requireAgentDir()
     const color = useColor()
     const sessionArg = typeof args.session === 'string' ? args.session : undefined
     const filterArg = typeof args.filter === 'string' ? args.filter : undefined

package/src/cli/logs.ts

@@ -1,9 +1,9 @@
 import { defineCommand } from 'citty'
 
 import { logs, parseTailValue } from '@/container'
-import { findAgentDir } from '@/init'
 
 import { runInspectViewer } from './inspect'
+import { requireAgentDir } from './require-agent-dir'
 import { c, errorLine } from './ui'
 
 export const logsCommand = defineCommand({
@@ -30,7 +30,7 @@ export const logsCommand = defineCommand({
     },
   },
   async run({ args }) {
-    const cwd = findAgentDir(process.cwd()) ?? process.cwd()
+    const cwd = requireAgentDir()
 
     let tail: string | undefined
     if (args.tail !== undefined) {

package/src/cli/mount.ts

@@ -8,7 +8,7 @@ import { c, errorLine, successLine } from './ui'
 const listSub = defineCommand({
   meta: {
     name: 'list',
-    description: 'list host directories mounted into the agent container',
+    description: 'list host files and directories mounted into the agent container',
   },
   args: {
     json: {
@@ -31,7 +31,7 @@ const listSub = defineCommand({
 const addSub = defineCommand({
   meta: {
     name: 'add',
-    description: 'add a host directory mount to typeclaw.json',
+    description: 'add a host file or directory mount to typeclaw.json',
   },
   args: {
     name: {
@@ -41,7 +41,7 @@ const addSub = defineCommand({
     },
     path: {
       type: 'positional',
-      description: 'host directory path to expose inside the container',
+      description: 'host file or directory path to expose inside the container',
       required: true,
     },
     'read-only': {
@@ -74,7 +74,7 @@ const addSub = defineCommand({
 const removeSub = defineCommand({
   meta: {
     name: 'remove',
-    description: 'remove a host directory mount from typeclaw.json',
+    description: 'remove a host mount from typeclaw.json',
   },
   args: {
     name: {
@@ -98,7 +98,7 @@ const removeSub = defineCommand({
 export const mountCommand = defineCommand({
   meta: {
     name: 'mount',
-    description: 'manage host directories mounted into the agent container',
+    description: 'manage host files and directories mounted into the agent container',
   },
   subCommands: {
     list: listSub,

package/src/cli/require-agent-dir.ts

@@ -0,0 +1,31 @@
+import { findAgentDir, isInitialized } from '@/init'
+
+import { errorLine } from './ui'
+
+export type RequiredAgentDir = { ok: true; cwd: string } | { ok: false; message: string }
+
+const NOT_AN_AGENT_FOLDER = 'TypeClaw config file not found. Run `typeclaw init` first, or cd into an agent folder.'
+
+// Operational host-stage commands (inspect, tui, logs, stop, shell, dreams) act
+// on a specific agent's container or on-disk state, so they must run from inside
+// an agent folder. The `findAgentDir(...) ?? startDir` fallback every caller used
+// silently degraded these commands into an agent-less view — e.g. `inspect` would
+// warn "container not running" and then offer only the container-logs row — instead
+// of failing. Resolving to a fail result keeps the existence check explicit.
+//
+// Diagnostic commands (status, doctor, role list) deliberately tolerate a missing
+// agent folder and must NOT use this gate.
+export function resolveRequiredAgentDir(startDir: string): RequiredAgentDir {
+  const cwd = findAgentDir(startDir) ?? startDir
+  if (!isInitialized(cwd)) return { ok: false, message: NOT_AN_AGENT_FOLDER }
+  return { ok: true, cwd }
+}
+
+export function requireAgentDir(startDir: string = process.cwd()): string {
+  const result = resolveRequiredAgentDir(startDir)
+  if (!result.ok) {
+    console.error(errorLine(result.message))
+    process.exit(1)
+  }
+  return result.cwd
+}

package/src/cli/restart.ts

@@ -6,7 +6,7 @@ import { start, stop } from '@/container'
 import { findAgentDir, isInitialized } from '@/init'
 
 import { guardIncompleteInit } from './incomplete-init'
-import { c, errorLine, renderStartSuccess, spinner } from './ui'
+import { c, errorLine, renderStartSuccess, reportConfigWarnings, spinner } from './ui'
 
 export const restartCommand = defineCommand({
   meta: {
@@ -61,6 +61,7 @@ export const restartCommand = defineCommand({
       console.error(errorLine(validated.reason))
       process.exit(1)
     }
+    reportConfigWarnings(validated.warnings)
 
     const stopSpin = spinner()
     stopSpin.start('Stopping container...')

package/src/cli/shell.ts

@@ -1,8 +1,8 @@
 import { defineCommand } from 'citty'
 
 import { shell } from '@/container'
-import { findAgentDir } from '@/init'
 
+import { requireAgentDir } from './require-agent-dir'
 import { c, errorLine } from './ui'
 
 export const shellCommand = defineCommand({
@@ -18,7 +18,7 @@ export const shellCommand = defineCommand({
     },
   },
   async run({ args }) {
-    const cwd = findAgentDir(process.cwd()) ?? process.cwd()
+    const cwd = requireAgentDir()
 
     console.log(c.cyan(`Attaching ${args.shell} inside the container...`))
 

package/src/cli/start.ts

@@ -6,7 +6,7 @@ import { start } from '@/container'
 import { findAgentDir, isInitialized } from '@/init'
 
 import { guardIncompleteInit } from './incomplete-init'
-import { errorLine, renderStartSuccess, spinner } from './ui'
+import { errorLine, renderStartSuccess, reportConfigWarnings, spinner } from './ui'
 
 export const startCommand = defineCommand({
   meta: {
@@ -61,6 +61,7 @@ export const startCommand = defineCommand({
       console.error(errorLine(validated.reason))
       process.exit(1)
     }
+    reportConfigWarnings(validated.warnings)
 
     const s = spinner()
     s.start('Starting container...')

package/src/cli/stop.ts

@@ -1,8 +1,8 @@
 import { defineCommand } from 'citty'
 
 import { stop } from '@/container'
-import { findAgentDir } from '@/init'
 
+import { requireAgentDir } from './require-agent-dir'
 import { c, spinner } from './ui'
 
 export const stopCommand = defineCommand({
@@ -11,7 +11,7 @@ export const stopCommand = defineCommand({
     description: 'stop the agent container (host stage)',
   },
   async run() {
-    const cwd = findAgentDir(process.cwd()) ?? process.cwd()
+    const cwd = requireAgentDir()
 
     const s = spinner()
     s.start('Stopping container...')

package/src/cli/tui.ts

@@ -1,12 +1,12 @@
 import { defineCommand } from 'citty'
 
 import { requireContainerRunning, resolveHostPort, resolveTuiToken } from '@/container'
-import { findAgentDir } from '@/init'
 import { CLI_VERSION } from '@/init/cli-version'
 import { runTuiViewer } from '@/inspect'
 import { formatVersionMismatchWarning } from '@/tui'
 
 import { runInspectViewer } from './inspect'
+import { requireAgentDir } from './require-agent-dir'
 import { errorLine } from './ui'
 
 export const tui = defineCommand({
@@ -27,9 +27,22 @@ export const tui = defineCommand({
     },
   },
   async run({ args }) {
-    const cwd = findAgentDir(process.cwd()) ?? process.cwd()
-    const resolveUrl: () => Promise<string> =
-      args.url !== undefined ? async () => args.url as string : () => defaultUrl(cwd)
+    // An explicit --url targets an agent over the wire and needs no local agent
+    // folder — only the default-URL discovery and the esc-detach picker read
+    // local state. Require an agent folder only when --url is absent, mirroring
+    // how reload/cron/role claim gate their default-target path, not the whole
+    // command.
+    const explicitUrl = typeof args.url === 'string' ? args.url : undefined
+    let cwd: string | undefined
+    let resolveUrl: () => Promise<string>
+    if (explicitUrl === undefined) {
+      const agentDir = requireAgentDir()
+      cwd = agentDir
+      resolveUrl = () => defaultUrl(agentDir)
+    } else {
+      cwd = undefined
+      resolveUrl = async () => explicitUrl
+    }
 
     const result = await runTuiViewer({
       resolveUrl,
@@ -45,8 +58,9 @@ export const tui = defineCommand({
     // can pick another session or the container logs — `tui` is just a deep-link
     // into the session viewer, pre-opened on the live session. allowWritable
     // is false because detaching ended the live session, so no row may be
-    // offered as a writable "live TUI" anymore.
-    if (result.ok && result.escToPicker === true) {
+    // offered as a writable "live TUI" anymore. A --url-only run has no local
+    // agent folder to browse, so it exits instead of opening the local picker.
+    if (result.ok && result.escToPicker === true && cwd !== undefined) {
       const viewerExit = await runInspectViewer({ cwd, allowWritable: false })
       process.exit(viewerExit)
       return

package/src/cli/ui.ts

@@ -222,6 +222,19 @@ export function successLine(message: string): string {
   return `${c.green('●')} ${message}`
 }
 
+export function warnLine(message: string): string {
+  return `${c.yellow('⚠')} ${message}`
+}
+
+// Single host-side sink for non-fatal validateConfig warnings (e.g. a
+// curl|bash docker.file.append line). Every CLI gate that calls validateConfig
+// before a start/rebuild routes through this so no path silently drops them.
+export function reportConfigWarnings(warnings: string[] | undefined): void {
+  for (const warning of warnings ?? []) {
+    console.warn(warnLine(warning))
+  }
+}
+
 // The exact JSON manifest a user pastes into
 // https://api.slack.com/apps → From a manifest. Kept as a typed object so
 // the file stays a single source of truth and `JSON.stringify` guarantees

package/src/compose/restart.ts

@@ -62,7 +62,7 @@ async function runOne(
     onStopped()
     const started = await start({ cwd, preferredHostPort, forceBuild, cliEntry })
     if (!started.ok) return { name, ok: false, reason: started.reason }
-    return { name, ok: true, data: { stop: stopped, start: started } }
+    return { name, ok: true, data: { stop: stopped, start: started }, warnings: validated.warnings }
   } catch (error) {
     return { name, ok: false, reason: error instanceof Error ? error.message : String(error) }
   }

package/src/compose/start.ts

@@ -3,7 +3,9 @@ import { start, type StartResult } from '@/container'
 
 import { discoverAgents, type AgentEntry } from './discover'
 
-export type AgentResult<T> = { name: string; ok: true; data: T } | { name: string; ok: false; reason: string }
+export type AgentResult<T> =
+  | { name: string; ok: true; data: T; warnings?: string[] }
+  | { name: string; ok: false; reason: string }
 
 export type StartSuccess = Extract<StartResult, { ok: true }>
 
@@ -55,7 +57,7 @@ async function runOne(
   try {
     const data = await start({ cwd, preferredHostPort, forceBuild, cliEntry })
     if (!data.ok) return { name, ok: false, reason: data.reason }
-    return { name, ok: true, data }
+    return { name, ok: true, data, warnings: validated.warnings }
   } catch (error) {
     return { name, ok: false, reason: error instanceof Error ? error.message : String(error) }
   }