@tea-agent/loop-agent 0.1.0

package/dist/task/runtime.js

@@ -0,0 +1,699 @@
+import { createHash } from 'node:crypto';
+import { access, mkdir, readFile, readdir, writeFile } from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { initializeArtifacts } from '../shared/artifacts-core.js';
+import { appendDecisionRecord, appendGoalEventRecord, appendWorkflowLog } from '../shared/logger.js';
+import { loadWorkflowState, saveWorkflowState } from './state.js';
+import { taskConfigSchema, taskGoalStatusSchema, } from '../shared/types.js';
+const STEP_ORDER = ['analyze', 'plan', 'implement', 'verify', 'retrospective'];
+/** Canonical task id: YYYY-MM-DD-<kebab-slug> using local business date at creation time. */
+export const CANONICAL_TASK_ID_PATTERN = /^\d{4}-\d{2}-\d{2}-[a-z0-9]+(-[a-z0-9]+)*$/;
+const GENERIC_TASK_SLUGS = new Set(['test', 'fix', 'tmp', 'new-task']);
+/** Local calendar date as YYYY-MM-DD (not UTC-derived). */
+export function formatLocalBusinessDate(date = new Date()) {
+    const year = date.getFullYear();
+    const month = String(date.getMonth() + 1).padStart(2, '0');
+    const day = String(date.getDate()).padStart(2, '0');
+    return `${year}-${month}-${day}`;
+}
+/** Compact local calendar date as YYYYMMDD for DAG run ids. */
+export function formatLocalCompactDate(date = new Date()) {
+    return formatLocalBusinessDate(date).replace(/-/g, '');
+}
+export function validateNewTaskId(taskId) {
+    const errors = [];
+    const warnings = [];
+    const trimmed = taskId.trim();
+    if (!trimmed) {
+        errors.push('taskId cannot be empty');
+        return { errors, warnings };
+    }
+    if (CANONICAL_TASK_ID_PATTERN.test(trimmed)) {
+        const slug = trimmed.slice(11);
+        const slugBase = slug.replace(/-r\d+$/, '');
+        if (GENERIC_TASK_SLUGS.has(slug) || GENERIC_TASK_SLUGS.has(slugBase)) {
+            errors.push(`taskId slug "${slug}" is too generic; use a descriptive kebab-slug instead of test/fix/tmp/new-task`);
+        }
+        return { errors, warnings };
+    }
+    warnings.push(`taskId "${trimmed}" does not match canonical YYYY-MM-DD-<slug>; legacy ids remain readable but new tasks should use a local business date prefix`);
+    const legacyBase = trimmed.replace(/-r\d+$/, '');
+    if (GENERIC_TASK_SLUGS.has(trimmed) || GENERIC_TASK_SLUGS.has(legacyBase)) {
+        errors.push(`taskId "${trimmed}" is too generic; use a descriptive kebab-slug`);
+    }
+    return { errors, warnings };
+}
+const ARTIFACT_KEY_BY_STEP = {
+    analyze: 'analysis',
+    plan: 'plan',
+    implement: 'modifyLog',
+    verify: 'verifyResult',
+    retrospective: 'retrospective',
+};
+const PLANNING_STEPS = new Set(['plan', 'spec']);
+const MAX_DECISION_LOG_ENTRIES = 50;
+export function getTaskDir(repoRoot, taskId) {
+    return path.join(repoRoot, '.harness', 'tasks', taskId);
+}
+export function getTaskPaths(repoRoot, taskId) {
+    const taskDir = getTaskDir(repoRoot, taskId);
+    return {
+        taskDir,
+        taskConfigPath: path.join(taskDir, 'task.json'),
+        logsDir: path.join(taskDir, 'logs'),
+        sourceDir: path.join(taskDir, 'source'),
+        statePath: path.join(taskDir, '.workflow_state.json'),
+    };
+}
+export async function createTask(repoRoot, taskId, title) {
+    const validation = validateNewTaskId(taskId);
+    for (const warning of validation.warnings) {
+        console.warn(`[new-task] warning: ${warning}`);
+    }
+    if (validation.errors.length > 0) {
+        throw new Error(`invalid taskId: ${validation.errors.join('; ')}`);
+    }
+    const paths = getTaskPaths(repoRoot, taskId);
+    try {
+        await access(paths.statePath);
+        throw new Error(`task already exists: ${taskId}`);
+    }
+    catch (error) {
+        const isMissing = typeof error === 'object' && error !== null && 'code' in error && error.code === 'ENOENT';
+        if (!isMissing)
+            throw error;
+    }
+    await mkdir(paths.sourceDir, { recursive: true });
+    await mkdir(paths.logsDir, { recursive: true });
+    await initializeArtifacts(paths.taskDir);
+    const taskConfig = {
+        taskId,
+        title: title ?? taskId,
+        sourceFiles: [],
+        taskKind: 'standard',
+        referenceRepos: [],
+        referenceDocs: [],
+        allowedPaths: [],
+        forbiddenPaths: [],
+        hardConstraints: [],
+        autoCommitAfterVerify: true,
+        autoCommitMessage: '',
+        complexity: 'medium',
+        dagFallbackReason: '',
+        contextProfile: 'full',
+        verifyMode: 'parallel',
+        verifyPreset: 'auto',
+        verifyQuota: 'full',
+        verifyRetryCount: 0,
+        verifyFailFast: false,
+        contextMaxFiles: 0,
+        requireRetrospective: false,
+        convergence: {
+            enabled: false,
+            maxPasses: 3,
+            stopOnVerdictPass: true,
+            stopOnHardVerifyPass: true,
+            pauseOnRegression: true,
+        },
+        loopAutoWritePolicy: 'off',
+        verifyEnv: 'clean',
+        maxGoalContinuationsPerRun: 5,
+        piSubagentMode: 'off',
+        executor: 'pi',
+        notes: '',
+    };
+    const state = {
+        taskId,
+        status: 'draft',
+        currentStep: 'analyze',
+        completedSteps: [],
+        lastUpdated: new Date().toISOString(),
+        executor: {
+            name: 'pi',
+            mode: 'json',
+        },
+        artifacts: {
+            analysis: false,
+            plan: false,
+            modifyLog: false,
+            verifyResult: false,
+            retrospective: false,
+        },
+        sourceState: {
+            currentHash: '',
+            plannedHash: '',
+            trackedFiles: [],
+            lastCheckedAt: '',
+            lastPlannedAt: '',
+            lastPlannedStep: null,
+            stalePlan: false,
+        },
+        goal: {
+            objective: '',
+            status: 'paused',
+            tokenBudget: null,
+            tokensUsed: 0,
+            timeUsedSeconds: 0,
+            pendingObjectiveUpdatedNotice: false,
+            pendingBudgetLimitNotice: false,
+            continuationRuns: 0,
+            createdAt: '',
+            updatedAt: '',
+        },
+        decisionLog: [],
+    };
+    await writeFile(paths.taskConfigPath, `${JSON.stringify(taskConfig, null, 2)}\n`, 'utf-8');
+    await saveWorkflowState(paths.statePath, state);
+    await writeFile(path.join(paths.logsDir, 'executor.jsonl'), '', 'utf-8');
+    await writeFile(path.join(paths.logsDir, 'decisions.jsonl'), '', 'utf-8');
+    await appendWorkflowLog(paths.taskDir, `created task ${taskId}`);
+    return paths.taskDir;
+}
+export async function getTaskStatus(repoRoot, taskId) {
+    return loadWorkflowState(getTaskPaths(repoRoot, taskId).statePath);
+}
+export async function loadTaskConfig(repoRoot, taskId) {
+    const raw = await readFile(getTaskPaths(repoRoot, taskId).taskConfigPath, 'utf-8');
+    return parseTaskConfigForRuntime(JSON.parse(raw));
+}
+export function parseTaskConfigForRuntime(rawConfig) {
+    const parsed = taskConfigSchema.parse(rawConfig);
+    if (typeof rawConfig === 'object' &&
+        rawConfig !== null &&
+        !Object.prototype.hasOwnProperty.call(rawConfig, 'maxFixLoops')) {
+        return {
+            ...parsed,
+            maxFixLoops: deriveMaxFixLoops(parsed.complexity),
+        };
+    }
+    return parsed;
+}
+export function deriveMaxFixLoops(complexity) {
+    if (complexity === 'small')
+        return 2;
+    return 3;
+}
+export async function listTaskSourceFiles(repoRoot, taskId) {
+    return listFilesRecursive(getTaskPaths(repoRoot, taskId).sourceDir);
+}
+/**
+ * Resolve tool names for a given step and piSubagentMode.
+ *
+ * - `off`: read-only tools for non-implement steps, standard tools for implement
+ * - `analyze-plan`: as `off` plus `subagent` for analyze/plan/spec
+ * - `full`: as `analyze-plan` plus `subagent` for retrospective
+ * - implement never gets `subagent` in any mode (avoids nested multi-writer)
+ */
+export function resolvePiSubagentTools(step, mode) {
+    const readOnlyTools = ['read', 'grep', 'find', 'ls'];
+    const implementTools = ['read', 'bash', 'edit', 'write', 'grep', 'find', 'ls'];
+    if (step === 'implement') {
+        return implementTools;
+    }
+    if (mode === 'off') {
+        return readOnlyTools;
+    }
+    const shouldHaveSubagent = step === 'analyze' || step === 'plan' || step === 'spec' ||
+        (mode === 'full' && step === 'retrospective');
+    if (shouldHaveSubagent) {
+        return [...readOnlyTools, 'subagent'];
+    }
+    return readOnlyTools;
+}
+/**
+ * Determine whether subagent guidance should be injected into the user message
+ * for a given step and piSubagentMode.
+ */
+export function shouldInjectSubagentGuidance(step, mode) {
+    if (mode === 'off')
+        return false;
+    if (step === 'implement')
+        return false;
+    if (mode === 'analyze-plan' && (step === 'analyze' || step === 'plan' || step === 'spec'))
+        return true;
+    if (mode === 'full' && (step === 'analyze' || step === 'plan' || step === 'spec' || step === 'retrospective'))
+        return true;
+    return false;
+}
+/** Advisory guidance for `analyze-plan` mode. */
+export const SUBAGENT_GUIDANCE_STANDARD = `<subagent_guidance>
+You have access to the \`subagent\` tool for lightweight delegation within this step.
+Use it only for read-only tasks:
+- Parallel scout: dispatch multiple subagents to search/read different areas simultaneously
+- Chain: scout -> planner (one subagent scouts, another plans based on findings)
+- Reviewer: have a subagent review your analysis/plan before finalizing
+Do NOT use subagent for writing, editing, or executing commands.
+Subagent output is advisory only; always verify and incorporate findings into your own output.
+Do NOT treat subagent results as authoritative state or artifact sources.
+</subagent_guidance>`;
+/** Strong guidance for `full` mode — prescriptive when to delegate. */
+export const SUBAGENT_GUIDANCE_STRONG = `<subagent_guidance>
+You have access to the \`subagent\` tool for lightweight delegation within this step.
+
+You SHOULD delegate to subagent scouts when:
+- The task requires scanning 3+ directories or comparing implementations across modules
+- You would otherwise need 5+ sequential read/grep calls to gather context
+- A reviewer subagent can independently catch scope drift before you finalize your output
+
+Delegation saves context tokens and produces better results.
+
+Allowed patterns:
+- Parallel scout: dispatch 2-3 subagents simultaneously to cover different file trees
+- Chain: scout -> planner (one subagent scouts, another plans based on findings)
+- Reviewer: have a subagent review your analysis/plan before finalizing
+
+Do NOT use subagent for writing, editing, or executing commands.
+Subagent output is advisory only; always verify and incorporate findings into your own output.
+Do NOT treat subagent results as authoritative state or artifact sources.
+</subagent_guidance>`;
+/** Preserved for backward compatibility (alias of STANDARD). */
+export const SUBAGENT_GUIDANCE = SUBAGENT_GUIDANCE_STANDARD;
+/** Resolve the correct guidance text for a given piSubagentMode. */
+export function resolveSubagentGuidance(mode) {
+    return mode === 'full' ? SUBAGENT_GUIDANCE_STRONG : SUBAGENT_GUIDANCE_STANDARD;
+}
+export function getNextStep(step) {
+    if (step === 'spec') {
+        return 'implement';
+    }
+    const currentIndex = STEP_ORDER.indexOf(step);
+    return STEP_ORDER[Math.min(currentIndex + 1, STEP_ORDER.length - 1)] ?? 'retrospective';
+}
+export function getSupportedNextCommand(step, taskId, status, options) {
+    const hasActiveGoal = Boolean(options?.goal?.objective) && options?.goal?.status === 'active';
+    if (status === 'completed') {
+        return `task ${taskId} completed`;
+    }
+    if (hasActiveGoal) {
+        return `npm run dev -- loop status ${taskId}`;
+    }
+    if (step === 'analyze' || step === 'plan' || step === 'spec' || step === 'implement' || step === 'verify' || step === 'retrospective') {
+        const dagPath = path.join(os.tmpdir(), `${taskId}-dag.json`);
+        return `npm run dev -- dag run-task ${taskId} --profile auto --strict-models --output ${JSON.stringify(dagPath)}`;
+    }
+    return `${step} step not yet implemented in this prototype; human intervention required`;
+}
+export async function refreshSourceState(repoRoot, taskId) {
+    const paths = getTaskPaths(repoRoot, taskId);
+    const state = await loadWorkflowState(paths.statePath);
+    state.sourceState = await computeSourceState(paths.sourceDir, state.sourceState);
+    state.lastUpdated = new Date().toISOString();
+    await saveWorkflowState(paths.statePath, state);
+    return state;
+}
+export async function assertPlanFreshForImplement(repoRoot, taskId) {
+    const state = await refreshSourceState(repoRoot, taskId);
+    if (!state.sourceState.plannedHash) {
+        throw new Error('implement requires a completed plan/spec baseline before execution');
+    }
+    if (state.sourceState.stalePlan) {
+        throw new Error('source materials changed after the last plan/spec; rerun plan or spec before implement');
+    }
+    return state;
+}
+export async function markTaskRunning(repoRoot, taskId, step, detail) {
+    const paths = getTaskPaths(repoRoot, taskId);
+    const state = await loadWorkflowState(paths.statePath);
+    const previousStatus = state.status;
+    state.sourceState = await computeSourceState(paths.sourceDir, state.sourceState);
+    state.status = 'active';
+    state.currentStep = step;
+    state.lastUpdated = new Date().toISOString();
+    await recordDecision(state, paths.taskDir, {
+        time: state.lastUpdated,
+        step,
+        fromStatus: previousStatus,
+        toStatus: 'active',
+        reason: detail?.reason ?? `step ${step} started`,
+        evidence: detail?.evidence ?? '',
+    });
+    await saveWorkflowState(paths.statePath, state);
+}
+export async function markTaskFailed(repoRoot, taskId, step, detail) {
+    const paths = getTaskPaths(repoRoot, taskId);
+    const state = await loadWorkflowState(paths.statePath);
+    const previousStatus = state.status;
+    state.sourceState = await computeSourceState(paths.sourceDir, state.sourceState);
+    state.status = 'failed';
+    state.currentStep = step;
+    state.lastUpdated = new Date().toISOString();
+    await recordDecision(state, paths.taskDir, {
+        time: state.lastUpdated,
+        step,
+        fromStatus: previousStatus,
+        toStatus: 'failed',
+        reason: detail?.reason ?? `step ${step} failed`,
+        evidence: detail?.evidence ?? '',
+    });
+    await saveWorkflowState(paths.statePath, state);
+}
+export async function markStepCompleted(repoRoot, taskId, step, detail) {
+    await updateStepCompletion(repoRoot, taskId, step, false, detail);
+}
+export async function markTaskCompleted(repoRoot, taskId, step, detail) {
+    await updateStepCompletion(repoRoot, taskId, step, true, detail);
+}
+export async function markVerifyGoalPending(repoRoot, taskId, detail) {
+    const paths = getTaskPaths(repoRoot, taskId);
+    const state = await loadWorkflowState(paths.statePath);
+    const previousStatus = state.status;
+    state.sourceState = await computeSourceState(paths.sourceDir, state.sourceState);
+    state.status = 'active';
+    state.currentStep = 'implement';
+    state.lastUpdated = new Date().toISOString();
+    state.completedSteps = Array.from(new Set([...state.completedSteps, 'verify']));
+    state.artifacts.verifyResult = true;
+    await recordDecision(state, paths.taskDir, {
+        time: state.lastUpdated,
+        step: 'verify',
+        fromStatus: previousStatus,
+        toStatus: 'active',
+        reason: detail?.reason ?? 'verify completed but goal audit still pending',
+        evidence: detail?.evidence ?? 'artifacts/验证结果.md',
+    });
+    await saveWorkflowState(paths.statePath, state);
+}
+export async function markSpecCompleted(repoRoot, taskId) {
+    const paths = getTaskPaths(repoRoot, taskId);
+    const state = await loadWorkflowState(paths.statePath);
+    const previousStatus = state.status;
+    state.sourceState = await computeSourceState(paths.sourceDir, state.sourceState);
+    state.status = 'active';
+    state.currentStep = 'implement';
+    state.lastUpdated = new Date().toISOString();
+    state.completedSteps = Array.from(new Set([...state.completedSteps, 'spec', 'analyze', 'plan']));
+    state.artifacts.analysis = true;
+    state.artifacts.plan = true;
+    state.sourceState.plannedHash = state.sourceState.currentHash;
+    state.sourceState.lastPlannedAt = state.lastUpdated;
+    state.sourceState.lastPlannedStep = 'spec';
+    state.sourceState.stalePlan = false;
+    await recordDecision(state, paths.taskDir, {
+        time: state.lastUpdated,
+        step: 'spec',
+        fromStatus: previousStatus,
+        toStatus: 'active',
+        reason: 'spec completed and refreshed plan baseline',
+        evidence: 'artifacts/分析报告.md + artifacts/实现计划.md',
+    });
+    await saveWorkflowState(paths.statePath, state);
+}
+async function updateStepCompletion(repoRoot, taskId, step, completeTask, detail) {
+    const paths = getTaskPaths(repoRoot, taskId);
+    const state = await loadWorkflowState(paths.statePath);
+    const previousStatus = state.status;
+    const nextStep = getNextStep(step);
+    state.sourceState = await computeSourceState(paths.sourceDir, state.sourceState);
+    state.status = step === 'retrospective' || completeTask ? 'completed' : 'active';
+    state.currentStep = nextStep;
+    state.lastUpdated = new Date().toISOString();
+    state.completedSteps = Array.from(new Set([...state.completedSteps, step]));
+    if (step !== 'spec') {
+        state.artifacts[ARTIFACT_KEY_BY_STEP[step]] = true;
+    }
+    if (PLANNING_STEPS.has(step)) {
+        state.sourceState.plannedHash = state.sourceState.currentHash;
+        state.sourceState.lastPlannedAt = state.lastUpdated;
+        state.sourceState.lastPlannedStep = step === 'spec' ? 'spec' : 'plan';
+        state.sourceState.stalePlan = false;
+    }
+    await recordDecision(state, paths.taskDir, {
+        time: state.lastUpdated,
+        step,
+        fromStatus: previousStatus,
+        toStatus: state.status,
+        reason: detail?.reason ?? `step ${step} completed`,
+        evidence: detail?.evidence ?? artifactEvidenceForStep(step),
+    });
+    await saveWorkflowState(paths.statePath, state);
+    if (completeTask) {
+        const { cleanupWorktreeAfterTaskCompleted } = await import('./worktree-cleanup.js');
+        await cleanupWorktreeAfterTaskCompleted(repoRoot, taskId).catch(() => {
+            /* best-effort; errors logged in worktree cleanup */
+        });
+    }
+}
+export function resolveTaskFlow(taskConfig) {
+    if (taskConfig.flow !== 'auto') {
+        return taskConfig.flow;
+    }
+    if (taskConfig.taskKind === 'feature-study') {
+        return 'feature-study';
+    }
+    return taskConfig.complexity === 'small' ? 'micro' : 'standard';
+}
+export function shouldRunRetrospective(taskConfig) {
+    return taskConfig.requireRetrospective || taskConfig.complexity === 'large' || resolveTaskFlow(taskConfig) === 'loop';
+}
+export async function getTaskGoal(repoRoot, taskId) {
+    const state = await getTaskStatus(repoRoot, taskId);
+    return state.goal;
+}
+export async function setTaskGoal(repoRoot, taskId, objective, options) {
+    const paths = getTaskPaths(repoRoot, taskId);
+    const state = await loadWorkflowState(paths.statePath);
+    const now = new Date().toISOString();
+    const normalizedObjective = objective.trim();
+    if (!normalizedObjective) {
+        throw new Error('goal objective cannot be empty');
+    }
+    const nextStatus = options?.status ?? 'active';
+    taskGoalStatusSchema.parse(nextStatus);
+    state.goal = {
+        objective: normalizedObjective,
+        status: nextStatus,
+        tokenBudget: options?.tokenBudget ?? state.goal.tokenBudget ?? null,
+        tokensUsed: state.goal.tokensUsed ?? 0,
+        timeUsedSeconds: state.goal.timeUsedSeconds ?? 0,
+        pendingObjectiveUpdatedNotice: Boolean(state.goal.objective) && state.goal.objective !== normalizedObjective,
+        pendingBudgetLimitNotice: false,
+        continuationRuns: 0,
+        createdAt: state.goal.createdAt || now,
+        updatedAt: now,
+    };
+    state.lastUpdated = now;
+    await saveWorkflowState(paths.statePath, state);
+    await appendWorkflowLog(paths.taskDir, `goal set status=${state.goal.status} budget=${state.goal.tokenBudget ?? 'none'} objective=${summarize(state.goal.objective)}`);
+    await appendGoalEventRecord(paths.taskDir, {
+        event: 'external_set',
+        goalStatus: state.goal.status,
+        objective: summarize(state.goal.objective),
+        at: now,
+        details: {
+            tokenBudget: state.goal.tokenBudget,
+            replacedObjective: Boolean(state.goal.pendingObjectiveUpdatedNotice),
+        },
+    });
+    return state.goal;
+}
+export async function updateTaskGoalStatus(repoRoot, taskId, status) {
+    const paths = getTaskPaths(repoRoot, taskId);
+    const state = await loadWorkflowState(paths.statePath);
+    const now = new Date().toISOString();
+    taskGoalStatusSchema.parse(status);
+    if (!state.goal.objective) {
+        throw new Error('goal is not set for this task');
+    }
+    state.goal.status = status;
+    state.goal.updatedAt = now;
+    state.lastUpdated = now;
+    await saveWorkflowState(paths.statePath, state);
+    await appendWorkflowLog(paths.taskDir, `goal status updated to ${status}`);
+    await appendGoalEventRecord(paths.taskDir, {
+        event: 'status_updated',
+        goalStatus: state.goal.status,
+        objective: summarize(state.goal.objective),
+        at: now,
+    });
+    return state.goal;
+}
+export async function clearTaskGoal(repoRoot, taskId) {
+    const paths = getTaskPaths(repoRoot, taskId);
+    const state = await loadWorkflowState(paths.statePath);
+    const now = new Date().toISOString();
+    state.goal = {
+        objective: '',
+        status: 'paused',
+        tokenBudget: null,
+        tokensUsed: 0,
+        timeUsedSeconds: 0,
+        pendingObjectiveUpdatedNotice: false,
+        pendingBudgetLimitNotice: false,
+        continuationRuns: 0,
+        createdAt: '',
+        updatedAt: now,
+    };
+    state.lastUpdated = now;
+    await saveWorkflowState(paths.statePath, state);
+    await appendWorkflowLog(paths.taskDir, 'goal cleared');
+    await appendGoalEventRecord(paths.taskDir, {
+        event: 'external_clear',
+        goalStatus: '',
+        objective: '',
+        at: now,
+    });
+}
+export async function incrementGoalContinuationRuns(repoRoot, taskId) {
+    const paths = getTaskPaths(repoRoot, taskId);
+    const state = await loadWorkflowState(paths.statePath);
+    if (!state.goal.objective) {
+        return state.goal;
+    }
+    const now = new Date().toISOString();
+    state.goal.continuationRuns += 1;
+    state.goal.updatedAt = now;
+    state.lastUpdated = now;
+    await saveWorkflowState(paths.statePath, state);
+    await appendWorkflowLog(paths.taskDir, `goal continuation run count=${state.goal.continuationRuns}`);
+    return state.goal;
+}
+export async function recordTaskGoalProgress(repoRoot, taskId, usage) {
+    const paths = getTaskPaths(repoRoot, taskId);
+    const state = await loadWorkflowState(paths.statePath);
+    if (!state.goal.objective) {
+        return state.goal;
+    }
+    const now = new Date().toISOString();
+    const tokenDelta = Math.max(0, Math.trunc(usage.tokensUsed ?? 0));
+    const timeDelta = Math.max(0, Math.trunc(usage.elapsedSeconds ?? 0));
+    state.goal.tokensUsed += tokenDelta;
+    state.goal.timeUsedSeconds += timeDelta;
+    state.goal.updatedAt = now;
+    let budgetLimitedTriggered = false;
+    if (state.goal.tokenBudget && state.goal.tokensUsed >= state.goal.tokenBudget && state.goal.status === 'active') {
+        state.goal.status = 'budget_limited';
+        state.goal.pendingBudgetLimitNotice = true;
+        budgetLimitedTriggered = true;
+    }
+    state.lastUpdated = now;
+    await saveWorkflowState(paths.statePath, state);
+    if (budgetLimitedTriggered) {
+        await appendGoalEventRecord(paths.taskDir, {
+            event: 'budget_limited',
+            goalStatus: state.goal.status,
+            objective: summarize(state.goal.objective),
+            at: now,
+            details: {
+                tokenBudget: state.goal.tokenBudget,
+                tokensUsed: state.goal.tokensUsed,
+            },
+        });
+    }
+    return state.goal;
+}
+export async function markTaskGoalComplete(repoRoot, taskId, options) {
+    const paths = getTaskPaths(repoRoot, taskId);
+    const state = await loadWorkflowState(paths.statePath);
+    if (!state.goal.objective)
+        return;
+    if (!options.completionAuditPassed) {
+        throw new Error('cannot mark goal complete without passing goal completion audit');
+    }
+    const now = new Date().toISOString();
+    state.goal.status = 'complete';
+    state.goal.pendingObjectiveUpdatedNotice = false;
+    state.goal.pendingBudgetLimitNotice = false;
+    state.goal.updatedAt = now;
+    state.lastUpdated = now;
+    await saveWorkflowState(paths.statePath, state);
+    await appendWorkflowLog(paths.taskDir, 'goal completed');
+    await appendGoalEventRecord(paths.taskDir, {
+        event: 'completed',
+        goalStatus: state.goal.status,
+        objective: summarize(state.goal.objective),
+        at: now,
+    });
+}
+export async function consumeTaskGoalNotices(repoRoot, taskId) {
+    const paths = getTaskPaths(repoRoot, taskId);
+    const state = await loadWorkflowState(paths.statePath);
+    const objectiveUpdated = state.goal.pendingObjectiveUpdatedNotice;
+    const budgetLimited = state.goal.pendingBudgetLimitNotice;
+    if (!objectiveUpdated && !budgetLimited) {
+        return { objectiveUpdated: false, budgetLimited: false };
+    }
+    state.goal.pendingObjectiveUpdatedNotice = false;
+    state.goal.pendingBudgetLimitNotice = false;
+    state.goal.updatedAt = new Date().toISOString();
+    state.lastUpdated = state.goal.updatedAt;
+    await saveWorkflowState(paths.statePath, state);
+    await appendGoalEventRecord(paths.taskDir, {
+        event: 'notices_consumed',
+        goalStatus: state.goal.status,
+        objective: summarize(state.goal.objective),
+        at: state.goal.updatedAt,
+        details: {
+            objectiveUpdated,
+            budgetLimited,
+        },
+    });
+    return { objectiveUpdated, budgetLimited };
+}
+function artifactEvidenceForStep(step) {
+    if (step === 'analyze')
+        return 'artifacts/分析报告.md';
+    if (step === 'plan')
+        return 'artifacts/实现计划.md';
+    if (step === 'implement')
+        return 'artifacts/修改记录.md';
+    if (step === 'verify')
+        return 'artifacts/验证结果.md';
+    if (step === 'retrospective')
+        return 'artifacts/复盘报告.md';
+    return '';
+}
+function summarize(text) {
+    return text.replace(/\s+/g, ' ').trim().slice(0, 120);
+}
+async function recordDecision(state, taskDir, decision) {
+    state.decisionLog = [...state.decisionLog, decision].slice(-MAX_DECISION_LOG_ENTRIES);
+    await appendDecisionRecord(taskDir, decision);
+}
+async function computeSourceState(sourceDir, previous) {
+    const files = await listFilesRecursive(sourceDir);
+    const relativeFiles = files.map((file) => path.relative(sourceDir, file).replace(/\\/g, '/'));
+    const hash = createHash('sha256');
+    for (const file of files) {
+        const relative = path.relative(sourceDir, file).replace(/\\/g, '/');
+        const content = await readFile(file, 'utf-8');
+        const normalizedContent = normalizeSourceContentForHash(relative, content);
+        hash.update(relative);
+        hash.update('\n');
+        hash.update(normalizedContent);
+        hash.update('\n---\n');
+    }
+    const currentHash = relativeFiles.length > 0 ? hash.digest('hex') : '';
+    const plannedHash = previous?.plannedHash ?? '';
+    return {
+        currentHash,
+        plannedHash,
+        trackedFiles: relativeFiles,
+        lastCheckedAt: new Date().toISOString(),
+        lastPlannedAt: previous?.lastPlannedAt ?? '',
+        lastPlannedStep: previous?.lastPlannedStep ?? null,
+        stalePlan: Boolean(plannedHash) && plannedHash !== currentHash,
+    };
+}
+function normalizeSourceContentForHash(relativePath, content) {
+    if (relativePath === '需求.md') {
+        return content.replace(/-\s*\[[ xX]\]/g, '- [ ]');
+    }
+    return content;
+}
+async function listFilesRecursive(dir) {
+    let entries;
+    try {
+        entries = await readdir(dir, { withFileTypes: true });
+    }
+    catch {
+        return [];
+    }
+    const nested = await Promise.all(entries.map(async (entry) => {
+        const target = path.join(dir, entry.name);
+        if (entry.isDirectory())
+            return listFilesRecursive(target);
+        return [target];
+    }));
+    return nested.flat().sort();
+}