typeclaw 0.9.1 → 0.10.0

package/src/bundled-plugins/memory/stream-io.ts

@@ -1,4 +1,4 @@
-import { readFile, appendFile, readdir, writeFile, rename } from 'node:fs/promises'
+import { readFile, appendFile, readdir, stat, writeFile, rename } from 'node:fs/promises'
 import { join } from 'node:path'
 
 import { getDreamedIds, loadDreamingState } from './dreaming-state'
@@ -8,7 +8,59 @@ import { parseEventLine, type StreamEvent } from './stream-events'
 const STREAM_FILE_PATTERN = /^\d{4}-\d{2}-\d{2}\.jsonl$/
 const STREAM_DATE_FROM_FILENAME = /^(\d{4}-\d{2}-\d{2})\.jsonl$/
 
+// Per-file event cache. `(mtimeMs, ctimeMs, size)` is the invalidation key,
+// mirroring `load-shards.ts`'s shard cache. The three writers in this module
+// — `appendEvents` (memory-logger appends), `writeEventsAtomic` (dreaming
+// compaction + migration), and any external `writeFile` — all bump mtime
+// and/or ctime, so stat-based invalidation is sufficient without explicit
+// hooks. ctimeMs guards metadata-preserving external edits (rsync -t,
+// `touch -r`, restored backups, `git checkout` with timestamps): the kernel
+// always bumps ctime on inode content changes and ctime cannot be backdated
+// via utimes.
+//
+// Module-level keyed by absolute file path. One Bun process owns one agent
+// dir in production (the container stage), so cardinality is small. Multi-
+// path support exists because dreaming compacts multiple files per run and
+// memory_search reads every dated stream.
+type StreamFileCacheEntry = {
+  mtimeMs: number
+  ctimeMs: number
+  size: number
+  events: StreamEvent[]
+}
+const streamFileCache = new Map<string, StreamFileCacheEntry>()
+
 export async function readEvents(path: string): Promise<StreamEvent[]> {
+  const fileStat = await statFile(path)
+  if (fileStat === null) {
+    // File disappeared since last cache populate (e.g. dreaming dropped a
+    // fully-GC'd day). Drop the entry so a future recreate gets fresh
+    // content.
+    streamFileCache.delete(path)
+    return []
+  }
+
+  const cached = streamFileCache.get(path)
+  if (
+    cached !== undefined &&
+    cached.mtimeMs === fileStat.mtimeMs &&
+    cached.ctimeMs === fileStat.ctimeMs &&
+    cached.size === fileStat.size
+  ) {
+    return cached.events
+  }
+
+  const events = await readEventsFromDisk(path)
+  streamFileCache.set(path, {
+    mtimeMs: fileStat.mtimeMs,
+    ctimeMs: fileStat.ctimeMs,
+    size: fileStat.size,
+    events,
+  })
+  return events
+}
+
+async function readEventsFromDisk(path: string): Promise<StreamEvent[]> {
   let raw: string
   try {
     raw = await readFile(path, 'utf-8')
@@ -34,6 +86,24 @@ export async function readEvents(path: string): Promise<StreamEvent[]> {
   return events
 }
 
+async function statFile(path: string): Promise<{ mtimeMs: number; ctimeMs: number; size: number } | null> {
+  try {
+    const s = await stat(path)
+    return { mtimeMs: s.mtimeMs, ctimeMs: s.ctimeMs, size: s.size }
+  } catch (err) {
+    if ((err as NodeJS.ErrnoException).code === 'ENOENT') return null
+    throw err
+  }
+}
+
+// Test-only helper. Clears the in-memory stream-file cache so tests that
+// exercise the cache invalidation path can simulate a cold start without
+// spinning up a fresh process. Mirrors `__resetShardCacheForTests` in
+// `load-shards.ts`.
+export function __resetStreamFileCacheForTests(): void {
+  streamFileCache.clear()
+}
+
 export async function appendEvents(path: string, events: readonly StreamEvent[]): Promise<void> {
   if (events.length === 0) return
   const joined = events.map((e) => `${JSON.stringify(e)}\n`).join('')

package/src/bundled-plugins/security/index.ts

@@ -49,22 +49,23 @@ type PerGuardSecurityPermission = Exclude<
 // not a silent fallback.
 const BYPASS_ROLE_HINT = {
   [SECURITY_PERMISSIONS.bypassSecretExfilBash]:
-    'only owner has it by default (medium tier; trusted does NOT carry this — operators can grant `security.bypass.secretExfilBash` explicitly in roles.trusted.permissions[] if they want the pre-PR ergonomics back)',
+    'owner and trusted have it by default (medium tier); member and guest do not. Operators can grant `security.bypass.secretExfilBash` explicitly in roles.<role>.permissions[] to widen.',
   [SECURITY_PERMISSIONS.bypassGitExfil]:
-    'NOBODY has it by default — high tier requires per-call ack from every role, including owner. Operators can grant `security.bypass.gitExfil` explicitly in roles.<role>.permissions[] to re-open the auto-bypass for one role.',
+    'owner and trusted have it by default (medium tier); member and guest do not. The audience-leak surface for git lives in `gitRemoteTainted` (high tier, owner-only) — pushing to an attacker-retargeted remote is still blocked for trusted by the two-step taint defense.',
   [SECURITY_PERMISSIONS.bypassGitRemoteTainted]:
-    'NOBODY has it by default — high tier requires per-call ack from every role. Even an operator-granted `security.bypass.gitExfil` does NOT bypass this second-step taint check (the recorder still fires for the first step, so the push is still gated).',
-  [SECURITY_PERMISSIONS.bypassSecretExfilRead]: 'only owner has it by default (medium tier)',
-  [SECURITY_PERMISSIONS.bypassSsrf]: 'only owner has it by default (medium tier)',
-  [SECURITY_PERMISSIONS.bypassSessionSearchSecrets]: 'only owner has it by default (medium tier)',
-  [SECURITY_PERMISSIONS.bypassSystemPromptLeak]:
-    'NOBODY has it by default — high tier requires per-call ack from every role, including owner.',
+    'only owner has it by default (high tier). The two-step taint defense (recorder + checker) still fires whenever the actor lacks `security.bypass.gitRemoteTainted`, including across owner-granted gitExfil bypasses.',
+  [SECURITY_PERMISSIONS.bypassSecretExfilRead]:
+    'owner and trusted have it by default (medium tier); member and guest do not.',
+  [SECURITY_PERMISSIONS.bypassSsrf]: 'owner and trusted have it by default (medium tier); member and guest do not.',
+  [SECURITY_PERMISSIONS.bypassSessionSearchSecrets]:
+    'owner and trusted have it by default (medium tier); member and guest do not.',
+  [SECURITY_PERMISSIONS.bypassSystemPromptLeak]: 'only owner has it by default (high tier).',
   [SECURITY_PERMISSIONS.bypassOutboundSecret]:
-    'NOBODY has it by default — high tier requires per-call ack from every role, including owner. The audience-leak rule: even owner posting to a public channel must not silently include credentials.',
+    'only owner has it by default (high tier). The audience-leak risk: an owner-permissioned channel author can silently include credentials in outbound messages. Operators who match owner to a channel author should narrow that match or remove owner from `roles.owner.permissions[]` for those origins.',
   [SECURITY_PERMISSIONS.bypassRolePromotion]:
-    'NOBODY has it by default — high tier requires per-call ack from every role, including owner. The audience-leak rule generalizes to privilege escalation: even owner running from TUI must not silently rewrite the access-control table on behalf of a channel message.',
+    'owner and trusted have it by default (medium tier); member and guest do not. The privilege-escalation defense for trusted now depends on operator review of `typeclaw.json` backup commits — `roles` is restart-required, so the operator has wall-clock time to revert before the new role table takes effect. Operators who do not review can re-tighten by replacing `roles.trusted.permissions[]` with an explicit list that omits `security.bypass.medium`.',
   [SECURITY_PERMISSIONS.bypassCronPromotion]:
-    'NOBODY has it by default — high tier requires per-call ack from every role, including owner. Same shape as rolePromotion but deferred: a new cron job (or a changed scheduledByRole) is a privilege grant that fires at schedule-time, and the operator must not silently author one on behalf of a channel message.',
+    'owner and trusted have it by default (medium tier); member and guest do not. Same shape as rolePromotion but deferred: a new cron job (or a changed scheduledByRole) fires at schedule-time as the stamped role. The operator-review window between write and execution is the trusted-tier defense.',
 } as const satisfies Record<PerGuardSecurityPermission, string>
 
 function withPermissionHint(
@@ -83,12 +84,13 @@ function withPermissionHint(
 
 export default definePlugin({
   permissions: Object.values(SECURITY_PERMISSIONS),
-  // High-tier per-guard strings AND the `security.bypass.high` tier
-  // string itself are excluded from the owner-wildcard expansion. Owner
-  // still has the wildcard sentinel (so future low/medium plugin-
-  // contributed bypasses keep auto-flowing to owner), but audience-leak
-  // guards require either per-call ack or an explicit operator grant.
-  ownerWildcardExclusions: [...HIGH_TIER_PER_GUARD_PERMISSIONS, SECURITY_PERMISSIONS.bypassHigh],
+  // No wildcard exclusions: owner bypasses every security tier by default
+  // under the role-tower model. `BUILTIN_ROLES.owner.permissions` carries
+  // `security.bypass.{low,medium,high}` explicitly; the wildcard sentinel
+  // additionally fans out to every per-guard string (including high-tier
+  // ones). The owner-in-public-channel defense now lives in
+  // `roles.owner.match[]` discipline, not in the language defaults.
+  ownerWildcardExclusions: [],
   plugin: async (ctx) => ({
     hooks: {
       'session.prompt': async (event) => {

package/src/bundled-plugins/security/permissions.ts

@@ -37,16 +37,17 @@ export const SEVERITY_PERMISSION: Record<SecuritySeverity, string> = {
   high: SECURITY_PERMISSIONS.bypassHigh,
 }
 
-// Per-guard permission strings whose guards are classified `high`. The
-// owner-wildcard expander excludes these so the wildcard sentinel does
-// not auto-grant high-tier bypass to owner. Operators who explicitly
-// want to re-open a high-tier bypass for owner (or any role) can still
-// add the per-guard string to that role's `permissions[]` by hand.
+// Per-guard permission strings whose guards are classified `high`.
+// Plumbed through to the owner-wildcard expander's `ownerWildcardExclusions`
+// parameter at boot; the bundled security plugin currently passes `[]` so
+// owner DOES auto-bypass every high-tier per-guard string, but third-party
+// plugins (or a future tightening of the bundled defaults) can use this
+// constant to exclude high-tier strings from the wildcard expansion.
+// Keep this list in sync with the `'high'` classifications in
+// `policies/*.ts` — the drift-guard test in `permissions.test.ts` will
+// fail if a guard's severity constant disagrees with its membership here.
 export const HIGH_TIER_PER_GUARD_PERMISSIONS: readonly string[] = [
-  SECURITY_PERMISSIONS.bypassGitExfil,
   SECURITY_PERMISSIONS.bypassGitRemoteTainted,
   SECURITY_PERMISSIONS.bypassOutboundSecret,
   SECURITY_PERMISSIONS.bypassSystemPromptLeak,
-  SECURITY_PERMISSIONS.bypassRolePromotion,
-  SECURITY_PERMISSIONS.bypassCronPromotion,
 ]

package/src/bundled-plugins/security/policies/cron-promotion.ts

@@ -7,8 +7,23 @@ import type { SecuritySeverity } from '../permissions'
 import { ACKNOWLEDGE_GUARDS, type SecurityBlock, isGuardAcknowledged } from '../policy'
 
 export const GUARD_CRON_PROMOTION = 'cronPromotion'
-// Classified `high` (audience-leak axis, adapted — same reasoning as
-// `rolePromotion`).
+// Classified `medium` (silent-attack axis). Originally `high`; reclassified
+// for the same reason as `rolePromotion`: the deferred-execution surface
+// is still operator-reviewable before the job fires. `cron.json` is
+// force-committed by the auto-backup plugin, the change appears in
+// `git log` and backup commits, and the cron consumer dispatches by
+// schedule — there is wall-clock time between the privileged write and
+// the privileged execution during which the operator can revert or
+// disable. Bypass produces operator-reviewable state, not direct
+// audience-leak.
+//
+// Net effect on the role-tower model: owner and trusted both bypass
+// without ack; member and guest still get blocked. The defense for
+// trusted depends on backup-commit review discipline — same tradeoff
+// as `rolePromotion`. Operators who want to keep this at high for
+// trusted can subtract: replace `roles.trusted.permissions[]` with an
+// explicit list that omits `security.bypass.medium`, then add narrower
+// per-guard medium grants as needed.
 //
 // Cron is the deferred-execution sibling of `roles`. Every cron job
 // carries a `scheduledByRole` field that the runtime stamps into the
@@ -17,12 +32,14 @@ export const GUARD_CRON_PROMOTION = 'cronPromotion'
 // table"). The `parseCronFile` boot gate rejects entries without
 // `scheduledByRole`, but it accepts any role name the file declares.
 //
-// Concrete breach pattern: a `member`-role agent that can `write`
-// `cron.json` authors a brand-new job with `"scheduledByRole": "owner"`
-// and a prompt that does whatever the agent's tool surface allows when
-// running as owner. The cron consumer fires it on schedule; the firing
-// session resolves to `owner` because that role name exists in the role
-// table. The agent has laundered itself into owner via the schedule.
+// Concrete breach pattern blocked at `medium`: a `member`-role agent
+// that can `write` `cron.json` authors a brand-new job with
+// `"scheduledByRole": "owner"` and a prompt that does whatever the
+// agent's tool surface allows when running as owner. The cron consumer
+// fires it on schedule; the firing session resolves to `owner` because
+// that role name exists in the role table. The agent has laundered
+// itself into owner via the schedule. This guard blocks the first step
+// — member does not carry `bypass.medium`.
 //
 // Same two-step shape as `gitRemoteTainted`: "do a privileged write
 // now, run the privileged thing later." This guard blocks the first
@@ -66,7 +83,7 @@ export const GUARD_CRON_PROMOTION = 'cronPromotion'
 // is treated as new and flagged. The only false positive is "operator
 // authored a fresh `cron.json` with privileged jobs," which they
 // acknowledge in the same call.
-export const GUARD_CRON_PROMOTION_SEVERITY: SecuritySeverity = 'high'
+export const GUARD_CRON_PROMOTION_SEVERITY: SecuritySeverity = 'medium'
 
 export type CronPromotionFinding =
   | { kind: 'job-added'; id: string; scheduledByRole: string }

package/src/bundled-plugins/security/policies/git-exfil.ts

@@ -3,24 +3,32 @@ import { ACKNOWLEDGE_GUARDS, type SecurityBlock, isGuardAcknowledged } from '../
 import { getRemoteTaint, recordRemoteTaint } from './remote-taint-state'
 
 export const GUARD_GIT_EXFIL = 'gitExfil'
-// Classified `high` (audience-leak axis): `git push` sends every tracked
-// file to a remote git host. The host (GitHub/GitLab/attacker-controlled
-// box) is a third-party audience outside the operator's control loop.
-// Even a private remote owned by an attacker is now outside the
-// perimeter. No role auto-bypasses high — owner pushing from TUI must ack
-// each push. The historical per-guard string `security.bypass.gitExfil`
-// remains valid as an explicit grant for operators who knowingly want to
-// re-open the auto-bypass (see SKILL.md must-not-do guidance).
-export const GUARD_GIT_EXFIL_SEVERITY: SecuritySeverity = 'high'
+// Classified `medium` (silent-attack axis). Originally `high`; reclassified
+// because the actual audience-leak surface for `git push` lives in
+// `gitRemoteTainted`, not here. A `git push` to a CLEAN, operator-configured
+// remote is not audience-leak — the audience (the remote git host) was
+// chosen by the operator and is inside their perimeter. The breach pattern
+// PR #134 was written for (re-point origin to attacker URL, then push) is
+// gated by `gitRemoteTainted` (still high). The recorder-vs-checker split
+// is what makes this reclassification safe: the recorder fires for any
+// actor who can run a `git remote set-url` (per-guard bypass OR the
+// medium-tier permission via the OR check), so trusted's first-step
+// set-url still records taint and the second-step push still gets caught
+// by `gitRemoteTainted` even though trusted no longer needs to ack the
+// push itself. Net effect: trusted users can push to remotes the operator
+// configured without per-call acks, but cannot retarget-and-push.
+export const GUARD_GIT_EXFIL_SEVERITY: SecuritySeverity = 'medium'
 export const GUARD_GIT_REMOTE_TAINTED = 'gitRemoteTainted'
-// Classified `high` (audience-leak axis): same path as gitExfil, second
-// step. A push after a mid-session `git remote set-url` to an
+// Classified `high` (audience-leak axis): the actual audience-leak gate
+// for git. A push after a mid-session `git remote set-url` to an
 // attacker-controlled URL is exactly the breach pattern that motivated
-// the entire security plugin per PR #134. The recorder-vs-checker split
+// the entire security plugin per PR #134. Stays high regardless of how
+// `gitExfil` is classified — the two are independent per-guard strings
+// AND independent tier classifications. The recorder-vs-checker split
 // (see comment on recordGitRemoteTaintIfAny below) is still load-bearing:
-// the recorder fires for anyone who can run the underlying command (ack
-// or the per-guard `bypassGitExfil` grant), so even if an operator
-// explicitly grants `bypassGitExfil` to a role, the second-step taint
+// the recorder fires for anyone who can run the underlying `set-url`
+// command (ack, per-guard `bypassGitExfil`, OR the medium-tier permission
+// — which now includes trusted by default), so the second-step taint
 // check still fires on the eventual push.
 export const GUARD_GIT_REMOTE_TAINTED_SEVERITY: SecuritySeverity = 'high'
 

package/src/bundled-plugins/security/policies/role-promotion.ts

@@ -8,25 +8,32 @@ import type { SecuritySeverity } from '../permissions'
 import { ACKNOWLEDGE_GUARDS, type SecurityBlock, isGuardAcknowledged } from '../policy'
 
 export const GUARD_ROLE_PROMOTION = 'rolePromotion'
-// Classified `high` (audience-leak axis, adapted).
+// Classified `medium` (silent-attack axis). Originally `high`; reclassified
+// because the privilege escalation does NOT take effect until the operator
+// reloads or restarts — `roles` is `restart-required` in FIELD_EFFECTS, and
+// even the `match`-only path that's classified `applied` writes through
+// `typeclaw.json` which is force-committed by the auto-backup plugin on
+// idle. The operator sees the file change in `git log`, in `typeclaw reload`
+// output, and in their backup commits BEFORE the new role mapping takes
+// effect. There is an operator-visible step between bypass and breach,
+// which puts this guard squarely on the medium axis: bypass produces
+// attacker-favorable state in operator-reviewable surface, not direct
+// audience-leak.
 //
-// Role promotion is privilege escalation: the agent rewrites
-// `typeclaw.json#roles` so a previously-unprivileged actor now resolves
-// to a privileged role. The breach pattern: a `member`-role speaker in a
-// chat asks "give me permission" / "promote me to admin"; the agent
-// edits typeclaw.json with what looks like a routine config change; the
-// schema is valid, the managedConfig guard passes, nonWorkspaceWrite
-// allowlists typeclaw.json — and on next reload the speaker resolves to
-// `owner` with full bypasses.
+// Net effect on the role-tower model: owner and trusted both bypass without
+// ack; member and guest still get blocked. The defense for trusted now
+// depends on operator config-review discipline — if backup commits are
+// reviewed and `typeclaw reload` output is read before applying, a
+// trusted-laundered role promotion is caught before it fires. Operators
+// who do not review can re-tighten by adding `security.bypass.rolePromotion`
+// to `trusted.permissions[]` as an explicit subtraction (replace the
+// default tier grant with a narrower list) — see typeclaw-permissions skill.
 //
-// This is the same audience-leak shape as gitExfil and outboundSecret:
-// the "audience" here is the future-self of the access-control table,
-// which is outside the operator's per-call control loop. Even an `owner`
-// operating from TUI must not silently rewrite the role table based on
-// a channel message — the canonical owner-in-public-channel attack
-// generalizes from "post credentials" to "promote the asker". No role
-// auto-bypasses; per-call ack or an explicit `security.bypass.rolePromotion`
-// grant is required.
+// Breach pattern blocked at `medium`: a `member`-role speaker in a chat
+// asks "promote me to admin"; the agent edits typeclaw.json; the change is
+// schema-valid, managedConfig accepts it, nonWorkspaceWrite allowlists
+// typeclaw.json — but this guard still blocks because member does not
+// carry `bypass.medium` by default.
 //
 // What counts as a promotion (any of):
 //   1. A role's `permissions[]` gained an entry.
@@ -58,7 +65,7 @@ export const GUARD_ROLE_PROMOTION = 'rolePromotion'
 //     agent cannot start a claim, only consume one whose code the
 //     operator already broadcast. That makes the bypass intentionally
 //     out-of-band — do not extend this guard to cover it.
-export const GUARD_ROLE_PROMOTION_SEVERITY: SecuritySeverity = 'high'
+export const GUARD_ROLE_PROMOTION_SEVERITY: SecuritySeverity = 'medium'
 
 export type RolePromotionFinding = {
   role: string

package/src/channels/manager.ts

@@ -5,6 +5,7 @@ import type { PermissionService } from '@/permissions'
 import type { GithubSecretsBlock } from '@/secrets'
 import { SecretsKakaoCredentialStore } from '@/secrets/kakao-store'
 import { SecretsBackend } from '@/secrets/storage'
+import type { Stream } from '@/stream'
 
 import { createDiscordBotAdapter, type DiscordBotAdapter } from './adapters/discord-bot'
 import { createGithubAdapter, type GithubAdapter } from './adapters/github'
@@ -78,6 +79,11 @@ export type ChannelManagerOptions = {
   // a URL" so error logs can be precise. Same shape as
   // `tunnelUrlForChannel` for consistency. Optional for tests.
   tunnelConfiguredForChannel?: (channelName: string) => boolean
+  // Forwarded to the router as `stream`. When set, every inbound the
+  // router sees is published as a tagged broadcast for inspect surfacing.
+  // Production wiring (`src/run/index.ts`) always passes the agent's
+  // Stream; tests typically omit it.
+  stream?: Stream
 }
 
 export type ChannelManager = {
@@ -113,6 +119,7 @@ export function createChannelManager(options: ChannelManagerOptions): ChannelMan
     ...(options.createSessionForChannel ? { createSessionForChannel: options.createSessionForChannel } : {}),
     ...(options.permissions ? { permissions: options.permissions } : {}),
     ...(options.claimHandler ? { claimHandler: options.claimHandler } : {}),
+    ...(options.stream ? { stream: options.stream } : {}),
   })
   const createDiscordAdapter = options.createDiscordAdapter ?? createDiscordBotAdapter
   const createGithub = options.createGithubAdapter ?? createGithubAdapter