typeclaw 0.11.1 → 0.13.0

package/src/secrets/export-codex-auth-file.ts

@@ -0,0 +1,243 @@
+import {
+  chmodSync,
+  mkdirSync,
+  readFileSync,
+  readlinkSync,
+  renameSync,
+  statSync,
+  unlinkSync,
+  writeFileSync,
+} from 'node:fs'
+import { homedir } from 'node:os'
+import { dirname, isAbsolute, join, resolve } from 'node:path'
+
+import { decodeCodexAccessTokenExpiryMs, emitCodexAuthJson } from './codex-auth-json'
+import type { ProviderCredential, Providers } from './schema'
+import { SecretsBackend } from './storage'
+
+const FILE_MODE = 0o600
+const DIR_MODE = 0o700
+
+export type ExportCodexAuthFileResult =
+  | { action: 'skipped'; reason: SkipReason }
+  | { action: 'wrote'; path: string }
+  | { action: 'failed'; reason: string }
+
+export type SkipReason =
+  | 'codex-cli-disabled'
+  | 'no-openai-codex-credential'
+  | 'credential-not-oauth'
+  | 'on-disk-is-fresher'
+
+export type ExportCodexAuthFileOptions = {
+  codexCliEnabled: boolean
+  providers: Providers
+  homeDir?: string
+  now?: () => number
+  log?: (message: string) => void
+}
+
+// Writes typeclaw's openai-codex OAuth credential to $HOME/.codex/auth.json
+// when it's safe to do so. The Dockerfile entrypoint shim symlinks
+// $HOME/.codex/auth.json to /agent/.typeclaw/home/.codex/auth.json on every
+// boot, so the write follows the symlink and lands on the persistent
+// host-side path — that's the stable contract from src/init/dockerfile.ts
+// "link_persistent_home_files" and we MUST use it instead of writing to
+// /agent/.typeclaw/home/ directly.
+//
+// Three guards, cheapest first. The first two return without ever touching
+// the filesystem, which keeps the 90% case (users who don't enable Codex
+// CLI) at zero overhead on every container start.
+export function exportCodexAuthFileIfApplicable(options: ExportCodexAuthFileOptions): ExportCodexAuthFileResult {
+  if (!options.codexCliEnabled) return { action: 'skipped', reason: 'codex-cli-disabled' }
+
+  const credential = options.providers['openai-codex']
+  if (credential === undefined) return { action: 'skipped', reason: 'no-openai-codex-credential' }
+  if (credential.type !== 'oauth') return { action: 'skipped', reason: 'credential-not-oauth' }
+
+  const targetPath = join(options.homeDir ?? homedir(), '.codex', 'auth.json')
+
+  try {
+    if (!shouldOverwrite(targetPath, credential, options.now ?? Date.now)) {
+      return { action: 'skipped', reason: 'on-disk-is-fresher' }
+    }
+    const contents = emitCodexAuthJson(credential)
+    writeAtomic(targetPath, contents)
+    return { action: 'wrote', path: targetPath }
+  } catch (err) {
+    const reason = err instanceof Error ? err.message : String(err)
+    options.log?.(`exportCodexAuthFile: ${reason}`)
+    return { action: 'failed', reason }
+  }
+}
+
+// Newer-wins: skip the write unless typeclaw's stored credential is
+// strictly fresher than the on-disk JWT. Codex CLI rotates tokens
+// in-place (it rewrites auth.json with a refreshed access_token whose
+// JWT exp is later), so on a restart the file may legitimately be ahead
+// of secrets.json. We must not clobber that.
+//
+// Ties skip: when expiries match, there's nothing to gain from a write,
+// and avoiding the I/O keeps the steady state at zero churn after the
+// first boot. The only writes we ever do are first-write (B1), recovery
+// (B6), or refresh-from-typeclaw-side (B3).
+//
+// On any error reading or parsing the on-disk file (missing, corrupt JSON,
+// missing JWT, undecodable exp), we return true. That's the "we have a
+// valid credential, the file is unusable, replace it" fallback case (B1
+// and B6 in the design doc).
+function shouldOverwrite(
+  targetPath: string,
+  credential: ProviderCredential & { expires?: unknown; access?: unknown },
+  now: () => number,
+): boolean {
+  let raw: string
+  try {
+    raw = readFileSync(targetPath, 'utf8')
+  } catch {
+    return true
+  }
+
+  let parsed: unknown
+  try {
+    parsed = JSON.parse(raw)
+  } catch {
+    return true
+  }
+
+  const onDiskAccess = readOnDiskAccessToken(parsed)
+  if (onDiskAccess === null) return true
+
+  const onDiskExpiry = decodeCodexAccessTokenExpiryMs(onDiskAccess)
+  if (onDiskExpiry === null) return true
+
+  const credentialExpiry = readCredentialExpiry(credential, now)
+  return credentialExpiry > onDiskExpiry
+}
+
+function readOnDiskAccessToken(parsed: unknown): string | null {
+  if (typeof parsed !== 'object' || parsed === null) return null
+  const tokens = (parsed as Record<string, unknown>)['tokens']
+  if (typeof tokens !== 'object' || tokens === null) return null
+  const access = (tokens as Record<string, unknown>)['access_token']
+  return typeof access === 'string' && access.length > 0 ? access : null
+}
+
+// Resolution order for the credential's expiry:
+//   1. The `expires` field pi-ai writes (absolute ms epoch).
+//   2. The JWT `exp` claim decoded from `access`.
+//   3. Now — guarantees we still write on first boot when the credential
+//      lacks both, rather than silently skipping forever.
+function readCredentialExpiry(credential: { expires?: unknown; access?: unknown }, now: () => number): number {
+  if (typeof credential.expires === 'number' && Number.isFinite(credential.expires)) {
+    return credential.expires
+  }
+  if (typeof credential.access === 'string') {
+    const fromJwt = decodeCodexAccessTokenExpiryMs(credential.access)
+    if (fromJwt !== null) return fromJwt
+  }
+  return now()
+}
+
+// Atomic temp-then-rename, mirroring src/secrets/storage.ts's
+// writeEnvelopeAtomic. The directory is created with 0700 and the file
+// with 0600 because $HOME/.codex/auth.json holds a long-lived refresh
+// token — leaking it via lax permissions defeats the whole point of
+// running typeclaw on a multi-user host. The 0600 chmod after rename is
+// belt-and-suspenders: writeFileSync's `mode` is applied at create time,
+// but umask can mask it down on some filesystems.
+//
+// Symlink preservation: the entrypoint shim
+// (src/init/dockerfile.ts link_persistent_home_files) installs
+// $HOME/.codex/auth.json as a symlink to
+// /agent/.typeclaw/home/.codex/auth.json on every boot. POSIX rename(2)
+// replaces the directory entry at the destination atomically — it does
+// NOT follow symlinks — so a naive `renameSync(tmp, $HOME/.codex/auth.json)`
+// would replace the symlink with a regular file, leaving the persistent
+// path empty. Next boot the shim recreates the symlink (force-removing
+// our file), the persistent path is still empty, and Codex's in-place
+// token refresh is silently lost on every restart.
+//
+// Fix: resolve the symlink target with readlinkSync and rename against
+// the real path so the symlink itself is preserved. The temp file MUST
+// live alongside the real target (same filesystem) because renameSync
+// across filesystems fails with EXDEV — $HOME is the container's
+// overlayfs, but the symlink target is a bind-mounted host path.
+function writeAtomic(targetPath: string, contents: string): void {
+  const realTarget = resolveSymlinkTarget(targetPath)
+  const dir = dirname(realTarget)
+  mkdirSync(dir, { recursive: true, mode: DIR_MODE })
+  const tmp = `${realTarget}.${process.pid}.${Date.now()}.tmp`
+  writeFileSync(tmp, contents, { encoding: 'utf8', mode: FILE_MODE })
+  try {
+    renameSync(tmp, realTarget)
+  } catch (err) {
+    try {
+      unlinkSync(tmp)
+    } catch {
+      // best-effort cleanup of the temp file when rename fails
+    }
+    throw err
+  }
+  // statSync + chmodSync rather than unconditional chmod so a 0644 file
+  // installed by something else stays visible in tests (we WANT to overwrite
+  // permissions when we own the file).
+  try {
+    statSync(realTarget)
+    chmodSync(realTarget, FILE_MODE)
+  } catch {
+    // ignore — file vanished between rename and chmod is benign
+  }
+}
+
+// Returns the absolute path renameSync should target. When `path` is a
+// symlink (production: $HOME/.codex/auth.json -> /agent/.typeclaw/home/...),
+// returns the resolved absolute target so we write through the link
+// instead of replacing it. Otherwise (tests, or first boot before the
+// shim installs the symlink — though the shim runs before the agent in
+// production), returns the path unchanged.
+//
+// readlinkSync throws EINVAL when the path exists but isn't a symlink,
+// and ENOENT when nothing is there. Either case → write to the original
+// path; the parent-dir mkdir + atomic rename handle the rest. We don't
+// distinguish errno because both have the same fallback.
+function resolveSymlinkTarget(path: string): string {
+  let link: string
+  try {
+    link = readlinkSync(path)
+  } catch {
+    return path
+  }
+  return isAbsolute(link) ? link : resolve(dirname(path), link)
+}
+
+export type ExportCodexAuthFileForAgentOptions = {
+  agentDir: string
+  codexCliEnabled: boolean
+  homeDir?: string
+  log?: (message: string) => void
+}
+
+// Boot-time convenience wrapper for src/run/index.ts. Mirrors
+// hydrateChannelEnvFromSecrets's contract: takes agentDir, never throws,
+// returns a result the caller can ignore. Secrets-file read failures are
+// caught and surfaced as a 'failed' result so the agent boot is not blocked
+// by a missing or malformed secrets.json — same non-fatal policy hydrate
+// uses on the channels slice.
+export function exportCodexAuthFileForAgent(options: ExportCodexAuthFileForAgentOptions): ExportCodexAuthFileResult {
+  if (!options.codexCliEnabled) return { action: 'skipped', reason: 'codex-cli-disabled' }
+  let providers: Providers
+  try {
+    providers = new SecretsBackend(join(options.agentDir, 'secrets.json')).tryReadProvidersSync()
+  } catch (err) {
+    const reason = err instanceof Error ? err.message : String(err)
+    options.log?.(`exportCodexAuthFile: ${reason}`)
+    return { action: 'failed', reason }
+  }
+  return exportCodexAuthFileIfApplicable({
+    codexCliEnabled: options.codexCliEnabled,
+    providers,
+    ...(options.homeDir !== undefined ? { homeDir: options.homeDir } : {}),
+    ...(options.log !== undefined ? { log: options.log } : {}),
+  })
+}

package/src/secrets/index.ts

@@ -7,3 +7,9 @@ export { type Secret } from './resolve'
 export { hydrateChannelEnvFromSecrets } from './hydrate'
 
 export { migrateKakaotalkCredentials } from './migrate-kakaotalk'
+
+export {
+  type ExportCodexAuthFileResult,
+  exportCodexAuthFileForAgent,
+  exportCodexAuthFileIfApplicable,
+} from './export-codex-auth-file'

package/src/server/command-runner.ts

@@ -1,5 +1,6 @@
 import {
   createSessionWithDispose,
+  renderTurnTimeAnchor,
   type CreateSessionOptions,
   type CreateSessionResult,
   type SessionOrigin,
@@ -392,7 +393,7 @@ export async function runPromptForCommand(args: {
   })
   const detachAbort = bindSignalToSession(args.signal, session)
   try {
-    await session.prompt(args.text)
+    await session.prompt(`${renderTurnTimeAnchor()}\n\n${args.text}`)
     return session.getLastAssistantText() ?? ''
   } finally {
     detachAbort()

package/src/server/index.ts

@@ -3,6 +3,7 @@ import type { Server as BunServer, ServerWebSocket } from 'bun'
 
 import {
   createSessionWithDispose as defaultCreateSessionWithDispose,
+  renderTurnTimeAnchor,
   type AgentSession,
   type CreateSessionOptions,
   type CreateSessionResult,
@@ -711,7 +712,7 @@ export function createServer({
               })
             }
             try {
-              await state.session.prompt(msg.text)
+              await state.session.prompt(`${renderTurnTimeAnchor()}\n\n${msg.text}`)
               send(ws, { type: 'done' })
             } catch (err) {
               const message = err instanceof Error ? err.message : String(err)
@@ -951,7 +952,7 @@ async function drain(ws: Ws, state: SessionState, agentDir: string | undefined,
 
       await fireTurnStart(item.text)
       try {
-        await state.session.prompt(item.text)
+        await state.session.prompt(`${renderTurnTimeAnchor()}\n\n${item.text}`)
         send(ws, { type: 'done' })
       } catch (err) {
         const message = err instanceof Error ? err.message : String(err)

package/src/shared/index.ts

@@ -24,4 +24,10 @@ export {
   type TunnelSnapshot,
 } from './protocol'
 
-export { formatLocalDate, formatLocalDateTime, resolveLocalTimezoneName } from './local-time'
+export {
+  formatLocalDate,
+  formatLocalDateTime,
+  formatLocalWeekday,
+  type LocalWeekday,
+  resolveLocalTimezoneName,
+} from './local-time'

package/src/shared/local-time.ts

@@ -36,3 +36,35 @@ export function resolveLocalTimezoneName(): string {
     return 'UTC'
   }
 }
+
+// English + Korean weekday name pair for a given Date. The per-turn time
+// anchor renders both so the model has the answer to "what day is it"
+// without computing weekday-from-ISO-date — a step LLMs get wrong often
+// enough to matter, especially when answering in a non-English language.
+// Pre-computing in both candidate reply languages removes the arithmetic
+// step entirely instead of trusting the model to do it correctly each
+// turn.
+//
+// Uses Intl.DateTimeFormat with explicit locales. No `timeZone` option:
+// the container's local clock is already host-local (the entrypoint
+// propagates TZ via `-e TZ=<host-tz>`), so the runtime's default zone is
+// the one the user sees. Both locales fall back to the hand-rolled
+// 7-entry lookup if Intl throws (no-tzdata, locked-down sandbox) — the
+// fallback names stay readable and never make the prefix empty.
+const WEEKDAYS_EN = ['Sunday', 'Monday', 'Tuesday', 'Wednesday', 'Thursday', 'Friday', 'Saturday'] as const
+const WEEKDAYS_KO = ['일요일', '월요일', '화요일', '수요일', '목요일', '금요일', '토요일'] as const
+
+export type LocalWeekday = { en: string; ko: string }
+
+export function formatLocalWeekday(date: Date = new Date()): LocalWeekday {
+  const dow = date.getDay()
+  const fallback: LocalWeekday = { en: WEEKDAYS_EN[dow]!, ko: WEEKDAYS_KO[dow]! }
+  try {
+    return {
+      en: new Intl.DateTimeFormat('en-US', { weekday: 'long' }).format(date),
+      ko: new Intl.DateTimeFormat('ko-KR', { weekday: 'long' }).format(date),
+    }
+  } catch {
+    return fallback
+  }
+}

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

@@ -1,6 +1,6 @@
 ---
 name: typeclaw-channel-github
-description: Use this skill BEFORE every `channel_reply` or `channel_send` call whose adapter is `github`, AND before composing replies to GitHub-originated inbounds, AND before opening new issues or PRs with `gh`, AND ALWAYS when an inbound says "requested your review on PR #N" or "requested a review from team @… on PR #N" (the agent has been assigned as a reviewer and must do a real code review with line-by-line comments via `gh api`). GitHub renders **real markdown** — `**bold**`, `## headings`, `| tables |`, fenced code blocks, and `inline code` all render natively. Use rich markdown freely. GitHub cannot send file attachments via API — do not call `channel_send` with attachments on github chats. GitHub has no typing indicator. PR review threads use `thread` keyed on the root comment id; reply to a thread to stay in it, or omit `thread` to post a top-level issue/PR comment. To open new issues or PRs use the `gh` CLI — `GH_TOKEN` is pre-set by the adapter. Read this skill before composing anything on GitHub.
+description: Use this skill BEFORE every `channel_reply` or `channel_send` call whose adapter is `github`, AND before composing replies to GitHub-originated inbounds, AND before opening new issues or PRs with `gh`, AND ALWAYS when an inbound says "requested your review on PR #N" or "requested a review from team @… on PR #N" (the agent has been assigned as a reviewer and must delegate the analysis to the `reviewer` subagent, then translate its findings into line-by-line comments via `gh api`). GitHub renders **real markdown** — `**bold**`, `## headings`, `| tables |`, fenced code blocks, and `inline code` all render natively. Use rich markdown freely. GitHub cannot send file attachments via API — do not call `channel_send` with attachments on github chats. GitHub has no typing indicator. PR review threads use `thread` keyed on the root comment id; reply to a thread to stay in it, or omit `thread` to post a top-level issue/PR comment. To open new issues or PRs use the `gh` CLI — `GH_TOKEN` is pre-set by the adapter. Read this skill before composing anything on GitHub.
 ---
 
 GitHub renders normal Markdown in issues, PRs, discussions, and review comments. Use headings, lists, tables, fenced code blocks, links, and inline code when they improve clarity.
@@ -25,27 +25,56 @@ For App auth, `GH_TOKEN` is an installation access token that refreshes automati
 
 ## Reviewing pull requests
 
-When an incoming message says **"requested your review on PR #N"** (or "requested a review from team @… on PR #N"), you have been assigned as a reviewer. Do a real code review and post line-by-line comments via `gh api`. Do **not** just reply in the channel — the user wants feedback on the diff.
+When an incoming message says **"requested your review on PR #N"** (or "requested a review from team @… on PR #N"), you have been assigned as a reviewer. Do **not** review inline yourself and do **not** just reply in the channel — delegate the analysis to the bundled `reviewer` subagent, then translate its findings into line-by-line comments via `gh api`.
+
+Why delegate: the `reviewer` subagent runs on the `deep` model profile, loads a curated `code-review` skill on demand, and produces a structured `<review>` block with severity-tagged findings. You are the integration layer between that output and GitHub's review API.
 
 ### Workflow
 
-1. **Read the diff and context**:
+1. **Confirm the target.** Capture the PR number, the repo, and the head SHA — you'll need the SHA to read files at the revision the reviewer analyzed.
 
    ```sh
-   gh pr diff <N> --repo owner/repo
    gh pr view <N> --repo owner/repo --json title,body,baseRefName,headRefOid,files
    ```
 
-2. **Submit a multi-comment review** in one API call by piping a JSON payload to `gh api --input -`. `comments[]` accepts line-level entries; each one lands on the diff exactly like a human reviewer's inline comment:
+2. **Spawn the `reviewer` subagent with the PR target.** Use `run_in_background: true` so you stay responsive while the deep model works. Pass the PR URL (or `owner/repo#N`) plus any context the requester gave you (focus areas, specific files, etc.) so the reviewer knows what the requester cares about.
+
+   The reviewer will fetch the diff itself (`gh pr diff`, `gh api /repos/.../pulls/<n>`), load the matching skill (`code-review` for a code PR; `general` for a mixed-format change), and return a `<review>` block.
+
+3. **Wait for the completion `<system-reminder>`,** then call `subagent_output({ task_id })` to read the reviewer's final assistant message. The structured payload looks like:
+
+   ```xml
+   <review>
+   <summary>...</summary>
+   <findings>
+     <finding severity="blocker|concern|nit|praise" location="path:line">
+       <issue>...</issue>
+       <evidence>...</evidence>
+       <suggestion>...</suggestion>
+     </finding>
+   </findings>
+   <verdict>approve | request-changes | comment</verdict>
+   </review>
+   ```
+
+4. **Translate findings into a `gh api` review payload.** Each `<finding>` with `severity` of `blocker`, `concern`, or `nit` and a `location="path:line"` becomes one entry in `comments[]`. Compose the inline `body` from the reviewer's `<issue>` + `<evidence>` + `<suggestion>` — preserve the reviewer's wording, do not paraphrase. Findings whose `location` is `general` (no file:line anchor) go into the top-level review `body` instead. **Skip `praise` findings when building `comments[]`** — they are not actionable, and inline praise comments are exactly the noise the reviewer is supposed to filter out at the source; if you want to surface them, weave them into the top-level review `body` alongside the summary. Map the reviewer's `<verdict>` to the GitHub `event`:
+
+   | Reviewer verdict  | GitHub `event`    |
+   | ----------------- | ----------------- |
+   | `approve`         | `APPROVE`         |
+   | `request-changes` | `REQUEST_CHANGES` |
+   | `comment`         | `COMMENT`         |
+
+   Then submit the review in one API call:
 
    ```sh
    cat <<'JSON' | gh api -X POST /repos/owner/repo/pulls/<N>/reviews --input -
    {
      "event": "COMMENT",
-     "body": "Overall: looks good with a few nits.",
+     "body": "<reviewer's <summary> goes here>",
      "comments": [
-       { "path": "src/foo.ts", "line": 42, "side": "RIGHT", "body": "nit: prefer `const` here." },
-       { "path": "src/bar.ts", "line": 10, "side": "RIGHT", "body": "Consider extracting this branch into a helper." }
+       { "path": "src/foo.ts", "line": 42, "side": "RIGHT", "body": "<issue + evidence + suggestion from the reviewer's finding>" },
+       { "path": "src/bar.ts", "line": 10, "side": "RIGHT", "body": "..." }
      ]
    }
    JSON
@@ -53,17 +82,22 @@ When an incoming message says **"requested your review on PR #N"** (or "requeste
 
    **Always use `--input -` with a quoted heredoc (`<<'JSON'`) for review bodies.** Do **not** use `-f body=...` or `-F 'comments[][body]=...'`: those go through shell argument parsing, so backticks (\`) trigger command substitution and have to be backslash-escaped, which leaks the literal `\` into the rendered comment. The quoted heredoc passes the JSON through untouched — backticks, newlines, and `${...}` all survive verbatim. The same applies to any other `gh api` POST whose body contains backticks, embedded newlines, or shell metacharacters.
 
-3. **Then** post a one-line summary with `channel_reply` so the conversation has a human-readable trace pointing at the review.
+5. **Post a one-line summary with `channel_reply`** so the conversation has a human-readable trace pointing at the review (e.g., "Posted review on PR #N: <verdict>, N findings.").
 
 ### Rules
 
-- Use `event=COMMENT` by default. Use `APPROVE` only when you have high confidence the PR is ready to merge. Use `REQUEST_CHANGES` only when the PR has clear blockers — not for nits.
-- **Only post comments that the author needs to act on.** Do not post praise ("looks good", "nice refactor", "great work"), affirmations of correct code, or restatements of what a line does. If every comment in your review is positive, post a top-level summary via `channel_reply` instead of a review — or skip commenting and just `APPROVE`. Inline comments are for changes, questions, and blockers, not validation.
+- **Always delegate to the `reviewer` subagent.** Do not perform the review craft yourself. The reviewer is the source of truth for severity, evidence quality, and what counts as a finding. Your job is mechanics: spawn, wait, translate, post.
+- **Trust the verdict.** Use the GitHub `event` mapped from the reviewer's `<verdict>`. Do not upgrade `comment` → `APPROVE` to seem agreeable, and do not downgrade `request-changes` → `COMMENT` to soften the tone. The reviewer chose deliberately.
+- **No actionable findings → no inline review post.** A finding is "actionable" if its severity is `blocker`, `concern`, or `nit`. If the reviewer returns zero actionable findings:
+  - `approve` verdict → post a plain `APPROVE` with the `<summary>` as the review body (no `comments[]` array).
+  - `comment` verdict → post the summary as a top-level PR comment via `gh api -X POST /repos/.../issues/<N>/comments` instead of submitting an empty review.
+  - `request-changes` verdict → submit `REQUEST_CHANGES` with the `<summary>` as the review body and no `comments[]` array. This combination is rare (the reviewer's contract says `request-changes` requires at least one blocker or load-bearing concern), so if it happens, faithfully encode the verdict and trust the reviewer's reasoning is in the summary.
+- **Preserve the reviewer's wording.** Inline comment bodies should reflect the reviewer's `<issue>`, `<evidence>`, and `<suggestion>` verbatim (modulo markdown formatting). Paraphrasing dilutes the analysis — the deep-model reviewer chose those words on purpose.
 - `line` is a line number **in the file**, not a position in the diff. `side: RIGHT` is the new revision (default for additions); `side: LEFT` is the old revision (use for comments on removed lines).
 - For multi-line comments, also set `start_line` and `start_side` (same semantics).
-- If you need to read whole files at the PR's head SHA, use `gh api /repos/owner/repo/contents/<path>?ref=<headRefOid>`.
+- If you need to read whole files at the PR's head SHA, use `gh api /repos/owner/repo/contents/<path>?ref=<headRefOid>`. The reviewer can do this itself, but you may need to as well — e.g., when validating a finding's `location` against the actual file before posting.
 - The bundled `agent-browser` is **not** for PR reviews — `gh api` is faster and more reliable. Only use the browser when the API genuinely can't reach what you need.
-- A `review_request_removed` event means the requester un-assigned you. Stop any in-progress review work; do not post a partial review.
+- A `review_request_removed` event means the requester un-assigned you. Cancel any in-flight reviewer subagent (`subagent_cancel`) and do not post a partial review.
 
 ### Self-loop safety
 

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

@@ -1,6 +1,6 @@
 ---
 name: typeclaw-channel-kakaotalk
-description: Use this skill BEFORE every `channel_reply` or `channel_send` call whose adapter is `kakaotalk`, AND before calling `channel_fetch_attachment` against a KakaoTalk URL. KakaoTalk renders messages as plain text — `**bold**`, `## headings`, `| tables |`, fenced code blocks, and other markdown all appear literally. There is no `@mention` syntax, no message threads, no replies-with-quote, and no outbound stickers. Outbound file attachments (photos, videos, audio, generic files, multi-photo galleries) ARE supported — pass them via `attachments[]` on `channel_send` / `channel_reply` and the adapter routes by MIME. Inbound photos / files / video / audio CAN be downloaded via `channel_fetch_attachment` (the placeholder text includes the URL); inbound stickers are metadata-only and cannot be fetched. URLs expire ~3 days after the message arrives. Read this skill before composing or fetching anything on KakaoTalk.
+description: Use this skill BEFORE every `channel_reply` or `channel_send` call whose adapter is `kakaotalk`, AND before fetching/viewing KakaoTalk inbound attachments. KakaoTalk renders messages as plain text — `**bold**`, `## headings`, `| tables |`, fenced code blocks, and other markdown all appear literally. There is no `@mention` syntax, no message threads, no replies-with-quote, and no outbound stickers. Outbound file attachments (photos, videos, audio, generic files, multi-photo galleries) ARE supported — pass them via `attachments[]` on `channel_send` / `channel_reply` and the adapter routes by MIME. Inbound attachments appear as `[KakaoTalk attachment #N: ...]`; fetch with `channel_fetch_attachment({ attachment_id: N })` or view images with `look_at_channel_attachment({ attachment_id: N })`. Read this skill before composing or fetching anything on KakaoTalk.
 ---
 
 # typeclaw-channel-kakaotalk
@@ -37,24 +37,23 @@ If you produce any of the following, KakaoTalk will render it literally and the
 
 ## Inbound attachments and stickers
 
-Even though you cannot SEND attachments or stickers, you DO receive them. The adapter surfaces incoming non-text content by appending a `[KakaoTalk message with ...]` placeholder to the inbound text (same convention as Slack/Discord/Telegram). Examples of what you'll see:
+Even though you cannot SEND stickers, you DO receive attachments and stickers. The adapter surfaces incoming non-text content by appending a ref-free `[KakaoTalk attachment #N: <kind> <metadata>]` placeholder to the inbound text (same convention as Slack/Discord/Telegram). Examples of what you'll see:
 
-- A photo (with no caption): `[KakaoTalk message with photo 1320x2868 (image/jpeg) https://talk.kakaocdn.net/...]`
-- A photo with a caption: `look at this\n[KakaoTalk message with photo 1320x2868 (image/jpeg) https://...]`
-- A file: `[KakaoTalk message with file spec.pdf (application/pdf) size=12345 https://...]`
-- A video / audio (with a usable URL): `[KakaoTalk message with video (keys=[dur,url]) https://talk.kakaocdn.net/...]`. The SDK leaves video / audio / multiphoto payloads opaque, so we list the keys that were present alongside the URL when one exists; when no URL is present the placeholder is just `[KakaoTalk message with video keys=[...]]` and there is nothing for you to fetch.
-- A sticker / emoticon: `[KakaoTalk message with sticker (sticker) pack=4412724 path=4412724.emot_001.webp]`
-- An animated sticker: `[KakaoTalk message with sticker (sticker_ani) pack=... path=...]`
+- A photo (with no caption): `[KakaoTalk attachment #1: photo 1320x2868 image/jpeg]`
+- A photo with a caption: `look at this\n[KakaoTalk attachment #1: photo 1320x2868 image/jpeg]`
+- A file: `[KakaoTalk attachment #1: file application/pdf name=spec.pdf size=12345]`
+- A video / audio / multiphoto: `[KakaoTalk attachment #1: video video/mp4]` or `[KakaoTalk attachment #1: multiphoto]`
+- A sticker / emoticon: `[KakaoTalk attachment #1: sticker name=4412724.emot_001.webp]`
 
 ### Fetching attachment bytes
 
-For photos, files, and any video / audio / multiphoto whose placeholder includes a `https://...kakaocdn.net/...` URL, call `channel_fetch_attachment` with that URL as the `ref` to download the bytes. The adapter validates the host (only `*.kakaocdn.net` is accepted — you cannot use this tool as a generic web fetcher) and returns the raw buffer plus mimetype.
+For photos, files, and any video / audio / multiphoto with an attachment token, call `channel_fetch_attachment` with the numeric `attachment_id` from the token to download the bytes. To view an image directly, call `look_at_channel_attachment` with the same `attachment_id`.
 
 Use this when you actually need to look at the content — e.g. the user sends a screenshot and asks "what's in this?". The download lands in your inbox directory and you can pass it to a vision-capable inspection tool or read it directly depending on the file type.
 
-**Expiry caveat**: KakaoCDN URLs are pre-signed with an `expires=` timestamp baked into the query string — empirically ~3 days after the message arrived. Fetch promptly. If the URL has expired you will get a `403` error with the hint _"likely an expired pre-signed URL; ask the sender to re-share"_ — relay that to the user verbatim rather than guessing the cause.
+If no attachment token appears in the inbound text, no attachment was sent. Do not invent attachment ids — the tool will reject ids that do not appear in the current turn.
 
-**Stickers cannot be fetched** as bytes through this tool. The sticker placeholder carries `pack=` and `path=` identifiers (KakaoTalk sticker pack metadata), not a downloadable URL. Treat stickers as descriptive metadata only — acknowledge them ("cute sticker") without trying to "see" them.
+**Stickers cannot be fetched** as bytes through this tool. Treat stickers as descriptive metadata only — acknowledge them ("cute sticker") without trying to "see" them.
 
 If the inbound text is JUST a sticker (no accompanying text), the agent still gets a routed event — stickers count as engagement under `reply` and `dm` triggers (group chats with only sticker activity will not trigger `mention` because aliases require text matching).
 

package/src/skills/typeclaw-channel-telegram-bot/SKILL.md

@@ -48,6 +48,14 @@ You do NOT need to manually escape any of `_ * [ ] ( ) ~ \` > # + - = | { } . !`
 
 URLs containing **unescaped parentheses** (Wikipedia-style `Foo_(bar)`) intentionally fall back to escaped literal text rather than render as a link — the adapter cannot disambiguate the closing `)` from a content paren. If you need to link such a URL, percent-encode the parens in the URL (`%28`, `%29`) before putting it in the link.
 
+## Inbound attachments
+
+Inbound Telegram messages with photos or documents show a ref-free attachment token in the text: `[Telegram attachment #N: <kind> <metadata>]`, for example `[Telegram attachment #1: photo 1280x960]` or `[Telegram attachment #1: file application/pdf name=spec.pdf]`.
+
+- To download the attachment, call `channel_fetch_attachment` with `attachment_id: N`.
+- To view an image, call `look_at_channel_attachment` with `attachment_id: N`.
+- If no attachment token appears in the inbound, no attachment was sent. Do not invent attachment ids — the tool will reject ids that do not appear in the current turn.
+
 ## When the user says "your formatting looks broken"
 
 Three classes of failure to triage in this order:

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

@@ -38,7 +38,8 @@ If `codex` is installed but no credential is set up, you have to broker the auth
 
 **Decision rule, top to bottom:**
 
-1. **Already authenticated?** Check both env (`env | grep -E '^(OPENAI_API_KEY|CODEX_API_KEY)='`) and on-disk (`test -f ~/.codex/auth.json`). If either resolves, skip auth entirely.
+0. **typeclaw may have already done it for you.** If the agent was initialized with the `openai-codex` provider (the user pasted/ran OAuth into typeclaw itself), typeclaw writes `~/.codex/auth.json` automatically on every container start — provided `docker.file.codexCli: true` is set. Check `test -f ~/.codex/auth.json && jq -e '.tokens.access_token' ~/.codex/auth.json >/dev/null`; if both succeed, skip auth and go straight to delegation. The file is refreshed on every start via the newer-wins compare in `src/secrets/export-codex-auth-file.ts`, so a stale credential gets replaced without user intervention as long as the typeclaw-side credential is fresher.
+1. **Already authenticated some other way?** Check both env (`env | grep -E '^(OPENAI_API_KEY|CODEX_API_KEY)='`) and on-disk (`test -f ~/.codex/auth.json`). If either resolves, skip auth entirely.
 2. **User has an OpenAI API account** (api.openai.com billing, no ChatGPT Plus/Pro subscription) → API key path.
 3. **User has a ChatGPT Plus / Pro / Team / Enterprise subscription and wants to use their subscription credits** → OAuth path via `codex login`.
 4. **User is unsure** → ask which kind of OpenAI account they have. Both paths are equally low-friction. Pick by account shape, not by flow complexity.

package/src/skills/typeclaw-codex-cli/references/auth-flow.md

@@ -4,6 +4,28 @@ Deep dive for the auth paths. Read it when `SKILL.md`'s "First-time auth (intera
 
 The two paths are intentionally symmetric: in both, the user produces one artifact on their side, pastes it to you, you validate it, you do read-modify-write on `.env` (or write `~/.codex/auth.json`), you offer a restart. Only the credential medium differs.
 
+## Path 0 — typeclaw-managed OAuth (auto-export, no user action)
+
+Before walking the user through either interactive path, check whether typeclaw has already provisioned `~/.codex/auth.json` from its own secrets store. This is the canonical state for users who configured `openai-codex` as their typeclaw model backend during `typeclaw init`:
+
+- `typeclaw init` ran the OAuth flow against pi-ai and wrote the credential to `secrets.json#providers.openai-codex` (shape: `{ type: 'oauth', access, refresh, expires, accountId }`).
+- `docker.file.codexCli: true` is set in `typeclaw.json`, so the Codex CLI is installed in the container.
+- On every `typeclaw start` / `typeclaw restart`, `src/run/index.ts`'s boot sequence calls `exportCodexAuthFileForAgent`, which:
+  - Returns early (zero filesystem touches) if `codexCli` is off or no `openai-codex` credential exists.
+  - Otherwise emits the modern `~/.codex/auth.json` shape (`{ tokens: { access_token, refresh_token, account_id? } }`) — no top-level `expires`, because Codex CLI re-derives expiry from the JWT on every load.
+  - Compares the JWT `exp` claim in the on-disk access token against typeclaw's stored expiry. If the on-disk token is the same or newer (Codex CLI rotated it in-place since the last typeclaw write), the file is left alone — no clobber. If typeclaw's copy is strictly fresher (the user re-pasted OAuth), the file is replaced atomically.
+
+Detection check before launching the interactive flow:
+
+```sh
+test -f ~/.codex/auth.json \
+  && jq -e '.tokens.access_token' ~/.codex/auth.json >/dev/null
+```
+
+If both succeed, the credential is ready; skip Paths A and B and proceed to delegation. If only the first succeeds but the second fails (file exists but no `tokens.access_token`), the file is either an API-key shape (legacy) or corrupt — the runtime exporter's next-start pass will overwrite it from `secrets.json` if typeclaw has a valid OAuth credential, but for the current delegation you can either re-run `typeclaw restart` to force the resync, or fall back to interactive Path A / Path B.
+
+If the user has `docker.file.codexCli: true` but typeclaw was initialized with a non-`openai-codex` model backend (e.g. `anthropic`, `openai`, `fireworks`), Path 0 won't fire — the auto-export's gate-2 returns because `secrets.json#providers.openai-codex` is absent. The user's manually-pasted `~/.codex/auth.json` (if any) is never touched in that case. Fall through to Path A or Path B.
+
 ## Path A — API key (`OPENAI_API_KEY`)
 
 The API key path is direct. Summary: