typeclaw 0.36.8 → 0.37.1

package/src/server/command-runner.ts

@@ -55,6 +55,10 @@ export type CommandRunnerOptions = {
   // wire for the handler/command path.
   channelRouter: ChannelRouter | undefined
   mcpManager?: McpManager
+  // When true, prompt sessions spawned here omit the system-prompt `# Memory`
+  // section (vector agents inject memory per-turn). Forwarded to createSession
+  // so command/handler sessions stay coherent with the rest of the runtime.
+  suppressSystemMemory?: boolean
 }
 
 type CommandHandle = {
@@ -194,6 +198,7 @@ export function createCommandRunner(opts: CommandRunnerOptions): CommandRunner {
               signal: abortController.signal,
               sessionFactory: opts.sessionFactory,
               channelRouter: opts.channelRouter,
+              ...(opts.suppressSystemMemory !== undefined ? { suppressSystemMemory: opts.suppressSystemMemory } : {}),
               ...(opts.mcpManager !== undefined ? { mcpManager: opts.mcpManager } : {}),
             }),
           subagent: (subName, payload) =>
@@ -380,6 +385,7 @@ export async function runPromptForCommand(args: {
   // so the spawned session exposes `channel_send`.
   channelRouter?: ChannelRouter
   mcpManager?: McpManager
+  suppressSystemMemory?: boolean
   // 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
@@ -409,10 +415,27 @@ export async function runPromptForCommand(args: {
     ...(args.mcpManager !== undefined ? { mcpManager: args.mcpManager } : {}),
     ...(args.runtimeVersion !== undefined ? { runtimeVersion: args.runtimeVersion } : {}),
     ...(args.containerName !== undefined ? { containerName: args.containerName } : {}),
+    ...(args.suppressSystemMemory !== undefined ? { suppressSystemMemory: args.suppressSystemMemory } : {}),
   })
   const detachAbort = bindSignalToSession(args.signal, session)
+  // Mirror the other turn drivers (TUI/channel/cron/subagent): fire
+  // session.turn.start with a retrievalContext so a vector agent — whose
+  // system-prompt `# Memory` section is suppressed — gets its long-term memory
+  // injected per-turn into the user prompt here too. Without this, command and
+  // handler prompt sessions would have no memory at all under vector mode.
+  const turnEvent = { sessionId, agentDir: args.agentDir, origin: args.origin }
+  const retrievalContext = { results: '' }
   try {
-    await session.prompt(`${renderTurnTimeAnchor()}\n\n${args.text}`)
+    await snapshot.hooks.runSessionTurnStart({ ...turnEvent, userPrompt: args.text, retrievalContext })
+    const turnText =
+      retrievalContext.results.length > 0
+        ? `${renderTurnTimeAnchor()}\n\n${args.text}\n\n${retrievalContext.results}`
+        : `${renderTurnTimeAnchor()}\n\n${args.text}`
+    try {
+      await session.prompt(turnText)
+    } finally {
+      await snapshot.hooks.runSessionTurnEnd(turnEvent)
+    }
     return session.getLastAssistantText() ?? ''
   } finally {
     detachAbort()

package/src/server/index.ts

@@ -15,6 +15,7 @@ import { forgetSharedLoopGuardTool } from '@/agent/plugin-tools'
 import { detectProviderError } from '@/agent/provider-error'
 import { requestContainerRestart } from '@/agent/restart'
 import { consumeRestartHandoff, type RestartHandoff } from '@/agent/restart-handoff'
+import { sessionMetaPayload } from '@/agent/session-meta'
 import type { SessionOrigin } from '@/agent/session-origin'
 import { parseSubagentCompletedPayload, renderSubagentCompletionReminder } from '@/agent/subagent-completion-reminder'
 import type { CreateSessionForSubagent } from '@/agent/subagents'
@@ -541,7 +542,12 @@ export function createServer({
               state.unsubTurnOutcome = subscribeTurnOutcome(session, agentDir, origin, sessionFileId, logger)
             }
 
-            liveSessionRegistry?.register({ sessionId: sessionFileId, session })
+            liveSessionRegistry?.register({
+              sessionId: sessionFileId,
+              session,
+              origin: sessionMetaPayload(origin).origin,
+              registeredAtMs: Date.now(),
+            })
             forwardSessionEvents(ws, state, logger, sessionFileId)
 
             if (stream) {
@@ -760,17 +766,23 @@ export function createServer({
             }
             send(ws, { type: 'prompt_started', messageId: `local-${crypto.randomUUID()}`, text: msg.text })
             const fallbackHooks = state.runtimeSnapshot?.hooks
+            const retrievalContext: { results: string } = { results: '' }
             if (fallbackHooks !== undefined && agentDir !== undefined) {
               await fallbackHooks.runSessionTurnStart({
                 sessionId: state.sessionFileId,
                 agentDir,
                 userPrompt: msg.text,
                 origin: state.origin,
+                retrievalContext,
               })
             }
             state.lastUsage = null
             try {
-              await state.session.prompt(`${renderTurnTimeAnchor()}\n\n${msg.text}`)
+              const turnText =
+                retrievalContext.results.length > 0
+                  ? `${renderTurnTimeAnchor()}\n\n${msg.text}\n\n${retrievalContext.results}`
+                  : `${renderTurnTimeAnchor()}\n\n${msg.text}`
+              await state.session.prompt(turnText)
               send(ws, doneMessage(state))
             } catch (err) {
               const message = err instanceof Error ? err.message : String(err)
@@ -1019,15 +1031,24 @@ function makeIdleHookCaller(state: SessionState): () => Promise<void> {
 function makeTurnHookCallers(
   state: SessionState,
   agentDir: string | undefined,
-): { fireTurnStart: (userPrompt: string) => Promise<void>; fireTurnEnd: () => Promise<void> } {
+): { fireTurnStart: (userPrompt: string) => Promise<{ results: string }>; fireTurnEnd: () => Promise<void> } {
   const hooks: HookBus | undefined = state.runtimeSnapshot?.hooks
   if (hooks === undefined || agentDir === undefined) {
-    return { fireTurnStart: async () => {}, fireTurnEnd: async () => {} }
+    return { fireTurnStart: async () => ({ results: '' }), fireTurnEnd: async () => {} }
   }
   const turnEndEvent = { sessionId: state.sessionFileId, agentDir, origin: state.origin }
   return {
-    fireTurnStart: (userPrompt) =>
-      hooks.runSessionTurnStart({ sessionId: state.sessionFileId, agentDir, userPrompt, origin: state.origin }),
+    fireTurnStart: async (userPrompt) => {
+      const retrievalContext = { results: '' }
+      await hooks.runSessionTurnStart({
+        sessionId: state.sessionFileId,
+        agentDir,
+        userPrompt,
+        origin: state.origin,
+        retrievalContext,
+      })
+      return retrievalContext
+    },
     fireTurnEnd: () => hooks.runSessionTurnEnd(turnEndEvent),
   }
 }
@@ -1058,10 +1079,14 @@ async function drain(
         }).catch((err) => logger.error(`[server] ${state.sessionFileId}: todo turn-start failed: ${describeErr(err)}`))
       }
 
-      await fireTurnStart(item.text)
+      const retrievalContext = await fireTurnStart(item.text)
       state.lastUsage = null
       try {
-        await state.session.prompt(`${renderTurnTimeAnchor()}\n\n${item.text}`)
+        const turnText =
+          retrievalContext.results.length > 0
+            ? `${renderTurnTimeAnchor()}\n\n${item.text}\n\n${retrievalContext.results}`
+            : `${renderTurnTimeAnchor()}\n\n${item.text}`
+        await state.session.prompt(turnText)
         send(ws, doneMessage(state))
       } catch (err) {
         const message = err instanceof Error ? err.message : String(err)
@@ -1269,6 +1294,15 @@ function handleInspectMessage(
     sendInspect(ws, { type: 'pong', id: msg.id })
     return
   }
+  if (msg.type === 'list_live') {
+    const sessions = (liveSessionRegistry?.listLive() ?? []).map((e) => ({
+      sessionId: e.sessionId,
+      origin: e.origin!,
+      registeredAtMs: e.registeredAtMs ?? 0,
+    }))
+    sendInspect(ws, { type: 'live_sessions', sessions })
+    return
+  }
   if (msg.type !== 'subscribe' || typeof msg.sessionId !== 'string' || msg.sessionId === '') {
     sendInspect(ws, { type: 'error', message: 'invalid inspect subscription' })
     ws.close()

package/src/shared/index.ts

@@ -14,6 +14,8 @@ export {
   type InspectClientMessage,
   type InspectFramePayload,
   type InspectServerMessage,
+  type LiveSessionOriginPayload,
+  type LiveSessionPayload,
   type PromptDelivery,
   type QueueStateItem,
   type ReloadResultPayload,

package/src/shared/protocol.ts

@@ -60,6 +60,36 @@ export type InspectClientMessage =
   // distinguish "idle" from "dead"; a missed pong can. Guards a wedged
   // WebSocket that stays ESTABLISHED yet never fires 'close'/'error'.
   | { type: 'ping'; id: number }
+  // One-shot query for sessions live in the container's registry but not yet on
+  // disk (pi-coding-agent defers the first .jsonl write to the first assistant
+  // message). Lets the host-stage inspect picker show in-flight sessions before
+  // their reply lands. Answered with a single `live_sessions` reply.
+  | { type: 'list_live' }
+
+// Wire mirror of MinimalSessionOrigin (@/agent/session-meta). Duplicated rather
+// than imported because @/shared is a leaf module — @/agent depends on it, so
+// importing back would create a cycle. A compile-time assertion in session-meta
+// keeps the two structurally in sync; drift fails typecheck.
+export type LiveSessionOriginPayload =
+  | { kind: 'tui' }
+  | { kind: 'cron'; jobId: string; jobKind: 'prompt' | 'exec' | 'subagent' | 'handler' }
+  | {
+      kind: 'channel'
+      adapter: string
+      workspace: string
+      workspaceName?: string
+      chat: string
+      chatName?: string
+      thread: string | null
+    }
+  | { kind: 'subagent'; subagent: string; parentSessionId: string }
+  | { kind: 'system'; component: string }
+
+export type LiveSessionPayload = {
+  sessionId: string
+  origin: LiveSessionOriginPayload
+  registeredAtMs: number
+}
 
 export type InspectFramePayload =
   | { kind: 'text_delta'; sessionId: string; delta: string }
@@ -137,6 +167,7 @@ export type InspectServerMessage =
   | { type: 'frame'; ts: number; payload: InspectFramePayload }
   | { type: 'error'; message: string }
   | { type: 'pong'; id: number }
+  | { type: 'live_sessions'; sessions: LiveSessionPayload[] }
 
 export type ClientMessage =
   | { type: 'prompt'; text: string; delivery?: PromptDelivery }

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

@@ -1,6 +1,6 @@
 ---
 name: typeclaw-channels
-description: "TypeClaw channel behavior: how the agent decides to engage vs. stay silent on external messenger inbound (Discord, Slack, Telegram, KakaoTalk). Covers the `channels.<adapter>.engagement` triggers (mention/reply/dm), reply stickiness, the non-configurable solo-human fallback, history-prefetch windows, and the `alias` system — plain-text names the agent answers to, substring match semantics, peer-name suppressors, and engagement priority. Load when the user asks why the agent did or did not respond in a channel, wants to change when it auto-replies, asks to 'be quieter'/'stop auto-replying', wants it to answer to a nickname, or mentions engagement, stickiness, aliases, mentions, trigger words, suppressors, or '응답', '호출', '채널', '별칭', '왜 답을 안 해'. Access control (who is admitted at all) lives in `roles` — see typeclaw-permissions. The `channels`/`alias` schema, defaults, and safe-edit workflow live in typeclaw-config."
+description: "TypeClaw channel behavior: how the agent decides to engage vs. stay silent on external messenger inbound (Discord, Slack, Telegram, LINE, KakaoTalk). Covers the `channels.<adapter>.engagement` triggers (mention/reply/dm), reply stickiness, the non-configurable solo-human fallback, history-prefetch windows, and the `alias` system — plain-text names the agent answers to, substring match semantics, peer-name suppressors, and engagement priority. Load when the user asks why the agent did or did not respond in a channel, wants to change when it auto-replies, asks to 'be quieter'/'stop auto-replying', wants it to answer to a nickname, or mentions engagement, stickiness, aliases, mentions, trigger words, suppressors, or '응답', '호출', '채널', '별칭', '왜 답을 안 해'. Access control (who is admitted at all) lives in `roles` — see typeclaw-permissions. The `channels`/`alias` schema, defaults, and safe-edit workflow live in typeclaw-config."
 ---
 
 # typeclaw-channels
@@ -16,7 +16,7 @@ Both `channels` and `alias` are **live-reloadable** — edits take effect on the
 
 ## Channels
 
-`channels` configures which external messenger adapters are enabled and how the engagement layer should behave on each. **Access control lives in `roles`, not here** — to admit a chat, declare a role match-rule that covers it (see `typeclaw-permissions`). The shape is `channels: { "<adapter-id>": { engagement, history, enabled } }`. Today the adapters are `discord-bot`, `slack-bot`, `telegram-bot`, and `kakaotalk`.
+`channels` configures which external messenger adapters are enabled and how the engagement layer should behave on each. **Access control lives in `roles`, not here** — to admit a chat, declare a role match-rule that covers it (see `typeclaw-permissions`). The shape is `channels: { "<adapter-id>": { engagement, history, enabled } }`. Today the adapters are `discord-bot`, `slack-bot`, `telegram-bot`, `line`, and `kakaotalk`.
 
 The channels block is **live-reloadable** — edits take effect on the next `reload`, no container restart.
 
@@ -78,8 +78,8 @@ This says: the `discord-bot` adapter is enabled with default engagement; one spe
 
 This is a **`roles`** edit, not a `channels` edit. See the `typeclaw-permissions` skill for the full procedure. Short version:
 
-1. Get the platform ID (Discord channel ID, Slack channel ID, Telegram chat ID, KakaoTalk chat ID).
-2. Append a match-rule to `roles.member.match` using the canonical DSL (`discord:<guild>/<channel>`, `slack:<team>/<channel>`, `telegram:<chat>`, `kakao:<chat>`). Pass `acknowledgeGuards: { rolePromotion: true }` in the `write`/`edit` args — the `rolePromotion` security guard blocks any widening of `roles.<role>.match` without an ack (see `typeclaw-permissions`).
+1. Get the platform ID (Discord channel ID, Slack channel ID, Telegram chat ID, LINE chat ID, KakaoTalk chat ID).
+2. Append a match-rule to `roles.member.match` using the canonical DSL (`discord:<guild>/<channel>`, `slack:<team>/<channel>`, `telegram:<chat>`, for LINE the bucketed form `line:dm/<chatId>`, `line:group/<chatId>`, or `line:square/<chatId>` — pick the bucket from the chat's classification; an unbucketed `line:<chatId>` is read as a workspace and never matches — and `kakao:<chat>`). Pass `acknowledgeGuards: { rolePromotion: true }` in the `write`/`edit` args — the `rolePromotion` security guard blocks any widening of `roles.<role>.match` without an ack (see `typeclaw-permissions`).
 3. **`roles.<role>.match[]` edits are live-reloadable** — they take effect on the next `typeclaw reload` (the classifier marks `roles.match` as `applied`, and the permission service rebuilds its role table). Only `roles.<role>.permissions[]` edits are restart-required. So adding a match-rule to admit a channel applies on `reload`; no container restart needed.
 
 ### When the user asks "stop replying in this channel"

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

@@ -18,7 +18,7 @@ The runtime reads `typeclaw.json` at container startup. Some fields are picked u
 - `mounts` — additional host directories the user has chosen to expose to you. Each entry produces a `docker run -v <hostPath>:/agent/mounts/<name>` flag at `typeclaw start` time, so the directory shows up at `mounts/<name>` inside your agent folder. **The launcher reads this; the running container does not.** Editing `mounts` only takes effect on the next `typeclaw start`. **Restart-required.**
 - `plugins` — array of plugin module specifiers loaded at server boot: npm package names for published plugins, or relative paths for local plugins you are authoring. **Restart-required.**
 - `alias` — additional names the agent answers to when a channel message contains its name in plain text (no `<@id>` mention). The agent folder's directory name (`basename(agentDir)`) is always implicit; `alias` adds further forms (Latin transliteration, nicknames, Korean particles, etc.). Used by the channel engagement layer alongside the structural mention/reply/dm triggers. **Live-reloadable.**
-- `channels` — per-adapter engagement triggers and history-prefetch knobs for external messengers (Discord, Slack, Telegram, KakaoTalk), plus the GitHub channel (a webhook-driven adapter that watches repos and reviews PRs — see **GitHub channel** below). Access control lives in `roles`, not here. **Live-reloadable** — edits take effect on the next `reload` without a container restart.
+- `channels` — per-adapter engagement triggers and history-prefetch knobs for external messengers (Discord, Slack, Telegram, LINE, KakaoTalk), plus the GitHub channel (a webhook-driven adapter that watches repos and reviews PRs — see **GitHub channel** below). Access control lives in `roles`, not here. **Live-reloadable** — edits take effect on the next `reload` without a container restart.
 - `docker.file` — controls what ships in the autogenerated container image. Two layers: (1) **toggles** for opinionated package installs — `tmux`, `gh`, `python`, `xvfb` default on (`true`); `cjkFonts` defaults to `"auto"` (resolved from host locale at start); `ffmpeg`, `cloudflared`, `claudeCode`, `codexCli` default off (`false`) — set a toggle to `false` to omit, or to a version string like `"2.40.0"` to apt-pin (`python`, `cjkFonts`, `cloudflared`, `xvfb`, `claudeCode`, and `codexCli` are boolean-only). Most toggles install apt packages with BuildKit cache mounts; `cloudflared`, `claudeCode`, and `codexCli` are exceptions — `cloudflared` downloads the pinned GitHub release, `claudeCode` runs Anthropic's official `curl | bash` installer, `codexCli` `bun install`s the `@openai/codex` npm package. (2) **`append`** — extra Dockerfile lines spliced in right before `ENTRYPOINT` for anything the toggles don't cover. The whole Dockerfile is rewritten on every `start` from the typeclaw template. Lives under the `docker` namespace alongside future Docker-related blocks (e.g. `docker.compose`). **Restart-required** (next `typeclaw start` rebuilds the image).
 - `git.ignore.append` — extra `.gitignore` patterns `typeclaw start` splices into the TypeClaw-owned `.gitignore` before the protected TypeClaw rules. The whole `.gitignore` is rewritten and auto-committed on every `start` when it changes; `append` is the supported escape hatch for local ignore patterns without editing the managed file by hand. Lives under the `git` namespace. **Restart-required** (next `typeclaw start` refreshes and commits `.gitignore`).
 - `portForward` — allow/deny policy for the auto port-forwarder (the host-stage `_hostd` daemon's portbroker). When the agent runs a server inside the container that LISTENs on a TCP port, the broker proxies it to the same port number on `127.0.0.1` of the host so the user can hit it directly. `portForward` decides which ports are allowed through. **Restart-required** — the broker captures the policy at register time on `typeclaw start`.
@@ -134,7 +134,7 @@ The reference is **a lookup table, not a wishlist** — recommending a path ther
 
 ## Channels and Alias
 
-`channels` configures which external adapters (`discord-bot`, `slack-bot`, `telegram-bot`, `kakaotalk`, and `github`) are enabled and how the engagement layer behaves on each; `alias` lists plain-text names the agent answers to. Both are **live-reloadable** — edits take effect on the next `reload`, no container restart.
+`channels` configures which external adapters (`discord-bot`, `slack-bot`, `telegram-bot`, `line`, `kakaotalk`, and `github`) are enabled and how the engagement layer behaves on each; `alias` lists plain-text names the agent answers to. Both are **live-reloadable** — edits take effect on the next `reload`, no container restart.
 
 This skill owns only the **schema and edit mechanics** of these two fields (see the schema table above): `channels: { "<adapter-id>": { engagement, history, enabled } }` and `alias: [...]`. The **behavioral contract** for the messenger adapters — when the agent wakes to reply vs. observes, engagement triggers (mention/reply/dm), reply stickiness, the non-configurable solo-human fallback, alias substring-match semantics, and peer-name suppressors — lives in the **`typeclaw-channels`** skill. **Load `typeclaw-channels` before answering any "why did/didn't the agent respond", "make it quieter", "answer to this nickname", or engagement/alias-behavior question.** Editing the fields here still follows the standard safe-edit workflow (read whole file, validate, write back, commit); since both are live-reloadable, tell the user the change takes effect on the next `reload` — no container restart.
 

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

@@ -9,7 +9,9 @@ The agent's long-term memory is sharded across files in `memory/topics/<slug>.md
 
 ## Reading
 
-The `# Memory` section of every system prompt comes from topic shards only. Undreamed daily-stream events are **not** injected — call `memory_search` when you need them. When total shard bytes are above the 16 KB injection budget (or when speaking in a channel), shard bodies are also dropped from the prompt — only the heading + `cites=N, days=N, lastReinforced=YYYY-MM-DD` shows; call `memory_search` to fetch the bodies you need. The same `memory_search` covers both surfaces (topic shards and undreamed stream events), so one tool call reaches everything.
+The `# Memory` section comes from topic shards only. Undreamed daily-stream events are **not** injected — call `memory_search` when you need them. When total shard bytes are above the 16 KB injection budget (or when speaking in a channel), shard bodies are dropped — only the heading + `cites=N, days=N, lastReinforced=YYYY-MM-DD` shows; call `memory_search` to fetch the bodies you need. The same `memory_search` covers both surfaces (topic shards and undreamed stream events), so one tool call reaches everything.
+
+**Where the `# Memory` section lives depends on `memory.vector.enabled`.** With vector **off** (default), it's part of the system prompt, snapshotted once at session creation. With vector **on**, it is removed from the system prompt and injected fresh into each **user turn** instead: under budget you get all shard bodies, over budget you get the top-K shards/fragments most relevant to the current message (hybrid vector + keyword search). This keeps the system-prompt cache prefix stable across a session and lets retrieval track the current topic instead of a stale session-start snapshot. Either way `memory_search` remains available on demand.
 
 ## Writing
 

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

@@ -63,7 +63,7 @@ For each user turn, the current speaker's effective role is delivered in the tur
 ```
 tui                                # any TUI session
 *                                  # any channel session, any platform
-<platform>:*                       # any chat on this platform (slack | discord | telegram | kakao)
+<platform>:*                       # any chat on this platform (slack | discord | telegram | line | kakao)
 <platform>:<workspace>             # one workspace, any chat
 <platform>:<workspace>/<chat>      # one specific chat
 <platform>:dm/*                    # any DM on this platform
@@ -74,7 +74,7 @@ kakao:open/*                       # any KakaoTalk open chat
 
 `cron`, `subagent`, and `subagent:<name>` are also valid parser shapes (they parse without error), but they do **not** grant a role to a running cron or subagent session — those resolve from stamped provenance (`scheduledByRole` / `spawnedByRole`) instead. Don't write those rules expecting them to admit traffic the way channel rules do.
 
-Within a single string, tokens are **AND**'d. Across multiple strings in `match[]`, they're **OR**'d. The platform names are exactly `slack | discord | telegram | kakao`. Workspace and chat coordinates are platform-native IDs (Slack team `T0123`, Discord guild `123456789012345678`, Telegram chat `42`, KakaoTalk chat hash) — **never** display names. If the user gives you a name, you need to resolve it to an ID before writing the match rule.
+Within a single string, tokens are **AND**'d. Across multiple strings in `match[]`, they're **OR**'d. The platform names are exactly `slack | discord | telegram | line | kakao`. Workspace and chat coordinates are platform-native IDs (Slack team `T0123`, Discord guild `123456789012345678`, Telegram chat `42`, LINE chat ID, KakaoTalk chat hash) — **never** display names. If the user gives you a name, you need to resolve it to an ID before writing the match rule.
 
 Things the DSL rejects (the parser emits actionable errors at boot, but you should not write these in the first place):
 
@@ -149,7 +149,7 @@ To distinguish cause 1/2 from cause 3: if `typeclaw logs <container> -f` (host s
 
 This is a `roles` edit. The full procedure:
 
-1. **Resolve the coordinates.** Get the platform name (`slack | discord | telegram | kakao`), the workspace ID, the chat ID. If the user gave you names, ask them or look them up in the participants list of a previous inbound from that channel.
+1. **Resolve the coordinates.** Get the platform name (`slack | discord | telegram | line | kakao`), the workspace ID, the chat ID. If the user gave you names, ask them or look them up in the participants list of a previous inbound from that channel.
 2. **Pick a role.** Default to `member` for "give them normal channel access" — `member` carries `bypass.low` only, so no medium/high security guards are skipped. Use `trusted` if they're operator-class for this agent: trusted carries `bypass.medium` by default, which means trusted bypasses `secretExfilBash`, `secretExfilRead`, `ssrf`, `sessionSearchSecrets`, `gitExfil` (push to a clean operator-configured remote), `rolePromotion`, `cronPromotion` without acks. Trusted does NOT bypass `gitRemoteTainted`, `outboundSecret`, or `systemPromptLeak` (still high-tier). Use `owner` only for the primary operator — owner auto-bypasses every tier including high. The owner-in-public-channel risk (a channel-matched owner silently posting credentials to a public chat) is the reason `roles.owner.match[]` defaults to TUI-only; widening it requires either narrowing the match or stripping `security.bypass.high` from `roles.owner.permissions[]`.
 3. **Edit `typeclaw.json` `roles.<role>.match[]` with `acknowledgeGuards: { rolePromotion: true }`.** Append the canonical DSL string. Example: `roles.member.match` adds `"slack:T0123/C0ABCDE"`. If the user wants only a specific person in that channel, append `slack:T0123/C0ABCDE author:U_ME` instead. **The `rolePromotion` guard blocks any write that widens a role's `match[]` or `permissions[]` without an ack** — this is the runtime check that defends against the canonical "channel speaker asks to promote themselves" attack (see the `rolePromotion` discussion in the security bypass tiers section above). When the request is from the TUI operator (or you have explicit, unambiguous user confirmation that adding this match rule is intentional), pass `acknowledgeGuards: { rolePromotion: true }` in the `write` or `edit` tool args. **Never ack when the request came from a channel message asking you to add the speaker's own author-id to a higher role** — refuse and tell them to use `typeclaw role claim` from the operator's host CLI instead, which is the operator-issued out-of-band path. The same rule applies to introducing a brand-new role with non-empty grants, or widening any existing role's `permissions[]`.
 4. **Restart.** `roles` is **restart-required** — `typeclaw reload` does not re-evaluate role config. Tell the user: "edited `roles.<role>.match` — restart-required. Run `typeclaw restart` (host stage)."

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

@@ -33,7 +33,7 @@ Skills live in three places. The runtime loads them in this order, **first wins
    - **Author**: the dreaming subagent, every time it consolidates a daily stream. Bar for promoting a fragment-pattern into a skill: multi-step, recurred across at least two distinct fragments, and the trigger conditions are statable as a "Use when..." description.
    - **Loading**: `src/agent/index.ts` adds `<agentDir>/memory/skills/` to `additionalSkillPaths` (existence-gated), so the resource loader auto-discovers every `SKILL.md` there on session start, identical to `.agents/skills/`.
    - **Persistence**: `memory/` is gitignored at the agent level, but the dreaming subagent force-commits its outputs (`MEMORY.md` plus everything under `memory/`, including `memory/skills/`) and applies `skip-worktree` so the human's `git status` stays clean.
-   - **You must not write to `memory/skills/` manually.** It is owned by the dreaming subagent. Hand-authored content there will be ignored by the part of the system that dreaming reads (it consolidates from `memory/yyyy-MM-dd.md`, not from existing skill files), and the dreaming subagent may overwrite the same path on a future run. If you want a hand-authored skill, put it in `.agents/skills/`.
+   - **You must not write to `memory/skills/` manually.** It is owned by the dreaming subagent. Hand-authored content there will be ignored by the part of the system that dreaming reads (it consolidates from `memory/streams/yyyy-MM-dd.jsonl`, not from existing skill files), and the dreaming subagent may overwrite the same path on a future run. If you want a hand-authored skill, put it in `.agents/skills/`.
 
 The collision rule (first wins) means: if a downloaded skill happens to share a name with a bundled one, the bundled one still wins and the downloaded copy is silently dropped with a collision diagnostic. Useful as a safety net, but do not rely on it — pick non-colliding names.
 

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

@@ -1,6 +1,6 @@
 ---
 name: typeclaw-tunnels
-description: Use when the user mentions tunnel, ngrok, webhook URL, cloudflared, expose to internet, show my friend, public URL, GitHub webhook, port forward to public, reverse proxy, trycloudflare, or making a container-local service reachable from the internet. Read it before suggesting tunnel add/remove/status/logs or editing typeclaw.json tunnels[].
+description: Use when the user mentions tunnel, ngrok, webhook URL, cloudflared, expose to internet, show my friend, public URL, GitHub webhook, port forward to public, reverse proxy, trycloudflare, or making a container-local service reachable from the internet. Read it before suggesting tunnel add/remove/status/logs or editing typeclaw.json tunnels[]. Also read it the moment a tunnel "doesn't work": a Cloudflare tunnel with no public URL usually means `cloudflared` was never baked into the image — it is opt-in (`docker.file.cloudflared`, default false), so a hand-added tunnel needs it set explicitly. Diagnose root cause by reading typeclaw.json + checking `command -v cloudflared` rather than trusting a single error line; tell the user to set `docker.file.cloudflared: true` and `typeclaw restart`; never curl/vendor cloudflared yourself or report a cryptic error as if the tunnel were down.
 ---
 
 # typeclaw-tunnels
@@ -107,6 +107,27 @@ Unhealthy logs often show:
 
 Use `typeclaw tunnel logs <name> -f` while restarting the agent if you need to watch URL discovery live.
 
+## Diagnosing "the tunnel doesn't work" (you, the agent)
+
+When a tunnel has no public URL, **diagnose the root cause directly — don't stop at a single error line.** The most common cause by far is that `cloudflared` was never baked into the image (it's opt-in; see below), not a runtime outage. These checks always work from your shell inside the container:
+
+1. **Read `typeclaw.json`.** Look at `tunnels[]` (is the tunnel even configured? which `provider`?) and `docker.file.cloudflared` (is it `true`?).
+2. **Check the binary:** `command -v cloudflared`. If a `cloudflare-quick` / `cloudflare-named` tunnel is configured but this prints nothing, the cloudflared layer was never installed — that is the root cause (see "### `cloudflared` is not installed" below).
+3. **Check the upstream is alive — but probe the right port per provider:**
+   - `cloudflare-quick`: the service must be listening on the tunnel's `upstreamPort` from `typeclaw.json` (e.g. `curl -sS -o /dev/null -w '%{http_code}' http://127.0.0.1:<upstreamPort>/`).
+   - `cloudflare-named`: there is **no** `upstreamPort` (the schema rejects it; the dashboard's Public Hostname mapping `localhost:<port>` captures the upstream — see the named-tunnel section above). Ask the user which port the dashboard's Public Hostname points at, then probe `127.0.0.1:<that port>`.
+   - `external`: the upstream lives behind the user's own reverse proxy, so there is no container-local port to probe — skip this check unless the user names the upstream.
+
+Then tell the user honestly and offer the fix. For the common "hand-added tunnel, no `cloudflared`" case, send something like:
+
+> This agent has a `cloudflare-quick` tunnel configured, but `cloudflared` was never installed into the image — it's opt-in (`docker.file.cloudflared`, default `false`), and this tunnel was hand-added to `typeclaw.json` without enabling it. Want me to set `docker.file.cloudflared: true`? It's a boot setting, so after I edit it you'll run `typeclaw restart` from the host project directory, and the tunnel URL will come up.
+
+Only after the user agrees: edit `typeclaw.json` (use the `typeclaw-config` skill), ask them to `typeclaw restart` from the **host** stage, and confirm the URL once the rebuilt container is back. Never `curl`/vendor `cloudflared` yourself.
+
+### If `typeclaw tunnel status/list/logs` prints `✖ [object ErrorEvent]`
+
+On older containers the in-container CLI couldn't reach the agent websocket (it resolved the port/token via `docker`, which isn't on `$PATH` inside the container), so these commands failed at the handshake with the opaque line `✖ [object ErrorEvent]`. **That is a CLI-reachability quirk, not a tunnel outage** — do not report it to the user as "the tunnel is down" or "I can't get the URL." Fall back to the direct diagnosis above (read `typeclaw.json`, `command -v cloudflared`, probe the upstream). Current containers resolve the websocket from the in-container `TYPECLAW_*` env instead, so `tunnel status` works in-container and prints a real `detail` line; if you still see `[object ErrorEvent]`, the agent is running an older build and the direct checks are authoritative.
+
 ## Common failure modes
 
 ### `cloudflared` is not installed

package/src/tunnels/providers/cloudflare-quick.ts

@@ -3,12 +3,14 @@ import type { Unsubscribe } from '@/stream'
 import { createLogRing, type LogLineSubscriber, type LogRing } from '../log-ring'
 import { extractQuickTunnelUrl } from '../quick-url-parser'
 import type { TunnelConfig, TunnelProviderHandle, TunnelState } from '../types'
+import { isUpstreamReachable, type UpstreamProbe } from '../upstream-probe'
 import { isBinaryNotFound, MISSING_BINARY_DETAIL } from './cloudflared-binary'
 
 const DEFAULT_BINARY = 'cloudflared'
 const DEFAULT_RESTART_BACKOFF_MS = [1_000, 2_000, 4_000, 10_000, 30_000]
 const DEFAULT_MAX_FAILURES_WITHOUT_URL = 10
 const DEFAULT_STOP_GRACE_MS = 5_000
+const DEFAULT_UPSTREAM_RECHECK_MS = 2_000
 
 export type CloudflareQuickProviderOptions = {
   config: TunnelConfig
@@ -18,6 +20,8 @@ export type CloudflareQuickProviderOptions = {
   restartBackoffMs?: number[]
   maxConsecutiveFailuresWithoutUrl?: number
   stopGraceMs?: number
+  probeUpstream?: UpstreamProbe
+  upstreamRecheckMs?: number
 }
 
 export type CloudflareQuickProviderHandle = TunnelProviderHandle & {
@@ -38,6 +42,8 @@ export function createCloudflareQuickProvider(options: CloudflareQuickProviderOp
   const restartBackoffMs = options.restartBackoffMs ?? DEFAULT_RESTART_BACKOFF_MS
   const maxConsecutiveFailuresWithoutUrl = options.maxConsecutiveFailuresWithoutUrl ?? DEFAULT_MAX_FAILURES_WITHOUT_URL
   const stopGraceMs = options.stopGraceMs ?? DEFAULT_STOP_GRACE_MS
+  const probeUpstream = options.probeUpstream ?? isUpstreamReachable
+  const upstreamRecheckMs = options.upstreamRecheckMs ?? DEFAULT_UPSTREAM_RECHECK_MS
   const logs = createLogRing()
   const state: TunnelState = {
     name: config.name,
@@ -53,12 +59,65 @@ export function createCloudflareQuickProvider(options: CloudflareQuickProviderOp
   let stopping = false
   let proc: ReturnType<typeof Bun.spawn> | null = null
   let retryTimer: ReturnType<typeof setTimeout> | null = null
+  let recheckTimer: ReturnType<typeof setTimeout> | null = null
   let restartFailuresWithoutUrl = 0
   let attemptEmittedUrl = false
+  let broadcastedUrl: string | null = null
+  // Identifies the current live cloudflared attempt. Bumped on every launch, on
+  // process exit, and on stop. A probe captures the generation it was started
+  // under; if the process exits (into restart backoff) or the tunnel is stopped
+  // while a probe is in flight, the resolved probe sees a stale generation and
+  // bails — so it can never mark a dead process's tunnel healthy.
+  let launchGeneration = 0
+
+  function clearRecheckTimer(): void {
+    if (recheckTimer !== null) {
+      clearTimeout(recheckTimer)
+      recheckTimer = null
+    }
+  }
+
+  // cloudflared emits the URL once, but the upstream service may still be
+  // booting. We broadcast the URL immediately (channel adapters need it) yet
+  // gate `healthy` on a real upstream probe, re-checking on an interval so the
+  // status flips to healthy the moment the service comes up — and surfaces a
+  // 502-explaining detail until then.
+  async function onQuickUrl(url: string, generation: number): Promise<void> {
+    if (generation !== launchGeneration) return
+    attemptEmittedUrl = true
+    restartFailuresWithoutUrl = 0
+    state.url = url
+    state.lastUrlAt = Date.now()
+    if (broadcastedUrl !== url) {
+      broadcastedUrl = url
+      onUrlChange(url)
+    }
+    await reprobeUpstream(generation)
+  }
+
+  async function reprobeUpstream(generation: number): Promise<void> {
+    if (generation !== launchGeneration || !started || stopping || state.url === null) return
+    const reachable = await probeUpstream(upstreamPort)
+    if (generation !== launchGeneration || !started || stopping || state.url === null) return
+    if (reachable) {
+      state.status = 'healthy'
+      state.detail = 'quick tunnel URL emitted; upstream reachable'
+      clearRecheckTimer()
+      return
+    }
+    state.status = 'unhealthy'
+    state.detail = `quick tunnel URL emitted but upstream 127.0.0.1:${upstreamPort} is not reachable (requests will 502)`
+    clearRecheckTimer()
+    recheckTimer = setTimeout(() => {
+      recheckTimer = null
+      void reprobeUpstream(generation)
+    }, upstreamRecheckMs)
+  }
 
   async function launch(): Promise<void> {
     if (!started || stopping) return
 
+    const generation = ++launchGeneration
     attemptEmittedUrl = false
     state.status = 'starting'
     state.detail = 'starting cloudflared'
@@ -81,13 +140,7 @@ export function createCloudflareQuickProvider(options: CloudflareQuickProviderOp
     void pumpStderr(spawned.stderr, logs, (line) => {
       const url = extractQuickTunnelUrl(line)
       if (url === null) return
-      attemptEmittedUrl = true
-      restartFailuresWithoutUrl = 0
-      state.url = url
-      state.status = 'healthy'
-      state.lastUrlAt = Date.now()
-      state.detail = 'quick tunnel URL emitted'
-      onUrlChange(url)
+      void onQuickUrl(url, generation)
     })
 
     void spawned.exited.then((code) => {
@@ -99,6 +152,8 @@ export function createCloudflareQuickProvider(options: CloudflareQuickProviderOp
   }
 
   function handleExit(code: number): void {
+    launchGeneration += 1
+    clearRecheckTimer()
     if (!attemptEmittedUrl) restartFailuresWithoutUrl += 1
     if (restartFailuresWithoutUrl >= maxConsecutiveFailuresWithoutUrl) {
       state.status = 'permanently-failed'
@@ -127,6 +182,9 @@ export function createCloudflareQuickProvider(options: CloudflareQuickProviderOp
       if (!started && proc === null) return
       started = false
       stopping = true
+      broadcastedUrl = null
+      launchGeneration += 1
+      clearRecheckTimer()
       if (retryTimer !== null) {
         clearTimeout(retryTimer)
         retryTimer = null

package/src/tunnels/upstream-probe.ts

@@ -0,0 +1,25 @@
+import { createConnection } from 'node:net'
+
+// cloudflared allocates a public quick-tunnel URL even when nothing is
+// listening upstream, so a "healthy" tunnel can still 502 every request. We
+// probe the upstream ourselves before claiming health; refused connections,
+// timeouts, and socket errors all count as unreachable.
+export async function isUpstreamReachable(port: number, timeoutMs = 1_000): Promise<boolean> {
+  return new Promise((resolve) => {
+    let settled = false
+    const finish = (reachable: boolean): void => {
+      if (settled) return
+      settled = true
+      socket.destroy()
+      resolve(reachable)
+    }
+
+    const socket = createConnection({ host: '127.0.0.1', port })
+    socket.setTimeout(timeoutMs)
+    socket.once('connect', () => finish(true))
+    socket.once('timeout', () => finish(false))
+    socket.once('error', () => finish(false))
+  })
+}
+
+export type UpstreamProbe = (port: number) => Promise<boolean>