@arcfold/dsh 0.0.0-stage → 0.4.0

package/src/learning-defaults.mjs

@@ -0,0 +1,98 @@
+import { isAbsolute } from 'node:path';
+import { DomainError } from './store.mjs';
+
+const KIND = 'learn_defaults', ID = 'web';
+const CHOICE = ['provider', 'model', 'reasoningEffort'];
+const EXECUTION = [...CHOICE, 'maxTokens', 'preset', 'cwd'];
+const fail = (code, message) => { throw new DomainError(code, message); };
+const choice = value => Object.fromEntries(CHOICE.map(key => [key, value?.[key]]));
+
+function assertChoice(value) {
+  if (!value || !CHOICE.every(key => typeof value[key] === 'string' && value[key].trim()))
+    fail('learning_configuration_unavailable', '学习需要明确的模型提供方、型号和思考强度。');
+}
+
+/** A detached frozen execution identity; no lookup of today's defaults. */
+export function learningExecutionConfig(run) {
+  const value = run?.executionConfig;
+  if (!Number.isSafeInteger(run?.defaultsRevision) || run.defaultsRevision < 1 || !value ||
+      Object.keys(value).sort().join() !== [...EXECUTION].sort().join())
+    fail('learning_execution_config_missing', '旧学习没有可核实的执行配置，不能采用今天的设置重发。');
+  assertChoice(value);
+  if (!Number.isSafeInteger(value.maxTokens) || value.maxTokens < 1 ||
+      typeof value.preset !== 'string' || !value.preset ||
+      typeof value.cwd !== 'string' || !isAbsolute(value.cwd))
+    fail('learning_execution_config_missing', '学习执行配置不完整，不能自动恢复。');
+  return Object.freeze({ ...value });
+}
+
+/** One independent default in the existing business store, not a main model or execution queue. */
+export class LearningDefaults {
+  constructor({ business, deployment, assertSelection } = {}) {
+    if (!business?.storage) throw new TypeError('Learning defaults require business storage');
+    this.store = business.storage;
+    this.deployment = deployment ? Object.freeze({ ...choice(deployment), maxTokens: deployment.maxTokens,
+      preset: deployment.preset, cwd: deployment.cwd }) : null;
+    this.assertSelection = assertSelection;
+  }
+
+  read() { return this.store.get(KIND, ID); }
+
+  validate(selected) {
+    assertChoice(selected);
+    const executionConfig = learningExecutionConfig({ defaultsRevision: 1,
+      executionConfig: { ...choice(selected), maxTokens: this.deployment?.maxTokens,
+        preset: this.deployment?.preset, cwd: this.deployment?.cwd } });
+    if (typeof this.assertSelection !== 'function')
+      fail('learning_configuration_unavailable', '学习设置尚未接入当前授权路线检查。');
+    const result = this.assertSelection(executionConfig);
+    if (result && typeof result.then === 'function') {
+      Promise.resolve(result).catch(() => {});
+      fail('learning_validator_async', '学习设置授权检查必须同步完成。');
+    }
+    if (result === false) fail('learning_configuration_unavailable', '当前路线不允许这项学习设置。');
+    return executionConfig;
+  }
+
+  initialize() {
+    return this.store.transaction(() => {
+      const existing = this.read();
+      if (existing) return existing;
+      this.validate(this.deployment);
+      return this.store.save(KIND, { id: ID, ...choice(this.deployment),
+        provenance: { kind: 'explicit_learning_deployment', initialSelection: choice(this.deployment) } });
+    });
+  }
+
+  save(request) {
+    if (!request || Object.keys(request).sort().join() !== [...CHOICE, 'expectedRevision'].sort().join() ||
+        !Number.isSafeInteger(request.expectedRevision) || request.expectedRevision < 1)
+      fail('invalid_learning_defaults', '只接受模型三字段和明确的原版本；输出上限与工作目录属于部署配置。');
+    return this.store.transaction(() => {
+      const existing = this.read();
+      if (!existing) fail('learning_configuration_unavailable', '未明确配置学习，不能通过日常设置启用。');
+      if (existing.revision !== request.expectedRevision) fail('revision_conflict', '学习默认设置已变化，请刷新后保存。');
+      this.validate(request);
+      return this.store.save(KIND, { ...existing, ...choice(request),
+        provenance: { kind: 'validated_learning_default_edit', previousRevision: existing.revision,
+          initializedFrom: existing.provenance.initializedFrom ?? existing.provenance } },
+      { expectedRevision: existing.revision });
+    });
+  }
+
+  snapshot() {
+    return this.store.transaction(() => {
+      const record = this.read();
+      if (!record) fail('learning_configuration_unavailable', '学习尚无明确的默认设置。');
+      return Object.freeze({ executionConfig: this.validate(record), defaultsRevision: record.revision });
+    });
+  }
+}
+
+/** Compatibility until the runtime supplies its live authorized-route validator. */
+export function deploymentSelectionValidator(deployment) {
+  return selected => {
+    if (!deployment || CHOICE.some(key => selected[key] !== deployment[key]))
+      fail('learning_configuration_unavailable', '当前组件只允许显式部署的学习选择；动态路线尚未接通。');
+  };
+}

package/src/learning-goals.mjs

@@ -0,0 +1,165 @@
+import { linkWork } from './goal-work.mjs';
+// Business-only adaptation of Arcfold 3.0 service.mjs applyGoalChanges,
+// saveGoalTransition and invalidateDependents. No jobs are created/cancelled.
+import { ContractError, digest } from './learning-contracts.mjs';
+import { pauseMethod } from './method-lifecycle.mjs';
+
+const invalid = message => { throw new ContractError('invalid_output', message); };
+
+export function saveGoalTransition(store, before, after, { commandId, pendingId, reason, sourceIds = [], actor = 'assistant_inference' }) {
+  const id = 'goal-audit-' + digest(commandId);
+  if (store.get('audit', id)) throw new ContractError('learning_conflict', '目标变更身份已经使用');
+  const saved = store.save('goals', after, { expectedRevision: before?.revision ?? null });
+  store.save('audit', { id, commandId, goalId: saved.id, actor, reason,
+    pendingId, sourceIds, before: before || null, after: saved });
+  return saved;
+}
+
+function assertAcyclic(goals) {
+  const byId = new Map(goals.map(goal => [goal.id, goal])), edges = new Map();
+  for (const goal of goals) {
+    if (goal.deleted || goal.withdrawn || goal.useProhibited) continue;
+    for (const relation of goal.relations || []) {
+      const target = byId.get(relation.targetId);
+      if (relation.type === 'part_of' && target && !target.deleted && !target.withdrawn &&
+          !target.useProhibited && target.definitionVersion === relation.targetDefinitionVersion)
+        edges.set(goal.id, [...(edges.get(goal.id) || []), target.id]);
+    }
+  }
+  const visiting = new Set(), done = new Set();
+  function visit(id) {
+    if (visiting.has(id)) invalid('目标组成关系不能成环');
+    if (done.has(id)) return;
+    visiting.add(id);
+    for (const next of edges.get(id) || []) visit(next);
+    visiting.delete(id); done.add(id);
+  }
+  for (const id of byId.keys()) visit(id);
+}
+
+/** All rows and their definition/relationship versions share one section transaction. */
+export function applyGoalChanges(store, { pendingId, material, rows, assertTarget, assertSources, understandingRefs }) {
+  const aliases = new Map(), ids = new Set(), prepared = [];
+  for (const [index, row] of rows.entries()) {
+    const old = row.operation === 'update' ? assertTarget('goals', row.targetId) : null;
+    const repair = old && material.existingGoals.find(goal => goal.id === old.id)?.repairOnly === true;
+    if (repair && (!old.useProhibited || old.sourceInvalidation?.kind !== 'source_dependency' ||
+        old.withdrawn || old.deleted || !row.sourceIds.some(id => material.inputEventIds.includes(id))))
+      invalid('重新澄清须有本次新用户原话，且只能修复程序标记的来源失效目标');
+    if (row.operation === 'create' && row.targetId !== '') invalid('新建目标不能指定旧编号');
+    if ((row.operation === 'update' && row.clientRef) ||
+        (row.clientRef && (!row.clientRef.startsWith('new-goal:') || aliases.has(row.clientRef))))
+      invalid('临时目标编号仅限同区新建且不可重复');
+    const id = old?.id || 'goal-' + digest([pendingId, index]).slice(0, 32);
+    if (ids.has(id)) invalid('同一区不能重复修改一个目标');
+    ids.add(id);
+    if (row.clientRef) aliases.set(row.clientRef, id);
+    const references = understandingRefs(row.understandingIds);
+    const dependencies = [...assertSources(row.sourceIds, true), ...references];
+    const scope = row.scope === 'global' ? {} : { conversationId: old?.conversationId || material.sessionId };
+    const definition = { title: row.title, outcome: row.outcome, scope, understandingRefs: references };
+    const previous = old && { title: old.title, outcome: old.outcome, scope: old.scope || {},
+      understandingRefs: (old.dependencies || []).filter(ref => ref.kind === 'understandings') };
+    const definitionVersion = old ? old.definitionVersion + Number(digest(definition) !== digest(previous)) : 1;
+    if (!Number.isSafeInteger(definitionVersion) || definitionVersion < 1) invalid('旧目标缺少有效定义版本');
+    if (!row.progress.content.trim() && (row.progress.content !== '' || row.progress.sourceIds.length))
+      invalid('空进展必须使用空文字和空来源');
+    const progressDependencies = row.progress.content ? assertSources(row.progress.sourceIds) : [];
+    const controlSources = row.sourceIds.map(id => store.get('events', id)).filter(source =>
+      material.inputEventIds.includes(source?.id) && source.message?.role === 'user' &&
+      source.message.source?.kind === 'user' && source.message.source.principal === undefined);
+    if (row.controlProposal !== 'none' && !controlSources.length)
+      invalid('追踪解释必须引用本轮真实owner原话，后台续轮不能改变追踪');
+    const controlBoundary = old?.userControl?.nativeBoundary;
+    const laterThanHumanControl = !old?.userControl || controlBoundary && controlSources.some(source => {
+      const ref = source.provenance?.sourceRef;
+      return ref?.type === 'agent/inbox/spliced' && ref.sessionId === controlBoundary.sessionId &&
+        ref.seq > controlBoundary.throughSeq;
+    });
+    const applyTracking = row.controlProposal !== 'none' && laterThanHumanControl;
+
+    const next = { ...old, id, conversationId: old?.conversationId || material.sessionId,
+      title: row.title, outcome: row.outcome, scope, definitionVersion,
+      understandingIds: row.understandingIds, sourceIds: row.sourceIds, dependencies,
+      status: applyTracking ? { pause: 'paused', resume: 'tracking', close: 'closed' }[row.controlProposal] : old?.status || 'tracking',
+      userControl: old?.userControl ?? null,
+      ...(row.controlProposal !== 'none' ? { trackingInterpretation: { action: row.controlProposal,
+        sourceIds: controlSources.map(source => source.id), pendingId, claimType: 'inference',
+        applied: Boolean(applyTracking), reason: applyTracking ? 'current_owner_input' : 'prior_user_control_order_unproven' } } : {}),
+      progress: { content: row.progress.content, sourceIds: row.progress.sourceIds,
+        dependencies: progressDependencies, runId: pendingId },
+      relations: [], controlProposal: row.controlProposal === 'none' ? null : {
+        action: row.controlProposal, definitionVersion, sourceIds: row.sourceIds,
+        dependencies: assertSources(row.sourceIds), claimType: 'inference', runId: pendingId },
+      claimType: 'inference', contentAuthor: 'assistant', userEndorsement: 'not_established_by_this_record',
+      learnedFromRunId: old?.learnedFromRunId || pendingId, updatedFromRunId: pendingId };
+    if (repair) {
+      next.useProhibited = false;
+      next.sourceInvalidation = null;
+      next.withdrawalReason = null;
+    }
+    prepared.push({ old, next, row, index });
+  }
+  const replacements = new Map(prepared.map(item => [item.next.id, item.next]));
+  for (const item of prepared) {
+    const seen = new Set();
+    for (const relation of item.row.relations) {
+      const targetId = aliases.get(relation.targetId) || relation.targetId;
+      const target = replacements.get(targetId) || assertTarget('goals', targetId);
+      const key = relation.type + ':' + targetId;
+      if (!target || targetId === item.next.id || seen.has(key)) invalid('目标关系不能自连、重复或缺少两端');
+      seen.add(key);
+      // A full Learn update explicitly reproposes each relation. Bind both
+      // definitions; retaining an old stored edge never silently rebases it.
+      item.next.relations.push({ ...relation, targetId, sourceDefinitionVersion: item.next.definitionVersion,
+        targetDefinitionVersion: target.definitionVersion,
+        dependencies: assertSources(relation.sourceIds) });
+    }
+  }
+  assertAcyclic([...store.listAll('goals').filter(goal => !replacements.has(goal.id)), ...replacements.values()]);
+  const result = prepared.map(({ old, next, index }) => saveGoalTransition(store, old, next, {
+    commandId: `${pendingId}:goals:${index}`, pendingId, reason: old ? 'learn_update' : 'learn_create',
+    sourceIds: next.sourceIds }).id);
+  const workIds = new Set();
+  for (const { next, row, index } of prepared) for (const selection of row.workLinks || []) {
+    if (workIds.has(selection.workId)) invalid('同一工作在本区只能联系一个明确目标');
+    workIds.add(selection.workId);
+    const shown = material.goalWorks?.find(work => work.id === selection.workId);
+    if (!shown || shown.sessionId !== material.sessionId) invalid('工作联系必须逐字选择本次交付的真实工作编号');
+    assertSources(selection.sourceIds);
+    linkWork(store, { work: store.get('goal_works', shown.id), goal: store.get('goals', next.id),
+      state: shown, reason: selection.reason, sourceIds: selection.sourceIds,
+      expectedRelationId: shown.relationId,
+      origin: { kind: 'learning', pendingId, index } });
+  }
+  return result;
+}
+
+/** Invalidate dependent business knowledge only; execution remains host-owned. */
+export function invalidateDependents(store, { ids, pendingId, reason }) {
+  const invalidIds = new Set(ids), changes = [];
+  const inventory = ['understandings', 'methods', 'opportunities', 'goals']
+    .flatMap(kind => store.listAll(kind).map(record => ({ kind, record })));
+  let advanced;
+  do {
+    advanced = false;
+    for (const item of inventory) {
+      const { kind, record } = item;
+      if (invalidIds.has(record.id) || (!(record.sourceIds || []).some(id => invalidIds.has(id)) &&
+          !(record.dependencies || []).some(ref => invalidIds.has(ref.id)))) continue;
+      invalidIds.add(record.id); advanced = true;
+      const next = kind === 'goals'
+        ? { ...record, useProhibited: true, sourceInvalidation: { kind: 'source_dependency', reason }, withdrawalReason: reason }
+        : { ...record, status: kind === 'understandings' ? 'withdrawn' : kind === 'methods' ? 'paused' : 'dismissed',
+          withdrawalReason: reason, ...(kind === 'methods' ? { pauseReason: reason } : {}) };
+      item.record = kind === 'methods'
+        ? pauseMethod(store, record, { reason, changes: { withdrawalReason: reason }, pendingId })
+        : store.save(kind, next, { expectedRevision: record.revision });
+      changes.push({ kind, id: record.id, revision: item.record.revision });
+      if (kind === 'goals') store.save('audit', {
+        id: 'goal-audit-' + digest([pendingId, reason, record.id, record.revision]),
+        goalId: record.id, pendingId, actor: 'program_source_guard', reason, before: record, after: item.record });
+    }
+  } while (advanced);
+  return changes;
+}

package/src/learning-plugin.mjs

@@ -0,0 +1,28 @@
+import { LearningService } from './learning.mjs';
+import { LearningRunner } from './learning-runner.mjs';
+import { LearningDefaults, deploymentSelectionValidator } from './learning-defaults.mjs';
+
+export const name = 'arcfold-learning';
+export const inject = ['arcfoldBusiness', 'arcfoldBridge', 'agents', 'agentPresets', 'sessions', 'sessionPersistence', 'workingDirectory', 'llm'];
+export async function apply(ctx, config = {}) {
+  const learning = new LearningService({ business: ctx.arcfoldBusiness, maxCharacters: config.maxCharacters ?? 180000 });
+  const deployment = { ...config, cwd: config.cwd ?? ctx.workingDirectory.defaultDirectory };
+  const defaults = new LearningDefaults({ business: ctx.arcfoldBusiness, deployment,
+    assertSelection: ctx.get('arcfoldRuntimeModels')?.assertLearningSelection ?? deploymentSelectionValidator(deployment) });
+  const runner = new LearningRunner({ business: ctx.arcfoldBusiness, learning, host: ctx, config, defaults, onSettled: pendingId => ctx.emit('arcfold/opportunities-committed', pendingId), logger: ctx.logger });
+  ctx.effect(() => () => runner.close(), 'stop auxiliary learning before its business storage');
+  ctx.on('llm/stream', (options, next) => runner.guardStream(options, next));
+  ctx.on('session/event', (session, event) => {
+    if (event.type !== 'turn/end' || !ctx.arcfoldBridge.isBound(session.id)) return;
+    // Bridge observation schedules reconciliation synchronously. Await only that
+    // durable business commit, never a main-turn hook or another main Agent.
+    void Promise.resolve().then(async () => {
+      await ctx.arcfoldBridge.pending.get(session.id);
+      if (!runner.closed) await runner.kick();
+    }).catch(error => ctx.logger.error?.(error));
+  });
+  ctx.provide('arcfoldLearningDefaults', defaults);
+  ctx.provide('arcfoldLearning', runner);
+  await runner.recover();
+  void runner.kick().catch(error => ctx.logger.error?.(error));
+}

package/src/learning-runner.mjs

@@ -0,0 +1,275 @@
+import { randomUUID } from 'node:crypto';
+import { hash } from './context-material.mjs';
+import { canonicalJson } from './store.mjs';
+import { LearningDefaults, learningExecutionConfig, deploymentSelectionValidator } from './learning-defaults.mjs';
+
+// DSH rc.1 keeps this required fact even when optional context is suppressed.
+// Match workingDirectory.contextText + joinContextSections, never a free-form
+// model instruction. Native projection may regenerate its message id.
+export function directoryContext(cwd) {
+  const section = { name: 'working-directory:current', text: `Current working directory: ${JSON.stringify(cwd)}.` };
+  return { role: 'user', source: { kind: 'runtime-context', form: 'snapshot', sections: [section] },
+    content: [{ type: 'text', text: `Current runtime context. This snapshot supersedes earlier runtime-context snapshots.\n\n${section.text}` }] };
+}
+export function contextMatches(message, expected) {
+  if (!message || typeof message.id !== 'string' || !message.id) return false;
+  const { id, ...body } = message;
+  return canonicalJson(body) === canonicalJson(expected);
+}
+
+/** Dispatches durable learning intents through DSH; it contains no model/tool loop. */
+export class LearningRunner {
+  constructor({ business, learning, host, config, defaults, onSettled = () => {}, logger = console }) {
+    if (!config || !['preset', 'provider', 'model', 'reasoningEffort'].every(key => typeof config[key] === 'string' && config[key]))
+      throw new Error('Learning requires an explicit preset, provider, model and reasoningEffort');
+    if (!Number.isSafeInteger(config.maxTokens) || config.maxTokens < 1)
+      throw new Error('Learning requires an explicit positive maxTokens');
+    Object.assign(this, { business, learning, host, config: { ...config }, logger });
+    this.storage = business.storage;
+    this.defaults = defaults ?? new LearningDefaults({ business,
+      deployment: { ...config, cwd: config.cwd ?? host.workingDirectory?.defaultDirectory },
+      assertSelection: deploymentSelectionValidator(config) });
+    this.defaults.initialize();
+    this.onSettled = onSettled;
+    this.closed = false;
+    this.active = null;
+    this.handle = null;
+    this.rerunRequested = false;
+    this.closing = null;
+    this.creation = new AbortController();
+  }
+
+  executionConfigFor(id) { return learningExecutionConfig(this.storage.get('learning_runs', id)); }
+
+  updateRun(id, changes) {
+    const run = this.storage.get('learning_runs', id);
+    if (!run) throw new Error('Missing learning dispatch identity');
+    if ('executionConfig' in changes || 'defaultsRevision' in changes)
+      throw new Error('A started learning execution configuration cannot be replaced');
+    return this.storage.save('learning_runs', { ...run, ...changes }, { expectedRevision: run.revision });
+  }
+
+  attention(id, error) {
+    const details = { code: error?.code || 'learning_host_failure', message: String(error?.message || error) };
+    this.storage.transaction(() => {
+      const run = this.storage.get('learning_runs', id);
+      if (run && run.state !== 'settled') this.updateRun(id, {
+        state: run.state === 'prepared' ? 'failed' : 'unknown', error: details,
+      });
+      const pending = this.storage.get('learning_pending', id);
+      if (pending?.status === 'pending') this.storage.save('learning_pending', {
+        ...pending, status: 'needs_attention', error: details,
+        effect: 'the delivered answer is retained; no automatic model retry',
+      }, { expectedRevision: pending.revision });
+    });
+    this.logger.warn?.(`Arcfold learning ${id}: ${details.message}`);
+  }
+
+  kick() {
+    if (this.closed) return this.active || Promise.resolve();
+    if (this.active) { this.rerunRequested = true; return this.active; }
+    this.rerunRequested = false;
+    // Leave synchronous event publication. One helper at a time, independently
+    // of all main Agents; a new human input never awaits this promise.
+    const task = Promise.resolve().then(async () => {
+      while (!this.closed) {
+        const pending = this.storage.list('learning_pending', { where: { status: 'pending' }, limit: 1 })[0];
+        if (!pending) return;
+        try { await this.runOne(pending.id); }
+        catch (error) { this.attention(pending.id, error); }
+      }
+    });
+    this.active = task;
+    void task.finally(() => {
+      if (this.active === task) this.active = null;
+      if (this.rerunRequested && !this.closed) void this.kick().catch(error => this.logger.error?.(error));
+    }).catch(error => this.logger.error?.(error));
+    return task;
+  }
+
+  async readSession(sessionId, ownedHandle = null) {
+    const live = this.host.sessions.get(sessionId);
+    if (live && live !== ownedHandle?.agent.session) throw new Error('Recovery refused: the learning session already has a live owner');
+    let handle;
+    try { handle = await this.host.sessionPersistence.open(sessionId, 'read'); }
+    catch (error) {
+      if (error?.name === 'SessionPersistenceNotFoundError' && error.sessionId === sessionId) return null;
+      throw error;
+    }
+    try { return (await handle.read()).events; }
+    finally { await handle.close(); }
+  }
+
+  guardStream(options, next) {
+    const runs = typeof options.sessionId === 'string'
+      ? this.storage.listAll('learning_runs', { where: { sessionId: options.sessionId } }) : [];
+    if (!runs.length) return next();
+    const runner = this;
+    return (async function* () {
+      options.signal?.throwIfAborted();
+      const run = runner.storage.get('learning_runs', runs[0].id);
+      const execution = runner.executionConfigFor(run.id);
+      const input = runner.learning.prepare(run.id);
+      const originals = options.messages.filter(message => message.source?.kind === 'arcfold/learning');
+      const contexts = options.messages.filter(message => message.source?.kind === 'runtime-context');
+      const systems = options.messages.filter(message => message.role === 'system')
+        .flatMap(message => message.content || []).filter(block => block.type === 'text').map(block => block.text).join('\n');
+      const unexpected = options.messages.some(message => message.role !== 'system' &&
+        !['arcfold/learning', 'runtime-context'].includes(message.source?.kind));
+      const session = runner.host.sessions.get(options.sessionId);
+      if (runner.closed || runs.length !== 1 || run.state !== 'submitted' || run.dispatchCount !== 0 ||
+          options.purpose !== undefined || options.provider !== execution.provider || options.model !== execution.model ||
+          options.reasoningEffort !== execution.reasoningEffort || options.maxTokens !== execution.maxTokens ||
+          options.tools?.length || options.toolHistory?.tools?.length || options.toolHistory?.updates?.length ||
+          unexpected || options.system !== undefined ||
+          options.messages.length !== 3 || originals.length !== 1 || hash(originals[0]) !== hash(run.message) || systems !== input.prompt ||
+          !session || run.hostCwd !== execution.cwd || runner.host.workingDirectory.get(session) !== run.hostCwd || contexts.length !== 1 ||
+          !contextMatches(contexts[0], run.hostContext))
+        throw new Error('Learning request differs from its single-call, no-tools, frozen-input contract');
+      // This is a dispatch intent, NOT proof that a provider received or billed
+      // it. Persist before entering downstream code; uncertainty never retries.
+      runner.updateRun(run.id, { dispatchCount: 1, requestHash: hash({ messages: options.messages, tools: options.tools || [] }),
+        runtimeContextMessage: contexts[0],
+        dispatchEvidence: 'validated-before-downstream-stream; provider outcome requires native events' });
+      yield* next();
+    })();
+  }
+
+  async setup(agentCtx, input, execution) {
+    await this.host.agentPresets.mount(agentCtx, execution.preset);
+    agentCtx.tools.restrict({ allow: [] });
+    // Only this no-tools helper has a complete frozen prompt. Main Arcfold
+    // Agents retain DSH's native persona/tool instructions and runtime context.
+    agentCtx.systemPrompt.suppressRuntimeContext();
+    agentCtx.systemPrompt.section({ name: 'arcfold:learning', order: 50, interpolate: false, complete: true, text: input.prompt });
+    agentCtx.on('agent/pre-step', async (payload, next) => {
+      const decision = await next();
+      if (decision.kind === 'reject') return decision;
+      // DSH prepares once more with no messages to finish a normal turn. That
+      // empty completion check is not another model call and must remain valid.
+      if (payload.step > 1 && decision.messages.length) throw new Error('Learning accepts exactly one input and one model request');
+      this.learning.prepare(input.id);
+      if (payload.step === 1) {
+        const cwd = this.host.workingDirectory.get(payload.agent.session);
+        const contexts = decision.messages.filter(message => message.source?.kind === 'runtime-context');
+        const expected = directoryContext(cwd);
+        if (cwd !== execution.cwd || contexts.length !== 1 || !contextMatches(contexts[0], expected))
+          throw new Error('Learning requires the exact native working-directory context and no other runtime facts');
+        this.updateRun(input.id, { hostCwd: cwd, hostContext: expected });
+      }
+      return decision;
+    });
+    return { commit: () => {
+      if (this.closed) throw new Error('Learning plugin is stopping');
+      this.learning.prepare(input.id);
+    } };
+  }
+
+  async runOne(id) {
+    let run = this.storage.get('learning_runs', id);
+    let existingEvents = null;
+    if (run) {
+      // Inspect before resume: resuming a DSH Agent can start its pending inbox.
+      existingEvents = await this.readSession(run.sessionId);
+      if (run.state !== 'prepared') {
+        if (['submitted', 'settled', 'unknown'].includes(run.state) && existingEvents?.some(event => event.type === 'turn/end')) {
+          if (run.state === 'unknown') this.updateRun(id, { state: 'submitted',
+            recoveredFrom: 'unknown; durable-native-log-found-without-model-dispatch' });
+          const result = this.learning.commit(id, { sessionId: run.sessionId, events: existingEvents });
+          this.updateRun(id, { state: 'settled', resultStatus: result.status, recoveredFrom: 'durable-native-log' });
+          this.onSettled(id);
+          return result;
+        }
+        throw new Error('Prior learning submission has no complete durable result; no request was repeated');
+      }
+      if (existingEvents?.some(event => ['turn/start', 'user/message', 'agent/inbox/spliced', 'assistant/request'].includes(event.type)))
+        throw new Error('Prepared learning identity already contains execution evidence; automatic resume refused');
+    }
+    // A legacy prepared row is never filled from today's configuration.
+    if (run) this.executionConfigFor(id);
+    let input;
+    this.storage.transaction(() => {
+      input = this.learning.prepare(id);
+      if (run) return;
+      const snapshot = this.defaults.snapshot();
+      const message = { id: `arcfold-learning-${randomUUID()}`, role: 'user',
+        source: { kind: 'arcfold/learning', pendingId: id, deliveryId: input.deliveryId },
+        content: [{ type: 'text', text: input.inputText }] };
+      run = this.storage.save('learning_runs', { id, pendingId: id, deliveryId: input.deliveryId,
+        sessionId: `session-${randomUUID()}`, messageId: message.id, message,
+        inputHash: input.inputHash, state: 'prepared', dispatchCount: 0, ...snapshot,
+        authority: 'auxiliary-learning; does-not-act-as-human-or-authorize-tools' });
+    });
+    if (this.closed) return;
+    const execution = this.executionConfigFor(id);
+    const agentOptions = { provider: execution.provider, model: execution.model, maxTokens: execution.maxTokens,
+      reasoningEffort: execution.reasoningEffort };
+    const setup = agentCtx => this.setup(agentCtx, input, execution);
+    const handle = existingEvents
+      ? await this.host.agents.resume({ resumeSessionId: run.sessionId, agentOptions, setup, signal: this.creation.signal })
+      : await this.host.agents.create({ sessionId: run.sessionId, agentOptions, setup,
+        signal: this.creation.signal,
+        meta: { agentPreset: execution.preset, cwd: execution.cwd } });
+    this.handle = handle;
+    try {
+      if (this.closed) throw new Error('Learning plugin stopped before submission');
+      if (await this.host.sessions.flush(handle.agent.session) !== true)
+        throw new Error('Learning requires a durable native session writer');
+      this.learning.prepare(id);
+      this.updateRun(id, { state: 'submitted', submissionEvidence: 'intent persisted before followup; not proof of provider receipt' });
+      handle.agent.followup(run.message);
+      await handle.agent.whenIdle();
+      const expected = handle.agent.session.snapshotEvents();
+      let events;
+      try {
+        if (await this.host.sessions.flush(handle.agent.session) !== true)
+          throw new Error('Learning output was not confirmed durable');
+        events = await this.readSession(run.sessionId, handle);
+      } catch (error) {
+        if (!this.closed) throw error;
+        // Cordis unloads sibling effects in parallel, including the host's
+        // handle owner. Wait for that same disposer and then read durable data.
+        await handle.dispose();
+        events = await this.readSession(run.sessionId);
+      }
+      if (!events || events.length < expected.length || hash(events.slice(0, expected.length)) !== hash(expected))
+        throw new Error('Durable learning readback differs from the completed native prefix');
+      const result = this.learning.commit(id, { sessionId: run.sessionId, events });
+      this.updateRun(id, { state: 'settled', resultStatus: result.status });
+      this.onSettled(id);
+      return result;
+    } finally {
+      await handle.dispose();
+      if (this.handle === handle) this.handle = null;
+    }
+  }
+
+  close() {
+    if (!this.closing) {
+      this.closed = true;
+      this.creation.abort(new Error('Learning plugin is stopping'));
+      // DSH owns cancellation, native session persistence and tool cleanup.
+      this.closing = (async () => {
+        this.handle?.agent.cancel({ kind: 'disposed' }, { keepInbox: true });
+        await this.active;
+      })();
+    }
+    return this.closing;
+  }
+
+  async recover() {
+    // Read-only recovery of already-submitted work; never creates/resumes an
+    // Agent. Complete durable output can be committed even after a prior stop.
+    for (const run of this.storage.listAll('learning_runs')) {
+      if (!['submitted', 'unknown'].includes(run.state)) continue;
+      try {
+        const events = await this.readSession(run.sessionId);
+        if (!events?.some(event => event.type === 'turn/end')) throw new Error('Learning outcome remains unknown; request was not repeated');
+        if (run.state === 'unknown') this.updateRun(run.id, { state: 'submitted', recoveredFrom: 'durable-native-log; no-model-retry' });
+        const result = this.learning.commit(run.id, { sessionId: run.sessionId, events });
+        this.updateRun(run.id, { state: 'settled', resultStatus: result.status, recoveredFrom: 'durable-native-log' });
+        this.onSettled(run.id);
+      } catch (error) { this.attention(run.id, error); }
+    }
+  }
+}