elanous 0.2.37 → 0.2.40

package/src/intake-plane/intake-to-tasks.ts

@@ -1,5 +1,5 @@
 import { createHash, randomUUID } from 'node:crypto';
-import { appendFileSync, existsSync, mkdirSync, readFileSync, readdirSync, renameSync, writeFileSync } from 'node:fs';
+import { appendFileSync, closeSync, existsSync, mkdirSync, openSync, readFileSync, readdirSync, renameSync, rmSync, writeFileSync } from 'node:fs';
 import { isAbsolute, join } from 'node:path';
 import { debug } from '../debug/log.js';
 import type { TaskPriority } from '../task-orchestrator/types.js';
@@ -71,15 +71,187 @@ export function interpretIntakeInput(response: string): IntakeInputInterpretatio
   return { tasks, questions };
 }
 
+export const CHANNEL_PUBLISH_APPROVAL_CATEGORIES = ['first-release', 'patent', 'external-contract'] as const;
+export const CHANNEL_PUBLISH_CROWN_OWNER = '\u{1F451}';
+export type ChannelPublishApprovalCategory = (typeof CHANNEL_PUBLISH_APPROVAL_CATEGORIES)[number];
+export type ChannelPublishStatus = 'queued' | 'approved' | 'published';
+type ChannelPublishApproval = { kind: 'automatic' } | { kind: 'human'; approvedBy: string };
+
+export interface ChannelPublishDraft {
+  channel: string;
+  cadence: string;
+  voice: string;
+  owner: string;
+  category: ChannelPublishApprovalCategory | (string & {});
+  title: string;
+  body: string;
+}
+
+export interface ChannelPublishPlan extends ChannelPublishDraft {
+  status: ChannelPublishStatus;
+  approvedBy?: string;
+}
+
+export interface ChannelPublishConnector {
+  publish(plan: ChannelPublishPlan): Promise<{ publishedId: string }>;
+}
+
+// MK·crown 소유자의 첫 공개·특허·외부 계약 초안은 사람 승인 전 자동 승인하지 않는다.
+export function isChannelPublishApprovable(draft: ChannelPublishDraft): boolean {
+  if (draft.owner !== 'MK' && draft.owner !== CHANNEL_PUBLISH_CROWN_OWNER) return true;
+  return !(CHANNEL_PUBLISH_APPROVAL_CATEGORIES as readonly string[]).includes(draft.category);
+}
+
+export function toChannelPublishDraft(row: Record<string, unknown>): ChannelPublishDraft | null {
+  const text = (key: string, max: number): string | null => {
+    const value = row[key];
+    if (typeof value !== 'string') return null;
+    const trimmed = value.trim();
+    return trimmed && trimmed.length <= max ? trimmed : null;
+  };
+  const channel = text('channel', 200);
+  const cadence = text('cadence', 200);
+  const voice = text('voice', 200);
+  const owner = text('owner', 200);
+  const category = text('category', 200);
+  const title = text('title', TASK_DEFAULTS.titleMaxLen);
+  const body = text('body', TASK_DEFAULTS.descriptionMaxLen);
+  if (!channel || !cadence || !voice || !owner || !category || !title || !body) return null;
+  return { channel, cadence, voice, owner, category, title, body };
+}
+
+function isChannelPublishPlan(value: unknown): value is ChannelPublishPlan {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return false;
+  const plan = value as Record<string, unknown>;
+  return toChannelPublishDraft(plan) !== null
+    && (plan.status === 'queued' || plan.status === 'approved' || plan.status === 'published')
+    && (plan.approvedBy === undefined || typeof plan.approvedBy === 'string');
+}
+
+export class ChannelPublishQueue {
+  readonly queueDir: string;
+  readonly publishedFile: string;
+
+  constructor(instanceRoot: string) {
+    this.queueDir = join(intakeLedgerDir(instanceRoot), 'channel-publish', 'queue');
+    this.publishedFile = join(intakeLedgerDir(instanceRoot), 'channel-publish', 'published.jsonl');
+    mkdirSync(this.queueDir, { recursive: true, mode: 0o700 });
+  }
+
+  entryPath(id: string): string {
+    return join(this.queueDir, `${createHash('sha256').update(`channel:${id}`).digest('hex')}.json`);
+  }
+
+  tryAcquirePublish(id: string): (() => void) | null {
+    const path = `${this.entryPath(id)}.publishing`;
+    const token = randomUUID();
+    // Do not auto-steal stale locks: a takeover race could duplicate an irreversible external post.
+    // If a process dies mid-publish, reconcile the approved queue entry and lock explicitly.
+    let fd: number;
+    try {
+      fd = openSync(path, 'wx', 0o600);
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code === 'EEXIST') return null;
+      throw error;
+    }
+    try { writeFileSync(fd, token); }
+    catch (error) { rmSync(path, { force: true }); throw error; }
+    finally { closeSync(fd); }
+    return () => {
+      // Never let a late releaser remove a lock created by another publisher.
+      try {
+        if (readFileSync(path, 'utf8') === token) rmSync(path);
+      } catch { /* The lock is already gone; leave a replacement untouched. */ }
+    };
+  }
+
+  plan(id: string): ChannelPublishPlan | null {
+    const path = this.entryPath(id);
+    if (!existsSync(path)) return null;
+    const value: unknown = JSON.parse(readFileSync(path, 'utf8'));
+    if (!isChannelPublishPlan(value)) throw new Error('invalid channel publish plan');
+    return value;
+  }
+
+  entries(): ChannelPublishPlan[] {
+    return readdirSync(this.queueDir).filter((name) => /^[a-f0-9]{64}\.json$/.test(name))
+      .map((name) => {
+        const value: unknown = JSON.parse(readFileSync(join(this.queueDir, name), 'utf8'));
+        if (!isChannelPublishPlan(value)) throw new Error('invalid channel publish plan');
+        return value;
+      });
+  }
+
+  count(): number { return this.entries().length; }
+
+  publishedIds(): Set<string> {
+    if (!existsSync(this.publishedFile)) return new Set();
+    const ids = new Set<string>();
+    for (const line of readFileSync(this.publishedFile, 'utf8').split('\n')) {
+      try {
+        const row: unknown = JSON.parse(line);
+        if (row && typeof row === 'object' && !Array.isArray(row) && typeof (row as Record<string, unknown>).id === 'string') {
+          ids.add((row as { id: string }).id);
+        }
+      } catch { /* ignore incomplete ledger lines */ }
+    }
+    return ids;
+  }
+
+  enqueue(id: string, draft: ChannelPublishDraft): ChannelPublishPlan {
+    if (this.publishedIds().has(id)) return { ...draft, status: 'published' };
+    const existing = this.plan(id);
+    if (existing) return existing;
+    const plan: ChannelPublishPlan = { ...draft, status: 'queued' };
+    this.savePlan(id, plan);
+    return plan;
+  }
+
+  approve(id: string, plan: ChannelPublishPlan, approval: ChannelPublishApproval): ChannelPublishPlan {
+    if (plan.status !== 'queued') return plan;
+    if (!isChannelPublishApprovable(plan) && approval.kind !== 'human') return plan;
+    if (approval.kind === 'human' && approval.approvedBy !== 'MK' && approval.approvedBy !== CHANNEL_PUBLISH_CROWN_OWNER) return plan;
+    const approvedBy = approval.kind === 'human' ? approval.approvedBy : 'automation';
+    const approved: ChannelPublishPlan = { ...plan, status: 'approved', approvedBy };
+    this.savePlan(id, approved);
+    return approved;
+  }
+
+  savePlan(id: string, plan: ChannelPublishPlan): void {
+    const path = this.entryPath(id);
+    const temporary = `${path}.${randomUUID()}.tmp`;
+    writeFileSync(temporary, JSON.stringify(plan));
+    renameSync(temporary, path);
+  }
+
+  recordPublished(id: string, plan: ChannelPublishPlan, publishedId: string): void {
+    // Ledger first, then remove the plan: a crash between the connector call and this append may
+    // republish (at-least-once), matching the HookQueue queue-file/seen ordering across restarts.
+    appendFileSync(this.publishedFile, JSON.stringify({ id, channel: plan.channel, publishedId }) + '\n');
+    rmSync(this.entryPath(id), { force: true });
+  }
+}
+
+/** Explicit approval entry point for a human-controlled API, CLI, or UI action. */
+export function approveChannelPublish(instanceRoot: string, id: string, approvedBy: string): ChannelPublishPlan | null {
+  const queue = new ChannelPublishQueue(instanceRoot);
+  const plan = queue.plan(id);
+  if (!plan || plan.status !== 'queued' || isChannelPublishApprovable(plan)
+    || (approvedBy !== 'MK' && approvedBy !== CHANNEL_PUBLISH_CROWN_OWNER)) return null;
+  return queue.approve(id, plan, { kind: 'human', approvedBy });
+}
+
 export type IntakeTaskInput =
   | { kind: 'goal-line'; id: string; fact: string; current: string; url?: string }
-  | { kind: 'idea-note'; id: string; content: string; url?: string };
+  | { kind: 'idea-note'; id: string; content: string; url?: string }
+  | { kind: 'channel-post'; id: string; draft: ChannelPublishDraft | null };
 
 export interface IntakeToTasksDeps {
   llm: (input: IntakeTaskInput) => Promise<string>;
   post: (request: IntakeTaskRequest) => Promise<{ taskId: string; deduplicated?: boolean }>;
   list?: typeof listIntakeItems;
   readNote?: (path: string) => string;
+  connector?: ChannelPublishConnector;
 }
 
 export interface IntakeToTasksResult {
@@ -87,7 +259,19 @@ export interface IntakeToTasksResult {
   created: number;
   skipped: number;
   failed: number;
-  items: Array<{ id: string; status: 'created' | 'deduplicated' | 'dry-run' | 'skipped' | 'failed'; taskId?: string; types?: IntakeTaskType[]; reason?: string }>;
+  items: Array<{
+    id: string;
+    status: 'created' | 'deduplicated' | 'dry-run' | 'skipped' | 'failed' | 'queued' | 'approved' | 'published';
+    taskId?: string;
+    types?: IntakeTaskType[];
+    reason?: string;
+    channel?: string;
+    cadence?: string;
+    voice?: string;
+    owner?: string;
+    category?: string;
+    publishedId?: string;
+  }>;
 }
 
 export function interpretIntakeItem(response: string): IntakeTaskInterpretation | null {
@@ -180,6 +364,10 @@ function goalLines(root: string): IntakeTaskInput[] {
         const value: unknown = JSON.parse(line);
         if (!value || typeof value !== 'object' || Array.isArray(value)) return;
         const row = value as Record<string, unknown>;
+        if (row.kind === 'channel-post') {
+          rows.push({ kind: 'channel-post', id: goalLineId(file, index), draft: toChannelPublishDraft(row) });
+          return;
+        }
         if (typeof row.fact !== 'string' || !row.fact.trim()) return;
         rows.push({ kind: 'goal-line', id: goalLineId(file, index), fact: row.fact, current: typeof row.current === 'string' ? row.current : '',
           ...(typeof row.url === 'string' ? { url: row.url } : {}) });
@@ -240,6 +428,61 @@ export async function runIntakeToTasks(
     .filter(({ input }) => !consumed.has(input.id)).slice(0, limit);
   const result: IntakeToTasksResult = { processed: selected.length, created: 0, skipped: 0, failed: 0, items: [] };
   for (const { input, path } of selected) {
+    if (input.kind === 'channel-post') {
+      if (opts.dryRun) {
+        result.items.push({ id: input.id, status: 'dry-run' });
+        continue;
+      }
+      if (!input.draft) {
+        result.skipped++;
+        result.items.push({ id: input.id, status: 'skipped', reason: 'invalid-channel-post-draft' });
+        continue;
+      }
+      const queue = new ChannelPublishQueue(instanceRoot);
+      try {
+        const queued = queue.enqueue(input.id, input.draft);
+        const plan = isChannelPublishApprovable(queued) ? queue.approve(input.id, queued, { kind: 'automatic' }) : queued;
+        if (plan.status === 'published') {
+          // Crash between the publish ledger and the consumed ledger: the post is already out.
+          appendFileSync(consumedFile(instanceRoot), JSON.stringify({ id: input.id }) + '\n');
+          result.items.push({ id: input.id, status: 'published', channel: plan.channel, cadence: plan.cadence, voice: plan.voice });
+          continue;
+        }
+        if (plan.status === 'approved' && deps.connector) {
+          const release = queue.tryAcquirePublish(input.id);
+          if (release) {
+            try {
+              // Recheck under the per-item lock; another process may have completed before it was acquired.
+              const current = queue.plan(input.id);
+              if (current?.status === 'approved' && !queue.publishedIds().has(input.id)) {
+                const { publishedId } = await deps.connector.publish(current);
+                queue.recordPublished(input.id, current, publishedId);
+                appendFileSync(consumedFile(instanceRoot), JSON.stringify({ id: input.id, publishedId }) + '\n');
+                result.items.push({
+                  id: input.id, status: 'published', channel: current.channel, cadence: current.cadence,
+                  voice: current.voice, owner: current.owner, category: current.category, publishedId,
+                });
+                continue;
+              }
+              if (queue.publishedIds().has(input.id)) {
+                appendFileSync(consumedFile(instanceRoot), JSON.stringify({ id: input.id }) + '\n');
+                result.items.push({ id: input.id, status: 'published', channel: plan.channel, cadence: plan.cadence, voice: plan.voice });
+                continue;
+              }
+            } finally { release(); }
+          }
+          // Another process owns the publish attempt. Leave this item approved for its next pass.
+          result.items.push({ id: input.id, status: 'approved', channel: plan.channel, cadence: plan.cadence, voice: plan.voice });
+          continue;
+        }
+        result.items.push({ id: input.id, status: plan.status, channel: plan.channel, cadence: plan.cadence, voice: plan.voice });
+      } catch {
+        result.failed++;
+        result.items.push({ id: input.id, status: 'failed', reason: 'channel publish failed' });
+        debug.log('intake.to-tasks', 'channel-publish-failed', { id: input.id });
+      }
+      continue;
+    }
     try {
       let plan = loadTaskPlan(instanceRoot, input.id);
       if (!plan) {

package/src/interactive-terminal-modal.ts

@@ -55,6 +55,8 @@ export interface InteractiveTerminalModalSpec {
    *  of a plain local shell. Empty default keeps the legacy behaviour. */
   shellArgs?: readonly string[];
   env?: Record<string, string>;
+  /** Remove captured login-shell environment keys after composition. */
+  unsetEnv?: readonly string[];
   /** Ghostty-compatible terminfo name. Defaults via PreviewTerminal
    *  to xterm-256color. */
   termName?: string;
@@ -212,6 +214,7 @@ export function createInteractiveTerminalModal(
     shell: spec.shell,
     shellArgs: spec.shellArgs,
     env: spec.env,
+    unsetEnv: spec.unsetEnv,
     termName: spec.termName,
     useRegistry: spec.useRegistry,
     registryKind: spec.registryKind,

package/src/keybindings.ts

@@ -54,32 +54,27 @@ export const KEYBINDINGS: KeyBinding[] = [
   { keys: ['Ctrl+K', 'Ctrl+ㅏ'],   action: 'Open SSH remote picker',         context: 'global', note: 'FU-1 — registerKeyBinding({handler})' },
   { keys: ['Ctrl+P', 'Ctrl+ㅔ'],   action: 'Open finder (file picker)',      context: 'global', note: 'FU-1 — registerKeyBinding({handler})' },
   { keys: ['Ctrl+M', 'Ctrl+ㅡ'],   action: 'Arm pane-modal chord (1 s window; next letter opens deferred pane)', context: 'global', note: 'FU-1 — coordinator chord, SHORTCUT_TABLE' },
-  { keys: ['Ctrl+B', 'Ctrl+ㅠ'],   action: 'Arm virtual-window chord (1 s window; see §14)', context: 'global', note: 'FU-2 — coordinator chord' },
-  { keys: ['Ctrl+B w'],            action: 'Focus working-dir browser',      context: 'global', note: 'tmux-style prefix chord' },
-  { keys: ['Ctrl+B o'],            action: 'Focus Obsidian browser',         context: 'global' },
-  { keys: ['Ctrl+B s'],            action: 'Reopen scratchpad (pane-browse) · Enter sync mode (chat input) — A3',  context: 'global', note: 'input-focus route added P5 / unified in C1' },
-  { keys: ['Ctrl+B g'],            action: 'Exit sync/control mode → general (chat input)',                       context: 'global', note: 'P5 input-focus only' },
-  { keys: ['Ctrl+B S'],            action: 'Focus sessions sidebar',         context: 'global', note: 'ST4 — jumps focus to the leadColumn session list' },
-  { keys: ['Ctrl+B n'],            action: 'Next VW / advance to next session + focus sidebar', context: 'global', note: 'ST4 + VW chord — context gated' },
-  { keys: ['Ctrl+B p'],            action: 'Prev VW / retreat to previous session + focus sidebar', context: 'global', note: 'ST4 + VW chord — context gated' },
-  { keys: ['Ctrl+B 0'],            action: 'Open window picker (VW chord)',  context: 'global', note: 'FU-2' },
-  { keys: ['Ctrl+B 1'],            action: 'Switch to VW 1 (Ctrl+1 also works)', context: 'global', note: 'FU-2 — also 2..9' },
-  { keys: ['Ctrl+B c'],            action: 'New virtual window — terminal (pane-browse) · Enter control mode (chat input)', context: 'global', note: 'FU-2 + P5 input-focus chord overlay' },
-  { keys: ['Ctrl+B t'],            action: 'Toggle modal ↔ virtual-window session', context: 'global', note: 'FU-2' },
-  { keys: ['Ctrl+B x'],            action: 'Close focused pane (VW chord)',  context: 'global', note: 'FU-2' },
-  { keys: ['Ctrl+B Shift+X'],      action: 'Close whole window (VW chord)',  context: 'global', note: 'FU-2 — Shift+X dispatch fixed' },
-  { keys: ['Ctrl+B %', 'Ctrl+B s'], action: 'Horizontal split',              context: 'global', note: 'FU-2' },
-  { keys: ['Ctrl+B "', 'Ctrl+B v'], action: 'Vertical split',                context: 'global', note: 'FU-2' },
-  { keys: ['Ctrl+B ?'],            action: 'Open VW chord help popup (transient modal, 8 s)', context: 'global', note: 'FU-2 — upgraded from chatLines' },
-  { keys: ['Ctrl+B z'],            action: 'Toggle zoom on focused pane (fullscreen within VW)', context: 'global', note: 'VW-U5' },
-  { keys: ['Ctrl+B Tab'],          action: 'Focus last pane (alt-tab within VW)',             context: 'global', note: 'VW-U5' },
-  { keys: ['Ctrl+B R'],            action: 'Rename foreground window (input modal)',          context: 'global', note: 'VW-B1 — tmux `,` 는 prev 이라 R 사용' },
-  { keys: ['Ctrl+B A'],            action: 'Rename focused pane (VW-local override, empty clears)', context: 'global', note: 'VW-B2' },
+  { keys: ['Ctrl+B'],             action: 'Background running child tasks (while streaming; turn continues)', context: 'global' },
+  { keys: ['Ctrl+X', 'Ctrl+ㅌ'],   action: 'Arm dashboard pane chord (1 s window)', context: 'pane' },
+  { keys: ['Ctrl+X Ctrl+W'],       action: 'Focus working-dir browser',      context: 'global', note: 'pane-browse chord' },
+  { keys: ['Ctrl+X Ctrl+O'],       action: 'Focus Obsidian browser',         context: 'global', note: 'pane-browse chord' },
+  { keys: ['Ctrl+X Ctrl+S'],       action: 'Reopen scratchpad (pane-browse)', context: 'global' },
+  { keys: ['Ctrl+X s'],            action: 'Enter sync mode (chat input)',   context: 'input' },
+  { keys: ['Ctrl+X g'],            action: 'Exit sync/control mode → general (chat input)', context: 'input' },
+  { keys: ['Ctrl+X S'],            action: 'Focus sessions sidebar',        context: 'pane' },
+  { keys: ['Ctrl+X n'],            action: 'Advance to next session + focus sidebar', context: 'pane' },
+  { keys: ['Ctrl+X p'],            action: 'Retreat to previous session + focus sidebar', context: 'pane' },
+  { keys: ['Ctrl+X c'],            action: 'Enter control mode (chat input)', context: 'input' },
+  { keys: ['Ctrl+X x'],            action: 'Close focused pane',             context: 'pane' },
+  { keys: ['Ctrl+X z'],            action: 'Toggle log zoom',               context: 'pane' },
+  { keys: ['Ctrl+X t'],            action: 'Open preview terminal',          context: 'pane' },
+  { keys: ['Ctrl+X e'],            action: 'Toggle preview terminal expansion', context: 'pane' },
+  { keys: ['Ctrl+X f'],            action: 'Toggle all log folds',          context: 'pane' },
   { keys: ['Alt+N', 'Alt+ㅜ'],     action: 'Next virtual window (fast-switch, no chord)',       context: 'global', note: 'VW-U2 — guarded by list().length>1' },
   { keys: ['Alt+P', 'Alt+ㅔ'],     action: 'Prev virtual window (fast-switch, no chord)',       context: 'global', note: 'VW-U2' },
   { keys: ['Alt+1..9'],            action: 'Switch directly to Nth virtual window',             context: 'global', note: 'VW-U2 — guarded by list().length>1' },
   { keys: ['Alt+0'],               action: 'Open window picker (fast, no chord)',               context: 'global', note: 'VW-U2' },
-  { keys: ['Ctrl+B b'],            action: 'Toggle notification bell modal',  context: 'global', note: 'NT5 — open/close bell modal with unread + error filter' },
+  { keys: ['Ctrl+X b'],            action: 'Toggle notification bell modal',  context: 'pane', note: 'NT5 — open/close bell modal with unread + error filter' },
   { keys: ['Ctrl+Shift+V', 'Ctrl+Shift+ㅍ'], action: 'Enter Voice mode (Space hold push-to-talk · Esc to exit)', context: 'global', note: 'PR-S1V.4 — voice-input-host · kitty >3u on entry · brand prefix routing' },
   { keys: ['Alt+S', 'Alt+ㄴ'], action: 'Toggle continuous voice-chat mode (real-time STT + auto-TTS · ESC or chord again to exit)', context: 'global', note: '2026-05-03 — moved from Alt+R to free R for reasoning cycle (V/D/R mnemonic)' },
   { keys: ['Alt+R', 'Alt+ㄱ'], action: 'Cycle reasoning level (off → low → medium → high → xhigh). Codex / Claude reasoning models only — no-op on grok/gemini', context: 'global', note: '2026-05-03 — provider-agnostic ReasoningLevel cycle, same effect as `/reasoning` slash. V/D/R mnemonic: V=voice control (Ctrl+Shift+V), D=batch dictation (Space-longpress), R=reasoning' },

package/src/lessons/friction-ledger.ts

@@ -0,0 +1,154 @@
+import { Database } from 'bun:sqlite';
+import { chmodSync, mkdirSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { elanousStateRoot } from '../autopilot/state-paths.js';
+import { debug } from '../debug/log.js';
+import type { LessonLedgerOptions } from './lesson-ledger.js';
+
+export type FrictionActor = 'OP' | 'TC' | 'MK' | 'UX' | 'ceo' | 'person';
+export type FrictionKind = 'hand-step' | 'ceo-correction' | 'repeat-question';
+
+export const FRICTION_ACTORS: readonly FrictionActor[] = ['OP', 'TC', 'MK', 'UX', 'ceo', 'person'];
+export const FRICTION_KINDS: readonly FrictionKind[] = ['hand-step', 'ceo-correction', 'repeat-question'];
+export const FRICTION_CANDIDATE_MIN = 3;
+
+export interface FrictionRecordInput {
+  actor: FrictionActor;
+  kind: FrictionKind;
+  signature: string;
+  note?: string;
+  ref: string;
+}
+
+export interface FrictionRow {
+  id: number;
+  actor: FrictionActor;
+  kind: FrictionKind;
+  signature: string;
+  note: string;
+  ref: string;
+  recorded_at: string;
+}
+
+export interface FrictionCandidate {
+  kind: FrictionKind;
+  signature: string;
+  count: number;
+  firstAt: string;
+  lastAt: string;
+  refs: string[];
+}
+
+export class FrictionInputError extends Error {
+  override name = 'FrictionInputError';
+}
+
+/** Secret-shaped note bodies are never persisted: a token or key would be copied into the ledger. */
+const SECRET_PATTERNS: readonly RegExp[] = [
+  /sk-[A-Za-z0-9_-]{8,}/u,
+  /(?:ghp|gho|ghu|ghs|ghr)_[A-Za-z0-9]{8,}/u,
+  /AKIA[0-9A-Z]{12,}/u,
+  /xox[bapr]-[A-Za-z0-9-]{8,}/u,
+  /-----BEGIN [A-Z ]*PRIVATE KEY-----/u,
+  /\b[0-9a-f]{32,}\b/u,
+  /\b[A-Za-z0-9+/=_-]{40,}\b/u,
+  /(?:api[_-]?key|access[_-]?key|token|secret|password)\s*[:=]\s*\S{8,}/iu,
+];
+
+function required(value: unknown, field: string): string {
+  if (typeof value !== 'string' || !value.trim()) throw new FrictionInputError(`${field} is required`);
+  return value.trim();
+}
+
+function checkActor(value: FrictionActor): FrictionActor {
+  if (!FRICTION_ACTORS.includes(value)) throw new FrictionInputError(`actor must be one of ${FRICTION_ACTORS.join(', ')}`);
+  return value;
+}
+
+function checkKind(value: FrictionKind): FrictionKind {
+  if (!FRICTION_KINDS.includes(value)) throw new FrictionInputError(`kind must be one of ${FRICTION_KINDS.join(', ')}`);
+  return value;
+}
+
+/** Same hand step spelled differently is the same hand step: lower case, whitespace runs folded to one space. */
+function normalizeSignature(value: unknown): string {
+  const signature = required(value, 'signature').replace(/\s+/gu, ' ').toLowerCase();
+  if (!signature) throw new FrictionInputError('signature is required');
+  return signature;
+}
+
+export function frictionActor(name: string): FrictionActor {
+  const key = name.trim().toLowerCase();
+  return FRICTION_ACTORS.find(actor => actor.toLowerCase() === key) ?? 'person';
+}
+
+function secretFreeNote(note: unknown): string {
+  const text = note === undefined || note === null ? '' : String(note);
+  if (SECRET_PATTERNS.some(pattern => pattern.test(text))) throw new FrictionInputError('note looks like a secret (token or key)');
+  return text;
+}
+
+export class FrictionLedger {
+  readonly path: string;
+  private readonly now: () => Date;
+
+  constructor(options: LessonLedgerOptions = {}) {
+    this.path = join(options.stateDir ?? elanousStateRoot(), 'lessons', 'friction.sqlite');
+    this.now = options.now ?? (() => new Date());
+  }
+
+  private open(): Database {
+    mkdirSync(dirname(this.path), { recursive: true });
+    const db = new Database(this.path, { create: true, strict: true });
+    try {
+      chmodSync(this.path, 0o600);
+      db.exec('PRAGMA busy_timeout = 10000');
+      db.exec('PRAGMA journal_mode = WAL');
+      db.exec(`CREATE TABLE IF NOT EXISTS friction (
+        id INTEGER PRIMARY KEY AUTOINCREMENT,
+        actor TEXT NOT NULL CHECK(actor IN ('OP','TC','MK','UX','ceo','person')),
+        kind TEXT NOT NULL CHECK(kind IN ('hand-step','ceo-correction','repeat-question')),
+        signature TEXT NOT NULL, note TEXT NOT NULL DEFAULT '', ref TEXT NOT NULL, recorded_at TEXT NOT NULL);
+        CREATE INDEX IF NOT EXISTS friction_group ON friction (kind, signature);`);
+      return db;
+    } catch (error) { db.close(); throw error; }
+  }
+
+  private using<T>(work: (db: Database) => T): T {
+    const db = this.open();
+    try { return work(db); } finally { db.close(); }
+  }
+
+  record(input: FrictionRecordInput): FrictionRow {
+    const actor = checkActor(input.actor);
+    const kind = checkKind(input.kind);
+    const signature = normalizeSignature(input.signature);
+    const note = secretFreeNote(input.note);
+    const ref = required(input.ref, 'ref');
+    return this.using(db => {
+      const at = this.now().toISOString();
+      const inserted = db.query('INSERT INTO friction (actor, kind, signature, note, ref, recorded_at) VALUES (?, ?, ?, ?, ?, ?)')
+        .run(actor, kind, signature, note, ref, at);
+      const row = db.query('SELECT id, actor, kind, signature, note, ref, recorded_at FROM friction WHERE id = ?')
+        .get(Number(inserted.lastInsertRowid)) as FrictionRow | null;
+      if (!row) throw new FrictionInputError('friction row was not stored');
+      debug.log('lessons.friction', 'record', { id: row.id, kind: row.kind, actor: row.actor });
+      return row;
+    });
+  }
+
+  /** Same hand step three times is a proposal candidate (§4⑤ SELF-PROPOSE-BASE), not one-off noise. */
+  candidates(min: number = FRICTION_CANDIDATE_MIN): FrictionCandidate[] {
+    if (!Number.isInteger(min) || min < 1) throw new FrictionInputError('min must be a positive integer');
+    return this.using(db => {
+      const groups = db.query(`SELECT kind, signature, count(*) AS count, min(recorded_at) AS firstAt, max(recorded_at) AS lastAt
+        FROM friction GROUP BY kind, signature HAVING count(*) >= ?
+        ORDER BY count DESC, lastAt DESC, kind, signature`).all(min) as Omit<FrictionCandidate, 'refs'>[];
+      return groups.map(group => ({
+        ...group,
+        refs: (db.query('SELECT ref FROM friction WHERE kind = ? AND signature = ? ORDER BY id')
+          .all(group.kind, group.signature) as { ref: string }[]).map(row => row.ref),
+      }));
+    });
+  }
+}