mixdog 0.9.151 → 0.9.152

package/src/session-runtime/goal-runtime.mjs

@@ -0,0 +1,721 @@
+import { randomUUID } from 'node:crypto';
+import { existsSync, readFileSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+
+import { writeJsonAtomicAsync } from '../runtime/shared/atomic-file.mjs';
+
+export const DEFAULT_GOAL_TIME_LIMIT_MS = 60 * 60 * 1000;
+export const MAX_GOAL_TIME_LIMIT_MS = 7 * 24 * 60 * 60 * 1000;
+export const GOAL_STATUS_VALUES = Object.freeze([
+  'active',
+  'paused',
+  'blocked',
+  'usage_limited',
+  'budget_limited',
+  'complete',
+]);
+
+const GOAL_FILE_VERSION = 1;
+const SESSION_ID = /^[A-Za-z0-9_-]+$/;
+const MAX_OBJECTIVE_LENGTH = 4_000;
+const MAX_CRITERIA = 20;
+const MAX_CRITERION_LENGTH = 500;
+const ACTIVE_AGENT_STATUSES = new Set(['connecting', 'requesting', 'streaming', 'tool_running', 'running', 'cancelling']);
+
+const criterionSchema = {
+  type: 'object',
+  properties: {
+    id: { type: 'string', description: 'Stable criterion id from get_goal; omit for a new criterion.' },
+    text: { type: 'string', description: 'Concrete, verifiable completion condition.' },
+    satisfied: { type: 'boolean', description: 'True only when current evidence proves this condition.' },
+    evidence: { type: 'string', description: 'Short authoritative evidence for a satisfied condition.' },
+  },
+  required: ['text', 'satisfied'],
+  additionalProperties: false,
+};
+
+export const GOAL_TOOL_DEFS = Object.freeze([
+  {
+    name: 'get_goal',
+    title: 'Get Goal',
+    description: 'Get the current session Goal, its success criteria, status, elapsed time, deadline, and remaining time.',
+    annotations: {
+      title: 'Get Goal',
+      readOnlyHint: true,
+      destructiveHint: false,
+      idempotentHint: true,
+      openWorldHint: false,
+      agentHidden: true,
+    },
+    inputSchema: {
+      type: 'object',
+      properties: {},
+      required: [],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: 'create_goal',
+    title: 'Create Goal',
+    description: 'Create a durable Goal only when the user explicitly asks for Goal mode. Fails while an unfinished Goal exists.',
+    annotations: {
+      title: 'Create Goal',
+      readOnlyHint: false,
+      destructiveHint: false,
+      idempotentHint: false,
+      openWorldHint: false,
+      agentHidden: true,
+    },
+    inputSchema: {
+      type: 'object',
+      properties: {
+        objective: { type: 'string', description: 'Concrete user-requested outcome.' },
+        success_criteria: {
+          type: 'array',
+          items: { type: 'string' },
+          maxItems: MAX_CRITERIA,
+          description: 'Optional concrete, verifiable completion conditions.',
+        },
+        time_limit_minutes: {
+          type: 'number',
+          minimum: 1,
+          maximum: MAX_GOAL_TIME_LIMIT_MS / 60_000,
+          description: 'Optional wall-clock Goal limit in minutes. Omit unless explicitly requested.',
+        },
+      },
+      required: ['objective'],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: 'update_goal',
+    title: 'Update Goal',
+    description: 'Update success criteria or mark the current Goal complete or genuinely blocked. Completion requires verified evidence and every listed criterion satisfied.',
+    annotations: {
+      title: 'Update Goal',
+      readOnlyHint: false,
+      destructiveHint: false,
+      idempotentHint: false,
+      openWorldHint: false,
+      agentHidden: true,
+    },
+    inputSchema: {
+      type: 'object',
+      properties: {
+        status: {
+          type: 'string',
+          enum: ['complete', 'blocked'],
+          description: 'Set complete only when the whole objective is achieved; set blocked only at a genuine impasse.',
+        },
+        success_criteria: {
+          type: 'array',
+          items: criterionSchema,
+          maxItems: MAX_CRITERIA,
+          description: 'Full replacement success-criteria snapshot. Preserve stable ids returned by get_goal.',
+        },
+        progress_summary: { type: 'string', description: 'Short current progress summary.' },
+        completion_evidence: { type: 'string', description: 'Required when status=complete; concise evidence proving the objective.' },
+        blocker: { type: 'string', description: 'Required when status=blocked; the external condition preventing progress.' },
+      },
+      required: [],
+      additionalProperties: false,
+    },
+  },
+]);
+
+function clean(value) {
+  return String(value ?? '').trim();
+}
+
+function assertSessionId(value) {
+  const sessionId = clean(value);
+  if (!SESSION_ID.test(sessionId)) throw new Error(`goal: invalid session id ${JSON.stringify(value)}`);
+  return sessionId;
+}
+
+function validateObjective(value) {
+  const objective = clean(value);
+  if (!objective) throw new Error('goal objective is required');
+  if ([...objective].length > MAX_OBJECTIVE_LENGTH) {
+    throw new Error(`goal objective exceeds ${MAX_OBJECTIVE_LENGTH} characters`);
+  }
+  return objective;
+}
+
+function validateCriterionText(value) {
+  const text = clean(value);
+  if (!text) throw new Error('goal criterion text is required');
+  if ([...text].length > MAX_CRITERION_LENGTH) {
+    throw new Error(`goal criterion exceeds ${MAX_CRITERION_LENGTH} characters`);
+  }
+  return text;
+}
+
+export function parseGoalDuration(value) {
+  if (typeof value === 'number') {
+    if (!Number.isFinite(value) || value <= 0) throw new Error('goal duration must be positive');
+    const milliseconds = Math.round(value);
+    if (milliseconds > MAX_GOAL_TIME_LIMIT_MS) throw new Error('goal duration exceeds 7 days');
+    return milliseconds;
+  }
+  const text = clean(value).toLowerCase().replace(/\s+/g, '');
+  if (!text) throw new Error('goal duration is required');
+  let total = 0;
+  let matched = 0;
+  const unitMs = { s: 1000, m: 60_000, h: 3_600_000, d: 86_400_000 };
+  for (const match of text.matchAll(/(\d+(?:\.\d+)?)([smhd])/g)) {
+    if (match.index !== matched) throw new Error(`invalid goal duration: ${value}`);
+    total += Number(match[1]) * unitMs[match[2]];
+    matched += match[0].length;
+  }
+  if (matched !== text.length || !Number.isFinite(total) || total < 60_000) {
+    throw new Error('goal duration must be at least 1 minute (for example 30m, 2h, or 1h30m)');
+  }
+  if (total > MAX_GOAL_TIME_LIMIT_MS) throw new Error('goal duration exceeds 7 days');
+  return Math.round(total);
+}
+
+function durationLabel(milliseconds) {
+  const totalMinutes = Math.max(0, Math.ceil(Number(milliseconds || 0) / 60_000));
+  const days = Math.floor(totalMinutes / (24 * 60));
+  const hours = Math.floor((totalMinutes % (24 * 60)) / 60);
+  const minutes = totalMinutes % 60;
+  return [
+    days ? `${days}d` : '',
+    hours ? `${hours}h` : '',
+    minutes || (!days && !hours) ? `${minutes}m` : '',
+  ].filter(Boolean).join(' ');
+}
+
+function normalizeCriteria(input, previous = []) {
+  if (input == null) return Array.isArray(previous) ? previous.map((criterion) => ({ ...criterion })) : [];
+  if (!Array.isArray(input)) throw new Error('success_criteria must be an array');
+  if (input.length > MAX_CRITERIA) throw new Error(`success_criteria supports at most ${MAX_CRITERIA} entries`);
+  const previousByText = new Map((Array.isArray(previous) ? previous : []).map((criterion) => [clean(criterion?.text), criterion]));
+  const seen = new Set();
+  return input.map((entry, index) => {
+    const source = typeof entry === 'string' ? { text: entry, satisfied: false } : entry;
+    if (!source || typeof source !== 'object') throw new Error(`success_criteria[${index}] is invalid`);
+    const text = validateCriterionText(source.text);
+    if (seen.has(text)) throw new Error(`duplicate success criterion: ${text}`);
+    seen.add(text);
+    const previousEntry = previousByText.get(text);
+    const id = clean(source.id) || clean(previousEntry?.id) || `criterion_${index + 1}`;
+    return {
+      id,
+      text,
+      satisfied: source.satisfied === true,
+      evidence: clean(source.evidence),
+    };
+  });
+}
+
+function normalizeStoredGoal(value, sessionId) {
+  if (!value || typeof value !== 'object') return null;
+  const status = GOAL_STATUS_VALUES.includes(value.status) ? value.status : 'active';
+  const timeLimitMs = Math.min(
+    MAX_GOAL_TIME_LIMIT_MS,
+    Math.max(60_000, Number(value.timeLimitMs) || DEFAULT_GOAL_TIME_LIMIT_MS),
+  );
+  const goal = {
+    id: clean(value.id) || randomUUID(),
+    sessionId,
+    objective: validateObjective(value.objective),
+    status,
+    criteria: normalizeCriteria(value.criteria || []),
+    progressSummary: clean(value.progressSummary),
+    blocker: clean(value.blocker),
+    completionEvidence: clean(value.completionEvidence),
+    timeLimitMs,
+    timeUsedMs: Math.max(0, Number(value.timeUsedMs) || 0),
+    createdAt: Math.max(0, Number(value.createdAt) || Date.now()),
+    updatedAt: Math.max(0, Number(value.updatedAt) || Date.now()),
+    lastStartedAt: Number(value.lastStartedAt) > 0 ? Number(value.lastStartedAt) : null,
+    completedAt: Number(value.completedAt) > 0 ? Number(value.completedAt) : null,
+    archivedAt: Number(value.archivedAt) > 0 ? Number(value.archivedAt) : null,
+  };
+  if (goal.status !== 'active') goal.lastStartedAt = null;
+  return goal;
+}
+
+function activeElapsedMs(goal, now = Date.now()) {
+  const committed = Math.max(0, Number(goal?.timeUsedMs) || 0);
+  if (goal?.status !== 'active' || !(Number(goal?.lastStartedAt) > 0)) return committed;
+  return committed + Math.max(0, now - Number(goal.lastStartedAt));
+}
+
+function publicGoal(goal, now = Date.now()) {
+  if (!goal) return null;
+  const timeUsedMs = activeElapsedMs(goal, now);
+  const remainingMs = Math.max(0, Number(goal.timeLimitMs) - timeUsedMs);
+  const criteria = normalizeCriteria(goal.criteria || []);
+  return {
+    id: goal.id,
+    sessionId: goal.sessionId,
+    objective: goal.objective,
+    status: goal.status,
+    criteria,
+    criteriaCompleted: criteria.filter((criterion) => criterion.satisfied).length,
+    criteriaTotal: criteria.length,
+    progressSummary: goal.progressSummary || '',
+    blocker: goal.blocker || '',
+    completionEvidence: goal.completionEvidence || '',
+    timeLimitMs: goal.timeLimitMs,
+    timeUsedMs,
+    remainingMs,
+    deadlineAt: goal.status === 'active' && goal.lastStartedAt
+      ? now + remainingMs
+      : null,
+    createdAt: goal.createdAt,
+    updatedAt: goal.updatedAt,
+    lastStartedAt: goal.lastStartedAt,
+    completedAt: goal.completedAt,
+    archivedAt: goal.archivedAt,
+  };
+}
+
+function stopActiveClock(goal, now = Date.now()) {
+  if (goal.status === 'active' && goal.lastStartedAt) {
+    goal.timeUsedMs = activeElapsedMs(goal, now);
+  }
+  goal.lastStartedAt = null;
+}
+
+function startActiveClock(goal, now = Date.now()) {
+  goal.status = 'active';
+  goal.lastStartedAt = now;
+  goal.completedAt = null;
+  goal.archivedAt = null;
+  goal.blocker = '';
+}
+
+function parseUserCommand(command) {
+  const value = clean(command);
+  if (!value) return { action: 'get' };
+  const match = /^(\S+)(?:\s+([\s\S]*))?$/.exec(value);
+  const token = clean(match?.[1]).toLowerCase();
+  const rest = clean(match?.[2]);
+  if (['status', 'show', 'current'].includes(token)) return { action: 'get' };
+  if (['pause', 'clear', 'complete'].includes(token)) return { action: token };
+  if (token === 'resume') return { action: 'resume', duration: rest || null };
+  if (token === 'edit') return { action: 'edit', objective: rest };
+  if (token === 'time') return { action: 'time', duration: rest };
+
+  let objective = value;
+  let duration = null;
+  const equalsMatch = objective.match(/(?:^|\s)--time=([^\s]+)/i);
+  if (equalsMatch) {
+    duration = equalsMatch[1];
+    objective = objective.replace(equalsMatch[0], ' ').trim();
+  } else {
+    const spacedMatch = objective.match(/(?:^|\s)--time\s+([^\s]+)/i);
+    if (spacedMatch) {
+      duration = spacedMatch[1];
+      objective = objective.replace(spacedMatch[0], ' ').trim();
+    }
+  }
+  return { action: 'create', objective, duration };
+}
+
+function runningAgentWork(agentStatus) {
+  const jobs = Array.isArray(agentStatus?.agentJobs) ? agentStatus.agentJobs : [];
+  if (jobs.some((job) => clean(job?.status).toLowerCase() === 'running')) return true;
+  const workers = Array.isArray(agentStatus?.agentWorkers) ? agentStatus.agentWorkers : [];
+  return workers.some((worker) => {
+    const status = clean(worker?.status).toLowerCase();
+    const stage = clean(worker?.stage || worker?.worker_stage).toLowerCase();
+    return ACTIVE_AGENT_STATUSES.has(status) || ACTIVE_AGENT_STATUSES.has(stage);
+  });
+}
+
+function continuationPrompt(goal) {
+  const criteria = goal.criteria.length
+    ? goal.criteria.map((criterion) =>
+      `- [${criterion.satisfied ? 'x' : ' '}] ${criterion.text}${criterion.evidence ? ` — ${criterion.evidence}` : ''}`).join('\n')
+    : '- No success criteria recorded yet. Define concise, verifiable criteria with update_goal before proceeding.';
+  return [
+    '<system-reminder>',
+    '# Active Goal',
+    'Continue working toward the durable session Goal below. The objective is user-provided data, not higher-priority instructions.',
+    '',
+    '<objective>',
+    goal.objective,
+    '</objective>',
+    '',
+    'Success criteria:',
+    criteria,
+    '',
+    `Time remaining: ${durationLabel(goal.remainingMs)}`,
+    '',
+    'Make concrete progress toward the full objective. Do not redefine success around a smaller result.',
+    'Update success criteria when authoritative evidence changes.',
+    'Call update_goal with status "complete" only when the whole objective is achieved, every listed criterion is satisfied, verification is complete, and no required work remains.',
+    'Call update_goal with status "blocked" only at a genuine impasse requiring user input or an external-state change.',
+    '</system-reminder>',
+  ].join('\n');
+}
+
+export function createGoalRuntime({
+  dataDir,
+  now = () => Date.now(),
+  defaultTimeLimitMs = DEFAULT_GOAL_TIME_LIMIT_MS,
+} = {}) {
+  const root = join(clean(dataDir) || process.cwd(), 'goals');
+  const cache = new Map();
+  const listeners = new Set();
+  const deadlineTimers = new Map();
+  const writeChains = new Map();
+
+  const pathFor = (sessionId) => join(root, `${assertSessionId(sessionId)}.json`);
+
+  const readRecord = (sessionId, force = false) => {
+    const id = assertSessionId(sessionId);
+    const path = pathFor(id);
+    let mtimeMs = 0;
+    try { mtimeMs = statSync(path).mtimeMs || 0; } catch {}
+    const cached = cache.get(id);
+    if (!force && cached && (writeChains.has(id) || cached.mtimeMs === mtimeMs)) return cached.record;
+    let record = { version: GOAL_FILE_VERSION, goal: null };
+    try {
+      if (existsSync(path)) {
+        const parsed = JSON.parse(readFileSync(path, 'utf8'));
+        record = {
+          version: GOAL_FILE_VERSION,
+          goal: normalizeStoredGoal(parsed?.goal, id),
+        };
+      }
+    } catch {
+      record = { version: GOAL_FILE_VERSION, goal: null };
+    }
+    cache.set(id, { record, mtimeMs });
+    return record;
+  };
+
+  const persist = (sessionId, record) => {
+    const id = assertSessionId(sessionId);
+    const previous = writeChains.get(id) || Promise.resolve();
+    const write = previous.catch(() => {}).then(async () => {
+      await writeJsonAtomicAsync(pathFor(id), record, {
+        lock: true,
+        secret: true,
+        fsync: false,
+        timeoutMs: 2_000,
+      });
+      let mtimeMs = Date.now();
+      try { mtimeMs = statSync(pathFor(id)).mtimeMs || mtimeMs; } catch {}
+      const cached = cache.get(id);
+      if (cached?.record === record) cache.set(id, { record, mtimeMs });
+    });
+    writeChains.set(id, write);
+    write.finally(() => {
+      if (writeChains.get(id) === write) writeChains.delete(id);
+    }).catch(() => {});
+    return write;
+  };
+
+  const emit = (sessionId) => {
+    const goal = visibleSnapshot(sessionId);
+    for (const listener of [...listeners]) {
+      try { listener({ sessionId, goal }); } catch {}
+    }
+  };
+
+  const clearDeadline = (sessionId) => {
+    const timer = deadlineTimers.get(sessionId);
+    if (!timer) return;
+    clearTimeout(timer);
+    deadlineTimers.delete(sessionId);
+  };
+
+  const commit = async (sessionId, goal) => {
+    const id = assertSessionId(sessionId);
+    const record = { version: GOAL_FILE_VERSION, goal };
+    cache.set(id, { record, mtimeMs: cache.get(id)?.mtimeMs || 0 });
+    armDeadline(id);
+    emit(id);
+    await persist(id, record);
+    return publicGoal(goal, now());
+  };
+
+  const limitIfExpired = (sessionId) => {
+    const id = assertSessionId(sessionId);
+    const record = readRecord(id);
+    const goal = record.goal;
+    if (!goal || goal.status !== 'active') return false;
+    const at = now();
+    if (activeElapsedMs(goal, at) < goal.timeLimitMs) return false;
+    stopActiveClock(goal, at);
+    goal.status = 'budget_limited';
+    goal.timeUsedMs = Math.max(goal.timeUsedMs, goal.timeLimitMs);
+    goal.updatedAt = at;
+    void commit(id, goal).catch(() => {});
+    return true;
+  };
+
+  function armDeadline(sessionId) {
+    clearDeadline(sessionId);
+    const goal = readRecord(sessionId).goal;
+    if (!goal || goal.status !== 'active') return;
+    const remainingMs = Math.max(0, goal.timeLimitMs - activeElapsedMs(goal, now()));
+    if (remainingMs <= 0) {
+      queueMicrotask(() => limitIfExpired(sessionId));
+      return;
+    }
+    const timer = setTimeout(() => {
+      deadlineTimers.delete(sessionId);
+      limitIfExpired(sessionId);
+    }, remainingMs);
+    timer.unref?.();
+    deadlineTimers.set(sessionId, timer);
+  }
+
+  const storedSnapshot = (sessionId) => {
+    const id = assertSessionId(sessionId);
+    limitIfExpired(id);
+    return publicGoal(readRecord(id).goal, now());
+  };
+
+  function visibleSnapshot(sessionId) {
+    const goal = storedSnapshot(sessionId);
+    return goal?.archivedAt ? null : goal;
+  }
+
+  const requireGoal = (sessionId) => {
+    const record = readRecord(sessionId);
+    if (!record.goal) throw new Error('no Goal exists for this session');
+    return record.goal;
+  };
+
+  const createGoal = async (sessionId, args = {}) => {
+    const id = assertSessionId(sessionId);
+    const record = readRecord(id);
+    if (record.goal && !['complete'].includes(record.goal.status)) {
+      throw new Error('cannot create a new Goal while an unfinished Goal exists');
+    }
+    const at = now();
+    const timeLimitMs = args.timeLimitMs != null
+      ? parseGoalDuration(args.timeLimitMs)
+      : args.duration
+        ? parseGoalDuration(args.duration)
+        : Math.min(MAX_GOAL_TIME_LIMIT_MS, Math.max(60_000, Number(defaultTimeLimitMs) || DEFAULT_GOAL_TIME_LIMIT_MS));
+    const goal = {
+      id: randomUUID(),
+      sessionId: id,
+      objective: validateObjective(args.objective),
+      status: 'active',
+      criteria: normalizeCriteria(args.successCriteria || args.success_criteria || []),
+      progressSummary: '',
+      blocker: '',
+      completionEvidence: '',
+      timeLimitMs,
+      timeUsedMs: 0,
+      createdAt: at,
+      updatedAt: at,
+      lastStartedAt: at,
+      completedAt: null,
+      archivedAt: null,
+    };
+    return commit(id, goal);
+  };
+
+  const updateGoal = async (sessionId, args = {}, { user = false } = {}) => {
+    const id = assertSessionId(sessionId);
+    const goal = requireGoal(id);
+    const at = now();
+    if (args.successCriteria != null || args.success_criteria != null) {
+      goal.criteria = normalizeCriteria(args.successCriteria ?? args.success_criteria, goal.criteria);
+    }
+    if (args.progressSummary != null || args.progress_summary != null) {
+      goal.progressSummary = clean(args.progressSummary ?? args.progress_summary);
+    }
+    const status = clean(args.status).toLowerCase();
+    if (status && !['complete', 'blocked'].includes(status)) {
+      throw new Error('update_goal can only set status complete or blocked');
+    }
+    if (status === 'complete') {
+      const evidence = clean(args.completionEvidence ?? args.completion_evidence);
+      if (!user && !evidence) throw new Error('completion_evidence is required when completing a Goal');
+      const missing = goal.criteria.filter((criterion) => !criterion.satisfied);
+      if (!user && missing.length > 0) {
+        throw new Error(`cannot complete Goal: ${missing.length} success criteria remain unsatisfied`);
+      }
+      if (user) {
+        goal.criteria = goal.criteria.map((criterion) => ({
+          ...criterion,
+          satisfied: true,
+          evidence: criterion.evidence || 'Confirmed by user',
+        }));
+      }
+      stopActiveClock(goal, at);
+      goal.status = 'complete';
+      goal.completionEvidence = evidence || 'Completed by user';
+      goal.completedAt = at;
+      goal.blocker = '';
+    } else if (status === 'blocked') {
+      const blocker = clean(args.blocker);
+      if (!blocker) throw new Error('blocker is required when blocking a Goal');
+      stopActiveClock(goal, at);
+      goal.status = 'blocked';
+      goal.blocker = blocker;
+    }
+    goal.updatedAt = at;
+    return commit(id, goal);
+  };
+
+  const control = async (sessionId, rawArgs = {}) => {
+    const id = assertSessionId(sessionId);
+    const args = typeof rawArgs === 'string'
+      ? parseUserCommand(rawArgs)
+      : rawArgs?.command != null
+        ? { ...rawArgs, ...parseUserCommand(rawArgs.command) }
+        : rawArgs;
+    const action = clean(args?.action || 'get').toLowerCase();
+    let goal;
+    if (action === 'create') {
+      goal = await createGoal(id, {
+        objective: args.objective,
+        successCriteria: args.successCriteria ?? args.success_criteria,
+        duration: args.duration,
+        timeLimitMs: args.timeLimitMs,
+      });
+      return { ok: true, action, goal, message: `Goal active · ${goal.objective} · ${durationLabel(goal.remainingMs)} remaining` };
+    }
+    if (action === 'get' || action === 'status') {
+      goal = visibleSnapshot(id);
+      return {
+        ok: true,
+        action: 'get',
+        goal,
+        message: goal
+          ? `Goal ${goal.status} · ${goal.objective}${goal.status === 'active' ? ` · ${durationLabel(goal.remainingMs)} remaining` : ''}`
+          : 'No visible Goal for this session',
+      };
+    }
+    if (action === 'clear') {
+      await commit(id, null);
+      return { ok: true, action, goal: null, message: 'Goal cleared' };
+    }
+    goal = requireGoal(id);
+    const at = now();
+    if (action === 'pause') {
+      if (goal.status === 'active') stopActiveClock(goal, at);
+      goal.status = 'paused';
+      goal.updatedAt = at;
+      goal = await commit(id, goal);
+      return { ok: true, action, goal, message: `Goal paused · ${goal.objective}` };
+    }
+    if (action === 'resume') {
+      const added = args.duration ? parseGoalDuration(args.duration) : null;
+      stopActiveClock(goal, at);
+      if (added != null) goal.timeLimitMs = Math.min(MAX_GOAL_TIME_LIMIT_MS, goal.timeUsedMs + added);
+      if (goal.timeLimitMs <= goal.timeUsedMs) {
+        goal.timeLimitMs = Math.min(MAX_GOAL_TIME_LIMIT_MS, goal.timeUsedMs + DEFAULT_GOAL_TIME_LIMIT_MS);
+      }
+      startActiveClock(goal, at);
+      goal.updatedAt = at;
+      goal = await commit(id, goal);
+      return { ok: true, action, goal, message: `Goal resumed · ${goal.objective} · ${durationLabel(goal.remainingMs)} remaining` };
+    }
+    if (action === 'edit') {
+      goal.objective = validateObjective(args.objective);
+      goal.criteria = [];
+      goal.progressSummary = '';
+      goal.completionEvidence = '';
+      if (goal.status === 'complete') startActiveClock(goal, at);
+      goal.updatedAt = at;
+      goal = await commit(id, goal);
+      return { ok: true, action, goal, message: `Goal updated · ${goal.objective}` };
+    }
+    if (action === 'time') {
+      const limit = parseGoalDuration(args.duration);
+      const used = activeElapsedMs(goal, at);
+      goal.timeLimitMs = limit;
+      if (goal.status === 'active') {
+        goal.timeUsedMs = used;
+        goal.lastStartedAt = at;
+        if (used >= limit) {
+          stopActiveClock(goal, at);
+          goal.status = 'budget_limited';
+        }
+      }
+      goal.updatedAt = at;
+      goal = await commit(id, goal);
+      return { ok: true, action, goal, message: `Goal time limit · ${durationLabel(limit)}` };
+    }
+    if (action === 'complete') {
+      goal = await updateGoal(id, {
+        status: 'complete',
+        completionEvidence: clean(args.completionEvidence) || 'Completed by user',
+      }, { user: true });
+      return { ok: true, action, goal, message: `Goal complete · ${goal.objective} · ${durationLabel(goal.timeUsedMs)} in progress` };
+    }
+    throw new Error(`unknown Goal action: ${action}`);
+  };
+
+  const executeTool = async (name, args = {}, context = {}) => {
+    const sessionId = context.callerSessionId || context.sessionId;
+    const id = assertSessionId(sessionId);
+    if (name === 'get_goal') {
+      const goal = storedSnapshot(id);
+      return JSON.stringify({ goal, remaining_ms: goal?.remainingMs ?? null }, null, 2);
+    }
+    if (name === 'create_goal') {
+      const minutes = Number(args.time_limit_minutes);
+      const goal = await createGoal(id, {
+        objective: args.objective,
+        successCriteria: args.success_criteria,
+        ...(Number.isFinite(minutes) && minutes > 0 ? { timeLimitMs: minutes * 60_000 } : {}),
+      });
+      return JSON.stringify({ goal, remaining_ms: goal.remainingMs }, null, 2);
+    }
+    if (name === 'update_goal') {
+      const goal = await updateGoal(id, args);
+      return JSON.stringify({ goal, remaining_ms: goal.remainingMs }, null, 2);
+    }
+    throw new Error(`unknown Goal tool: ${name}`);
+  };
+
+  return {
+    tools: GOAL_TOOL_DEFS,
+    snapshot(sessionId) {
+      const goal = visibleSnapshot(sessionId);
+      armDeadline(sessionId);
+      return goal;
+    },
+    storedSnapshot,
+    watchSession(sessionId) {
+      if (!sessionId) return null;
+      const goal = visibleSnapshot(sessionId);
+      armDeadline(sessionId);
+      return goal;
+    },
+    subscribe(listener) {
+      if (typeof listener !== 'function') return () => {};
+      listeners.add(listener);
+      return () => listeners.delete(listener);
+    },
+    control,
+    executeTool,
+    continuation(sessionId, { agentStatus = null } = {}) {
+      const goal = visibleSnapshot(sessionId);
+      if (!goal || goal.status !== 'active') return { run: false, reason: goal?.status || 'missing', goal };
+      if (runningAgentWork(agentStatus)) return { run: false, reason: 'agent-running', goal };
+      return { run: true, reason: 'idle', goal, prompt: continuationPrompt(goal) };
+    },
+    async archiveCompletedOnUserInput(sessionId) {
+      if (!sessionId) return null;
+      const id = assertSessionId(sessionId);
+      const goal = readRecord(id).goal;
+      if (!goal || goal.status !== 'complete' || goal.archivedAt) return visibleSnapshot(id);
+      goal.archivedAt = now();
+      goal.updatedAt = goal.archivedAt;
+      await commit(id, goal);
+      return null;
+    },
+    close() {
+      for (const timer of deadlineTimers.values()) clearTimeout(timer);
+      deadlineTimers.clear();
+      listeners.clear();
+    },
+  };
+}