berry-agent 0.1.0-alpha.1

package/dist/goal/command.js

@@ -0,0 +1,175 @@
+/**
+ * /goal 命令处理器（04 §12——/goal wake 手动起闹的纯程序面；list/show 观察面）。
+ *
+ * 形态律与 /tick 同族（tick.ts 先例）：五动词 argv → 人读文本；服务面守卫错
+ * （BaseError）折文本不抛（命令面是用户面不是异常面）；唤醒裁决（WakeDecision）
+ * 渲染落地/拒因。真正把唤醒消息投进会话的编舞归宿主装配（批 12）——本面只
+ * 裁决与呈现。create（U10——03 §10.5 U10 落码定形注①）是创建唯一写面：
+ * 恒人面命令，模型工具面零创建位（防自激励环入口）。
+ */
+import { BaseError } from '../contracts/index.js';
+import { foldGoalTodos, openGoalItems } from './fold.js';
+export const GOAL_USAGE = [
+    '用法：/goal create <schedule 串> <objective 全文> [--write] [--budget <n>] —— 建续跑 goal（锚本会话；schedule 串形见 /tick 用法）',
+    '　　　/goal list —— 全部 goal（状态/挂钟/预算速览）',
+    '　　　/goal show <goalId> —— 单 goal 详情（计划态 + 归因唤醒审计）',
+    '　　　/goal wake <goalId> —— 手动起闹（停滞/预算双复位 + 挂钟复活）',
+    '　　　/goal approve <goalId> —— 人面批准 needsWrite（command 判据门放行链）',
+].join('\n');
+/**
+ * create 动词：位参 schedule/objective + 可选 --write/--budget（/tick add 同款
+ * argv 位参先例——引号感知切分在 channels 面，本面 join 复原全文；位参前置
+ * 选项后置为正形，循环宽容交错）。
+ *
+ * 守卫面分工（U10 定形注②）：位参缺席/objective 仅空白/--budget 值域执法全在
+ * 命令层（goal 族既有**无码**用法错面——缺位参/未知选项/坏值同折纯文本 +
+ * GOAL_USAGE）；service 面契约信任调用方零校验（0 帽穿透 = 建即死 goal，故
+ * 正整数判归命令层）。schedule 透传律（定形注⑤）：零词法执法——好坏判据 =
+ * register 回执经 activate 折 GOAL_TRANSITION_INVALID + 行回卷（既有律）。
+ * 会话锚缺席（CLI 面/防御位）诚实拒——不猜默认会话源（定形注③）。
+ */
+async function goalCreate(rest, deps, sessionId) {
+    const usageErr = (message) => `${message}\n${GOAL_USAGE}`;
+    const positional = [];
+    let write = false;
+    let budget;
+    for (let i = 0; i < rest.length; i++) {
+        const tok = rest[i] ?? '';
+        if (tok === '--write') {
+            write = true;
+        }
+        else if (tok === '--budget') {
+            const raw = rest[++i];
+            // 正整数必需（0/负数/非数字/缺值均用法错——命令层执法）
+            if (raw === undefined || !/^\d+$/.test(raw) || Number(raw) <= 0) {
+                return usageErr(`--budget 须带正整数值（得「${raw ?? '缺席'}」）。`);
+            }
+            budget = Number(raw);
+        }
+        else if (tok.startsWith('--')) {
+            return usageErr(`未知选项「${tok}」（/goal create 仅识 --write 与 --budget）。`);
+        }
+        else {
+            positional.push(tok);
+        }
+    }
+    const schedule = positional[0];
+    // objective 全文 = 余位参 join 复原；仅空白 = 用法错（service 面 length 判
+    // 不辖空白——命令层 trim 判，complete 的 evidence 同律）
+    const objective = positional.slice(1).join(' ').trim();
+    if (sessionId === undefined) {
+        return usageErr('缺会话锚——/goal create 须在会话内执行（goal 是本会话的无人值守延续）。');
+    }
+    if (!schedule || objective === '') {
+        return usageErr('create 须带两段位参：<schedule 串> <objective 全文>（objective 含空格请整体引号；schedule 串形见 /tick 用法）。');
+    }
+    const row = await deps.service.activate({
+        sessionId,
+        objective,
+        schedule,
+        needsWrite: write,
+        budgetMessagesCap: budget ?? null,
+    });
+    // 回执不探测装配态（定形注⑤）——通用文案「挂钟行已排」如实（缺席迟到
+    // 暂存系测试形，core 双件恒装载）；首跑 = schedule 首到点（不开 create 即
+    // 起跑——立题档边界声明）
+    const lines = [
+        `已建 goal「${row.id}」——挂钟行已排（schedule ${row.schedule}；首跑 = 首次到点，即刻续跑请直接发言）。`,
+    ];
+    if (row.needsWrite) {
+        lines.push(`已申报 needsWrite（申报非授权）——/goal approve ${row.id} 批准后 command 判据门可用。`);
+    }
+    if (row.budgetMessagesCap !== null) {
+        lines.push(`预算帽 ${row.budgetMessagesCap}（前台计数 + 委派折叠合计对帽）。`);
+    }
+    return lines.join('\n');
+}
+/** /goal 处理器（argv → 人读文本；守卫错折文本；sessionId = 命令发起会话锚——U10 定形注③，缺席仅 create 受影响） */
+export async function runGoalCommand(argv, deps, sessionId) {
+    const [verb, ...rest] = argv;
+    try {
+        switch (verb) {
+            case 'create': {
+                // return await（非裸 return）——helper 的守卫错拒绝须经本层
+                // try/catch 折文本（裸 return 的 promise 拒绝发生在 catch 出口之后）
+                return await goalCreate(rest, deps, sessionId);
+            }
+            case 'wake': {
+                const goalId = rest[0];
+                if (!goalId)
+                    return `缺 goalId。\n${GOAL_USAGE}`;
+                const decision = await deps.service.wake(goalId, { trigger: 'manual', attribution: '/goal wake' });
+                return decision.landed
+                    ? `已手动唤醒 goal「${goalId}」（停滞/唤醒预算双复位，挂钟复活）。${decision.message}`
+                    : `唤醒未落地：${decision.message}`;
+            }
+            case 'approve': {
+                // 人面批准（f-1 定形注②——批准唯一写面；守卫错折文本同面）
+                const goalId = rest[0];
+                if (!goalId)
+                    return `缺 goalId。\n${GOAL_USAGE}`;
+                await deps.service.approve(goalId);
+                return `已批准 goal「${goalId}」的 needsWrite 申报——command 判据门申报解锁（todo 工具 gate 声明即刻可用）。`;
+            }
+            case 'list': {
+                const rows = deps.service.list();
+                if (rows.length === 0)
+                    return '无 goal。';
+                const lines = rows.map((row) => {
+                    const budget = row.budgetMessagesCap === null
+                        ? '无预算帽'
+                        : `预算 ${row.budgetMessagesUsed + row.budgetFoldedUnits}/${row.budgetMessagesCap}`;
+                    const clock = row.status === 'active' ? (row.stallStreak > 0 ? `挂钟（停滞 ${row.stallStreak}）` : '挂钟在跑') : '已停摆';
+                    return `- ${row.id}〔${row.status}〕${row.objective.slice(0, 40)} —— ${clock} · ${budget}`;
+                });
+                return `共 ${rows.length} 个 goal：\n${lines.join('\n')}`;
+            }
+            case 'show': {
+                const goalId = rest[0];
+                if (!goalId)
+                    return `缺 goalId。\n${GOAL_USAGE}`;
+                const row = deps.service.get(goalId);
+                if (!row)
+                    return `goal「${goalId}」不存在。`;
+                const scope = deps.service.goalScopeFor(row.sessionId);
+                const items = scope !== undefined && scope.goalId === goalId
+                    ? openGoalItems(foldGoalTodos(deps.eventsFor(row.sessionId), row.activatedSeq))
+                    : [];
+                const openLine = items.length === 0
+                    ? 'open 项：0'
+                    : `open 项：${items.length}（${items.map((i) => `[${i.status}] ${i.content}`).join('；')}）`;
+                const wakes = deps.service.wakes(goalId);
+                const wakeLines = wakes.length === 0
+                    ? '（无唤醒记录）'
+                    : wakes
+                        .slice(-5)
+                        .map((w) => `- ${w.wokeAt} ${w.trigger} 道 · ${w.progressed ? '有进展' : '无进展'} · 归因 ${w.attribution}`)
+                        .join('\n');
+                return [
+                    `goal「${goalId}」〔${row.status}〕`,
+                    `目标：${row.objective}`,
+                    `挂钟：${row.schedule}（激活锚 seq=${row.activatedSeq}，会话 ${row.sessionId}）`,
+                    `预算：前台 ${row.budgetMessagesUsed} + 委派折叠 ${row.budgetFoldedUnits}${row.budgetMessagesCap === null ? '（无帽）' : ` / 帽 ${row.budgetMessagesCap}`}`,
+                    `needsWrite：${row.needsWrite ? (row.writeApproved ? '已申报·已批准（command 判据门可用）' : '已申报·未批准（/goal approve 后可用）') : '未申报（command 判据门不可用）'}`,
+                    `停滞计数：${row.stallStreak}（帽内复位靠进展或手动）`,
+                    openLine,
+                    row.endingNote !== null ? `终态回执：${row.endingNote}` : '',
+                    `唤醒审计（末 5 条）：\n${wakeLines}`,
+                ]
+                    .filter((line) => line !== '')
+                    .join('\n');
+            }
+            case undefined:
+            case 'help':
+                return GOAL_USAGE;
+            default:
+                return `未知动词「${verb}」。\n${GOAL_USAGE}`;
+        }
+    }
+    catch (err) {
+        // 守卫错折文本（命令面是用户面——BaseError 码与人读原因直呈）
+        if (err instanceof BaseError)
+            return `${err.code}：${err.message}`;
+        throw err;
+    }
+}

package/dist/goal/fold.js

@@ -0,0 +1,121 @@
+import { occludedSeqs } from '../session/index.js';
+/** status 四值词表（与 conversation TodoItemData 同词表——结构兼容面） */
+const TODO_STATUSES = ['pending', 'in-progress', 'completed', 'deferred'];
+/**
+ * fold goal 段当前任务清单：倒扫 events（seq ≥ activatedSeq 的区间）——
+ * 先遇 `todo/write` → 其 items 即当前表（last-write-wins）；user/message
+ * 不停扫（跨轮存活）；扫出边界 → 空表（goal 段从未建表）。
+ */
+export function foldGoalTodos(events, activatedSeq) {
+    const occluded = occludedSeqs(events);
+    for (let seq = events.length - 1; seq >= 0; seq -= 1) {
+        if (seq < activatedSeq)
+            return []; // 越激活锚即出 goal 段——锚前历史不成表
+        if (occluded.has(seq))
+            continue;
+        const event = events[seq];
+        if (event.type === 'todo/write')
+            return validateGoalTodoItems(event.data.items);
+        // user/message 不重置（goal 生命周期段语义）；assistant/工具事件同不停扫
+    }
+    return [];
+}
+/**
+ * open 项集（完成否决律判据面）：open = 一切非 completed 状态项——
+ * deferred 含内无论窗到否（判窗是续跑提示的提示词义务，非机器放行面）。
+ */
+export function openGoalItems(items) {
+    return items.filter((item) => item.status !== 'completed');
+}
+/**
+ * fold 投影指纹（停滞判据面，04 §12 停滞硬停条）：计数分桶 + 逐条内容
+ * 散列——条目状态翻转或内容改写即变（planning-with-files ③ 单调进度护卫
+ * 的最小形：不做单调性断言，只做变更检测——单调性挂真实使用回访）。
+ */
+export function progressFingerprint(items) {
+    const counts = { pending: 0, 'in-progress': 0, completed: 0, deferred: 0 };
+    const parts = [];
+    for (const item of items) {
+        counts[item.status] += 1;
+        // status+content+扩展语义字段全入指纹——resume_when 改窗也是进展
+        parts.push(`${item.status}|${item.content}|${item.resumeWhen ?? ''}|${item.role ?? ''}|` +
+            `${item.taskClass ?? ''}|${item.followUp ?? ''}|${item.noFollowUp === true ? 1 : 0}|` +
+            `${item.gate ? JSON.stringify(item.gate) : ''}`);
+    }
+    return `p${counts.pending},i${counts['in-progress']},c${counts.completed},d${counts.deferred};${parts.join(';')}`;
+}
+/**
+ * resume_when 词法解析（03 §10.5 deferred 必携条）：`after@<ISO>` 绝对形
+ * 或 `after@+<n>[mhd]` 相对形（判窗锚 = 条目写入时刻——由调用方供锚）。
+ * 返回 null = 坏形（写侧 GOAL_TODO_SCOPE 拒、读侧不判窗机器面零消费）。
+ */
+export function parseResumeWhen(spec, anchorMs) {
+    if (!spec.startsWith('after@'))
+        return { ok: false, error: `resume_when 须以 after@ 起头（得「${spec}」）` };
+    const body = spec.slice('after@'.length);
+    // 绝对 ISO 形
+    if (!body.startsWith('+')) {
+        const ms = Date.parse(body);
+        if (Number.isNaN(ms))
+            return { ok: false, error: `after@ 后非合法 ISO 时间串（得「${body}」）` };
+        return { ok: true, dueAtMs: ms };
+    }
+    // 相对形：+<n>[mhd]
+    const m = /^\+(\d{1,8})([mhd])$/.exec(body);
+    if (!m)
+        return { ok: false, error: `相对形须为 +<正整数>[mhd]（得「${body}」）` };
+    const n = Number(m[1]);
+    const unitMs = m[2] === 'm' ? 60_000 : m[2] === 'h' ? 3_600_000 : 86_400_000;
+    return { ok: true, dueAtMs: anchorMs + n * unitMs };
+}
+/**
+ * 未知载荷 → goal 段条目列表（fold 读侧收窄面）：status 出词表/content
+ * 非串 → 整条丢弃；扩展字段仅收对应型别（型别不符剔除该字段不弃整条——
+ * 核心四字段健康即保留，扩展面保守降级）。
+ */
+export function validateGoalTodoItems(value) {
+    if (!Array.isArray(value))
+        return [];
+    const items = [];
+    for (const entry of value) {
+        if (typeof entry !== 'object' || entry === null)
+            continue;
+        const c = entry;
+        if (typeof c.status !== 'string' ||
+            !TODO_STATUSES.includes(c.status) ||
+            typeof c.content !== 'string') {
+            continue;
+        }
+        // 可写局部（WritableGoalTodoItem——readonly 契约形由收窄返回承载）
+        const item = { status: c.status, content: c.content };
+        if (typeof c.activeForm === 'string')
+            item.activeForm = c.activeForm;
+        if (typeof c.resumeWhen === 'string')
+            item.resumeWhen = c.resumeWhen;
+        if (c.role === 'agent' || c.role === 'user')
+            item.role = c.role;
+        if (typeof c.taskClass === 'string')
+            item.taskClass = c.taskClass;
+        if (typeof c.followUp === 'string')
+            item.followUp = c.followUp;
+        if (c.noFollowUp === true)
+            item.noFollowUp = true;
+        if (isGateSpec(c.gate))
+            item.gate = c.gate;
+        items.push(item);
+    }
+    return items;
+}
+/** gate 声明收窄（三源判据门形——{kind, spec} 平铺形） */
+function isGateSpec(value) {
+    if (typeof value !== 'object' || value === null)
+        return false;
+    const g = value;
+    if (g.kind === 'command' && typeof g.command === 'string')
+        return true;
+    if (g.kind === 'files' && Array.isArray(g.paths) && g.paths.every((p) => typeof p === 'string'))
+        return true;
+    if (g.kind === 'diagnostics' && Array.isArray(g.files) && g.files.every((f) => typeof f === 'string'))
+        return true;
+    return false;
+}

package/dist/goal/gates.js

@@ -0,0 +1,122 @@
+/**
+ * 判据门三源评测机（03 §10.5 gates 条——fail-closed）。
+ *
+ * 三源判据（goal 段 todo 项可选 gate 声明，完成否决律消费）：
+ *  - `command`：exit 0 放行、超时帽 30s、走 exec 三段管道全执法（exec seam
+ *    组合根注入——**v1 未接线**〔03 §10.5 s 批补注①诚实缺席律〕：todo 申报位
+ *    hasCommandExec 判据拒 + 评测位本件 fail 双拦，真接线随「exec 判据门真
+ *    接线」立题批）；**仅 goal needsWrite 申报批准后可用**（模型自造命令免
+ *    审批自跑是注入面——申报位与评测位双拦）；
+ *  - `files`：全部存在且非空；stat 前归一判工作区根内（裸 stat 不得是无
+ *    fence 存在性 oracle——路径归一后越根即 fail）；
+ *  - `diagnostics`：目标文件集 LSP 诊断无 error 级；lsp 查询窄面缺席时
+ *    **评测位亦 fail**（申报位已拒，双拦防御——fail-closed 非静默跳过）。
+ *
+ * 评测原则：一切 seam 缺席 = fail（不是 skip）——判据门是完成否决的机器
+ * 面，门面不在场即门不放行。
+ */
+import { isAbsolute, resolve, sep } from 'node:path';
+import { statSync } from 'node:fs';
+/** command gate 超时帽（30s——04 §12 exec 三段管道墙钟同量级） */
+export const GATE_COMMAND_TIMEOUT_MS = 30_000;
+/**
+ * 评测全部 gate 声明（完成否决律的机器面）：逐条独立评测、全量返回——
+ * 调用方聚合判「全绿」。无 gate 声明的条目不产条目（零门 = 零评测）。
+ */
+export async function evaluateGoalGates(items, deps) {
+    const outcomes = [];
+    for (const item of items) {
+        if (item.gate === undefined)
+            continue;
+        outcomes.push(await evaluateOne(item.gate, deps));
+    }
+    return outcomes;
+}
+/** 单门评测（fail-closed 分派） */
+async function evaluateOne(spec, deps) {
+    switch (spec.kind) {
+        case 'command':
+            return evaluateCommand(spec.command, deps);
+        case 'files':
+            return evaluateFiles(spec.paths, deps);
+        case 'diagnostics':
+            return evaluateDiagnostics(spec.files, deps);
+    }
+}
+/** command 源：needsWrite 批准 + seam 在场 + exit 0 三条件全过才放行 */
+async function evaluateCommand(command, deps) {
+    if (!deps.commandGateAllowed) {
+        return {
+            ok: false,
+            kind: 'command',
+            detail: 'goal 未申报 needsWrite（或未获批准）——command 判据门不可用（防模型自造命令免审批自跑）',
+        };
+    }
+    if (deps.exec === undefined) {
+        return { ok: false, kind: 'command', detail: 'exec 执行面缺席——fail-closed 不放行（组合根未接线）' };
+    }
+    const result = await deps.exec.execCommand(command);
+    if (result.timedOut) {
+        return { ok: false, kind: 'command', detail: `命令超时（>${GATE_COMMAND_TIMEOUT_MS}ms）——判未过` };
+    }
+    if (result.exitCode !== 0) {
+        const tail = result.stderrTail === '' ? '' : `（stderr 末行：${result.stderrTail}）`;
+        return { ok: false, kind: 'command', detail: `退出码 ${result.exitCode} 非 0${tail}` };
+    }
+    return { ok: true, kind: 'command', detail: `exit 0（命令：${command}）` };
+}
+/** files 源：全部存在且非空；stat 前归一判工作区根内 */
+function evaluateFiles(paths, deps) {
+    if (paths.length === 0) {
+        return { ok: false, kind: 'files', detail: '空目标集——空门即非门（申报位已拦，评测位双拦）' };
+    }
+    const root = deps.workspaceRoot;
+    const stat = deps.statFile ?? statFileDefault;
+    for (const p of paths) {
+        // 归一判根：resolve 锚工作区根（相对路径合法——判根后落根内）；越根即 fail
+        const abs = isAbsolute(p) ? resolve(p) : resolve(root, p);
+        if (abs !== root && !abs.startsWith(root + sep)) {
+            return {
+                ok: false,
+                kind: 'files',
+                detail: `路径「${p}」归一后在工作区根外（${abs}）——裸 stat 不是存在性 oracle`,
+            };
+        }
+        const s = stat(abs);
+        if (!s.exists)
+            return { ok: false, kind: 'files', detail: `文件不存在：${p}` };
+        if (s.size === 0)
+            return { ok: false, kind: 'files', detail: `文件为空：${p}` };
+    }
+    return { ok: true, kind: 'files', detail: `${paths.length} 个文件全部存在且非空` };
+}
+/** diagnostics 源：目标文件集 LSP 诊断无 error 级 */
+async function evaluateDiagnostics(files, deps) {
+    if (files.length === 0) {
+        return { ok: false, kind: 'diagnostics', detail: '空目标集——空门即非门（申报位已拦，评测位双拦）' };
+    }
+    if (deps.lsp === undefined) {
+        return { ok: false, kind: 'diagnostics', detail: 'lsp 诊断查询面缺席——fail-closed 不放行（组合根未接线）' };
+    }
+    const diags = await deps.lsp.queryDiagnostics([...files]);
+    const errors = diags.filter((d) => d.level === 'error');
+    if (errors.length > 0) {
+        const first = errors[0];
+        return {
+            ok: false,
+            kind: 'diagnostics',
+            detail: `${errors.length} 条 error 级诊断（如 ${first.file}: ${first.message}）`,
+        };
+    }
+    return { ok: true, kind: 'diagnostics', detail: `${files.length} 个目标文件无 error 级诊断` };
+}
+/** 文件源缺省真身（node:fs statSync——测试注 statFile 假件后不触盘） */
+function statFileDefault(p) {
+    try {
+        const s = statSync(p);
+        return { exists: true, size: Number(s.size) };
+    }
+    catch {
+        return { exists: false, size: 0 };
+    }
+}

package/dist/goal/index.js

@@ -0,0 +1,22 @@
+/**
+ * goal 模块公开面（L3——02 §4.1 席 23；机制真源 03 §10.5 + 04 §12）。
+ *
+ * 本批落码：goals 表族（migration v3）+ 计划态跨轮 fold（goal 段倒扫）+
+ * todo 工具换装件（GOAL_TODO_SCOPE 段约束双向执法）+ goal_update 终态申报件
+ * （完成否决律机器面）+ 判据门三源评测（fail-closed）+ GoalService（生命周期/
+ * wake 双帽/停滞硬停/重绑护栏/归因落账/预算双轨/挂钟迟到注入）+ /goal 命令。
+ * 装载态集成（批 19c-3 + 批 #99 驱动侧接线收口）：todo 换装（openTools
+ * todoTool 注入位）、goalScopeFor 注入（组合根闭包 → 驱动 fold 升格锚）、
+ * 挂钟引擎消费（双序迟到注入）、agent_pre_step 预算复验监听（ctx.on 瀑布
+ * ——budgetExceeded 置 stop）、recordTurn 记账腿（驱动 onRunSettled 窗扫
+ * 供给 messages 计数——三入口统一）、depositFor 轮间沉淀（goalDeposit 注入
+ * 位 + 指纹缓存单发）六件已入册 core:goal——run 入口批挂账全数兑现。
+ */
+import './codes.js';
+export { GOAL_MIGRATION, GOAL_APPROVAL_MIGRATION } from './migration.js';
+export { foldGoalTodos, openGoalItems, progressFingerprint, parseResumeWhen, validateGoalTodoItems } from './fold.js';
+export { evaluateGoalGates, GATE_COMMAND_TIMEOUT_MS, } from './gates.js';
+export { createGoalTodoTool } from './todo-tool.js';
+export { createGoalUpdateTool } from './update-tool.js';
+export { createGoalService, DEFAULT_STALL_LIMIT, DEFAULT_WAKE_BUDGET_LIMIT, GOAL_DEPOSIT_MAX_CHARS, } from './service.js';
+export { runGoalCommand, GOAL_USAGE } from './command.js';

package/dist/goal/migration.js

@@ -0,0 +1,48 @@
+export const GOAL_MIGRATION = {
+    version: 3,
+    name: 'goal-goals',
+    sql: `
+    CREATE TABLE goals (
+      id                    TEXT PRIMARY KEY,
+      session_id            TEXT NOT NULL,
+      objective             TEXT NOT NULL,
+      status                TEXT NOT NULL CHECK (status IN ('active', 'completed', 'abandoned')),
+      activated_seq         INTEGER NOT NULL,
+      schedule              TEXT NOT NULL,
+      prompt_snapshot       TEXT NOT NULL,
+      needs_write           INTEGER NOT NULL DEFAULT 0,
+      budget_messages_cap   INTEGER,
+      budget_messages_used  INTEGER NOT NULL DEFAULT 0,
+      budget_folded_units   INTEGER NOT NULL DEFAULT 0,
+      stall_streak          INTEGER NOT NULL DEFAULT 0,
+      wake_streak           INTEGER NOT NULL DEFAULT 0,
+      last_fingerprint      TEXT,
+      created_at            TEXT NOT NULL,
+      updated_at            TEXT NOT NULL,
+      ended_at              TEXT,
+      ending_note           TEXT
+    );
+    CREATE INDEX idx_goals_session_active ON goals (session_id) WHERE status = 'active';
+    CREATE TABLE goal_wakes (
+      id            INTEGER PRIMARY KEY AUTOINCREMENT,
+      goal_id       TEXT NOT NULL REFERENCES goals (id),
+      woke_at       TEXT NOT NULL,
+      trigger       TEXT NOT NULL CHECK (trigger IN ('clock', 'manual')),
+      attribution   TEXT NOT NULL,
+      fingerprint   TEXT NOT NULL,
+      progressed    INTEGER NOT NULL
+    );
+    CREATE INDEX idx_goal_wakes_goal ON goal_wakes (goal_id);
+  `,
+};
+/**
+ * goals 表增列迁移（迁移 v12——f-1 批 2026-09-13；05 §6.4「号随注册序顺延」：
+ * v11 memory 谱系批后本件顺占 v12）。write_approved = needsWrite 人面批准位
+ * （03 §10.5 f-1 定形注①——双 durable 位之批准位；缺省 0，唯一写面 =
+ * /goal approve）。
+ */
+export const GOAL_APPROVAL_MIGRATION = {
+    version: 12,
+    name: 'goal-write-approved',
+    sql: `ALTER TABLE goals ADD COLUMN write_approved INTEGER NOT NULL DEFAULT 0;`,
+};