lyra-core 0.1.0

package/src/pairing.test.ts

@@ -0,0 +1,212 @@
+import { afterEach, beforeEach, describe, expect, it } from 'bun:test'
+import { mkdtempSync, readFileSync, rmSync, statSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import {
+  PAIRING_ALPHABET,
+  PAIRING_CODE_LENGTH,
+  PAIRING_CODE_TTL_SECONDS,
+  PAIRING_LOCKOUT_SECONDS,
+  PAIRING_MAX_FAILED_ATTEMPTS,
+  PAIRING_MAX_PENDING_PER_PLATFORM,
+  PairingStore,
+} from './pairing'
+
+let testDir: string
+
+beforeEach(() => {
+  testDir = mkdtempSync(join(tmpdir(), 'lyra-pairing-test-'))
+})
+
+afterEach(() => {
+  rmSync(testDir, { recursive: true, force: true })
+})
+
+describe('PairingStore.generateCode', () => {
+  it('returns an 8-char code from the alphabet', () => {
+    const store = new PairingStore({ dir: testDir })
+    const code = store.generateCode('telegram', '111')
+    expect(code).not.toBeNull()
+    expect(code!.length).toBe(PAIRING_CODE_LENGTH)
+    for (const ch of code!) expect(PAIRING_ALPHABET).toContain(ch)
+  })
+
+  it('returns null when MAX_PENDING_PER_PLATFORM reached', () => {
+    const store = new PairingStore({ dir: testDir })
+    for (let i = 0; i < PAIRING_MAX_PENDING_PER_PLATFORM; i++) {
+      const c = store.generateCode('telegram', `user-${i}`)
+      expect(c).not.toBeNull()
+    }
+    const overflow = store.generateCode('telegram', 'user-overflow')
+    expect(overflow).toBeNull()
+  })
+
+  it('returns null when same user requests within rate limit window', () => {
+    const store = new PairingStore({ dir: testDir })
+    const a = store.generateCode('telegram', '111')
+    expect(a).not.toBeNull()
+    const b = store.generateCode('telegram', '111')
+    expect(b).toBeNull()
+  })
+
+  it('different users on same platform do not rate-limit each other', () => {
+    const store = new PairingStore({ dir: testDir })
+    expect(store.generateCode('telegram', '111')).not.toBeNull()
+    expect(store.generateCode('telegram', '222')).not.toBeNull()
+  })
+
+  it('cleans up expired codes before generating', () => {
+    let now = 1000
+    const store = new PairingStore({ dir: testDir, now: () => now })
+    const c1 = store.generateCode('telegram', 'user-1')
+    expect(c1).not.toBeNull()
+    now += PAIRING_CODE_TTL_SECONDS + 1
+    const after = store.listPending('telegram')
+    expect(after.length).toBe(0)
+  })
+})
+
+describe('PairingStore.approveCode', () => {
+  it('approves a valid code and adds the user to approved list', () => {
+    const store = new PairingStore({ dir: testDir })
+    const code = store.generateCode('telegram', '111', 'phantom')!
+    const result = store.approveCode('telegram', code)
+    expect(result).toEqual({ userId: '111', userName: 'phantom' })
+    expect(store.isApproved('telegram', '111')).toBe(true)
+  })
+
+  it('removes the code from pending after approval', () => {
+    const store = new PairingStore({ dir: testDir })
+    const code = store.generateCode('telegram', '111')!
+    store.approveCode('telegram', code)
+    expect(store.listPending('telegram').length).toBe(0)
+  })
+
+  it('returns null for unknown codes', () => {
+    const store = new PairingStore({ dir: testDir })
+    const result = store.approveCode('telegram', 'WRONGCOD')
+    expect(result).toBeNull()
+  })
+
+  it('is case-insensitive on the code input', () => {
+    const store = new PairingStore({ dir: testDir })
+    const code = store.generateCode('telegram', '111')!
+    const result = store.approveCode('telegram', code.toLowerCase())
+    expect(result?.userId).toBe('111')
+  })
+
+  it('trims whitespace from the code input', () => {
+    const store = new PairingStore({ dir: testDir })
+    const code = store.generateCode('telegram', '111')!
+    const result = store.approveCode('telegram', ` ${code} `)
+    expect(result?.userId).toBe('111')
+  })
+
+  it('locks out platform after MAX_FAILED_ATTEMPTS bad approvals', () => {
+    const now = 1000
+    const store = new PairingStore({ dir: testDir, now: () => now })
+    for (let i = 0; i < PAIRING_MAX_FAILED_ATTEMPTS; i++) {
+      expect(store.approveCode('telegram', 'NOTREAL1')).toBeNull()
+    }
+    expect(store.isLockedOut('telegram')).toBe(true)
+    expect(store.generateCode('telegram', '111')).toBeNull()
+  })
+
+  it('lockout clears after LOCKOUT_SECONDS', () => {
+    let now = 1000
+    const store = new PairingStore({ dir: testDir, now: () => now })
+    for (let i = 0; i < PAIRING_MAX_FAILED_ATTEMPTS; i++) {
+      store.approveCode('telegram', 'NOTREAL1')
+    }
+    expect(store.isLockedOut('telegram')).toBe(true)
+    now += PAIRING_LOCKOUT_SECONDS + 1
+    expect(store.isLockedOut('telegram')).toBe(false)
+  })
+
+  it('successful approval resets the failure counter', () => {
+    const store = new PairingStore({ dir: testDir })
+    store.approveCode('telegram', 'NOTREAL1')
+    store.approveCode('telegram', 'NOTREAL2')
+    const code = store.generateCode('telegram', '111')!
+    store.approveCode('telegram', code)
+    // Should not reach lockout from prior 2 fails
+    for (let i = 0; i < PAIRING_MAX_FAILED_ATTEMPTS - 1; i++) {
+      store.approveCode('telegram', 'NOTREALX')
+    }
+    expect(store.isLockedOut('telegram')).toBe(false)
+  })
+})
+
+describe('PairingStore.listPending / listApproved / clearPending', () => {
+  it('listPending returns codes for one platform', () => {
+    const store = new PairingStore({ dir: testDir })
+    store.generateCode('telegram', '111', 'a')
+    store.generateCode('telegram', '222', 'b')
+    const pending = store.listPending('telegram')
+    expect(pending.length).toBe(2)
+    expect(pending.map(p => p.userId).sort()).toEqual(['111', '222'])
+  })
+
+  it('listPending(undefined) aggregates across platforms', () => {
+    const store = new PairingStore({ dir: testDir })
+    store.generateCode('telegram', '111')
+    store.generateCode('discord', '222')
+    const pending = store.listPending()
+    expect(pending.length).toBe(2)
+    const platforms = pending.map(p => p.platform).sort()
+    expect(platforms).toEqual(['discord', 'telegram'])
+  })
+
+  it('listApproved aggregates across platforms', () => {
+    const store = new PairingStore({ dir: testDir })
+    const c1 = store.generateCode('telegram', '111', 'a')!
+    store.approveCode('telegram', c1)
+    const c2 = store.generateCode('discord', '222', 'b')!
+    store.approveCode('discord', c2)
+    const approved = store.listApproved()
+    expect(approved.length).toBe(2)
+  })
+
+  it('clearPending removes all pending and returns count', () => {
+    const store = new PairingStore({ dir: testDir })
+    store.generateCode('telegram', '111')
+    store.generateCode('telegram', '222')
+    expect(store.clearPending('telegram')).toBe(2)
+    expect(store.listPending('telegram').length).toBe(0)
+  })
+
+  it('revoke removes an approved user', () => {
+    const store = new PairingStore({ dir: testDir })
+    const code = store.generateCode('telegram', '111')!
+    store.approveCode('telegram', code)
+    expect(store.revoke('telegram', '111')).toBe(true)
+    expect(store.isApproved('telegram', '111')).toBe(false)
+  })
+
+  it('revoke returns false when user is not approved', () => {
+    const store = new PairingStore({ dir: testDir })
+    expect(store.revoke('telegram', '999')).toBe(false)
+  })
+})
+
+describe('PairingStore file permissions and atomicity', () => {
+  it('writes pending file with 0600 mode on POSIX', () => {
+    const store = new PairingStore({ dir: testDir })
+    store.generateCode('telegram', '111')
+    const path = join(testDir, 'telegram-pending.json')
+    if (process.platform !== 'win32') {
+      const mode = statSync(path).mode & 0o777
+      expect(mode).toBe(0o600)
+    }
+    const raw = JSON.parse(readFileSync(path, 'utf8')) as Record<string, unknown>
+    expect(Object.keys(raw).length).toBe(1)
+  })
+
+  it('atomic writes leave no .tmp residue on success', () => {
+    const store = new PairingStore({ dir: testDir })
+    store.generateCode('telegram', '111')
+    const { readdirSync } = require('node:fs') as typeof import('node:fs')
+    const files = readdirSync(testDir)
+    expect(files.some(f => f.includes('.tmp-'))).toBe(false)
+  })
+})

package/src/pairing.ts

@@ -0,0 +1,285 @@
+// DM pairing system — one-time codes for authorizing new platform users.
+//
+// Ports hermes gateway/pairing.py 1:1 to TypeScript. Operators run
+// `lyra pairing approve telegram <code>` after the bot DMs an unrecognized
+// user a code.
+//
+// Security:
+//  - 8-char codes from 32-char unambiguous alphabet (no 0/O, 1/I)
+//  - crypto-secure randomness via randomInt
+//  - 1-hour code TTL, max 3 pending per platform
+//  - 1 request / user / 10 min rate limit
+//  - 1-hour lockout after 5 failed approvals
+//  - chmod 0600 on all data files (best-effort on non-POSIX)
+//
+// Storage layout under `dir`:
+//   <platform>-pending.json     pending codes
+//   <platform>-approved.json    approved users
+//   _rate_limits.json           rate-limit + lockout tracking
+
+import { randomInt } from 'node:crypto'
+import {
+  chmodSync,
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  readdirSync,
+  renameSync,
+  writeFileSync,
+} from 'node:fs'
+import { join } from 'node:path'
+
+export const PAIRING_ALPHABET = 'ABCDEFGHJKLMNPQRSTUVWXYZ23456789'
+export const PAIRING_CODE_LENGTH = 8
+export const PAIRING_CODE_TTL_SECONDS = 3600
+export const PAIRING_RATE_LIMIT_SECONDS = 600
+export const PAIRING_LOCKOUT_SECONDS = 3600
+export const PAIRING_MAX_PENDING_PER_PLATFORM = 3
+export const PAIRING_MAX_FAILED_ATTEMPTS = 5
+
+export interface PairingStoreOpts {
+  dir: string
+  now?: () => number
+}
+
+export interface PendingEntry {
+  userId: string
+  userName: string
+  createdAt: number
+}
+
+export interface ApprovedEntry {
+  userName: string
+  approvedAt: number
+}
+
+export interface PendingListing {
+  platform: string
+  code: string
+  userId: string
+  userName: string
+  ageMinutes: number
+  createdAt: number
+}
+
+export interface ApprovedListing {
+  platform: string
+  userId: string
+  userName: string
+  approvedAt: number
+}
+
+export interface ApproveResult {
+  userId: string
+  userName: string
+}
+
+export class PairingStore {
+  readonly #dir: string
+  readonly #now: () => number
+
+  constructor(opts: PairingStoreOpts) {
+    this.#dir = opts.dir
+    this.#now = opts.now ?? (() => Date.now() / 1000)
+    mkdirSync(this.#dir, { recursive: true })
+  }
+
+  isApproved(platform: string, userId: string): boolean {
+    const approved = this.#loadJson<Record<string, ApprovedEntry>>(this.#approvedPath(platform))
+    return userId in approved
+  }
+
+  listApproved(platform?: string): ApprovedListing[] {
+    const platforms = platform ? [platform] : this.#allPlatforms('approved')
+    const out: ApprovedListing[] = []
+    for (const p of platforms) {
+      const approved = this.#loadJson<Record<string, ApprovedEntry>>(this.#approvedPath(p))
+      for (const [uid, info] of Object.entries(approved)) {
+        out.push({ platform: p, userId: uid, userName: info.userName, approvedAt: info.approvedAt })
+      }
+    }
+    return out
+  }
+
+  generateCode(platform: string, userId: string, userName = ''): string | null {
+    this.#cleanupExpired(platform)
+    if (this.#isLockedOut(platform)) return null
+    if (this.#isRateLimited(platform, userId)) return null
+    const pending = this.#loadJson<Record<string, PendingEntry>>(this.#pendingPath(platform))
+    if (Object.keys(pending).length >= PAIRING_MAX_PENDING_PER_PLATFORM) return null
+
+    let code = ''
+    for (let i = 0; i < PAIRING_CODE_LENGTH; i++) {
+      code += PAIRING_ALPHABET[randomInt(0, PAIRING_ALPHABET.length)]
+    }
+
+    pending[code] = { userId, userName, createdAt: this.#now() }
+    this.#saveJson(this.#pendingPath(platform), pending)
+    this.#recordRateLimit(platform, userId)
+    return code
+  }
+
+  approveCode(platform: string, code: string): ApproveResult | null {
+    this.#cleanupExpired(platform)
+    const normalized = code.toUpperCase().trim()
+    const pending = this.#loadJson<Record<string, PendingEntry>>(this.#pendingPath(platform))
+    const entry = pending[normalized]
+    if (!entry) {
+      this.#recordFailedAttempt(platform)
+      return null
+    }
+    delete pending[normalized]
+    this.#saveJson(this.#pendingPath(platform), pending)
+
+    const approved = this.#loadJson<Record<string, ApprovedEntry>>(this.#approvedPath(platform))
+    approved[entry.userId] = { userName: entry.userName, approvedAt: this.#now() }
+    this.#saveJson(this.#approvedPath(platform), approved)
+
+    this.#clearFailedAttempts(platform)
+    return { userId: entry.userId, userName: entry.userName }
+  }
+
+  listPending(platform?: string): PendingListing[] {
+    const platforms = platform ? [platform] : this.#allPlatforms('pending')
+    const out: PendingListing[] = []
+    for (const p of platforms) {
+      this.#cleanupExpired(p)
+      const pending = this.#loadJson<Record<string, PendingEntry>>(this.#pendingPath(p))
+      for (const [code, info] of Object.entries(pending)) {
+        const ageMinutes = Math.floor((this.#now() - info.createdAt) / 60)
+        out.push({
+          platform: p,
+          code,
+          userId: info.userId,
+          userName: info.userName,
+          ageMinutes,
+          createdAt: info.createdAt,
+        })
+      }
+    }
+    return out
+  }
+
+  clearPending(platform?: string): number {
+    const platforms = platform ? [platform] : this.#allPlatforms('pending')
+    let count = 0
+    for (const p of platforms) {
+      const pending = this.#loadJson<Record<string, PendingEntry>>(this.#pendingPath(p))
+      count += Object.keys(pending).length
+      this.#saveJson(this.#pendingPath(p), {})
+    }
+    return count
+  }
+
+  revoke(platform: string, userId: string): boolean {
+    const path = this.#approvedPath(platform)
+    const approved = this.#loadJson<Record<string, ApprovedEntry>>(path)
+    if (!(userId in approved)) return false
+    delete approved[userId]
+    this.#saveJson(path, approved)
+    return true
+  }
+
+  isLockedOut(platform: string): boolean {
+    return this.#isLockedOut(platform)
+  }
+
+  // ----- private helpers -----
+
+  #pendingPath(platform: string): string {
+    return join(this.#dir, `${platform}-pending.json`)
+  }
+  #approvedPath(platform: string): string {
+    return join(this.#dir, `${platform}-approved.json`)
+  }
+  #rateLimitPath(): string {
+    return join(this.#dir, '_rate_limits.json')
+  }
+
+  #loadJson<T>(path: string): T {
+    if (!existsSync(path)) return {} as T
+    try {
+      return JSON.parse(readFileSync(path, 'utf8')) as T
+    } catch {
+      return {} as T
+    }
+  }
+
+  #saveJson(path: string, data: unknown): void {
+    const tmp = `${path}.tmp-${process.pid}-${Date.now().toString(36)}`
+    writeFileSync(tmp, JSON.stringify(data, null, 2), 'utf8')
+    renameSync(tmp, path)
+    try {
+      chmodSync(path, 0o600)
+    } catch {
+      // non-POSIX; permissions are advisory only
+    }
+  }
+
+  #cleanupExpired(platform: string): void {
+    const path = this.#pendingPath(platform)
+    if (!existsSync(path)) return
+    const pending = this.#loadJson<Record<string, PendingEntry>>(path)
+    const now = this.#now()
+    let changed = false
+    for (const [code, info] of Object.entries(pending)) {
+      if (now - info.createdAt > PAIRING_CODE_TTL_SECONDS) {
+        delete pending[code]
+        changed = true
+      }
+    }
+    if (changed) this.#saveJson(path, pending)
+  }
+
+  #isRateLimited(platform: string, userId: string): boolean {
+    const limits = this.#loadJson<Record<string, number>>(this.#rateLimitPath())
+    const last = limits[`${platform}:${userId}`] ?? 0
+    return this.#now() - last < PAIRING_RATE_LIMIT_SECONDS
+  }
+
+  #recordRateLimit(platform: string, userId: string): void {
+    const limits = this.#loadJson<Record<string, number>>(this.#rateLimitPath())
+    limits[`${platform}:${userId}`] = this.#now()
+    this.#saveJson(this.#rateLimitPath(), limits)
+  }
+
+  #isLockedOut(platform: string): boolean {
+    const limits = this.#loadJson<Record<string, number>>(this.#rateLimitPath())
+    const lockoutUntil = limits[`_lockout:${platform}`] ?? 0
+    return this.#now() < lockoutUntil
+  }
+
+  #recordFailedAttempt(platform: string): void {
+    const limits = this.#loadJson<Record<string, number>>(this.#rateLimitPath())
+    const failKey = `_failures:${platform}`
+    const fails = (limits[failKey] ?? 0) + 1
+    limits[failKey] = fails
+    if (fails >= PAIRING_MAX_FAILED_ATTEMPTS) {
+      limits[`_lockout:${platform}`] = this.#now() + PAIRING_LOCKOUT_SECONDS
+      limits[failKey] = 0
+    }
+    this.#saveJson(this.#rateLimitPath(), limits)
+  }
+
+  #clearFailedAttempts(platform: string): void {
+    const limits = this.#loadJson<Record<string, number>>(this.#rateLimitPath())
+    if (`_failures:${platform}` in limits) {
+      delete limits[`_failures:${platform}`]
+      this.#saveJson(this.#rateLimitPath(), limits)
+    }
+  }
+
+  #allPlatforms(suffix: 'pending' | 'approved'): string[] {
+    if (!existsSync(this.#dir)) return []
+    const entries = readdirSync(this.#dir)
+    const tail = `-${suffix}.json`
+    const platforms = new Set<string>()
+    for (const f of entries) {
+      if (f.endsWith(tail)) {
+        const p = f.slice(0, -tail.length)
+        if (!p.startsWith('_')) platforms.add(p)
+      }
+    }
+    return Array.from(platforms)
+  }
+}

package/src/paths.ts

@@ -0,0 +1,70 @@
+import { homedir } from 'node:os'
+import { join } from 'node:path'
+
+/** Resolve `~/.lyra` at call time so tests can override via LYRA_ROOT or HOME. */
+function lyraRoot(): string {
+  return process.env.LYRA_ROOT ?? join(homedir(), '.lyra')
+}
+
+export interface AgentPaths {
+  readonly root: string
+  readonly config: string
+  readonly skills: string
+  readonly plugins: string
+  readonly agentsDir: string
+  agent(id: string): {
+    dir: string
+    keystore: string
+    cache: string
+    memoryDir: string
+    memoryIndex: string
+    agentMemoryDir: string
+    userMemoryDir: string
+    publicDir: string
+    activityLog: string
+    runtimeState: string
+    inboxDir: string
+    pairingDir: string
+  }
+}
+
+export const agentPaths: AgentPaths = {
+  get root() {
+    return lyraRoot()
+  },
+  get config() {
+    return join(lyraRoot(), 'config.ts')
+  },
+  get skills() {
+    return join(lyraRoot(), 'skills')
+  },
+  get plugins() {
+    return join(lyraRoot(), 'plugins')
+  },
+  get agentsDir() {
+    return join(lyraRoot(), 'agents')
+  },
+  agent(id: string) {
+    const dir = join(lyraRoot(), 'agents', id)
+    return {
+      dir,
+      keystore: join(dir, 'keystore.json'),
+      cache: join(dir, 'cache'),
+      memoryDir: join(dir, 'memory'),
+      memoryIndex: join(dir, 'memory', 'MEMORY.md'),
+      agentMemoryDir: join(dir, 'memory', 'agent'),
+      userMemoryDir: join(dir, 'memory', 'user'),
+      publicDir: join(dir, 'memory', 'public'),
+      activityLog: join(dir, 'activity.jsonl'),
+      runtimeState: join(dir, 'runtime', 'state.json'),
+      inboxDir: join(dir, 'inbox'),
+      pairingDir: join(dir, 'pairing'),
+    }
+  },
+}
+
+/** Compute the deterministic agent id from a wallet address. Stable pre-iNFT. */
+export function placeholderAgentId(walletAddress: string): string {
+  const clean = walletAddress.toLowerCase().replace(/^0x/, '')
+  return clean.slice(0, 16)
+}

package/src/permission/dangerous.ts

@@ -0,0 +1,105 @@
+/**
+ * Dangerous command pattern set ported from hermes-agent/tools/approval.py.
+ * Pattern matching is the cheap pre-LLM safety floor for `shell.run` and
+ * destructive shell-equivalent tool args. Brain still needs explicit approval
+ * for matches in `prompt` mode, but YOLO mode (`approvals.mode = "off"`) skips.
+ *
+ * Patterns adapted to JS regex flavor (no \b on hex/utf, no DOTALL by default).
+ * Each entry returns the human description used in approval prompts.
+ */
+
+const SENSITIVE_WRITE_TARGETS =
+  '/etc/[a-z]|/etc/passwd|/etc/shadow|/etc/sudoers|/boot/|/usr/local/etc/'
+
+export const DANGEROUS_PATTERNS: ReadonlyArray<readonly [RegExp, string]> = [
+  [/\brm\s+(-[^\s]*\s+)*\//, 'delete in root path'],
+  [/\brm\s+-[^\s]*r/, 'recursive delete'],
+  [/\brm\s+--recursive\b/, 'recursive delete (long flag)'],
+  [/\bchmod\s+(-[^\s]*\s+)*(777|666|o\+[rwx]*w|a\+[rwx]*w)\b/, 'world/other-writable permissions'],
+  [/\bchown\s+(-[^\s]*)?R\s+root/, 'recursive chown to root'],
+  [/\bmkfs\b/, 'format filesystem'],
+  [/\bdd\s+.*if=/, 'disk copy'],
+  [/>\s*\/dev\/sd/, 'write to block device'],
+  [/\bDROP\s+(TABLE|DATABASE)\b/i, 'SQL DROP'],
+  [/\bDELETE\s+FROM\b(?!.*\bWHERE\b)/i, 'SQL DELETE without WHERE'],
+  [/\bTRUNCATE\s+(TABLE)?\s*\w/i, 'SQL TRUNCATE'],
+  [/>\s*\/etc\//, 'overwrite system config'],
+  [/\bsystemctl\s+(stop|disable|mask)\b/, 'stop/disable system service'],
+  [/\bkill\s+-9\s+-1\b/, 'kill all processes'],
+  [/\bpkill\s+-9\b/, 'force kill processes'],
+  [/:\(\)\s*\{\s*:\s*\|\s*:\s*&\s*\}\s*;\s*:/, 'fork bomb'],
+  [/\b(bash|sh|zsh|ksh)\s+-[^\s]*c(\s+|$)/, 'shell command via -c/-lc flag'],
+  [/\b(python[23]?|perl|ruby|node)\s+-[ec]\s+/, 'script execution via -e/-c flag'],
+  [/\b(curl|wget)\b.*\|\s*(ba)?sh\b/, 'pipe remote content to shell'],
+  [
+    /\b(bash|sh|zsh|ksh)\s+<\s*<?\s*\(\s*(curl|wget)\b/,
+    'execute remote script via process substitution',
+  ],
+  [new RegExp(`\\btee\\b.*["']?(${SENSITIVE_WRITE_TARGETS})`), 'overwrite system file via tee'],
+  [new RegExp(`>>?\\s*["']?(${SENSITIVE_WRITE_TARGETS})`), 'overwrite system file via redirection'],
+  [/\bxargs\s+.*\brm\b/, 'xargs with rm'],
+  [/\bfind\b.*-exec\s+(\/\S*\/)?rm\b/, 'find -exec rm'],
+  [/\bfind\b.*-delete\b/, 'find -delete'],
+  // Self-termination protection
+  [/\b(pkill|killall)\b.*\b(lyra|cli\.ts|lyra\/bin)\b/, 'kill lyra process (self-termination)'],
+  [/\bkill\b.*\$\(\s*pgrep\b/, 'kill process via pgrep expansion (self-termination)'],
+  [/\bkill\b.*`\s*pgrep\b/, 'kill process via backtick pgrep expansion (self-termination)'],
+  [/\b(cp|mv|install)\b.*\s\/etc\//, 'copy/move file into /etc/'],
+  [/\bsed\s+-[^\s]*i.*\s\/etc\//, 'in-place edit of system config'],
+  [/\bsed\s+--in-place\b.*\s\/etc\//, 'in-place edit of system config (long flag)'],
+  [/\b(python[23]?|perl|ruby|node)\s+<</, 'script execution via heredoc'],
+  [/\bgit\s+reset\s+--hard\b/, 'git reset --hard (destroys uncommitted changes)'],
+  [/\bgit\s+push\b.*--force\b/, 'git force push (rewrites remote history)'],
+  [/\bgit\s+push\b.*\s-f\b/, 'git force push short flag (rewrites remote history)'],
+  [/\bgit\s+clean\s+-[^\s]*f/, 'git clean with force (deletes untracked files)'],
+  [/\bgit\s+branch\s+-D\b/, 'git branch force delete'],
+  [/\bchmod\s+\+x\b.*[;&|]+\s*\.\//, 'chmod +x followed by immediate execution'],
+] as const
+
+export interface DangerousMatch {
+  match: true
+  key: string
+  description: string
+}
+
+export interface NoMatch {
+  match: false
+}
+
+/**
+ * Pre-compiled case-insensitive twin of every pattern. `detectDangerousCommand`
+ * runs on the hot path of every shell.run; building 35 RegExp objects per call
+ * was visible in profiles. Compile once at module load, reuse forever.
+ */
+const COMPILED_PATTERNS: ReadonlyArray<readonly [RegExp, string]> = DANGEROUS_PATTERNS.map(
+  ([pattern, description]) =>
+    [
+      pattern.flags.includes('i') ? pattern : new RegExp(pattern.source, `${pattern.flags}i`),
+      description,
+    ] as const,
+)
+
+/**
+ * Normalize a command before pattern matching: strip ANSI sequences, NULs,
+ * and Unicode lookalikes (NFKC). Mirrors hermes' defense-in-depth so
+ * obfuscation tricks don't bypass detection. The patterns below intentionally
+ * include the control characters they detect, hence the noControlCharactersInRegex
+ * suppressions.
+ */
+function normalize(command: string): string {
+  // biome-ignore lint/suspicious/noControlCharactersInRegex: intentional ANSI matcher
+  const ansi = /\x1B(?:[@-Z\\-_]|\[[0-?]*[ -/]*[@-~]|\][^\x07]*(?:\x07|\x1B\\)|P[^\x1B]*\x1B\\)/g
+  let s = command.replace(ansi, '')
+  // biome-ignore lint/suspicious/noControlCharactersInRegex: intentional NUL stripping
+  s = s.replace(/\x00/g, '')
+  s = s.normalize('NFKC')
+  return s
+}
+
+export function detectDangerousCommand(command: string): DangerousMatch | NoMatch {
+  const norm = normalize(command).toLowerCase()
+  for (const [re, description] of COMPILED_PATTERNS) {
+    if (re.test(norm)) return { match: true, key: description, description }
+  }
+  return { match: false }
+}