blun-king-cli 9.1.589 → 9.1.595

package/bin/agentspine-king-goal-intake.mjs

@@ -0,0 +1,106 @@
+import { createHash } from 'node:crypto';
+import { lstat, readFile, realpath } from 'node:fs/promises';
+import path from 'node:path';
+
+const ASSIGNMENT_SCHEMA = 'blun.king-goal-assignment/v1';
+const INSTRUCTION_RE = /(ZIEL-[A-Za-z0-9._-]+\.json)\b[^\r\n]{0,200}?\bsha256\b\s*[=:]?\s*([a-f0-9]{64})(?:\s|[),.;]|$)/iu;
+
+function digest(value) {
+  return createHash('sha256').update(value).digest('hex');
+}
+
+function parseGoalInstruction(text) {
+  const match = String(text || '').match(INSTRUCTION_RE);
+  if (!match) throw new Error('GOAL_INSTRUCTION_REQUIRES_FILE_AND_SHA256');
+  return Object.freeze({ fileName: match[1], sha256: match[2].toLowerCase() });
+}
+
+function assignmentInput(value) {
+  if (!value || value.schema !== ASSIGNMENT_SCHEMA || typeof value.goalId !== 'string'
+    || typeof value.logicalPersonaId !== 'string' || typeof value.successCriterion !== 'string'
+    || !Array.isArray(value.steps) || value.steps.length === 0) {
+    throw new Error('GOAL_ASSIGNMENT_INVALID');
+  }
+  assertTerminalGoalGate(value.steps);
+  return value;
+}
+
+function assertTerminalGoalGate(steps) {
+  const ids = new Set(steps.map((step) => step?.stepId));
+  if (ids.size !== steps.length || ids.has(undefined)) throw new Error('GOAL_PLAN_STEP_IDS_INVALID');
+  const dependedOn = new Set(steps.flatMap((step) => Array.isArray(step.dependsOn) ? step.dependsOn : []));
+  const terminalSteps = steps.filter((step) => !dependedOn.has(step.stepId));
+  if (terminalSteps.length !== 1 || !terminalSteps[0].execution?.verification) {
+    throw new Error('GOAL_PLAN_TERMINAL_GATE_REQUIRED');
+  }
+  const terminalId = terminalSteps[0].stepId;
+  const byId = new Map(steps.map((step) => [step.stepId, step]));
+  const reachesGate = (stepId, seen = new Set()) => {
+    if (stepId === terminalId) return true;
+    if (seen.has(stepId)) return false;
+    seen.add(stepId);
+    return steps.some((candidate) => Array.isArray(candidate.dependsOn)
+      && candidate.dependsOn.includes(stepId) && reachesGate(candidate.stepId, new Set(seen)));
+  };
+  if ([...byId.keys()].some((stepId) => !reachesGate(stepId))) {
+    throw new Error('GOAL_PLAN_TERMINAL_GATE_MUST_DEPEND_ON_ALL_STEPS');
+  }
+}
+
+function inside(directory, candidate) {
+  const relative = path.relative(directory, candidate);
+  return relative !== '..' && !relative.startsWith(`..${path.sep}`) && !path.isAbsolute(relative);
+}
+
+async function readVerifiedGoalFile(exchangeDirectory, instruction) {
+  const exchange = await realpath(path.resolve(exchangeDirectory));
+  const candidate = path.resolve(exchange, instruction.fileName);
+  if (!inside(exchange, candidate)) throw new Error('GOAL_FILE_OUTSIDE_EXCHANGE');
+  const metadata = await lstat(candidate);
+  if (!metadata.isFile() || metadata.isSymbolicLink() || metadata.size > 1024 * 1024) {
+    throw new Error('GOAL_FILE_NOT_REGULAR');
+  }
+  const canonical = await realpath(candidate);
+  if (!inside(exchange, canonical)) throw new Error('GOAL_FILE_OUTSIDE_EXCHANGE');
+  const payload = await readFile(canonical);
+  if (digest(payload) !== instruction.sha256) throw new Error('GOAL_FILE_SHA256_MISMATCH');
+  let value;
+  try { value = JSON.parse(payload.toString('utf8')); }
+  catch { throw new Error('GOAL_FILE_INVALID_JSON'); }
+  return { assignment: assignmentInput(value), filePath: canonical, sha256: instruction.sha256 };
+}
+
+async function ingestGoalInstruction(input) {
+  const instruction = parseGoalInstruction(input.instructionText);
+  const verified = await readVerifiedGoalFile(input.exchangeDirectory, instruction);
+  const value = verified.assignment;
+  if (value.logicalPersonaId !== input.logicalPersonaId) throw new Error('GOAL_PERSONA_MISMATCH');
+  if (value.projectId !== input.projectId) throw new Error('GOAL_PROJECT_MISMATCH');
+  if (value.groupId !== input.groupId || value.ownerSubjectId !== input.ownerSubjectId) {
+    throw new Error('GOAL_AUTHORITY_MISMATCH');
+  }
+  if (value.snapshotSha256 !== input.snapshot.snapshotSha256) throw new Error('GOAL_SNAPSHOT_MISMATCH');
+  const result = await input.assignGoal({
+    root: input.snapshot.root,
+    goalId: value.goalId,
+    agentId: input.runtimePersonaId,
+    ownerSubjectId: value.ownerSubjectId,
+    projectId: value.projectId,
+    groupId: value.groupId,
+    priority: value.priority ?? 70,
+    successCriterion: value.successCriterion,
+    nextSafeStep: value.nextSafeStep ?? null,
+    steps: value.steps,
+    deadline: value.deadline ?? null,
+    confirmation: 'local-owner-confirmed',
+  });
+  return Object.freeze({ ...verified, duplicate: result.duplicate === true, goal: result.goal });
+}
+
+export {
+  ASSIGNMENT_SCHEMA,
+  assertTerminalGoalGate,
+  ingestGoalInstruction,
+  parseGoalInstruction,
+  readVerifiedGoalFile,
+};

package/bin/agentspine-king-host-runner.mjs

@@ -0,0 +1,109 @@
+import { randomUUID } from 'node:crypto';
+
+export const MAX_RAW_BYTES = 64 * 1024;
+export const MAX_CHECKPOINT_BYTES = 16 * 1024;
+export const MAX_TICK_MS = 1_800_000;
+export const RESULT_SCHEMA = 'agentspine.blun-step-result/v1';
+const HOST_ENVIRONMENT_KEYS = [
+  'AGENTSPINE_GATEWAY_CONTEXT', 'AGENTSPINE_ENTITY_ID', 'AGENTSPINE_PROJECT_ID',
+  'AGENTSPINE_HOST', 'AGENTSPINE_GATEWAY_QUEUE_ID', 'AGENTSPINE_GATEWAY_ATTEMPT',
+  'AGENTSPINE_GROUP_ID', 'AGENTSPINE_GOAL_ID', 'AGENTSPINE_GOAL_STEP_ID',
+  'AGENTSPINE_PLAN_DEFINITIONS_DIGEST', 'AGENTSPINE_CHANNEL_EVENT_ID',
+  'AGENTSPINE_CHANNEL_PROVIDER', 'AGENTSPINE_PORTAL_REF', 'AGENTSPINE_THREAD_REF',
+];
+
+function goalSessionKaos(kaos, environment) {
+  if (environment === undefined) return kaos;
+  if (!environment || typeof environment !== 'object' || Array.isArray(environment)
+    || Object.entries(environment).some(([key, value]) => !HOST_ENVIRONMENT_KEYS.includes(key)
+      || typeof value !== 'string' || value.includes('\0'))) throw new Error('GOAL_WORKER_ENVIRONMENT_INVALID');
+  if (typeof kaos?.withEnv !== 'function') throw new Error('GOAL_WORKER_ENVIRONMENT_REQUIRED');
+  // Replace the complete per-tick scope without changing process.env or the base Kaos.
+  return kaos.withEnv(Object.fromEntries(HOST_ENVIRONMENT_KEYS.map(key => [key, environment[key] ?? ''])));
+}
+
+export function buildGoalPrompt(item) {
+  return 'Execute exactly one bounded goal-plan tick. Return exactly one visible final JSON object.\n'
+    + JSON.stringify({ schema: 'agentspine.blun-step-request/v1', goal: item.goal, goalStep: item.goalStep,
+      selfHelpPolicy: item.selfHelpPolicy, requiredResult: { schema: RESULT_SCHEMA,
+        fields: ['text', 'checkpoint', 'completed', 'blocked', 'blocker', 'knowledgeGap', 'selfHelp', 'execution'],
+        rule: 'Every tick requires a non-null checkpoint; only report completed work backed by verification.' } });
+}
+
+export function parseGoalResult(text) {
+  if (Buffer.byteLength(text, 'utf8') > MAX_RAW_BYTES) throw new Error('GOAL_STEP_RESULT_EXCEEDS_64_KIB');
+  let value;
+  try { value = JSON.parse(text.trim()); } catch { throw new Error('GOAL_STEP_RESULT_INVALID_JSON'); }
+  if (!value || value.schema !== RESULT_SCHEMA || typeof value.text !== 'string'
+    || !value.text.trim() || value.text.length > 16000
+    || (value.completed !== undefined && typeof value.completed !== 'boolean')
+    || (value.blocked !== undefined && typeof value.blocked !== 'boolean')
+    || (value.completed === true && value.blocked === true)) throw new Error('GOAL_STEP_RESULT_INVALID');
+  if (value.checkpoint === undefined || value.checkpoint === null) throw new Error('GOAL_STEP_CHECKPOINT_REQUIRED');
+  if (Buffer.byteLength(JSON.stringify(value.checkpoint), 'utf8') > MAX_CHECKPOINT_BYTES) {
+    throw new Error('GOAL_STEP_CHECKPOINT_TOO_LARGE');
+  }
+  return value;
+}
+
+export function runSessionStep(session, item, timeoutMs, signal) {
+  return new Promise((resolve, reject) => {
+    let ended = false;
+    let text = '';
+    let turnId;
+    let unsubscribe = () => {};
+    const finish = (error) => {
+      if (ended) return;
+      ended = true; clearTimeout(timer); unsubscribe(); signal?.removeEventListener('abort', aborted);
+      if (error) { reject(error); return; }
+      try { resolve(parseGoalResult(text)); } catch (error) { reject(error); }
+    };
+    const aborted = () => finish(new Error('GOAL_WORKER_STOP_REQUESTED'));
+    const timer = setTimeout(() => finish(new Error('GOAL_STEP_DEADLINE')), timeoutMs);
+    unsubscribe = session.onEvent((event) => {
+      if (event.sessionId !== session.id || event.agentId !== 'main') return;
+      if (event.type === 'turn.started' && turnId === undefined) { turnId = event.turnId; return; }
+      if (event.type === 'error') { finish(new Error('GOAL_STEP_SESSION_ERROR')); return; }
+      if (turnId === undefined || event.turnId !== turnId) return;
+      if (event.type === 'turn.step.started' || event.type === 'turn.step.retrying') text = '';
+      if (event.type === 'assistant.delta') {
+        text += event.delta;
+        if (Buffer.byteLength(text, 'utf8') > MAX_RAW_BYTES) finish(new Error('GOAL_STEP_RESULT_EXCEEDS_64_KIB'));
+      }
+      if (event.type === 'turn.ended') finish(event.reason === 'completed' ? null : new Error('GOAL_STEP_TURN_NOT_COMPLETED'));
+    });
+    signal?.addEventListener('abort', aborted, { once: true });
+    if (signal?.aborted) aborted();
+    if (!ended) Promise.resolve().then(() => { if (!ended) return session.prompt(buildGoalPrompt(item)); }).catch(finish);
+  });
+}
+
+export function createGoalHostFactory({ harness, workDir, model, permission, tickTimeoutMs = MAX_TICK_MS,
+  cleanupTimeoutMs = 10000, sessionOptions, onSession, signal }) {
+  if (!Number.isInteger(tickTimeoutMs) || tickTimeoutMs < 1000 || tickTimeoutMs > MAX_TICK_MS
+    || !Number.isInteger(cleanupTimeoutMs) || cleanupTimeoutMs < 1 || cleanupTimeoutMs > 60000) {
+    throw new Error('GOAL_WORKER_TIMEOUT_OUT_OF_RANGE');
+  }
+  if (!['manual', 'auto', 'yolo'].includes(permission)) throw new Error('GOAL_WORKER_PERMISSION_REQUIRED');
+  return async (item) => {
+    if (item.projectRoot !== workDir || !item.goal) throw new Error('GOAL_WORKER_SCOPE_MISMATCH');
+    const session = await harness.createSession({ ...sessionOptions, id: 'worker-' + randomUUID(),
+      workDir, model, permission, kaos: goalSessionKaos(sessionOptions?.kaos, item.hostEnvironment),
+      metadata: { gatewayQueueId: item.queueId, gatewayAttempt: item.attempts } });
+    onSession?.(session);
+    let started = false;
+    return { sessionId: session.id,
+      async run() {
+        if (started) throw new Error('GOAL_WORKER_SESSION_ALREADY_RUN');
+        started = true;
+        return runSessionStep(session, item, tickTimeoutMs, signal);
+      },
+      async quiesce() {
+        const proof = await session.quiesce({ deadlineAt: Date.now() + cleanupTimeoutMs });
+        if (proof.status === 'quiescent' && proof.sessionId === session.id && proof.remaining.length === 0) {
+          await session.close();
+        }
+        return proof;
+      } };
+  };
+}

package/bin/agentspine-king-snapshot-policy.cjs

@@ -0,0 +1,80 @@
+'use strict';
+
+const { createHash } = require('node:crypto');
+const fs = require('node:fs');
+const path = require('node:path');
+
+const STAND_SCHEMA = 'blun.snapshot-stand/v1';
+const SHA256_RE = /^[a-f0-9]{64}$/iu;
+
+function sha256(value) {
+  return createHash('sha256').update(value).digest('hex');
+}
+
+function exactSha(value, label) {
+  const digest = String(value || '').trim().toLowerCase();
+  if (!SHA256_RE.test(digest)) throw new Error(`${label} must be a SHA256 digest`);
+  return digest;
+}
+
+function isInside(root, candidate) {
+  const relative = path.relative(root, candidate);
+  return relative === '' || (!relative.startsWith(`..${path.sep}`) && relative !== '..' && !path.isAbsolute(relative));
+}
+
+function standMetadata(fsImpl, root, standPath) {
+  if (!isInside(root, standPath)) throw new Error('SNAPSHOT_STAND_OUTSIDE_WORKSPACE');
+  const parts = path.relative(root, standPath).split(path.sep);
+  let cursor = root;
+  let metadata;
+  for (let index = 0; index < parts.length; index++) {
+    cursor = path.join(cursor, parts[index]);
+    metadata = fsImpl.lstatSync(cursor, { bigint: true });
+    if (metadata.isSymbolicLink() || (index < parts.length - 1 ? !metadata.isDirectory() : !metadata.isFile())) {
+      throw new Error('SNAPSHOT_STAND_NOT_REGULAR');
+    }
+  }
+  if (!isInside(root, fsImpl.realpathSync(standPath))) throw new Error('SNAPSHOT_STAND_OUTSIDE_WORKSPACE');
+  return metadata;
+}
+
+function sameFile(left, right) {
+  return left.isFile() && right.isFile() && ['dev', 'ino', 'size', 'mtimeNs', 'ctimeNs']
+    .every(key => left[key] === right[key]);
+}
+
+function verifyWorkspaceSnapshot(input, options = {}) {
+  const fsImpl = options.fsImpl || fs;
+  const root = fsImpl.realpathSync(path.resolve(input.root));
+  const standPath = path.resolve(root, input.standFile || '.blun-snapshot-stand.json');
+  const metadata = standMetadata(fsImpl, root, standPath);
+  const descriptor = fsImpl.openSync(standPath, fs.constants.O_RDONLY | (fs.constants.O_NOFOLLOW || 0));
+  let payload;
+  try {
+    const before = fsImpl.fstatSync(descriptor, { bigint: true });
+    if (!sameFile(metadata, before)) throw new Error('SNAPSHOT_STAND_CHANGED');
+    payload = fsImpl.readFileSync(descriptor);
+    const after = fsImpl.fstatSync(descriptor, { bigint: true });
+    if (!sameFile(before, after) || !sameFile(after, standMetadata(fsImpl, root, standPath))) {
+      throw new Error('SNAPSHOT_STAND_CHANGED');
+    }
+  } finally { fsImpl.closeSync(descriptor); }
+  const standSha256 = sha256(payload);
+  if (standSha256 !== exactSha(input.expectedStandSha256, 'expectedStandSha256')) {
+    throw new Error('SNAPSHOT_STAND_SHA256_MISMATCH');
+  }
+  let stand;
+  try { stand = JSON.parse(payload.toString('utf8')); }
+  catch { throw new Error('SNAPSHOT_STAND_INVALID_JSON'); }
+  if (stand?.schema !== STAND_SCHEMA || typeof stand.projectId !== 'string') {
+    throw new Error('SNAPSHOT_STAND_INVALID');
+  }
+  const snapshotSha256 = exactSha(stand.snapshotSha256, 'snapshotSha256');
+  if (snapshotSha256 !== exactSha(input.expectedSnapshotSha256, 'expectedSnapshotSha256')) {
+    throw new Error('SNAPSHOT_SHA256_MISMATCH');
+  }
+  if (stand.projectId !== input.projectId) throw new Error('SNAPSHOT_PROJECT_MISMATCH');
+  return Object.freeze({ root, standPath, standSha256, snapshotSha256, projectId: stand.projectId });
+}
+
+module.exports = { STAND_SCHEMA, verifyWorkspaceSnapshot };

package/bin/agentspine-king-status-policy.mjs

@@ -0,0 +1,226 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { lstat, mkdir, open, readFile, realpath, rename, unlink } from 'node:fs/promises';
+import path from 'node:path';
+
+const SCHEMA = 'blun.king-goal-status/v2';
+const MAX_BYTES = 4 * 1024 * 1024;
+const STATES = new Set(['pending', 'dispatching', 'uncertain', 'delivered']);
+const RESULT_REJECTIONS = new Set(['GOAL_STEP_RESULT_EXCEEDS_64_KIB', 'GOAL_STEP_RESULT_INVALID_JSON',
+  'GOAL_STEP_RESULT_INVALID', 'GOAL_STEP_CHECKPOINT_REQUIRED', 'GOAL_STEP_CHECKPOINT_TOO_LARGE']);
+const digest = value => createHash('sha256').update(JSON.stringify(value)).digest('hex');
+const identifier = value => typeof value === 'string' && /^[A-Za-z0-9:._@/-]{1,200}$/.test(value);
+const routeKeys = ['id', 'provider', 'tenantId', 'accountId', 'chatId', 'threadId', 'agentId',
+  'projectId', 'groupId', 'createdAt'];
+
+export function goalResultRejectionCode(error) {
+  const code = String(error?.message ?? error).replace(/^Host runtime unavailable: /, '');
+  return RESULT_REJECTIONS.has(code) ? code : null;
+}
+
+function normalizeScope(input) {
+  const keys = ['logicalPersonaId', 'runtimePersonaId', 'projectId', 'groupId', 'ownerSubjectId',
+    'chatId', 'senderId'];
+  if (!input || keys.some(key => !identifier(input[key]))
+    || (input.threadId !== null && input.threadId !== undefined && !identifier(input.threadId))) throw new Error('GOAL_STATUS_SCOPE_INVALID');
+  return { ...Object.fromEntries(keys.map(key => [key, input[key]])), threadId: input.threadId ?? null };
+}
+
+function errorCode(error) {
+  return /^(GOAL_[A-Z0-9_]{1,100})(?::|\s|$)/.exec(String(error ?? ''))?.[1] ?? 'GOAL_STATUS_OPERATION_REJECTED';
+}
+
+function normalizeEvent(input) {
+  if (!input || !identifier(input.eventId)) throw new Error('GOAL_STATUS_EVENT_INVALID');
+  if (input.kind === 'intake-rejected' && identifier(input.messageId)) {
+    return { kind: input.kind, eventId: input.eventId, messageId: input.messageId, error: errorCode(input.error) };
+  }
+  if (!identifier(input.goalId) || (input.goalStepId !== null && input.goalStepId !== undefined && !identifier(input.goalStepId))) {
+    throw new Error('GOAL_STATUS_EVENT_INVALID');
+  }
+  const event = { kind: input.kind, eventId: input.eventId, goalId: input.goalId, goalStepId: input.goalStepId ?? null };
+  if (input.kind === 'result-rejected' && Number.isSafeInteger(input.attempt) && input.attempt > 0) {
+    return { ...event, attempt: input.attempt, error: errorCode(input.error) };
+  }
+  if (input.kind !== 'goal-status' || !identifier(input.status)
+    || !['offen', 'blockiert', 'bestanden'].includes(input.gate)) throw new Error('GOAL_STATUS_EVENT_INVALID');
+  return { ...event, status: input.status, gate: input.gate };
+}
+
+function message(scope, event) {
+  if (event.kind === 'intake-rejected') {
+    return `${scope.logicalPersonaId} | Zielannahme Nachricht ${event.messageId} | abgelehnt | ${event.error}`;
+  }
+  if (event.kind === 'result-rejected') {
+    return `${scope.logicalPersonaId} | Zielantwort ${event.goalId} / ${event.goalStepId ?? '-'} | abgelehnt ${event.attempt} | ${event.error}`;
+  }
+  return `${scope.logicalPersonaId} | Ziel ${event.goalId} | Schritt ${event.goalStepId ?? '-'} | ${event.status} | Gate ${event.gate}`;
+}
+
+function matches(binding, scope) {
+  return binding?.status === 'active' && binding.provider === 'telegram'
+    && binding.authority === 'explicit-local-channel-policy'
+    && binding.agentId === scope.runtimePersonaId && binding.projectId === scope.projectId
+    && binding.groupId === scope.groupId && binding.chatId === scope.chatId
+    && (binding.threadId ?? null) === scope.threadId
+    && binding.senderIds?.includes(scope.senderId) && binding.capabilities?.includes('reply');
+}
+
+function selectRoute(loaded, scope) {
+  const candidates = loaded?.policy?.bindings?.filter(binding => matches(binding, scope)) ?? [];
+  if (candidates.length !== 1) return null;
+  const binding = candidates[0];
+  if (routeKeys.some(key => key !== 'threadId' && (typeof binding[key] !== 'string' || !binding[key]))) return null;
+  return Object.fromEntries(routeKeys.map(key => [key, binding[key] ?? null]));
+}
+
+function sameRoute(left, right) {
+  return left && right && routeKeys.every(key => left[key] === right[key]);
+}
+
+async function assertRegular(file) {
+  try {
+    const meta = await lstat(file);
+    if (!meta.isFile() || meta.isSymbolicLink()) throw new Error('GOAL_STATUS_NOT_REGULAR');
+  } catch (error) { if (error.code !== 'ENOENT') throw error; }
+}
+
+async function loadState(file) {
+  await assertRegular(file);
+  let bytes;
+  try { bytes = await readFile(file); } catch (error) {
+    if (error.code === 'ENOENT') return { schema: SCHEMA, receipts: [] };
+    throw error;
+  }
+  try {
+    if (bytes.length > MAX_BYTES) throw new Error('oversized');
+    const state = JSON.parse(bytes);
+    if (state?.schema !== SCHEMA || !Array.isArray(state.receipts)) throw new Error('schema');
+    const keys = new Set();
+    for (const record of state.receipts) {
+      const scope = normalizeScope(record.scope);
+      const event = normalizeEvent(record.event);
+      if (JSON.stringify(scope) !== JSON.stringify(record.scope) || JSON.stringify(event) !== JSON.stringify(record.event)
+        || record.key !== digest({ scope, event }) || keys.has(record.key) || !STATES.has(record.status)
+        || !Number.isSafeInteger(record.nextAttemptAt) || record.nextAttemptAt < 0
+        || !Number.isSafeInteger(record.attempts) || record.attempts < 0
+        || (record.route !== null && (!record.route || routeKeys.some(key => !(key in record.route))))
+        || (record.status === 'delivered' && !/^telegram-message:\d+$/.test(record.receipt))) throw new Error('receipt');
+      keys.add(record.key);
+    }
+    return state;
+  } catch { throw new Error('GOAL_STATUS_STATE_INVALID'); }
+}
+
+async function saveState(file, state, assertOwned) {
+  const bytes = JSON.stringify(state) + '\n';
+  if (Buffer.byteLength(bytes) > MAX_BYTES) throw new Error('GOAL_STATUS_CAPACITY');
+  const temporary = `${file}.${randomUUID()}.tmp`;
+  const handle = await open(temporary, 'wx', 0o600);
+  try {
+    await handle.writeFile(bytes);
+    await handle.sync();
+  } finally { await handle.close(); }
+  try {
+    await assertOwned();
+    await assertRegular(file);
+    await rename(temporary, file);
+  } finally { await unlink(temporary).catch(error => { if (error.code !== 'ENOENT') throw error; }); }
+}
+
+export function createGoalStatusReporter({ stateFile, scope: inputScope, withOwnedFileLock,
+  loadPolicy, adapter, now = Date.now, maxRecords = 512 }) {
+  const scope = normalizeScope(inputScope);
+  if (!path.isAbsolute(stateFile) || typeof withOwnedFileLock !== 'function'
+    || typeof loadPolicy !== 'function' || typeof adapter?.send !== 'function'
+    || !Number.isSafeInteger(maxRecords) || maxRecords < 1) throw new Error('GOAL_STATUS_CONFIG_INVALID');
+  const scopeKey = digest(scope);
+  const transact = async task => {
+    const directory = path.dirname(stateFile);
+    await mkdir(directory, { recursive: true });
+    if (path.relative(directory, await realpath(directory)) !== '') throw new Error('GOAL_STATUS_DIRECTORY_REDIRECTED');
+    const assertPath = async () => {
+      if (path.relative(directory, await realpath(directory)) !== '') throw new Error('GOAL_STATUS_DIRECTORY_REDIRECTED');
+      await assertRegular(`${stateFile}.lock`);
+    };
+    return withOwnedFileLock(`${stateFile}.lock`, async ({ assertOwned }) => {
+      const state = await loadState(stateFile);
+      return task(state, () => saveState(stateFile, state, assertOwned), assertOwned);
+    }, { assertPath });
+  };
+
+  const record = async input => {
+    const event = normalizeEvent(input);
+    return transact(async (state, save) => {
+      const key = digest({ scope, event });
+      const existing = state.receipts.find(row => row.key === key);
+      if (existing) return { key, status: existing.status };
+      // Retain the deduplication history and every unresolved delivery; never silently evict one.
+      if (state.receipts.length >= maxRecords) throw new Error('GOAL_STATUS_CAPACITY');
+      state.receipts.push({ key, scope, event, route: selectRoute(await loadPolicy(), scope),
+        status: 'pending', attempts: 0, nextAttemptAt: 0, receipt: null });
+      await save();
+      return { key, status: 'pending' };
+    });
+  };
+
+  const flush = () => transact(async (state, save, assertOwned) => {
+    const results = [];
+    for (const row of state.receipts) {
+      if (digest(row.scope) !== scopeKey || row.status === 'delivered') continue;
+      const result = status => { results.push({ key: row.key, status }); };
+      // A process may have died after Telegram accepted the request but before the receipt was saved.
+      if (row.status === 'dispatching') { row.status = 'uncertain'; await save(); }
+      if (row.status === 'uncertain') { result('uncertain'); continue; }
+      const current = selectRoute(await loadPolicy(), scope);
+      if (!current) { result(row.route ? 'route-changed' : 'unrouted'); continue; }
+      if (row.route && !sameRoute(row.route, current)) { result('route-changed'); continue; }
+      if (row.nextAttemptAt > now()) { result('waiting'); continue; }
+      row.route ??= current;
+      row.status = 'dispatching'; row.attempts++;
+      await save();
+      if (!sameRoute(row.route, selectRoute(await loadPolicy(), scope))) {
+        row.status = 'pending'; await save(); result('route-changed'); continue;
+      }
+      await assertOwned();
+      let outcome;
+      try {
+        outcome = await adapter.send({ provider: row.route.provider, bindingId: row.route.id,
+          tenantId: row.route.tenantId, accountId: row.route.accountId, chatId: row.route.chatId,
+          threadId: row.route.threadId, replyTo: null,
+          idempotencyKey: row.key, text: message(scope, row.event) });
+      } catch { outcome = { ok: false, effect: 'unknown' }; }
+      if (outcome?.ok === true && /^telegram-message:\d+$/.test(outcome.receipt)) {
+        row.status = 'delivered'; row.receipt = outcome.receipt;
+      } else if (outcome?.ok === false && outcome.effect === 'none') {
+        row.status = 'pending';
+        const wait = Number.isSafeInteger(outcome.retryAfterMs) && outcome.retryAfterMs > 0 ? outcome.retryAfterMs : 15000;
+        row.nextAttemptAt = Math.min(Number.MAX_SAFE_INTEGER, now() + wait);
+      } else { row.status = 'uncertain'; }
+      await save();
+      result(row.status);
+    }
+    return results;
+  });
+
+  const reconcile = async context => {
+    for (const goal of context.goals) {
+      if (goal.agentId !== scope.runtimePersonaId || goal.projectId !== scope.projectId
+        || goal.groupId !== scope.groupId || goal.ownerSubjectId !== scope.ownerSubjectId) continue;
+      const rows = context.queue.filter(row => row.goalId === goal.goalId && row.agentId === scope.runtimePersonaId
+        && row.projectId === scope.projectId && row.groupId === scope.groupId && row.attempts > 0);
+      const row = rows.toSorted((a, b) => a.updatedAt.localeCompare(b.updatedAt)).at(-1);
+      if (!row) continue;
+      const step = goal.plan?.steps.find(item => item.stepId === row.goalStepId);
+      if (row.goalStepId && !step) continue;
+      const identity = { eventId: `${row.queueId}:${row.attempts}`, goalId: goal.goalId, goalStepId: row.goalStepId ?? null };
+      const rejection = goalResultRejectionCode(row.lastError);
+      if (rejection) {
+        await record({ ...identity, kind: 'result-rejected', attempt: row.attempts, error: rejection });
+      }
+      const status = row.status === 'blocked' ? 'blocked' : step?.status ?? goal.status;
+      await record({ ...identity, kind: 'goal-status', status,
+        gate: goal.status === 'completed' ? 'bestanden' : status === 'blocked' ? 'blockiert' : 'offen' });
+    }
+  };
+  return Object.freeze({ record, flush, reconcile });
+}