@arcfold/dsh 0.0.0-stage → 0.4.0

package/src/evidence-ownership.mjs

@@ -0,0 +1,51 @@
+import { constants, existsSync, fstatSync, realpathSync, statSync } from 'node:fs';
+import { mkdir, open, stat } from 'node:fs/promises';
+import { dirname, isAbsolute, join, relative, resolve } from 'node:path';
+
+const held = new WeakMap();
+export function canonicalEvidenceDirectory(directory) {
+  if (typeof directory !== 'string' || !isAbsolute(directory) || directory.includes('\0'))
+    throw new Error('An absolute evidence directory is required');
+  let ancestor = resolve(directory); const tail = [];
+  while (!existsSync(ancestor)) {
+    const parent = dirname(ancestor); tail.unshift(relative(parent, ancestor)); ancestor = parent;
+  }
+  return join(realpathSync(ancestor), ...tail);
+}
+
+/** One existing kernel lock, shared by provider startup and owned initialization. */
+export async function ownEvidenceDirectory(directory) {
+  if (process.platform === 'win32') throw new Error('The metered provider currently requires a POSIX host');
+  directory = canonicalEvidenceDirectory(directory);
+  await mkdir(directory, { recursive: true, mode: 0o700 });
+  const { tryLockExclusive } = await import('@deepseek-ai/node-addon-system/flock');
+  const path = join(directory, 'owner.lock');
+  for (let attempt = 0; attempt < 3; attempt++) {
+    const handle = await open(path, constants.O_RDWR | constants.O_CREAT | constants.O_NOFOLLOW, 0o600);
+    try {
+      await tryLockExclusive(handle.fd);
+      const current = await stat(path, { bigint: true }).catch(error => {
+        if (error.code === 'ENOENT') return null; throw error;
+      });
+      const info = await handle.stat({ bigint: true });
+      if (current && info.ino === current.ino && info.dev === current.dev) {
+        const record = { handle, path, directory, closed: false };
+        const owner = Object.freeze({ directory, async close() {
+          if (record.closed) return; record.closed = true; await handle.close();
+        } });
+        held.set(owner, record); return owner;
+      }
+    } catch (error) { await handle.close(); throw error; }
+    await handle.close();
+  }
+  throw new Error('The transport evidence directory changed while acquiring ownership');
+}
+
+export function assertEvidenceOwnership(owner, directory) {
+  const record = held.get(owner);
+  if (!record || record.closed || record.directory !== canonicalEvidenceDirectory(directory))
+    throw new Error('A live evidence-directory lease is required');
+  const info = fstatSync(record.handle.fd, { bigint: true }), current = statSync(record.path, { bigint: true });
+  if (info.ino !== current.ino || info.dev !== current.dev)
+    throw new Error('The held evidence-directory lease was replaced');
+}

package/src/evidence.mjs

@@ -0,0 +1,35 @@
+import { createHash } from 'node:crypto';
+
+export const hash = value => createHash('sha256').update(JSON.stringify(value)).digest('hex');
+export const unavailable = row => !row || row.deleted || row.withdrawn === true || row.useProhibited || ['withdrawn', 'superseded', 'rejected', 'paused'].includes(row.status);
+const atSequence = (row, cutoff) => Number.isSafeInteger(row?.createdSequence) && Number.isSafeInteger(row.updatedSequence) && row.createdSequence <= cutoff && row.updatedSequence <= cutoff;
+export const sourceText = row => typeof row.content === 'string' ? row.content : (row.message?.content || []).filter(block => block.type === 'text').map(block => block.text).join('\n');
+// Provider replay state belongs to the original native message/transport, not
+// to quoted evidence. Keep its persisted original and sourceRef hash untouched;
+// only omit the known opaque field from the model-facing provenance copy.
+export function evidenceProvenance(provenance) {
+  if (provenance?.kind === 'dsh_session' && provenance.source?.kind === 'model') {
+    const { replayState, ...source } = provenance.source;
+    return structuredClone({ ...provenance, source });
+  }
+  return structuredClone(provenance ?? null);
+}
+export const sourceAvailable = (store, row) => !unavailable(row) && !(store.get('source_controls', row.id)?.useProhibited || store.get('source_controls', row.id)?.withdrawn);
+
+// A record never outlives its originals or the exact dependency revisions it read.
+export function dependenciesCurrent(store, row, cutoff, path = new Set()) {
+  if (unavailable(row) || !atSequence(row, cutoff) || path.has(row.id)) return false;
+  const next = new Set([...path, row.id]);
+  for (const ref of row.dependencies || []) {
+    const kind = ref.kind || ['events', 'understandings', 'methods'].find(k => store.get(k, ref.id));
+    if (!['events', 'understandings', 'methods'].includes(kind)) return false;
+    const dependency = store.get(kind, ref.id);
+    if (unavailable(dependency) || dependency.revision !== ref.revision || !atSequence(dependency, cutoff)) return false;
+    if (kind === 'events' && !sourceAvailable(store, dependency)) return false;
+    if (kind !== 'events' && !dependenciesCurrent(store, dependency, cutoff, next)) return false;
+  }
+  return Array.isArray(row.sourceIds) && row.sourceIds.length > 0 && row.sourceIds.every(id => {
+    const source = store.get('events', id);
+    return sourceAvailable(store, source) && atSequence(source, cutoff);
+  });
+}

package/src/goal-context.mjs

@@ -0,0 +1,52 @@
+import { hash } from './evidence.mjs';
+import { canonicalJson } from './store.mjs';
+
+export const GOAL_CONTEXT = 'arcfold/linked-goal';
+export const GOAL_TOOL = 'arcfold_link_goal';
+const INTRO = '以下长期目标已由本轮主助手关联，程序已核对其版本与原件。本次贡献是助手的判断，不是用户认可或目标已实现的证明。联系只解释当前工作，不扩大委托或工具权限；暂停或结束追踪的目标只能在用户明确选回时讨论，不因此恢复追踪。来源失效时仅可依本次新原话重新澄清，不使用无效旧内容。\n';
+
+export function goalContextMessage(bundle) {
+  return { id: 'arcfold-goal-context-' + hash(bundle), role: 'user',
+    source: { kind: GOAL_CONTEXT, sessionId: bundle.sessionId, turn: bundle.turn,
+      startSeq: bundle.startSeq, linkIds: bundle.links.map(row => row.linkId) },
+    content: [{ type: 'text', text: INTRO + JSON.stringify(bundle) }] };
+}
+
+function receiptOf(event) {
+  if (event?.type !== 'tool/result' || event.data.message?.isError !== false || event.data.error ||
+      event.data.message.role !== 'tool' || event.data.message.source?.kind !== 'tool' ||
+      event.data.message.source.callId !== event.data.message.toolCallId) return null;
+  const blocks = event.data.message.content;
+  if (!Array.isArray(blocks) || blocks.some(block => block.type !== 'text')) return null;
+  try { return JSON.parse(blocks.map(block => block.text).join('')); } catch { return null; }
+}
+
+// The link core is immutable. A later native call can return the same link only
+// for the exact same selection; derive its success from actual call/result pairs.
+export function hasSuccessfulGoalReceipt(events, link) {
+  return events.filter(event => event.seq > link.startSeq && event.type === 'tool/call' &&
+    event.data.turn === link.turn && event.data.name === GOAL_TOOL).some(call => {
+    if (events.filter(event => event.type === 'tool/call' && event.data.callId === call.data.callId).length !== 1)
+      return false;
+    let args;
+    try { args = JSON.parse(call.data.arguments); } catch { return false; }
+    if (!args || Object.keys(args).length !== 1 || !Object.hasOwn(args, 'selection') ||
+        canonicalJson(args.selection) !== canonicalJson(link.selection)) return false;
+    const results = events.filter(event => event.seq > call.seq && event.type === 'tool/result' &&
+      event.data.turn === link.turn && event.data.step === call.data.step &&
+      event.data.message?.toolCallId === call.data.callId);
+    if (results.length !== 1) return false;
+    const receipt = receiptOf(results[0]);
+    return receipt?.linkId === link.id && receipt.goal?.id === link.goalId &&
+      receipt.goal.revision === link.goalRevision && receipt.goal.definitionVersion === link.definitionVersion &&
+      receipt.goal.contentHash === link.contentHash;
+  });
+}
+
+export function eligibleGoalBundle(goals, events, position) {
+  const bundle = goals.currentBundle(position);
+  return { ...bundle, links: bundle.links.filter(entry => {
+    const link = goals.store.get('goal_links', entry.linkId);
+    return link && hasSuccessfulGoalReceipt(events, link);
+  }) };
+}

package/src/goal-execution-tool.mjs

@@ -0,0 +1,74 @@
+import { defineTool } from '@deepseek-ai/dsh-tools';
+import { HarnessError } from '@deepseek-ai/dsh-llm';
+import { resolveNativeContextCall, belongsToSelectionBatch } from './native-context-call.mjs';
+import { STAGE_TOOLS } from './goal-execution.mjs';
+
+export const name = 'arcfold-goal-execution';
+export const inject = ['tools', 'agents', 'goals', 'arcfoldBridge', 'arcfoldWork', 'systemPrompt'];
+const reject = message => { throw new HarnessError(message, 'ARCFOLD_STAGE_CONTROL_INVALID'); };
+const string = description => ({ type: 'string', required: true, description });
+const reference = { goal_id: string('Current native work id returned by get_goal.'), revision: { type: 'integer', required: true } };
+const definition = {
+  objective: string('The concrete currently delegated stage, bounded by the current user request.'),
+  doneWhen: string('Observable results that complete this stage; reaching these ends its automatic execution.'),
+  boundaries: string('Scope, exclusions, and decisions that require waiting for the user.'),
+  max_goal_rounds: { type: 'integer', description: 'Optional automatic rounds for this stage, default 3, maximum 128.' },
+};
+
+export function apply(ctx) {
+  const work = ctx.arcfoldWork;
+  work.attach(ctx.root);
+  ctx.on('goal/changed', ({ agent, change }) => work.observeNative(agent, change));
+  ctx.on('agent/inbox/inserted', ({ agent, message }) => work.ownerArrived(agent, message));
+  ctx.on('agent/turn-stopping', ({ agent, turn }) => work.stopping(agent, turn));
+  ctx.tools.guard(exec => {
+    if (['create_goal', 'update_goal'].includes(exec.name)) return 'Use Arcfold stage controls; native goal mutation cannot authorize execution.';
+    try {
+      if (STAGE_TOOLS.some(name => belongsToSelectionBatch(exec, name))) {
+        const events = exec.agent?.session.snapshotEvents() ?? [];
+        const call = events.findLast(e => e.type === 'tool/call' && e.data.callId === exec.callId);
+        const assistant = call && events.findLast(e => e.seq < call.seq && e.type === 'assistant/message');
+        if (assistant?.data.message.content.filter(block => block.type === 'tool-call').length !== 1)
+          return 'Call Arcfold work control alone, then read its receipt before any other action.';
+      }
+      if (exec.agent) work.assertCurrent(exec.agent, { tools: true, name: exec.name });
+    } catch (error) { return error.message; }
+  });
+  ctx.systemPrompt.section({ name: 'arcfold:execution-control', order: 52, interpolate: false,
+    text: `Arcfold 统一目标推进，DSH 负责执行当前明确委托的阶段。长期方向、当前阶段和本轮步骤分别维护：已有目标与学习提供背景，todo_write展示本轮操作，阶段工具落实继续或等待。你是作这些判断的同一位主助手。
+用户只讨论方向、要求建立长期目标或共同拆解时，先交流并让后台整理长期目标。只有当前原话已委托可独立持续推进的具体工作，才单独调用 arcfold_start_work，写清当前阶段、可检查的完成条件、范围及须等待用户的决定。完成条件面向眼前阶段，避免把整个长期愿景作为当前执行范围。
+本轮行动完成后，按实际结果单独调用 arcfold_decide_work。当前阶段的完成条件已满足时用 complete，stageDone=true、needsUserDecision=false；后续阶段即使还需共同讨论，也先结束已经完成的当前阶段并保留长期方向。完成当前阶段仍需用户判断或当前应停下时用 wait；仅当同一阶段还有明确、可独立完成的工作时用 continue，并写清下一步。普通文字提问也要落实为 wait。提交决定后交代本轮结果。没有明确继续决定，程序会等待新输入。
+阶段修改依据本轮新用户要求，用 arcfold_revise_work；修改作废旧许可并保持停止，继续时再用 arcfold_resume_work。恢复只针对已有具体阶段。旧版本只有长期执行目标而缺少阶段时，先根据新的用户要求明确阶段。get_goal可查看现有执行和阶段。
+每次continue只许可下一轮；结果仍需核实，完成步骤不等于长期目标达成。阶段控制的内容判断由你负责，程序核对原话、来源、版本及许可。后台学习更新理解与进展，不签发执行许可。` });
+  const output = { schema: { type: 'json' }, render: (_args, value) => [{ type: 'text', text: JSON.stringify(value) }] };
+  ctx.tools.register(defineTool({ name: 'get_goal', description: 'Read current delegated execution and its Arcfold stage; this does not start work.',
+    parameters: {}, output, execute(_args, exec) {
+      if (!exec.agent || ctx.agents.get(exec.agent.id) !== exec.agent) reject('A live main session is required.');
+      return work.receipt(exec.agent);
+    }, presentCall: () => ({ card: 'generic', title: '查看当前阶段', kind: 'read' }) }));
+  for (const [name, revise] of [['arcfold_start_work', false], ['arcfold_revise_work', true]]) {
+    ctx.tools.register(defineTool({ name,
+      description: revise ? 'Revise the current bounded stage from a new direct user request. Invalidates continuation and keeps execution stopped until explicitly resumed. Call alone.'
+        : 'Start one concrete stage explicitly delegated by the current user. A long-term goal or discussion alone is not a running stage. Define completion and user-decision boundaries. Call alone; no automatic next round without arcfold_decide_work.',
+      parameters: { ...(revise ? reference : {}), ...definition }, output,
+      async execute(args, exec) {
+        const call = await resolveNativeContextCall(ctx, exec, reject);
+        if (call.batch.length !== 1) reject('Stage control must be a standalone tool call.');
+        exec.signal.throwIfAborted();
+        return work.start(call, args, revise);
+      }, presentCall: () => ({ card: 'generic', title: revise ? '调整当前阶段' : '明确当前阶段', kind: 'other' }) }));
+  }
+  ctx.tools.register(defineTool({ name: 'arcfold_decide_work',
+    description: 'After this turn\'s work, decide whether the current stage is complete, needs the user, or has a concrete independent next step. continue grants only the next round of the same stage. Call alone as your last action, then explain results.',
+    parameters: { ...reference, action: { type: 'string', required: true, enum: ['continue', 'wait', 'complete'] },
+      reason: string('Evidence and reasoning from this turn for the decision.'),
+      stageDone: { type: 'boolean', required: true, description: 'Whether this stage\'s completion conditions are met.' },
+      needsUserDecision: { type: 'boolean', required: true, description: 'Whether a user choice or information is still required to complete this CURRENT stage. Set false once this stage is complete, even when future stages await discussion.' },
+      nextStep: string('Concrete independent next step within this same stage for continue; empty for wait/complete.') }, output,
+    async execute(args, exec) {
+      const call = await resolveNativeContextCall(ctx, exec, reject);
+      if (call.batch.length !== 1) reject('Stage control must be a standalone tool call.');
+      exec.signal.throwIfAborted();
+      return work.decision(call, args);
+    }, presentCall: () => ({ card: 'generic', title: '确定下一步', kind: 'other' }) }));
+}

package/src/goal-execution.mjs

@@ -0,0 +1,333 @@
+import { canonicalJson, DomainError } from './store.mjs';
+import { hash, sourceAvailable, sourceText, dependenciesCurrent } from './evidence.mjs';
+import { nativeDefinitionHash, workId, workRelation } from './goal-work.mjs';
+
+const fail = message => { throw new DomainError('stage_control_required', message); };
+const same = (a, b) => canonicalJson(a) === canonicalJson(b);
+const owner = message => message?.role === 'user' && message.source?.kind === 'user' && message.source.principal === undefined;
+const stageId = (sessionId, goalId) => 'execution-stage-' + hash([sessionId, goalId]);
+const ref = goal => ({ id: goal.id, revision: goal.revision });
+const currentTurn = events => events.findLast(event => event.type === 'turn/start');
+const goalInput = (events, start) => events.find(event => event.seq > start.seq && event.type === 'user/message' && event.data.source?.kind === 'goal');
+export const STAGE_TOOLS = ['arcfold_start_work', 'arcfold_revise_work', 'arcfold_decide_work', 'arcfold_resume_work'];
+
+/** Arcfold owns a bounded stage and one-round permission; DSH remains the only scheduler. */
+export class GoalExecution {
+  constructor({ business }) { this.store = business.storage; this.mutations = new WeakMap(); this.controls = new WeakMap(); }
+  attach(root) { this.root = root; }
+  native(agent) { return this.root?.get('goals')?.get(agent) ?? null; }
+  current(agent) {
+    const goal = this.native(agent);
+    return goal ? this.store.get('execution_stages', stageId(agent.session.id, goal.id)) : null;
+  }
+  view(stage) {
+    if (!stage) return null;
+    try { this.assertSources(stage); } catch {
+      return { id: stage.id, status: 'needs_review', nativeGoalId: stage.nativeGoalId, nativeRevision: stage.nativeRevision,
+        reason: '阶段依据已经变化，等待重新明确当前工作。', available: false };
+    }
+    return { id: stage.id, definitionVersion: stage.definitionVersion, epoch: stage.epoch,
+      objective: stage.objective, doneWhen: stage.doneWhen, boundaries: stage.boundaries,
+      status: stage.status, reason: stage.reason, nextStep: stage.permit?.nextStep ?? '',
+      nativeGoalId: stage.nativeGoalId, nativeRevision: stage.nativeRevision, goalRef: stage.goalRef,
+      sources: stage.sourceRefs.map(reference => {
+        const original = this.store.get('events', reference.id);
+        return { id: original.id, role: original.role, content: sourceText(original), receivedSeq: reference.receivedSeq };
+      }), available: true,
+      authority: 'arcfold-current-stage; native-execution-within-this-boundary' };
+  }
+  receipt(agent, extra = {}) { return { goal: this.native(agent), stage: this.view(this.current(agent)), ...extra }; }
+  save(stage, changes) { return this.store.save('execution_stages', { ...stage, ...changes }, { expectedRevision: stage.revision }); }
+  mutate(agent, operation, fn) {
+    if (this.mutations.has(agent)) fail('已有阶段控制正在处理。');
+    this.mutations.set(agent, operation);
+    try { return fn(); } finally { this.mutations.delete(agent); }
+  }
+  disarm(agent) { this.root.get('goals').disarm(agent); }
+  stoppedAfter(agent) {
+    const stop = agent.session.snapshotEvents().findLast(event => event.type === 'goal/change' &&
+      ['pause', 'block', 'clear'].includes(event.data.operation));
+    return Math.max(stop?.seq ?? -1, this.current(agent)?.stopBoundary ?? -1);
+  }
+  beginControl(agent) {
+    if (this.controls.has(agent)) fail('当前工作控制正在确认，请等待原请求的结果。');
+    let resolve;
+    const promise = new Promise(done => { resolve = done; });
+    this.controls.set(agent, promise);
+    return () => { this.controls.delete(agent); resolve(); };
+  }
+  async awaitControl(agent) { await this.controls.get(agent); }
+  abortControl(agent, decisionId) {
+    this.disarm(agent);
+    const stage = this.current(agent);
+    if (stage?.permit?.userDecision === decisionId) this.save(stage, { status: 'waiting', permit: null, admission: null,
+      reason: '恢复结果尚待确认，执行保持停止。', stopBoundary: agent.session.seq - 1 });
+  }
+  sources(call, after = -1) {
+    const refs = [];
+    for (const event of call.events.filter(e => e.seq > call.startSeq && e.seq < call.call.seq && e.type === 'user/message' && owner(e.data))) {
+      const received = call.events.findLast(e => e.type === 'agent/inbox/spliced' && e.seq < event.seq &&
+        e.data.inserted?.some(message => same(message, event.data)));
+      if (!received || received.seq <= after) continue;
+      const originals = this.store.listAll('events', { where: { sessionId: call.sessionId } }).filter(row =>
+        row.message?.id === event.data.id && same(row.message, event.data));
+      if (originals.length !== 1 || !sourceAvailable(this.store, originals[0])) continue;
+      refs.push({ id: originals[0].id, revision: originals[0].revision, messageHash: hash(event.data), receivedSeq: received.seq });
+    }
+    if (!refs.length) fail('明确或恢复当前阶段需要本轮新收到的用户原话。');
+    return refs;
+  }
+  assertSources(stage) {
+    if (!stage?.sourceRefs?.length) fail('这项旧工作还需要明确当前阶段，请根据用户本次要求重新整理。');
+    for (const source of stage.sourceRefs) {
+      const row = this.store.get('events', source.id);
+      if (!sourceAvailable(this.store, row) || row.revision !== source.revision || hash(row.message) !== source.messageHash)
+        fail('当前阶段的委托原话已经撤回或改变。');
+    }
+    if (stage.goalRef) {
+      const goal = this.store.get('goals', stage.goalRef.id);
+      if (!goal || goal.status !== 'tracking' || goal.definitionVersion !== stage.goalRef.definitionVersion ||
+          !dependenciesCurrent(this.store, { ...goal, status: 'active' }, this.store.currentSequence()))
+        fail('关联的长期目标已经变化，需根据当前要求重新明确阶段。');
+    }
+  }
+  assertNative(stage, goal) {
+    this.assertSources(stage);
+    if (!goal || goal.id !== stage.nativeGoalId || goal.revision !== stage.nativeRevision || nativeDefinitionHash(goal) !== stage.nativeDefinitionHash)
+      fail('执行版本已经变化，需要通过 Arcfold 重新明确当前阶段。');
+  }
+  definition(args) {
+    for (const key of ['objective', 'doneWhen', 'boundaries'])
+      if (typeof args[key] !== 'string' || !args[key].trim() || args[key].length > 3000) fail('当前阶段需要具体任务、完成条件和推进边界。');
+    const max = args.max_goal_rounds ?? 3;
+    if (!Number.isSafeInteger(max) || max < 1 || max > 128) fail('阶段续跑轮数应为1到128的整数。');
+    return { objective: args.objective.trim(), doneWhen: args.doneWhen.trim(), boundaries: args.boundaries.trim(), maxGoalRounds: max };
+  }
+  start(call, args, revise = false) {
+    const spec = this.definition(args), sourceRefs = this.sources(call, this.stoppedAfter(call.agent));
+    const before = this.native(call.agent), previous = this.current(call.agent);
+    if (revise && before?.phase === 'complete') fail('上一阶段已经完成，请用 arcfold_start_work 开始用户新委托的阶段。');
+    const roundsAtStart = revise ? before?.roundsStarted ?? 0 : 0;
+    const nativeRoundLimit = roundsAtStart + spec.maxGoalRounds;
+    if (nativeRoundLimit > 128) fail('本次阶段轮数超出宿主剩余轮数，请缩小当前阶段。');
+    if (revise && (!before || before.id !== args.goal_id || before.revision !== args.revision)) fail('修改须对应当前执行的编号和版本。');
+    if (!revise && before && before.phase !== 'complete') fail('已有工作需要通过 arcfold_revise_work 明确新阶段。');
+    if (previous && ['waiting', 'paused', 'needs_review', 'completed'].includes(previous.status)) this.sources(call, previous.stopBoundary ?? -1);
+    const link = this.store.listAll('goal_links', { where: { sessionId: call.sessionId, startSeq: call.startSeq } })[0];
+    const parent = link && this.store.get('goals', link.goalId);
+    const goalRef = parent?.status === 'tracking' ? { id: parent.id, definitionVersion: link.definitionVersion } : null;
+    this.assertSources({ sourceRefs, goalRef });
+    const goal = this.mutate(call.agent, revise ? 'edit' : 'create', () => revise
+      ? this.root.get('goals').edit(call.agent, ref(before), { objective: spec.objective, maxGoalRounds: nativeRoundLimit })
+      : this.root.get('goals').create(call.agent, { objective: spec.objective, maxGoalRounds: nativeRoundLimit }));
+    try {
+      const id = stageId(call.sessionId, goal.id), old = this.store.get('execution_stages', id);
+      this.store.save('execution_stages', { id, sessionId: call.sessionId, nativeGoalId: goal.id,
+        nativeRevision: goal.revision, nativeDefinitionHash: nativeDefinitionHash(goal), ...spec, roundsAtStart,
+        definitionVersion: (old?.definitionVersion ?? 0) + 1, epoch: (old?.epoch ?? 0) + 1,
+        sourceRefs, goalRef, status: revise ? 'waiting' : 'running',
+        reason: revise ? '当前阶段已修改，等待明确继续。' : '执行当前明确委托的阶段。',
+        stopBoundary: revise ? call.call.seq : null, decisionId: null, permit: null, admission: null,
+        origin: { callId: call.callId, turn: call.turn, callSeq: call.call.seq, operation: revise ? 'revise' : 'start' } },
+      { expectedRevision: old?.revision ?? null });
+      if (revise) this.disarm(call.agent);
+    } catch (error) { this.disarm(call.agent); throw error; }
+    return this.receipt(call.agent);
+  }
+  decision(call, args) {
+    let stage = this.current(call.agent); const goal = this.native(call.agent);
+    this.assertNative(stage, goal);
+    if (goal.id !== args.goal_id || goal.revision !== args.revision || stage.status !== 'running' || goal.activation !== 'armed')
+      fail('决定须对应正在执行的当前阶段与版本。');
+    if (this.decisionFor(stage, call.turn)) fail('本轮已经作出推进决定，请交代结果。');
+    if (args.action === 'continue' && [...call.agent.inbox.nextStep, ...call.agent.inbox.nextTurn].some(owner))
+      fail('先处理新收到的用户表达，再决定下一轮。');
+    if (!['continue', 'wait', 'complete'].includes(args.action) || typeof args.reason !== 'string' || !args.reason.trim() ||
+        args.reason.length > 2000 || typeof args.stageDone !== 'boolean' || typeof args.needsUserDecision !== 'boolean' ||
+        typeof args.nextStep !== 'string' || args.nextStep.length > 2000) fail('阶段决定需要结果依据、完成判断及是否需用户决定。');
+    if (args.action === 'continue' && (args.stageDone || args.needsUserDecision || !args.nextStep.trim() || goal.roundsStarted >= goal.maxGoalRounds))
+      fail('只有当前阶段尚未完成、无需用户决定且下一步明确时，才可许可下一轮。');
+    if (args.action === 'complete' && (!args.stageDone || args.needsUserDecision)) fail('请核对当前阶段的完成条件：满足时 complete 要求 stageDone=true 且 needsUserDecision=false；完成本阶段仍需信息或选择时用 wait。后续阶段的讨论另行保留。');
+    if (args.action !== 'continue' && args.nextStep !== '') fail('等待或完成不携带下一轮执行步骤。');
+    const id = 'stage-decision-' + hash([call.sessionId, call.callId]);
+    if (this.store.get('stage_decisions', id)) fail('此阶段决定已经记录，不能重复执行。');
+    const decision = { id, stageId: stage.id, sessionId: call.sessionId, definitionVersion: stage.definitionVersion,
+      epoch: stage.epoch, nativeGoalId: goal.id, nativeRevision: goal.revision, turn: call.turn, callId: call.callId,
+      callSeq: call.call.seq, action: args.action, reason: args.reason, stageDone: args.stageDone,
+      needsUserDecision: args.needsUserDecision, nextStep: args.nextStep, evidence: 'current-main-model-decision; semantic-judgment-not-proven-by-schema' };
+    this.store.save('stage_decisions', decision, { expectedRevision: null });
+    if (args.action === 'continue') {
+      this.save(stage, { decisionId: id, reason: args.reason, permit: { decisionId: id, nativeRevision: goal.revision,
+        round: goal.roundsStarted + 1, fromTurn: call.turn, nextStep: args.nextStep, issuedSeq: call.call.seq } });
+    } else {
+      const operation = args.action === 'wait' ? 'pause' : 'complete';
+      const after = this.mutate(call.agent, operation, () => this.root.get('goals')[operation](call.agent, ref(goal)));
+      try {
+        stage = this.current(call.agent);
+        this.save(stage, { nativeRevision: after.revision, status: args.action === 'wait' ? 'waiting' : 'completed',
+          reason: args.reason, decisionId: id, permit: null, stopBoundary: call.call.seq });
+      } catch (error) { this.disarm(call.agent); throw error; }
+    }
+    return this.receipt(call.agent, { decisionId: id });
+  }
+  decisionFor(stage, turn) {
+    const decision = stage?.decisionId && this.store.get('stage_decisions', stage.decisionId);
+    return decision?.turn === turn && decision.definitionVersion === stage.definitionVersion && decision.epoch === stage.epoch ? decision : null;
+  }
+  success(events, decision) {
+    return Boolean(decision && events.some(event => event.type === 'tool/result' && event.data.message?.toolCallId === decision.callId &&
+      event.data.message.isError === false && event.data.message.content?.some(block => {
+        if (block.type !== 'text') return false;
+        try { const value = JSON.parse(block.text); return value.decisionId === decision.id && value.stage?.id === decision.stageId; } catch { return false; }
+      })));
+  }
+  /** A browser or a new owner turn may resume the same stage, never revive an old ticket. */
+  resume(agent, { goalId, revision, sourceRefs = null, userDecision = null, currentTurn: turn = null, callId = null, callSeq = null, allowRevisedTurn = false }) {
+    let stage = this.current(agent); const goal = this.native(agent);
+    this.assertNative(stage, goal);
+    if (goal.id !== goalId || goal.revision !== revision || stage.status === 'completed' ||
+        goal.roundsStarted >= goal.maxGoalRounds || goal.phase === 'complete') fail('该阶段不能直接恢复，请重新明确当前工作。');
+    if (!sourceRefs?.length && !userDecision) fail('恢复需要新的用户决定。');
+    if (sourceRefs && !sourceRefs.some(source => source.receivedSeq > (stage.stopBoundary ?? -1)) && !allowRevisedTurn)
+      fail('恢复依据必须在停下之后新收到。');
+    const after = this.mutate(agent, 'resume', () => this.root.get('goals').resume(agent, ref(goal)));
+    try {
+      stage = this.current(agent);
+      const epoch = stage.epoch + 1;
+      this.save(stage, { nativeRevision: after.revision, epoch, status: 'running', reason: '按用户的新决定继续当前阶段。',
+        sourceRefs: sourceRefs ? [...stage.sourceRefs, ...sourceRefs.filter(source => !stage.sourceRefs.some(old => old.id === source.id))] : stage.sourceRefs,
+        decisionId: null, admission: null, permit: userDecision ? { nativeRevision: after.revision, round: after.roundsStarted + 1,
+          fromTurn: null, nextStep: stage.objective, issuedSeq: agent.session.seq - 1, userDecision } : null,
+        resumedBy: sourceRefs ? { kind: 'owner-input', sourceIds: sourceRefs.map(source => source.id), turn, callId, callSeq } : { kind: 'browser', userDecision } });
+    } catch (error) { this.disarm(agent); throw error; }
+    return this.receipt(agent);
+  }
+  observeNative(agent, change) {
+    if (this.mutations.get(agent) === change.operation) return;
+    const stage = this.current(agent) ?? (change.cleared?.id && this.store.get('execution_stages', stageId(agent.session.id, change.cleared.id)));
+    // Native controls may always stop execution. They cannot grant Arcfold stage authority.
+    this.disarm(agent);
+    if (stage) this.save(stage, { status: ['pause', 'block', 'clear'].includes(change.operation) ? 'paused' : 'needs_review',
+      reason: ['pause', 'block'].includes(change.operation) ? '当前执行已停下。' : '执行定义或控制已变化，需重新明确当前阶段。',
+      nativeRevision: change.goal?.revision ?? change.cleared?.revision ?? stage.nativeRevision, epoch: stage.epoch + 1,
+      permit: null, admission: null, decisionId: null, stopBoundary: agent.session.seq - 1 });
+  }
+  ownerArrived(agent, message) {
+    if (!owner(message)) return;
+    const stage = this.current(agent);
+    if (stage && (stage.permit || stage.decisionId)) this.save(stage, { permit: null, decisionId: null,
+      reason: '先处理用户的新表达，再决定是否继续。' });
+  }
+  ownerEntered(agent, messages) {
+    if (messages.some(owner)) this.ownerArrived(agent, messages.find(owner));
+  }
+  async stopping(agent, turn) {
+    const goal = this.native(agent), stage = this.current(agent);
+    if (!goal || goal.phase !== 'active') return;
+    const events = agent.session.snapshotEvents(), decision = this.decisionFor(stage, turn);
+    try {
+      this.assertNative(stage, goal);
+      if (stage.status === 'running' && stage.permit?.fromTurn === turn && stage.permit.nativeRevision === goal.revision &&
+          stage.permit.round === goal.roundsStarted + 1 && decision?.action === 'continue' && this.success(events, decision)) return;
+    } catch { /* The existing result remains delivered; invalid continuation stops. */ }
+    this.disarm(agent);
+    if (stage && stage.status === 'running') this.save(stage, { status: 'waiting', permit: null, admission: null,
+      reason: '本轮已结束，等待明确下一步。', stopBoundary: agent.session.seq - 1 });
+  }
+  admit(agent, messages, turn) {
+    const automatic = messages.find(message => message.source?.kind === 'goal');
+    if (!automatic) return;
+    const goal = this.native(agent), stage = this.current(agent), source = automatic.source;
+    try {
+      this.assertNative(stage, goal);
+      if (stage.admission?.turn === turn && stage.admission.messageId === automatic.id) return;
+      const permit = stage.permit;
+      if (source.round <= 0 || stage.status !== 'running' || goal.phase !== 'active' || goal.activation !== 'armed' ||
+          !permit || source.goalId !== goal.id || source.revision !== goal.revision || permit.nativeRevision !== goal.revision ||
+          permit.round !== source.round || source.round !== goal.roundsStarted + 1) fail('下一轮缺少当前阶段的单次继续许可。');
+      if (permit.decisionId && !this.success(agent.session.snapshotEvents(), this.store.get('stage_decisions', permit.decisionId)))
+        fail('继续决定缺少真实成功回执。');
+      if (permit.userDecision) {
+        const control = this.store.get('goal_work_controls', permit.userDecision);
+        if (control?.state !== 'applied' || control.request.action !== 'resume' ||
+            control.request.sessionId !== stage.sessionId || control.request.nativeGoalId !== goal.id ||
+            control.request.nativeRevision + 1 !== goal.revision) fail('网页恢复决定尚未确认生效。');
+      }
+      this.save(stage, { permit: null, decisionId: null, admission: { turn, messageId: automatic.id, round: source.round,
+        nativeRevision: source.revision, definitionVersion: stage.definitionVersion, epoch: stage.epoch,
+        decisionId: permit.decisionId ?? null, userDecision: permit.userDecision ?? null } });
+    } catch (error) { this.disarm(agent); throw error; }
+  }
+  controlSucceeded(events, control, stage) {
+    return Boolean(control?.callId && events.some(event => event.type === 'tool/result' &&
+      event.data.message?.toolCallId === control.callId && event.data.message.isError === false &&
+      event.data.message.content?.some(block => {
+        try { const result = JSON.parse(block.text); return result.stage?.id === stage.id &&
+          result.stage.definitionVersion === stage.definitionVersion; } catch { return false; }
+      })));
+  }
+  ownerTransition(agent) {
+    const events = agent.session.snapshotEvents(), start = currentTurn(events), stage = this.current(agent);
+    if (!start || !stage) return false;
+    const control = stage.resumedBy?.kind === 'owner-input' && stage.resumedBy.turn === start.data.turn
+      ? stage.resumedBy : stage.origin?.turn === start.data.turn ? stage.origin : null;
+    return this.controlSucceeded(events, control, stage);
+  }
+  freshOwner(agent) {
+    const events = agent.session.snapshotEvents(), start = currentTurn(events), stage = this.current(agent);
+    if (!start) return false;
+    const boundary = Math.max(stage?.origin?.callSeq ?? -1, stage?.resumedBy?.callSeq ?? -1, this.stoppedAfter(agent));
+    return events.some(event => event.seq > start.seq && event.type === 'user/message' && owner(event.data) &&
+      events.some(received => received.type === 'agent/inbox/spliced' && received.seq > boundary && received.seq < event.seq &&
+        received.data.inserted?.some(message => same(message, event.data))) &&
+      this.store.listAll('events', { where: { sessionId: agent.session.id } }).some(row =>
+        same(row.message, event.data) && sourceAvailable(this.store, row)));
+  }
+  historicalContinuation(agent) { return this.ownerTransition(agent) || this.freshOwner(agent); }
+  browserControlSaved(agent, id, request) {
+    const stage = this.store.get('execution_stages', stageId(agent.session.id, request.nativeGoalId));
+    return Boolean(stage?.resumedBy?.kind === 'browser' && stage.resumedBy.userDecision === id &&
+      stage.nativeRevision >= request.nativeRevision + 1);
+  }
+  boundToTurn(stage, turn) {
+    return Boolean(stage && (stage.origin?.turn === turn || stage.admission?.turn === turn ||
+      stage.resumedBy?.kind === 'owner-input' && stage.resumedBy.turn === turn));
+  }
+  assertCurrent(agent, { tools = false, name = null } = {}) {
+    const events = agent.session.snapshotEvents(), start = currentTurn(events);
+    if (!start) return;
+    const input = goalInput(events, start), stage = this.current(agent), decision = this.decisionFor(stage, start.data.turn);
+    const repair = ['get_goal', 'arcfold_start_work', 'arcfold_revise_work', 'arcfold_resume_work'].includes(name);
+    // A newly entered owner correction may inspect/redefine the stage. It does
+    // not authorize ordinary actions under an obsolete automatic admission.
+    if (this.freshOwner(agent) && (!tools || repair)) return;
+    if (tools && decision) fail('本轮已作出阶段决定，请交代结果，后续行动交由下一轮执行。');
+    const expected = this.store.listAll('context_snapshots', { where: { sessionId: agent.session.id, turn: start.data.turn } })[0]?.material.executionStage;
+    const boundOwner = this.boundToTurn(stage, start.data.turn);
+    if (!input && !boundOwner && !expected?.boundToTurn) return;
+    if (expected?.boundToTurn && expected.id !== stage?.id) fail('发起本次模型请求的阶段已被替换，旧动作不能继续执行。');
+    const goal = this.native(agent), admission = stage?.admission;
+    this.assertNative(stage, goal);
+    if (!tools && decision && ['wait', 'complete'].includes(decision.action) && this.success(events, decision)) return;
+    if (this.ownerTransition(agent)) {
+      if (!tools || repair || stage.status === 'running' && goal.phase === 'active' && goal.activation === 'armed') return;
+      fail('当前阶段已停下，先按用户要求恢复再执行。');
+    }
+    if (!input) fail('当前阶段控制缺少成功回执。');
+    if (!admission || admission.turn !== start.data.turn || admission.messageId !== input.data.id ||
+        admission.epoch !== stage.epoch || admission.definitionVersion !== stage.definitionVersion)
+      fail('此自动轮不再持有当前阶段的执行许可。');
+    if (stage.status !== 'running' || goal.phase !== 'active' || goal.activation !== 'armed' ||
+        admission.nativeRevision !== goal.revision || admission.round !== goal.roundsStarted)
+      fail('当前阶段已停下或改变，旧自动轮不能继续执行。');
+  }
+  stopForGoal(goalId) {
+    for (const stage of this.store.listAll('execution_stages').filter(row => row.status === 'running' &&
+      (row.goalRef?.id === goalId || workRelation(this.store, workId(row.sessionId, row.nativeGoalId))?.goalId === goalId))) {
+      const agent = this.root?.get('agents')?.get(stage.sessionId);
+      if (!agent || this.native(agent)?.id !== stage.nativeGoalId) continue;
+      const goal = this.native(agent);
+      if (goal.phase === 'active') this.root.get('goals').pause(agent, ref(goal));
+    }
+  }
+}

package/src/goal-tool.mjs

@@ -0,0 +1,56 @@
+import { defineTool } from '@deepseek-ai/dsh-tools';
+import { HarnessError } from '@deepseek-ai/dsh-llm';
+import { resolveNativeContextCall, belongsToSelectionBatch } from './native-context-call.mjs';
+import { GOAL_TOOL, goalContextMessage } from './goal-context.mjs';
+
+export const name = 'arcfold-goal-tool';
+export const inject = ['tools', 'agents', 'arcfoldBridge', 'arcfoldGoals'];
+const reject = message => { throw new HarnessError(message, 'ARCFOLD_GOAL_CALL_INVALID'); };
+export const resolveNativeGoalCall = (ctx, exec) => resolveNativeContextCall(ctx, exec, reject);
+
+function assertSelection(args) {
+  const fields = ['id', 'revision', 'definitionVersion', 'contentHash', 'reason', 'sourceIds'];
+  if (!args || typeof args !== 'object' || Array.isArray(args) || Object.keys(args).length !== 1 ||
+      !Object.hasOwn(args, 'selection')) reject('Provide exactly one goal selection.');
+  const item = args.selection;
+  if (!item || typeof item !== 'object' || Array.isArray(item) || Object.keys(item).length !== fields.length ||
+      fields.some(field => !Object.hasOwn(item, field)))
+    reject('A goal selection requires exactly id, revision, definitionVersion, contentHash, reason and sourceIds.');
+}
+
+export function apply(ctx) {
+  ctx.on('tools/pre-execute', async (exec, next) => {
+    if (!belongsToSelectionBatch(exec, GOAL_TOOL)) return next();
+    try {
+      const current = await resolveNativeGoalCall(ctx, exec);
+      if (current.batch.length !== 1 || current.batch[0].name !== GOAL_TOOL)
+        return { kind: 'deny', reason: 'Request arcfold_link_goal alone. Read the returned goal context in the next model step before requesting any action.' };
+    } catch (error) { return { kind: 'deny', reason: error.message }; }
+    return next();
+  });
+  ctx.tools.register(defineTool({
+    name: GOAL_TOOL,
+    description: 'Relate this turn to one goal shown in the current Arcfold catalog, with your reason and its displayed sources. Call alone in the assistant tool batch. The receipt is followed by program goal context in the next step. A link is your interpretation, not user confirmation, new work authority, resumed tracking or proof that the long-term goal is complete.',
+    parameters: { selection: { type: 'object', required: true, additionalProperties: false, properties: {
+      id: { type: 'string', required: true }, revision: { type: 'integer', required: true },
+      definitionVersion: { type: 'integer', required: true }, contentHash: { type: 'string', required: true },
+      reason: { type: 'string', required: true }, sourceIds: { type: 'array', required: true, items: { type: 'string' } },
+    } } },
+    output: { schema: { type: 'json' }, render: (_args, receipt) => [{ type: 'text', text: JSON.stringify(receipt) }] },
+    async execute(args, exec) {
+      assertSelection(args);
+      const current = await resolveNativeGoalCall(ctx, exec);
+      if (current.batch.length !== 1 || current.batch[0].name !== GOAL_TOOL || typeof exec.deferContext !== 'function')
+        reject('The goal selection must be a standalone native tool call.');
+      const { receipt, bundle } = ctx.arcfoldGoals.link({ sessionId: current.sessionId, turn: current.turn,
+        startSeq: current.startSeq, callId: current.callId, contextSnapshotId: current.contextSnapshotId,
+        contextMessageId: current.contextMessageId, selection: args.selection,
+        maxCharacters: ctx.arcfoldBridge.maxContextCharacters });
+      exec.signal.throwIfAborted();
+      exec.deferContext(goalContextMessage(bundle));
+      exec.signal.throwIfAborted();
+      return receipt;
+    },
+    presentCall: () => ({ card: 'generic', title: 'Relate this work to a goal', kind: 'read' }),
+  }));
+}