kimaki 0.9.0 → 0.9.1

package/skills/parallel-security-review/SKILL.md

@@ -0,0 +1,332 @@
+---
+name: parallel-security-review
+repo: https://github.com/remorses/kimaki
+description: >
+  DeepSec-inspired security review workflow for branch or PR changes. Use when
+  the user asks for a thorough, high-signal security review that should derive
+  repository context, split candidate discovery across focused agents, and run
+  per-finding false-positive validation before reporting.
+allowed-tools:
+  - Bash(git status:*)
+  - Bash(git diff:*)
+  - Bash(git log:*)
+  - Bash(git show:*)
+  - Read
+  - Glob
+  - Grep
+  - Task
+---
+
+# Parallel security review
+
+Use this workflow for **high-confidence security reviews** of branch or PR
+changes. It borrows the useful parts of DeepSec's prompt architecture: small
+core instructions, repo context, tech-specific reminders, finding-specific
+false-positive rules, concrete target files, strict output, and independent
+validation.
+
+## Goal
+
+Report only **real vulnerabilities introduced by the change under review**.
+Do not report hardening gaps, existing issues, test-only problems, style, or
+generic best-practice concerns.
+
+Keep the final report short. If there are no high-confidence findings, say so.
+
+## Review architecture
+
+Split the work into discovery and validation:
+
+```text
+main reviewer
+  │
+  ├─► context scout
+  │     auth model, trust boundaries, safe patterns, tech stack
+  │
+  ├─► candidate discovery agents
+  │     focused by vulnerability family, not by random files
+  │
+  ├─► one validator per candidate
+  │     tries to disprove exploitability and assign confidence
+  │
+  └─► final report
+        only validated findings with confidence >= 8/10
+```
+
+Discovery agents can be broad. Validator agents must be skeptical.
+
+## Step 1: collect branch context
+
+Use git to understand the review scope. Prefer the repository's base branch if
+known; otherwise use the merge base with the upstream/default branch when
+available.
+
+Read:
+
+- `git status -s -u`
+- changed file names
+- commit messages on the branch
+- complete diff for the review range
+
+Do not modify files. Do not commit.
+
+## Step 2: derive a compact repo security context
+
+Launch a **context scout** subagent before vulnerability discovery. Ask it to
+read relevant unchanged files too, not just the diff.
+
+The context scout returns at most 40 lines:
+
+```md
+## Security context
+
+**Auth primitives**
+- `requireUser()` protects server routes
+- `canManageTeam()` gates team admin actions
+
+**Trust boundaries**
+- HTTP route params and request bodies are attacker-controlled
+- CLI flags and environment variables are trusted for this review
+
+**Sensitive sinks**
+- database writes through `db.*`
+- filesystem writes under workspace root
+- subprocess execution through `execAsync()`
+
+**Known safe patterns**
+- Prisma object filters are parameterized
+- React text interpolation is escaped by default
+
+**Tech notes**
+- Next.js Server Actions are public POST endpoints unless guarded server-side
+```
+
+Use this context in every later subagent prompt.
+
+## Step 3: inject tech-specific reminders
+
+Add only the reminders that match the repository. Keep them short.
+
+**React / Angular**
+- Do not report XSS for normal text interpolation.
+- Only investigate raw HTML sinks like `dangerouslySetInnerHTML`,
+  `bypassSecurityTrustHtml`, DOM writes, or template compilation.
+
+**Next.js / React Server Components**
+- Server Actions are public POST endpoints. Check backend auth inside the
+  action, not just UI visibility.
+- Middleware is useful but not sufficient if routes can be reached through
+  alternate paths or internal handlers.
+- `params`, `searchParams`, headers, cookies, and request bodies are untrusted.
+
+**Express / Node HTTP servers**
+- Middleware order matters. Verify auth/validation runs before handlers.
+- For command execution, prove untrusted input reaches a shell or argv sink.
+- For path traversal, require a containment check like resolved path starts
+  with the intended root.
+
+**Prisma / SQL ORMs**
+- Prisma object filters are safe from SQL injection by default.
+- Investigate raw SQL APIs like `$queryRawUnsafe`, string-built SQL, or manual
+  driver calls.
+
+**Cloudflare Workers / edge apps**
+- Request headers, cookies, URL, and body are untrusted.
+- Bindings and environment variables are trusted.
+- Verify tenant/account identifiers are checked server-side before data access.
+
+**Rust / Go / memory-safe services**
+- Do not report memory safety issues unless unsafe/native code is directly in
+  scope and the exploit path is concrete.
+- Focus on auth, deserialization, filesystem, command execution, and SSRF.
+
+## Step 4: candidate discovery agents
+
+Launch focused agents in parallel when the diff is non-trivial. Use fewer
+agents for tiny diffs.
+
+Good split:
+
+1. **Auth and authorization**
+   - auth bypass
+   - privilege escalation
+   - cross-tenant access
+   - missing server-side checks
+
+2. **Injection and code execution**
+   - SQL/NoSQL/template injection
+   - command execution
+   - unsafe deserialization
+   - XSS through raw HTML sinks
+
+3. **Filesystem, network, and data exposure**
+   - path traversal
+   - SSRF with attacker-controlled host/protocol
+   - sensitive data leakage
+   - unsafe file upload/download paths
+
+4. **Business logic and state transitions**
+   - payment/subscription bypass
+   - permission state confusion
+   - irreversible actions missing authorization
+   - trust boundary changes introduced by the PR
+
+Each discovery agent must output **candidates**, not final findings:
+
+```md
+## Candidate
+
+- File: `path/to/file.ts:42`
+- Category: `auth_bypass`
+- Changed code: what changed
+- Input source: where attacker-controlled data enters
+- Sensitive sink or boundary: what is reached
+- Possible exploit path: concrete steps if real
+- Why it might be false positive: known guard, framework protection, trusted input, etc.
+```
+
+Discard candidates that do not name both an **attacker-controlled source** and a
+**security-sensitive sink or privilege boundary**.
+
+## Step 5: finding-specific false-positive rules
+
+Before validation, attach the relevant rules to each candidate.
+
+**SSRF**
+- Only report if attacker controls host, protocol, or can route to internal
+  services.
+- Do not report path-only control as SSRF.
+
+**SQL injection**
+- Only report if untrusted input reaches string-built SQL or explicitly unsafe
+  raw SQL APIs.
+- Do not report parameterized queries or normal ORM object filters.
+
+**Command injection**
+- Report shell injection when untrusted input reaches a shell string.
+- For argv-array execution, prove the called program interprets the argument as
+  code, flags, paths with dangerous semantics, or another command.
+- Shell scripts are usually trusted tooling. Only report if there is a concrete
+  untrusted input path.
+
+**Path traversal**
+- Report only when untrusted path segments can escape the intended root and
+  read/write/delete sensitive files.
+- A correct `resolve()` plus `startsWith(root)` or equivalent containment check
+  is usually enough to reject the finding.
+
+**XSS**
+- In React/Angular, ignore normal interpolation.
+- Look for raw HTML sinks, DOM APIs, markdown-to-HTML without sanitization, or
+  user-controlled script/style URLs.
+
+**Auth bypass**
+- Client-side missing checks are not vulnerabilities by themselves.
+- Prove the backend route/action/job lacks the required authorization or trusts
+  client-provided roles, tenant IDs, user IDs, or ownership claims.
+
+**Data exposure**
+- Logging URLs or non-PII data is not enough.
+- Report plaintext secrets, passwords, tokens, or concrete PII exposure.
+
+**AI prompt injection**
+- User-controlled content in an AI prompt is not automatically a vulnerability.
+- Report only if the prompt output controls a privileged tool, data access,
+  command execution, or authorization decision without a guard.
+
+## Step 6: one validator per candidate
+
+Launch one validator subagent per candidate, in parallel. The validator's job is
+to **disprove** the candidate.
+
+Validator prompt shape:
+
+````md
+You are validating one security-review candidate. Try to prove this is a false
+positive before accepting it.
+
+Repository security context:
+<paste compact context>
+
+Candidate:
+<paste one candidate>
+
+Rules:
+- Only consider vulnerabilities introduced by the reviewed diff.
+- Require a concrete attacker-controlled source.
+- Require a concrete sensitive sink or authorization boundary.
+- Apply the finding-specific false-positive rules.
+- Ignore tests, docs, generated files, hardening gaps, DoS, rate limiting,
+  dependency age, regex injection, regex DoS, and log spoofing.
+
+Return exactly:
+
+```json
+{
+  "verdict": "true_positive",
+  "confidence": 8,
+  "reasoning": "short explanation",
+  "exploitPath": "concrete exploit steps",
+  "fix": "specific fix"
+}
+```
+
+Use `"verdict": "false_positive"` or `"verdict": "uncertain"` when the exploit
+path is not concrete enough. Set `exploitPath` and `fix` to `null` in those
+cases.
+````
+
+Only keep candidates with `verdict: "true_positive"` and confidence `>= 8`.
+
+## Step 7: final report format
+
+If there are no findings:
+
+```md
+# Security review
+
+No high-confidence security findings in the reviewed changes.
+```
+
+If there are findings:
+
+```md
+# Security review
+
+## Finding 1: <category> in `<file>:<line>`
+
+- **Severity:** High | Medium
+- **Confidence:** 8/10
+- **Category:** `auth_bypass`
+- **Introduced by:** short description of the changed code
+- **Exploit path:** concrete attacker steps
+- **Impact:** what the attacker gains
+- **Recommendation:** specific fix
+```
+
+Never include rejected candidates in the final report unless the user asks for
+review notes or methodology.
+
+## Severity rules
+
+- **High:** direct path to authentication bypass, privilege escalation, RCE,
+  sensitive data breach, cross-tenant access, or account takeover.
+- **Medium:** concrete exploit path with meaningful impact but extra
+  preconditions or limited blast radius.
+- **Low:** do not report by default. Mention only if the user explicitly asks
+  for defense-in-depth findings.
+
+## Hard exclusions
+
+Never report these as findings:
+
+- Denial of service, resource exhaustion, memory/CPU/file descriptor leaks
+- Rate limiting gaps
+- Dependency age or vulnerable dependency advisories
+- Documentation-only issues
+- Test-only issues
+- Log spoofing
+- Regex injection or regex DoS
+- Generic lack of hardening, audit logs, or best practices
+- Environment variable or CLI flag attacks, unless the repo explicitly treats
+  them as untrusted input

package/src/cli-commands/user.ts

@@ -119,7 +119,7 @@ cli
 
 cli
   .command('tunnel', 'Expose a local port via tunnel')
-  .option('-p, --port <port>', 'Local port to expose (required)')
+  .option('-p, --port <port>', 'Local port to expose (optional when command output reveals one)')
   .option(
     '-t, --tunnel-id [id]',
     'Custom tunnel ID (only for services safe to expose publicly; prefer random default)',
@@ -128,25 +128,24 @@ cli
   .option('-s, --server [url]', 'Tunnel server URL')
   .option('-k, --kill', 'Kill any existing process on the port before starting')
   .action(async (options) => {
-      const { runTunnel, parseCommandFromArgv, CLI_NAME } = await import(
+      const { runTunnel, parseCommandFromArgv } = await import(
         'traforo/run-tunnel'
       )
+      const { command } = parseCommandFromArgv(process.argv)
 
-      if (!options.port) {
-        cliLogger.error('Error: --port is required')
-        cliLogger.error(`\nUsage: kimaki tunnel -p <port> [-- command]`)
+      if (!options.port && command.length === 0) {
+        cliLogger.error('Error: --port is required unless a command is provided after --')
+        cliLogger.error(`\nUsage: kimaki tunnel [-- command]`)
+        cliLogger.error(`   or: kimaki tunnel --port <port>`)
         process.exit(EXIT_NO_RESTART)
       }
 
-      const port = parseInt(options.port, 10)
-      if (isNaN(port) || port < 1 || port > 65535) {
+      const port = options.port ? parseInt(options.port, 10) : undefined
+      if (options.port && (!port || port < 1 || port > 65535)) {
         cliLogger.error(`Error: Invalid port number: ${options.port}`)
         process.exit(EXIT_NO_RESTART)
       }
 
-      // Parse command after -- from argv
-      const { command } = parseCommandFromArgv(process.argv)
-
       await runTunnel({
         port,
         tunnelId: options.tunnelId || undefined,

package/src/discord-bot.ts

@@ -20,7 +20,7 @@ import {
   stopOpencodeServer,
 } from './opencode.js'
 import { formatAutoWorktreeName, createWorktreeInBackground, worktreeCreatingMessage } from './commands/new-worktree.js'
-import { validateWorktreeDirectory, git } from './worktrees.js'
+import { validateWorktreeDirectory, git, isGitRepositoryRoot } from './worktrees.js'
 import { WORKTREE_PREFIX } from './commands/merge-worktree.js'
 import {
   escapeBackticksInCodeBlocks,
@@ -857,9 +857,21 @@ export async function startDiscordBot({
               .replace(/\s+/g, ' ')
               .trim() || 'kimaki thread'
 
-        // Check if worktrees should be enabled (CLI flag OR channel setting)
-        const shouldUseWorktrees =
+        // Check if worktrees should be enabled (CLI flag OR channel setting).
+        // Only create worktrees from the configured project directory when that
+        // directory is itself the git root. If the user registered a non-git
+        // workspace folder under a larger repo, git would create the worktree
+        // from the parent repo and strand follow-up messages on failure.
+        const wantsWorktrees =
           useWorktrees || (await getChannelWorktreesEnabled(channel.id))
+        const shouldUseWorktrees =
+          wantsWorktrees && (await isGitRepositoryRoot(projectDirectory))
+
+        if (wantsWorktrees && !shouldUseWorktrees) {
+          discordLogger.warn(
+            `[WORKTREE] Skipping automatic worktree for non-git project directory: ${projectDirectory}`,
+          )
+        }
 
         // Add worktree prefix if worktrees are enabled
         const threadName = shouldUseWorktrees
@@ -1062,7 +1074,7 @@ export async function startDiscordBot({
       // The runtime is created immediately so follow-up messages queue
       // naturally; the worktree promise is awaited inside enqueueIncoming.
       let worktreePromise: Promise<string | Error> | undefined
-      if (marker.worktree) {
+      if (marker.worktree && (await isGitRepositoryRoot(projectDirectory))) {
         discordLogger.log(`[BOT_SESSION] Creating worktree: ${marker.worktree}`)
 
         const worktreeStatusMessage = await thread
@@ -1079,6 +1091,10 @@ export async function startDiscordBot({
           projectDirectory,
           rest: discordClient.rest,
         })
+      } else if (marker.worktree) {
+        discordLogger.warn(
+          `[BOT_SESSION] Skipping requested worktree for non-git project directory: ${projectDirectory}`,
+        )
       }
 
       // --cwd: reuse an existing worktree directory. Revalidate at bot-time

package/src/onboarding-tutorial.ts

@@ -136,7 +136,7 @@ Pick a random port between 3000-9000 to avoid conflicts:
 
 ${backticks}bash
 PORT=$((RANDOM % 6000 + 3000))
-bunx tuistory launch "PORT=$PORT kimaki tunnel -p $PORT -- bun run server.ts" -s game-dev --cwd "$PWD"
+bunx tuistory launch "PORT=$PORT kimaki tunnel -- bun run server.ts" -s game-dev --cwd "$PWD"
 ${backticks}
 
 Wait a moment, then get the tunnel URL:

package/src/system-message.test.ts

@@ -97,23 +97,26 @@ describe('system-message', () => {
 
       Only do this when the user explicitly asks to close or archive the thread, and only after your final message.
 
-      ## searching discord users
+      ## discord user mentions
 
-      To search for Discord users in a guild (needed for mentions like <@userId>), run:
+      Prefer Discord user IDs for mentions. Discord bots cannot ping by @name; use \`<@userId>\` in message text or pass the ID to \`--user\`.
+      The current user's ID is available in the per-turn \`<discord-user ... user-id="..." />\` metadata.
+
+      To search for Discord users in a guild as a best-effort fallback, run:
 
       kimaki user list --guild guild_123 --query "username"
 
-      This returns user IDs you can use for Discord mentions.
+      This returns user IDs you can use for Discord mentions. It can fail when Server Members Intent is disabled, so prefer IDs from existing Discord metadata or raw mentions when possible.
 
       ## starting new sessions from CLI
 
       To start a new thread/session in this channel pro-grammatically, run:
 
-      kimaki send --channel chan_123 --prompt 'your prompt here' --agent <current_agent> --user 'Tommy'
+      kimaki send --channel chan_123 --prompt 'your prompt here' --agent <current_agent> --user '<discord-user-id>'
 
       You can use this to "spawn" parallel helper sessions like teammates: start new threads with focused prompts, then come back and collect the results.
       Prefer passing the current agent with \`--agent <current_agent>\` so spawned or scheduled sessions keep the same agent unless you are intentionally switching. Replace \`<current_agent>\` with the value from the per-turn \`Current agent\` reminder.
-      When writing \`kimaki send\` shell commands, use single quotes around \`--prompt\`, \`--user\`, \`--send-at\`, and other literal arguments so backticks inside prompts are not interpreted by the shell.
+      When writing \`kimaki send\` shell commands, use single quotes around \`--prompt\`, \`--user\`, \`--send-at\`, and other literal arguments so backticks inside prompts are not interpreted by the shell. Prefer \`--user '<discord-user-id>'\` over \`--user 'name'\` because name lookup depends on optional Server Members Intent.
 
       IMPORTANT: NEVER use \`--worktree\` unless the user explicitly asks for a worktree. Default to creating normal threads without worktrees.
 
@@ -131,19 +134,19 @@ describe('system-message', () => {
 
       Use --notify-only to create a notification thread without starting an AI session:
 
-      kimaki send --channel chan_123 --prompt 'User cancelled subscription' --notify-only --agent <current_agent> --user 'Tommy'
+      kimaki send --channel chan_123 --prompt 'User cancelled subscription' --notify-only --agent <current_agent> --user '<discord-user-id>'
 
-      Use --user to add a specific Discord user to the new thread:
+      Use --user with a Discord user ID or raw mention to add a specific Discord user to the new thread:
 
-      kimaki send --channel chan_123 --prompt 'Review the latest CI failure' --agent <current_agent> --user 'Tommy'
+      kimaki send --channel chan_123 --prompt 'Review the latest CI failure' --agent <current_agent> --user '<discord-user-id>'
 
       Use --worktree to create a git worktree for the session (ONLY when the user explicitly asks for a worktree):
 
-      kimaki send --channel chan_123 --prompt 'Add dark mode support' --worktree dark-mode --agent <current_agent> --user 'Tommy'
+      kimaki send --channel chan_123 --prompt 'Add dark mode support' --worktree dark-mode --agent <current_agent> --user '<discord-user-id>'
 
       Use --cwd to start a session in an existing git worktree directory (must be a worktree of the project):
 
-      kimaki send --channel chan_123 --prompt 'Continue work on feature' --cwd /path/to/existing-worktree --agent <current_agent> --user 'Tommy'
+      kimaki send --channel chan_123 --prompt 'Continue work on feature' --cwd /path/to/existing-worktree --agent <current_agent> --user '<discord-user-id>'
 
       Important:
       - NEVER use \`--worktree\` unless the user explicitly requests a worktree. Most tasks should use normal threads without worktrees.
@@ -154,7 +157,7 @@ describe('system-message', () => {
 
       Use --agent to specify which agent to use for the session:
 
-      kimaki send --channel chan_123 --prompt 'Plan the refactor of the auth module' --agent plan --user 'Tommy'
+      kimaki send --channel chan_123 --prompt 'Plan the refactor of the auth module' --agent plan --user '<discord-user-id>'
 
 
       Available agents:
@@ -166,7 +169,7 @@ describe('system-message', () => {
       You can trigger registered opencode commands (slash commands, skills, MCP prompts) by starting the \`--prompt\` with \`/commandname\`:
 
       kimaki send --thread <thread_id> --prompt '/review fix the auth module' --agent <current_agent>
-      kimaki send --channel chan_123 --prompt '/build-cmd update dependencies' --agent <current_agent> --user 'Tommy'
+      kimaki send --channel chan_123 --prompt '/build-cmd update dependencies' --agent <current_agent> --user '<discord-user-id>'
 
       The command name must match a registered opencode command. If the command is not recognized, the prompt is sent as plain text to the model. This works for both new threads (\`--channel\`) and existing threads (\`--thread\`/\`--session\`).
 
@@ -182,8 +185,8 @@ describe('system-message', () => {
 
       Use \`--send-at\` to schedule a one-time or recurring task:
 
-      kimaki send --channel chan_123 --prompt 'Reminder: review open PRs' --send-at '2026-03-01T09:00:00Z' --agent <current_agent> --user 'Tommy'
-      kimaki send --channel chan_123 --prompt 'Run weekly test suite and summarize failures' --send-at '0 9 * * 1' --agent <current_agent> --user 'Tommy'
+      kimaki send --channel chan_123 --prompt 'Reminder: review open PRs' --send-at '2026-03-01T09:00:00Z' --agent <current_agent> --user '<discord-user-id>'
+      kimaki send --channel chan_123 --prompt 'Run weekly test suite and summarize failures' --send-at '0 9 * * 1' --agent <current_agent> --user '<discord-user-id>'
 
       ALL scheduling is in UTC. Dates must be UTC ISO format ending with \`Z\`. Cron expressions also fire in UTC (e.g. \`0 9 * * 1\` means 9:00 UTC every Monday).
       When the user specifies a time without a timezone, ask them to confirm their timezone or the UTC equivalent. Never guess the user's timezone.
@@ -241,7 +244,7 @@ describe('system-message', () => {
       When the user asks to "create a worktree" or "make a worktree", they mean you should use the kimaki CLI to create it. Do NOT use raw \`git worktree add\` commands. Instead use:
 
       \`\`\`bash
-      kimaki send --channel chan_123 --prompt 'your task description' --worktree worktree-name --agent <current_agent> --user 'Tommy'
+      kimaki send --channel chan_123 --prompt 'your task description' --worktree worktree-name --agent <current_agent> --user '<discord-user-id>'
       \`\`\`
 
       This creates a new Discord thread with an isolated git worktree and starts a session in it. The worktree name should be kebab-case and descriptive of the task.
@@ -257,7 +260,7 @@ describe('system-message', () => {
       Use \`--cwd\` to start a session in an existing git worktree directory instead of creating a new one:
 
       \`\`\`bash
-      kimaki send --channel chan_123 --prompt 'Continue work on feature X' --cwd /path/to/existing-worktree --agent <current_agent> --user 'Tommy'
+      kimaki send --channel chan_123 --prompt 'Continue work on feature X' --cwd /path/to/existing-worktree --agent <current_agent> --user '<discord-user-id>'
       \`\`\`
 
       The path must be a git worktree of the project (validated via \`git worktree list\`). The session resolves to the correct project channel but uses the worktree as its working directory. Use \`--worktree\` to create a new worktree, \`--cwd\` to reuse an existing one.
@@ -271,7 +274,7 @@ describe('system-message', () => {
       When you are approaching the **context window limit** or the user explicitly asks to **handoff to a new thread**, use the \`kimaki send\` command to start a fresh session with context:
 
       \`\`\`bash
-      kimaki send --channel chan_123 --prompt 'Continuing from previous session: <summary of current task and state>' --agent <current_agent> --user 'Tommy'
+      kimaki send --channel chan_123 --prompt 'Continuing from previous session: <summary of current task and state>' --agent <current_agent> --user '<discord-user-id>'
       \`\`\`
 
       The command automatically handles long prompts (over 2000 chars) by sending them as file attachments.
@@ -504,11 +507,11 @@ describe('system-message', () => {
 
       Use random tunnel IDs by default. Only pass \`-t\` when exposing a service that is safe to be publicly discoverable.
 
-      \`kimaki tunnel\` injects \`TRAFORO_URL\` into the child process. Prefer wiring your app to that URL so OAuth callbacks, webhook URLs, and absolute links use the public tunnel instead of localhost.
+      \`kimaki tunnel\` injects \`TRAFORO_URL\` into the child process. Prefer wiring your app to that URL so OAuth callbacks, webhook URLs, and absolute links use the public tunnel instead of localhost. The local port is detected from the child process output, so do not pass \`-p\` when launching a dev server command unless detection fails.
 
       \`\`\`bash
       # Start the dev server in a named background session
-      bunx tuistory launch "kimaki tunnel -p 3000 -- pnpm dev" -s myapp-dev
+      bunx tuistory launch "kimaki tunnel -- pnpm dev" -s myapp-dev
 
       # Wait until the dev server prints something useful, then inspect it
       bunx tuistory -s myapp-dev wait "/ready|local|tunnel/i" --timeout 30000
@@ -517,7 +520,7 @@ describe('system-message', () => {
 
       ### passing the public URL to your app
 
-      If you launch the server command through \`kimaki tunnel -- ...\`, the local port is auto-detected from the child process logs in many common dev-server setups, so \`--port\` is often unnecessary.
+      If you launch the server command through \`kimaki tunnel -- ...\`, the local port is auto-detected from the child process logs in many common dev-server setups. Use \`--port\` only when the dev server does not print a detectable localhost URL or port line.
 
       \`\`\`bash
       # Your app can read process.env.TRAFORO_URL directly
@@ -544,13 +547,13 @@ describe('system-message', () => {
 
       \`\`\`bash
       # Next.js project
-      bunx tuistory launch "kimaki tunnel -p 3000 -- pnpm dev" -s projectname-nextjs-dev-3000
+      bunx tuistory launch "kimaki tunnel -- pnpm dev" -s projectname-nextjs-dev
 
-      # Vite project on port 5173
-      bunx tuistory launch "kimaki tunnel -p 5173 -- pnpm dev" -s vite-dev-5173
+      # Vite project
+      bunx tuistory launch "kimaki tunnel -- pnpm dev" -s vite-dev
 
       # Custom tunnel ID (only for intentionally public-safe services)
-      bunx tuistory launch "kimaki tunnel -p 3000 -t holocron -- pnpm dev" -s holocron-dev
+      bunx tuistory launch "kimaki tunnel -t holocron -- pnpm dev" -s holocron-dev
       \`\`\`
 
       ### stopping the dev server

package/src/system-message.ts

@@ -139,11 +139,11 @@ Use a tuistory session with a descriptive name like \`projectname-dev\` so you c
 
 Use random tunnel IDs by default. Only pass \`-t\` when exposing a service that is safe to be publicly discoverable.
 
-\`kimaki tunnel\` injects \`TRAFORO_URL\` into the child process. Prefer wiring your app to that URL so OAuth callbacks, webhook URLs, and absolute links use the public tunnel instead of localhost.
+\`kimaki tunnel\` injects \`TRAFORO_URL\` into the child process. Prefer wiring your app to that URL so OAuth callbacks, webhook URLs, and absolute links use the public tunnel instead of localhost. The local port is detected from the child process output, so do not pass \`-p\` when launching a dev server command unless detection fails.
 
 \`\`\`bash
 # Start the dev server in a named background session
-bunx tuistory launch "kimaki tunnel -p 3000 -- pnpm dev" -s myapp-dev
+bunx tuistory launch "kimaki tunnel -- pnpm dev" -s myapp-dev
 
 # Wait until the dev server prints something useful, then inspect it
 bunx tuistory -s myapp-dev wait "/ready|local|tunnel/i" --timeout 30000
@@ -152,7 +152,7 @@ bunx tuistory read -s myapp-dev
 
 ### passing the public URL to your app
 
-If you launch the server command through \`kimaki tunnel -- ...\`, the local port is auto-detected from the child process logs in many common dev-server setups, so \`--port\` is often unnecessary.
+If you launch the server command through \`kimaki tunnel -- ...\`, the local port is auto-detected from the child process logs in many common dev-server setups. Use \`--port\` only when the dev server does not print a detectable localhost URL or port line.
 
 \`\`\`bash
 # Your app can read process.env.TRAFORO_URL directly
@@ -179,13 +179,13 @@ bunx tuistory read -s myapp-dev
 
 \`\`\`bash
 # Next.js project
-bunx tuistory launch "kimaki tunnel -p 3000 -- pnpm dev" -s projectname-nextjs-dev-3000
+bunx tuistory launch "kimaki tunnel -- pnpm dev" -s projectname-nextjs-dev
 
-# Vite project on port 5173
-bunx tuistory launch "kimaki tunnel -p 5173 -- pnpm dev" -s vite-dev-5173
+# Vite project
+bunx tuistory launch "kimaki tunnel -- pnpm dev" -s vite-dev
 
 # Custom tunnel ID (only for intentionally public-safe services)
-bunx tuistory launch "kimaki tunnel -p 3000 -t holocron -- pnpm dev" -s holocron-dev
+bunx tuistory launch "kimaki tunnel -t holocron -- pnpm dev" -s holocron-dev
 \`\`\`
 
 ### stopping the dev server

package/src/voice-message.e2e.test.ts

@@ -865,6 +865,14 @@ e2eTest('voice message handling', () => {
         queueMessage: true,
       })
 
+      await waitForBotMessageContaining({
+        discord,
+        threadId: thread.id,
+        userId: TEST_USER_ID,
+        text: 'using deterministic-provider/deterministic-v2',
+        timeout: 4_000,
+      })
+
       await th.user(TEST_USER_ID).sendVoiceMessage()
 
       // 3. Transcription should appear, followed by queue notification