typeclaw 0.4.0 → 0.5.0

package/src/plugin/define.ts

@@ -18,11 +18,13 @@ type DefinePluginSpec<S extends z.ZodType<unknown> | undefined> =
     ? {
         configSchema: S
         permissions?: readonly string[]
+        ownerWildcardExclusions?: readonly string[]
         commands?: Record<string, PluginCommand>
         plugin: (ctx: PluginContext<T>) => Promise<PluginExports>
       }
     : {
         permissions?: readonly string[]
+        ownerWildcardExclusions?: readonly string[]
         commands?: Record<string, PluginCommand>
         plugin: (ctx: PluginContext<unknown>) => Promise<PluginExports>
       }

package/src/plugin/manager.ts

@@ -56,9 +56,11 @@ export async function loadPlugins(opts: LoadPluginsOptions): Promise<LoadPlugins
   ]
 
   const declaredPermissions = collectDeclaredPermissions(allPlugins)
+  const ownerWildcardExclusions = collectOwnerWildcardExclusions(allPlugins)
   const permissions = createPermissionService({
     ...(opts.roles !== undefined ? { roles: opts.roles } : {}),
     pluginPermissions: declaredPermissions,
+    ownerWildcardExclusions,
   })
 
   // Non-fatal: surface user-declared `permissions[]` strings that aren't in
@@ -158,6 +160,18 @@ function collectDeclaredPermissions(
   return out
 }
 
+function collectOwnerWildcardExclusions(
+  plugins: readonly { entry: string; resolved: ResolvedPlugin }[],
+): readonly string[] {
+  const out: string[] = []
+  for (const { resolved } of plugins) {
+    for (const perm of resolved.defined.ownerWildcardExclusions ?? []) {
+      if (!out.includes(perm)) out.push(perm)
+    }
+  }
+  return out
+}
+
 export function summarizeLoaded(loaded: LoadPluginsResult['loadedPlugins'], registry: PluginRegistry): string {
   const head = loaded.map((p) => (p.version !== undefined ? `${p.name} v${p.version}` : p.name)).join(', ')
   const counts = [

package/src/plugin/types.ts

@@ -318,6 +318,12 @@ export type PluginFixResult = {
 export type DefinedPlugin<TConfig = never> = {
   readonly configSchema?: z.ZodType<TConfig>
   readonly permissions?: readonly string[]
+  // Permission strings the owner wildcard sentinel MUST NOT auto-expand
+  // to. Used by the bundled security plugin to keep audience-leak
+  // (high-tier) bypasses off the owner role unless an operator grants
+  // them explicitly in roles.owner.permissions[]. Generic by design so
+  // any future plugin can carve specific permissions out of the wildcard.
+  readonly ownerWildcardExclusions?: readonly string[]
   // Declared by-value (not built inside the factory) so the host-stage CLI
   // can dispatch commands without booting plugin runtime state.
   readonly commands?: Record<string, PluginCommand>

package/src/run/index.ts

@@ -314,7 +314,7 @@ export async function startAgent({
       }
       await job.handler(ctx)
     },
-    createSessionForCron: async (job) => {
+    createSessionForCron: async (job, refOverride) => {
       const snap = pluginRuntime.get()
       const sessionManager = SessionManager.create(cwd, sessionFactory.sessionDir())
       const sessionId = sessionManager.getSessionId()
@@ -336,6 +336,7 @@ export async function startAgent({
         channelRouter: channelManager.router,
         origin: cronOrigin,
         permissions: pluginsLoaded.permissions,
+        ...(refOverride !== undefined ? { refOverride } : {}),
         ...(snap.hasAnyPluginContent
           ? {
               plugins: {

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

@@ -1,6 +1,6 @@
 ---
 name: typeclaw-memory
-description: Use this skill whenever the user asks what you remember, what you forgot, what you dreamed, why a fact is or isn't in your memory, when memory consolidation happens, or whenever you are about to read or write `MEMORY.md`, anything under `memory/`, or `memory/skills/`. Triggers include "what do you remember", "do you remember X", "forget that", "what did you dream", "when do you dream next", "why did you forget X", "edit MEMORY.md", "add to memory", "your daily streams", "memory-logger", "dreaming", "muscle memory", or any mention of `memory.idleMs` / `memory.dreaming.schedule` in `typeclaw.json`. Read it before you touch any memory file — `MEMORY.md` and `memory/yyyy-MM-dd.jsonl` are runtime-owned, hand-edits are easy to do wrong, and the user almost always means something more specific than "edit memory" when they say it.
+description: Use this skill whenever the user asks what you remember, what you forgot, what you dreamed, why a fact is or isn't in your memory, when memory consolidation happens, or whenever you are about to read or write `MEMORY.md`, anything under `memory/`, or `memory/skills/`. Triggers include "what do you remember", "do you remember X", "forget that", "what did you dream", "when do you dream next", "why did you forget X", "edit MEMORY.md", "add to memory", "your daily streams", "memory-logger", "dreaming", "muscle memory", or any mention of `memory.idleMs` / `memory.bufferBytes` / `memory.dreaming.schedule` in `typeclaw.json`. Read it before you touch any memory file — `MEMORY.md` and `memory/yyyy-MM-dd.jsonl` are runtime-owned, hand-edits are easy to do wrong, and the user almost always means something more specific than "edit memory" when they say it.
 ---
 
 # typeclaw-memory
@@ -13,7 +13,7 @@ This skill exists so you can answer the user's questions about your own memory h
 
 ### Stage 1: memory-logger (online, per-session)
 
-After every prompt completes, the runtime fires the `session.idle` hook. The memory plugin starts a debounce timer (`memory.idleMs`, default `10_000` ms; minimum `1000`). Every subsequent prompt completion resets the timer. When the user has been quiet for `idleMs`, the plugin spawns the **memory-logger** subagent for the current session. It also fires immediately on `session.end` (websocket close) so the final transcript never gets lost.
+After every prompt completes, the runtime fires the `session.idle` hook. The memory plugin starts a debounce timer (`memory.idleMs`, default `60_000` ms; minimum `1000`). Every subsequent prompt completion resets the timer. When the user has been quiet for `idleMs`, the plugin spawns the **memory-logger** subagent for the current session. It also fires immediately on `session.end` (websocket close) so the final transcript never gets lost.
 
 The memory-logger reads:
 
@@ -45,32 +45,40 @@ When dreaming fires, it reads:
 1. `MEMORY.md`
 2. The **undreamed fragments** of every `memory/yyyy-MM-dd.jsonl` (the runtime tells it which fragment ids are new — fragments whose ids are already in `memory/.dreaming-state.json#dreamedThrough[date].dreamedIds` have been consolidated and must NOT be re-cited)
 
-It rewrites `MEMORY.md` with the merged result, advances the per-day dreamed-id set in `memory/.dreaming-state.json`, optionally writes muscle-memory skills under `memory/skills/<name>/SKILL.md`, **compacts the touched daily streams** (drops superseded watermarks per source and fragments that are in `dreamedIds` but not cited from `MEMORY.md`), then commits the snapshot with a message shaped like `dream: <summary> <emoji>` — e.g. `dream: 3 fragments + new skill 'pr-review' 🔮`. The summary is derived from the staged diff (line additions in daily streams, newly-added skills, etc.), and the emoji is a random pick from a small thematic pool. After the commit, the runtime sets the `skip-worktree` index flag on the tracked memory artifacts so the user's `git status` and `git diff` stay clean. The flag is cleared and re-applied around every commit.
+It rewrites `MEMORY.md` with the merged result (treating it as a **saturated surface** that gets rebalanced every run, not an append-only log), advances the per-day dreamed-id set in `memory/.dreaming-state.json`, optionally writes muscle-memory skills under `memory/skills/<name>/SKILL.md`, **compacts the touched daily streams** (drops superseded watermarks per source and fragments that are in `dreamedIds` but not cited from `MEMORY.md`), then commits the snapshot with a message shaped like `dream: <summary> <emoji>` — e.g. `dream: 3 fragments + new skill 'pr-review' 🔮`. The summary is derived from the staged diff (line additions in daily streams, newly-added skills, etc.), and the emoji is a random pick from a small thematic pool. After the commit, the runtime sets the `skip-worktree` index flag on the tracked memory artifacts so the user's `git status` and `git diff` stay clean. The flag is cleared and re-applied around every commit.
 
 The dreaming subagent has only three tools: `read`, `write`, `ls`. No `bash`. No `edit`. It cannot run shell commands.
 
+**Strength-driven rebalancing.** On every run, the runtime computes per-topic strength signals from `MEMORY.md`'s existing citations (`cites`, `days` = distinct calendar days, `last reinforced` date, `age` in days) and injects them as a table at the top of the dreaming user prompt. Dreaming uses them to promote reinforced topics (`days >= 3` → "consistently", `days >= 7` → "always"), merge near-duplicates while preserving the **union** of their fragment ids, and demote decayed single-day topics into a `## Historical observations` bucket as one-line bullets that still cite the underlying fragment. Strong topics (`days >= 3`) are never demoted regardless of age. The bucket grows monotonically — there is no hard-deletion path today; every demoted citation stays alive forever via its bullet.
+
+**Citation-superset safety net.** The runtime cross-checks every MEMORY.md rewrite against the prior file's citation set. If dreaming's rewrite drops any previously-cited fragment id, the runtime reverts MEMORY.md to its pre-run bytes, skips fragment GC, but **advances dreamed-ids** anyway (so the same input cannot infinite-loop). The conscious tradeoff: a violation orphans this run's new undreamed fragments — they survive in the daily JSONL (force-committed, recoverable via `git log memory/`) but will never be re-shown to a future dreaming run. If the revert write itself fails, the runtime additionally skips the dreamed-id advance, skips compaction, and skips the commit, leaving recovery to the operator (`git checkout -- MEMORY.md && typeclaw restart`). Look for `[dreaming] citation-superset violation` log lines if `MEMORY.md` ever seems to stop updating.
+
 `MEMORY.md` after dreaming looks like:
 
 ```
 # Memory
 
-## <topic>
+## <strong topic — wording from days >= 3>
 <conclusion paragraph in dreaming's own words>
 
 fragments:
 - memory/yyyy-MM-dd#<fragment-id>
 - memory/yyyy-MM-dd#<fragment-id>
 
-## <topic>
+## <weaker topic>
 <conclusion paragraph>
 
 fragments:
 - memory/yyyy-MM-dd#<fragment-id>
+
+## Historical observations
+- yyyy-MM-dd: one-line summary of a demoted fact — memory/yyyy-MM-dd#<fragment-id>
+- yyyy-MM-dd: one-line summary of another demoted fact — memory/yyyy-MM-dd#<fragment-id>
 ```
 
-The first line is always `# Memory`. Topics are level-2 headings. Every topic cites the source fragments by `memory/yyyy-MM-dd#<uuidv7>` (the full id from the fragment event's `id` field) so any claim is traceable back to the daily stream entry that justified it. Citations are id-based, not line-based, so daily streams can be compacted between dreaming runs without invalidating prior references.
+The first line is always `# Memory`. Topics are level-2 headings. Every topic cites the source fragments by `memory/yyyy-MM-dd#<uuidv7>` (the full id from the fragment event's `id` field) so any claim is traceable back to the daily stream entry that justified it. Citations are id-based, not line-based, so daily streams can be compacted between dreaming runs without invalidating prior references. The `## Historical observations` bucket is always last when present.
 
-If the undreamed tails contain only watermarks, or every new fragment is already represented in `MEMORY.md`, dreaming **does nothing** and exits without writing. The watermark advances either way. "No-op dreaming" is a normal outcome, not a failure.
+Dreaming does NOT no-op just because there are no new fragments. Even with only watermarks past the tail, if the strength table shows obvious merge or demotion candidates (e.g. a stale single-day topic that has aged past the demotion threshold), the run is productive and rebalances. The truly-no-op case ("only watermarks AND every topic looks well-shaped at its current strength AND no procedure clears the muscle-memory bar") still exits without writing; the watermark advances either way.
 
 ### What gets injected into your prompt every turn
 
@@ -131,24 +139,26 @@ Stay concrete. Use this map:
 
 `typeclaw init` does **not** scaffold any of these. They appear when needed — `MEMORY.md` and `memory/` are created by the first dreaming run; daily streams appear when the first memory-logger fires.
 
-## When the user asks about `memory.idleMs` or `memory.dreaming.schedule`
+## When the user asks about `memory.idleMs`, `memory.bufferBytes`, or `memory.dreaming.schedule`
 
-These are the only two configurable knobs. They live in the `memory` block of `typeclaw.json`:
+These are the configurable knobs. They live in the `memory` block of `typeclaw.json`:
 
 ```json
 {
   "memory": {
-    "idleMs": 10000,
+    "idleMs": 60000,
+    "bufferBytes": 500000,
     "dreaming": { "schedule": "*/30 * * * *" }
   }
 }
 ```
 
-| Field                      | Default              | Effect                                                                                                                                                                                                        | Reload class      |
-| -------------------------- | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------- |
-| `memory.idleMs`            | `10000` (min `1000`) | Debounce window before `memory-logger` spawns after a prompt completes.                                                                                                                                       | Restart-required. |
-| `memory.dreaming`          | `{}` (cron job on)   | Dreaming cron job is always registered. Override `schedule` to change when it fires.                                                                                                                          | Restart-required. |
-| `memory.dreaming.schedule` | `"*/30 * * * *"`     | Cron expression. Parsed via `cron-parser`; an invalid expression fails config load. Fires with nothing past the watermark short-circuit before any LLM call, so frequent no-op fires are intentionally cheap. | Restart-required. |
+| Field                      | Default               | Effect                                                                                                                                                                                                                                                                              | Reload class      |
+| -------------------------- | --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------- |
+| `memory.idleMs`            | `60000` (min `1000`)  | Debounce window before `memory-logger` spawns after a prompt completes.                                                                                                                                                                                                             | Restart-required. |
+| `memory.bufferBytes`       | `500000` (0 disables) | Size-based ceiling. Spawns `memory-logger` immediately when the transcript has grown by this many bytes since the last run, regardless of `idleMs`. Lets busy channel sessions still produce memory updates without waiting for a full quiet window. Minimum `10000` when non-zero. | Restart-required. |
+| `memory.dreaming`          | `{}` (cron job on)    | Dreaming cron job is always registered. Override `schedule` to change when it fires.                                                                                                                                                                                                | Restart-required. |
+| `memory.dreaming.schedule` | `"*/30 * * * *"`      | Cron expression. Parsed via `cron-parser`; an invalid expression fails config load. Fires with nothing past the watermark short-circuit before any LLM call, so frequent no-op fires are intentionally cheap.                                                                       | Restart-required. |
 
 Both fields are restart-required because plugin config is read once at boot. After editing them, tell the user: "Edited `memory.<field>` — restart-required. Run `typeclaw restart` (host stage) to pick up the change." The bundled plugin's config schema is merged into `typeclaw.schema.json`, so editor autocomplete will validate these fields, but a `reload` will not re-instantiate the plugin.
 

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

@@ -21,12 +21,12 @@ Each role carries a set of **permissions** — opaque dotted strings like `chann
 
 You always have these four, even if `typeclaw.json` declares zero `roles`. User-declared roles **append** match rules to the built-ins but **replace** the permission list entirely (so `"permissions": []` on a built-in role means "no permissions" — be careful).
 
-| Role      | Built-in `match[]`                                                | Default `permissions[]`                                                                                                   |
-| --------- | ----------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
-| `owner`   | `["tui"]` (always prepended)                                      | `channel.respond`, `cron.schedule`, `cron.modify`, **all `security.bypass.*` contributed by plugins** (wildcard sentinel) |
-| `trusted` | none                                                              | `channel.respond`, `cron.schedule`, `security.bypass.secretExfilBash`, `security.bypass.gitExfil`                         |
-| `member`  | none                                                              | `channel.respond`                                                                                                         |
-| `guest`   | none (fallback when nothing else matches, or stamped role is bad) | none                                                                                                                      |
+| Role      | Built-in `match[]`                                                | Default `permissions[]`                                                                                                                                                                                                                                                                                                                                                                  |
+| --------- | ----------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `owner`   | `["tui"]` (always prepended)                                      | `channel.respond`, `cron.schedule`, `cron.modify`, `security.bypass.low`, `security.bypass.medium`, **plugin-contributed `security.bypass.*` MINUS high-tier strings** (the wildcard sentinel expands to plugin bypasses but excludes the security plugin's `ownerWildcardExclusions` — today: `gitExfil`, `gitRemoteTainted`, `outboundSecret`, `systemPromptLeak`, plus `bypass.high`) |
+| `trusted` | none                                                              | `channel.respond`, `cron.schedule`, `security.bypass.low`                                                                                                                                                                                                                                                                                                                                |
+| `member`  | none                                                              | `channel.respond`                                                                                                                                                                                                                                                                                                                                                                        |
+| `guest`   | none (fallback when nothing else matches, or stamped role is bad) | none                                                                                                                                                                                                                                                                                                                                                                                     |
 
 A session that doesn't match anything resolves to `guest`. `guest` has no `channel.respond`, so the router silently drops inbound messages whose author resolves to `guest`. **This is the most common cause of "the agent stopped responding"**: the user added a channel but did not add a match rule, so every speaker in that channel is `guest` and every inbound is dropped before you ever see it. There is no message in your session log when this happens — only a host-side line `[channels] <key>: denied by permissions (channel.respond) author=<id>`.
 
@@ -79,10 +79,24 @@ Things the DSL rejects (the parser emits actionable errors at boot, but you shou
 Three sources contribute permission strings:
 
 1. **Core** (always present): `channel.respond`, `cron.schedule`, `cron.modify`.
-2. **Bundled security plugin** (always loaded): `security.bypass.secretExfilBash`, `security.bypass.gitExfil`, `security.bypass.gitRemoteTainted`, `security.bypass.secretExfilRead`, `security.bypass.ssrf`, `security.bypass.sessionSearchSecrets`, `security.bypass.systemPromptLeak`, `security.bypass.outboundSecret`.
+2. **Bundled security plugin** (always loaded): the eight per-guard strings (`security.bypass.secretExfilBash`, `security.bypass.gitExfil`, `security.bypass.gitRemoteTainted`, `security.bypass.secretExfilRead`, `security.bypass.ssrf`, `security.bypass.sessionSearchSecrets`, `security.bypass.systemPromptLeak`, `security.bypass.outboundSecret`) AND three severity-tier strings (`security.bypass.low`, `security.bypass.medium`, `security.bypass.high`).
 3. **User-declared plugins** (variable): each plugin can contribute its own strings via `definePlugin({ permissions: [...] })`.
 
-`owner` carries every `security.bypass.*` from sources 2 and 3 by default (via a wildcard sentinel expanded at boot). `trusted` carries `security.bypass.secretExfilBash` and `security.bypass.gitExfil` by default (so a trusted actor can run dangerous bash and `git push` without per-call acks) but **deliberately not** `security.bypass.gitRemoteTainted` — the two-step social-attack defense (re-point remote, then push to it) still fires for trusted, so a prompt-injection mid-session that swaps the remote URL still blocks the eventual push. `member` and `guest` carry no `security.bypass.*` strings.
+The security plugin classifies each guard on a two-axis policy:
+
+- **high — audience-leak.** Bypass sends data to a third-party audience outside the operator's control loop (channel readers, remote git hosts). Inhabitants: `outboundSecret`, `systemPromptLeak`, `gitExfil`, `gitRemoteTainted`. **No role auto-bypasses high.** Per-call ack required from every role, including `owner`. The canonical case is **owner-in-public-channel**: even an owner asking "post deploy status to #general" must not silently include a `Bearer ghp_…` line; even `git push` from TUI must be ack'd. Operators who knowingly want one role to skip a high-tier guard add the per-guard string explicitly to `roles.<role>.permissions[]`.
+- **medium — silent-attack.** Bypass returns secrets / IAM creds into model context with no immediate operator visibility. Inhabitants: `secretExfilBash`, `secretExfilRead`, `ssrf`, `sessionSearchSecrets`. `owner` bypasses (operator already has host access); `trusted` does NOT.
+- **low — noisy, immediately recoverable.** No inhabitants today. Forward-compat for future guards. `trusted` carries `bypass.low` so a future low-tier guard auto-bypasses for trusted without a config edit.
+
+At `tool.before` time, an actor bypasses a guard if they hold **either** the tier permission **or** the per-guard permission (OR-check, both axes work forever).
+
+`owner` carries `security.bypass.low + security.bypass.medium` AND the wildcard sentinel; the sentinel expands to plugin-contributed `security.bypass.*` strings minus the security plugin's `ownerWildcardExclusions` (today: the four high-tier per-guard strings plus `bypass.high`). Net: `owner` auto-bypasses every low- and medium-tier guard; high-tier guards require ack from owner too. `trusted` carries only `bypass.low` — no per-guard medium/high grants by default. `member` and `guest` carry no `security.bypass.*` strings.
+
+**Trusted lost two per-guard grants in PR #255 compared to pre-PR behavior.** Before: trusted carried `bypassSecretExfilBash` and `bypassGitExfil` so they could `bash env` and `git push` without acks. After: those guards (medium and high respectively) need acks for trusted too. Operators who relied on the old ergonomics can restore them by adding the per-guard strings explicitly to `roles.trusted.permissions[]` in `typeclaw.json` — the per-guard path is supported forever via the OR-check. When the user complains "trusted can't push anymore," this is the explanation and the workaround.
+
+Note on the two-step `gitRemoteTainted` defense: even when an operator explicitly grants `security.bypass.gitExfil` to a role (re-opening the high-tier bypass for `git push`), the second-step `gitRemoteTainted` check still fires on the eventual push if origin was re-pointed mid-session. The recorder runs on the first step (the `set-url`) gated by "would the command actually run" — so the second-step checker has taint state to consult. Granting `bypassGitExfil` does NOT silently grant `bypassGitRemoteTainted`; those are independent per-guard strings AND independent high-tier guards.
+
+**Two-layer defense for channel-side git operations**: the runtime `tool.before` guards are not the only layer that gates `git push` from channel messages. The security plugin's `session.prompt` hook also pattern-matches inbound text for `git push` / `git remote add` / `gh repo create --push` and injects a refusal rule into the system prompt. **The prompt-side `git_exfil` defense is gated to non-subagent origins** — it fires for `channel` and `tui` prompts but skips `subagent` prompts. The reason: bundled subagents like `backup-diagnose` legitimately embed git stderr in their payloads (which contains literal "git push --help" hint strings on failures), and triggering the defense there would inject a "do NOT run git push" rule that contradicts the subagent's own system-prompt instructions to retry with an ack. The runtime `tool.before` is the universal backstop for subagents (under the audience-leak policy, even owner-spawned subagents need an ack for `git push`), so the prompt-side check is redundant for them and harmful to bundled-plugin recovery flows. For channel and TUI prompts the two layers agree: nobody auto-bypasses gitExfil at the runtime layer, so the prompt-injection layer's text-match refusal is the same answer the runtime would give. The only case where the two layers disagree is when an operator has explicitly granted `security.bypass.gitExfil` to a channel speaker's role in `typeclaw.json` — then the runtime would allow the push but the prompt-injection text-match would still refuse. That's a known narrow-scope gap (operator opted into the bypass already); if the user is confused why the agent refused a channel-side push despite the per-guard grant they added, this is why.
 
 User-declared `permissions[]` strings that don't appear in any of the three sources are **logged as warnings at boot** (`[permissions] role "X" declares unknown permission "Y" — did you mean 'Z'?`) but the role still resolves with the unknown string in its list. This is intentional — the runtime is forward-compatible with strings from plugins that aren't loaded yet — but it also means typos silently fail to bypass guards. If you wrote `security.bypass.secretExfilBach` instead of `Bash`, no guard will be skipped and you will only notice when you read the boot logs.
 
@@ -93,18 +107,19 @@ The security plugin's `tool.before` hook produces block messages of the form:
 ```
 Guard `<guardName>` blocked <what>. If this is genuinely intentional and the user
 explicitly asked for it, retry with `acknowledgeGuards.<guardName>: true` in the
-<tool> arguments. Or run as a role carrying `<permission>` (owner has all
-security.bypass.*; trusted has security.bypass.secretExfilBash and
-security.bypass.gitExfil — but not gitRemoteTainted).
+<tool> arguments. Or run as a role carrying `<per-guard-permission>` (...role hint...)
+or the tier permission `security.bypass.<low|medium|high>`; see the
+`typeclaw-permissions` skill.
 ```
 
-Three escape hatches, ordered from least to most invasive:
+Four escape hatches, ordered from least to most invasive:
 
 1. **`acknowledgeGuards.<guardName>: true`** in the tool args. This is a per-call, in-session bypass. Use it when the user has just explicitly told you to run the dangerous thing (e.g. "yes, push the secret to a private gist on purpose"). Never use it without explicit user confirmation — the guard exists for a reason.
-2. **Run as a role with the bypass permission**. If the user wants this pattern to keep working without an ack every time, they edit `roles.<role>.permissions[]` to include the `security.bypass.<X>` string the block message named. This is the right answer for "I'm `trusted` in this Slack channel and I want to be able to run dangerous bash without confirming each time" — give `trusted` the relevant `security.bypass.*` permission.
-3. **Run from a session that already resolves to a role with the bypass**. The TUI is always `owner`, so a guard that blocks in channel sessions for a `member` author will not block at all from the TUI. This is why "the agent can do X in TUI but not in Slack" is normal, not a bug.
+2. **Run as a role with the per-guard bypass permission**. If the user wants this pattern to keep working without an ack every time, they edit `roles.<role>.permissions[]` to include the specific `security.bypass.<guardName>` string the block message named. This is the most granular grant — it only opens up that one guard. Use this when the user wants exactly one capability and nothing else.
+3. **Run as a role with the tier bypass permission**. The block message also names the tier permission (`security.bypass.low` / `.medium` / `.high`). Granting the tier opens up every guard of that tier at once — broader than option 2, narrower than full owner. Use this when "let trusted users post credentials to chat AND view system prompt fingerprints AND search session history" is the user's actual intent rather than three separate per-guard grants.
+4. **Run from a session that already resolves to a role with the bypass**. The TUI is always `owner`, so a guard that blocks in channel sessions for a `member` author will not block at all from the TUI. This is why "the agent can do X in TUI but not in Slack" is normal, not a bug.
 
-When you see a block, tell the user **which permission would skip it** (the block message now names it) and **which built-in roles have that permission**. Do not just relay the guard reason — that loses the access-control framing entirely.
+When you see a block, tell the user **which permission would skip it** (the block message now names both the per-guard and the tier options) and **which built-in roles have those permissions**. Do not just relay the guard reason — that loses the access-control framing entirely.
 
 ## When the user asks "why aren't you replying in #channel?"
 
@@ -121,7 +136,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.
-2. **Pick a role.** Default to `member` for "give them normal channel access". Use `trusted` if they should also be able to schedule cron, bypass the bash secret guard, and run `git push` / `git remote add` / `git add -f` without per-call acks (the two-step taint defense still fires for trusted so a mid-session remote re-point still blocks the eventual push). Only use `owner` if they should have full bypass on every security guard, including the taint defense — typically the agent's primary operator.
+2. **Pick a role.** Default to `member` for "give them normal channel access". Use `trusted` if they should also be able to schedule cron — by default trusted gets ONLY `bypass.low` (no inhabitants today), so trusted on its own does NOT skip any security guard. If the user wants the old pre-PR-#255 trusted ergonomics (bypass bash secret guard, push without ack), add per-guard strings explicitly: `roles.trusted.permissions: ["channel.respond", "cron.schedule", "security.bypass.low", "security.bypass.secretExfilBash", "security.bypass.gitExfil"]`. Use `owner` only for the primary operator — owner auto-bypasses every medium-tier guard (`secretExfilBash`, `secretExfilRead`, `ssrf`, `sessionSearchSecrets`) but **still must ack every high-tier guard** (`gitExfil`, `gitRemoteTainted`, `outboundSecret`, `systemPromptLeak`) because audience-leak guards have no role auto-bypass — that's the owner-in-public-channel rule. If the user explicitly wants `git push` from TUI without acks, that's a per-guard explicit grant on `roles.owner.permissions[]` (re-add `security.bypass.gitExfil`), and the user should understand they are re-opening the audience-leak path for that guard.
 3. **Edit `typeclaw.json` `roles.<role>.match[]`.** 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.
 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)."
 5. **Commit the change.** See the `typeclaw-git` skill. The decision context in the commit message should name the role, the channel, and the author/scope ("let @X talk to me as `member` in #foo in workspace bar").
@@ -151,7 +166,10 @@ If you see a cron job mysteriously failing every fire with `denied by permission
 ## Things you must not do
 
 - **Do not write `*` in user-declared `permissions[]`.** The owner wildcard is a runtime sentinel, not part of the user-facing string format. The schema rejects `*` (it's not a valid dotted permission string anyway).
-- **Do not invent permission strings.** Only the three sources above (core, security plugin, declared plugins) contribute valid strings. A string like `bash.execute` looks plausible but is not gated by anything and will only earn a boot warning. If the user asks for a permission the model doesn't have, tell them — don't invent one.
+- **Do not invent permission strings.** Only the three sources above (core, security plugin including the eight per-guard + three tier strings, declared plugins) contribute valid strings. A string like `bash.execute` looks plausible but is not gated by anything and will only earn a boot warning. If the user asks for a permission the model doesn't have, tell them — don't invent one.
+
+- **Do not grant `security.bypass.high` casually.** High-tier guards (`gitExfil`, `gitRemoteTainted`, `outboundSecret`, `systemPromptLeak`) all defend the audience-leak axis — bypassing them means data leaves the operator's perimeter without per-call confirmation. Even `owner` doesn't have `bypass.high` by default for this exact reason. Granting `security.bypass.high` to any role opens audience-leak bypass on every current high-tier guard PLUS every future high-tier guard added by a security plugin update. If the user wants one specific high-tier bypass (e.g. "let me push from TUI without acks"), grant the **per-guard** string explicitly (`security.bypass.gitExfil`) on the specific role, not the tier — that's narrower and won't widen on plugin updates.
+- **Do not grant `security.bypass.medium` to roles wider than the operator.** Medium-tier bypasses (`secretExfilBash`, `secretExfilRead`, `ssrf`, `sessionSearchSecrets`) silently dump secrets into model context. Granting `bypass.medium` to a `trusted` role that matches a broad Slack workspace means any trusted speaker can ask the agent to dump environment variables and the bypass succeeds — the operator only sees on session review. If the user wants this anyway, name the specific guard with a per-guard grant rather than the whole tier.
 - **Do not promise that `typeclaw reload` applied a `roles` edit.** `roles` is restart-required. The reload tool will return success on the config file change, but the live `PermissionService` was built at boot and is not swapped on reload.
 - **Do not silently change a built-in role's permission list.** Setting `"permissions": []` on `member` is a wholesale replace, not a merge — you just took `channel.respond` away from every speaker who resolves to `member`. If the user said "give member just `channel.respond` and nothing else", that's fine (it's the same as the default), but say so explicitly: "this matches the default for `member`, no behavior change". If the user said "remove cron from `trusted`", make the change but warn that `trusted` no longer carries `cron.schedule` either.
 - **Do not write match rules using display names** (`#general`, `@user`, channel/user names). Match rules are platform IDs. Display names change; IDs don't. Always look up the ID before writing the rule.

package/src/tui/index.ts

@@ -1,5 +1,7 @@
 import { Editor, Key, Markdown, matchesKey, ProcessTerminal, type Terminal, Text, TUI } from '@mariozechner/pi-tui'
 
+import { parseCommand } from '@/commands'
+
 import { createClient as createClientDefault, type Client } from './client'
 import { formatQueuePanel, formatToolEnd, formatToolStart, formatUserPromptHistory } from './format'
 import { colors, editorTheme, markdownTheme } from './theme'
@@ -9,6 +11,21 @@ export type TerminalFactory = () => Terminal
 
 const DEFAULT_HANDSHAKE_TIMEOUT_MS = 30_000
 
+// Bare slash-command names (no leading `/`) the TUI intercepts client-side and
+// turns into a clean process exit. The hatching ritual tells the agent to point
+// users at `/quit` (see src/init/hatching.ts); without an intercept the literal
+// text would be shipped to the LLM as a chat message. Grammar (case-insensitive,
+// whitespace-tolerant, `//foo` escapes to a literal prompt) comes from
+// `parseCommand` in src/commands so channel and TUI slash commands stay
+// consistent. Arguments after the name disqualify the match: `/quit me a story`
+// is a real prompt, not a command.
+const QUIT_COMMAND_NAMES: ReadonlySet<string> = new Set(['quit', 'exit'])
+
+function isQuitCommand(text: string): boolean {
+  const parsed = parseCommand(text)
+  return parsed !== null && parsed.args.length === 0 && QUIT_COMMAND_NAMES.has(parsed.name)
+}
+
 export type VersionMismatch = { expected: string; actual: string }
 
 export type TuiOptions = {
@@ -205,14 +222,18 @@ export function createTui({
       return undefined
     })
 
+    const shutdown = (code: number) => {
+      tui.stop()
+      client.close()
+      exit(code)
+    }
+
     // Ctrl+C exits cleanly. In raw mode the kernel does NOT generate SIGINT,
     // so we must intercept the \x03 byte ourselves. The Editor would otherwise
     // swallow it. tui.stop() restores raw-mode/cursor/echo before we exit.
     tui.addInputListener((data) => {
       if (matchesKey(data, Key.ctrl('c'))) {
-        tui.stop()
-        client.close()
-        exit(0)
+        shutdown(0)
         return { consume: true }
       }
       return undefined
@@ -220,6 +241,10 @@ export function createTui({
 
     editor.onSubmit = (text) => {
       if (text.trim().length === 0) return
+      if (isQuitCommand(text)) {
+        shutdown(0)
+        return
+      }
       editor.setText('')
       editor.addToHistory(text)
       tui.requestRender()
@@ -238,6 +263,13 @@ export function createTui({
     }
 
     if (initialPrompt) {
+      // initialPrompt bypasses editor.onSubmit, so the quit intercept above
+      // would never run. Guard the same way so `typeclaw tui /quit` exits
+      // instead of leaking the command into the agent's chat context.
+      if (isQuitCommand(initialPrompt)) {
+        shutdown(0)
+        return
+      }
       await send(initialPrompt)
     }
 

package/src/usage/report.ts

@@ -145,27 +145,30 @@ function renderOriginLabel(kind: OriginKind, ctx: RenderCtx): string {
   }
 }
 
-// Sparkline trend across the full byDay range, scaled to the row's max cost.
-// Returns null when there are fewer than 2 days (a single point conveys no
-// trend information). The 8-level Unicode block scale `▁▂▃▄▅▆▇█` lets us
-// pack ~80 days into a one-line glance — wider than any table-based view
-// could fit at terminal widths under ~160 columns.
+// Sparkline trend across the full byDay range, scaled to the row's max token
+// count. Tokens (not cost) drive the chart because they're the load-bearing
+// usage signal — model price changes and free-tier credits shouldn't flatten
+// or distort the visible workload pattern. Returns null when there are fewer
+// than 2 days (a single point conveys no trend information). The 8-level
+// Unicode block scale `▁▂▃▄▅▆▇█` lets us pack ~80 days into a one-line glance
+// — wider than any table-based view could fit at terminal widths under ~160
+// columns.
 const SPARK_GLYPHS = '▁▂▃▄▅▆▇█'
 
-function renderDailyTrend(byDay: readonly { date: string; cost: number }[], ctx: RenderCtx): string | null {
+function renderDailyTrend(byDay: readonly { date: string; totalTokens: number }[], ctx: RenderCtx): string | null {
   if (byDay.length < 2) return null
-  const costs = byDay.map((d) => d.cost)
-  const max = costs.reduce((m, c) => Math.max(m, c), 0)
+  const tokens = byDay.map((d) => d.totalTokens)
+  const max = tokens.reduce((m, t) => Math.max(m, t), 0)
   if (max <= 0) return null
-  const spark = costs
-    .map((c) => {
-      const idx = Math.min(SPARK_GLYPHS.length - 1, Math.max(0, Math.round((c / max) * (SPARK_GLYPHS.length - 1))))
+  const spark = tokens
+    .map((t) => {
+      const idx = Math.min(SPARK_GLYPHS.length - 1, Math.max(0, Math.round((t / max) * (SPARK_GLYPHS.length - 1))))
       return SPARK_GLYPHS[idx]!
     })
     .join('')
   const first = byDay[0]!.date
   const last = byDay[byDay.length - 1]!.date
-  return `${dim('Trend (cost):', ctx)} ${color('cyan', spark, ctx)}  ${dim(`${first} → ${last}`, ctx)}`
+  return `${dim('Trend (tokens):', ctx)} ${color('cyan', spark, ctx)}  ${dim(`${first} → ${last}`, ctx)}`
 }
 
 function renderDaily(report: UsageReport, ctx: RenderCtx, limit: number | undefined): string {

package/typeclaw.schema.json

@@ -12,33 +12,59 @@
       "maximum": 65535
     },
     "models": {
-      "default": {
-        "default": "openai/gpt-5.4-nano"
-      },
       "type": "object",
       "propertyNames": {
         "type": "string",
         "minLength": 1
       },
       "additionalProperties": {
-        "type": "string",
-        "enum": [
-          "openai/gpt-5.4-nano",
-          "openai/gpt-5.4-mini",
-          "openai/gpt-5.4",
-          "openai/gpt-5.5",
-          "openai-codex/gpt-5.4-mini",
-          "openai-codex/gpt-5.4",
-          "openai-codex/gpt-5.5",
-          "fireworks/accounts/fireworks/routers/kimi-k2p6-turbo",
-          "zai/glm-4.5-air",
-          "zai/glm-4.6",
-          "zai/glm-4.7",
-          "zai-coding/glm-4.5-air",
-          "zai-coding/glm-4.7",
-          "zai-coding/glm-5",
-          "zai-coding/glm-5-turbo",
-          "zai-coding/glm-5.1"
+        "anyOf": [
+          {
+            "type": "string",
+            "enum": [
+              "openai/gpt-5.4-nano",
+              "openai/gpt-5.4-mini",
+              "openai/gpt-5.4",
+              "openai/gpt-5.5",
+              "openai-codex/gpt-5.4-mini",
+              "openai-codex/gpt-5.4",
+              "openai-codex/gpt-5.5",
+              "fireworks/accounts/fireworks/routers/kimi-k2p6-turbo",
+              "zai/glm-4.5-air",
+              "zai/glm-4.6",
+              "zai/glm-4.7",
+              "zai-coding/glm-4.5-air",
+              "zai-coding/glm-4.7",
+              "zai-coding/glm-5",
+              "zai-coding/glm-5-turbo",
+              "zai-coding/glm-5.1"
+            ]
+          },
+          {
+            "minItems": 1,
+            "type": "array",
+            "items": {
+              "type": "string",
+              "enum": [
+                "openai/gpt-5.4-nano",
+                "openai/gpt-5.4-mini",
+                "openai/gpt-5.4",
+                "openai/gpt-5.5",
+                "openai-codex/gpt-5.4-mini",
+                "openai-codex/gpt-5.4",
+                "openai-codex/gpt-5.5",
+                "fireworks/accounts/fireworks/routers/kimi-k2p6-turbo",
+                "zai/glm-4.5-air",
+                "zai/glm-4.6",
+                "zai/glm-4.7",
+                "zai-coding/glm-4.5-air",
+                "zai-coding/glm-4.7",
+                "zai-coding/glm-5",
+                "zai-coding/glm-5-turbo",
+                "zai-coding/glm-5.1"
+              ]
+            }
+          }
         ]
       }
     },
@@ -898,6 +924,7 @@
           "tmux": true,
           "cjkFonts": true,
           "cloudflared": true,
+          "xvfb": true,
           "append": []
         }
       },
@@ -911,6 +938,7 @@
             "tmux": true,
             "cjkFonts": true,
             "cloudflared": true,
+            "xvfb": true,
             "append": []
           },
           "type": "object",
@@ -963,6 +991,10 @@
               "default": true,
               "type": "boolean"
             },
+            "xvfb": {
+              "default": true,
+              "type": "boolean"
+            },
             "append": {
               "default": [],
               "type": "array",
@@ -1130,20 +1162,20 @@
     },
     "memory": {
       "default": {
-        "idleMs": 10000,
-        "bufferBytes": 100000,
+        "idleMs": 60000,
+        "bufferBytes": 500000,
         "spawnTimeoutMs": 50000
       },
       "type": "object",
       "properties": {
         "idleMs": {
-          "default": 10000,
+          "default": 60000,
           "type": "integer",
           "minimum": 1000,
           "maximum": 9007199254740991
         },
         "bufferBytes": {
-          "default": 100000,
+          "default": 500000,
           "type": "integer",
           "minimum": 0,
           "maximum": 9007199254740991