@agentpulselabs/cli-plugin-pulse 0.2.0 → 1.0.0

package/src/lib/ledger.js

@@ -0,0 +1,535 @@
+import path from 'node:path';
+import { ensureOwnerOnlyDirectory, readOwnerOnlyJson, writeOwnerOnlyJson } from './storage.js';
+import { HubError } from './errors.js';
+import { HUB_JOB_TYPES } from './intents.js';
+import { redactSecretsDeep } from './redaction.js';
+
+const STATE_FILE = 'ledger.json';
+const SCHEMA_VERSION = 1;
+const TERMINAL_STATES = new Set(['cancelled', 'succeeded', 'failed', 'fenced']);
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+const TRANSITIONS = Object.freeze({
+  leased: new Set(['running', 'cancel_requested', 'cancelled', 'succeeded', 'failed', 'fenced']),
+  running: new Set(['cancel_requested', 'cancelled', 'succeeded', 'failed', 'fenced']),
+  cancel_requested: new Set(['cancelled', 'succeeded', 'failed', 'fenced']),
+  cancelled: new Set(),
+  succeeded: new Set(),
+  failed: new Set(),
+  fenced: new Set(),
+});
+const MAX_OUTBOX_EVENTS = 10_000;
+const MAX_LEDGER_BYTES = 16 * 1024 * 1024;
+const EVENT_TYPES = new Set([
+  'agent.started',
+  'agent.progress',
+  'agent.waiting',
+  'agent.completed',
+  'agent.failed',
+  'job.started',
+  'job.progress',
+  'job.cancel_acknowledged',
+  'job.cancelled',
+  'job.succeeded',
+  'job.failed',
+  'evidence.available',
+  'content_withheld',
+]);
+const JOB_EVENT_TYPES = new Map([
+  ['delivery.plan', new Set(['job.started', 'job.progress', 'job.succeeded', 'job.failed', 'content_withheld'])],
+  ['workspace.inspect', new Set(['job.started', 'job.progress', 'job.cancel_acknowledged', 'job.cancelled', 'job.succeeded', 'job.failed', 'content_withheld'])],
+  ['worktree.create', new Set(['job.started', 'job.progress', 'job.cancel_acknowledged', 'job.cancelled', 'job.succeeded', 'job.failed', 'content_withheld'])],
+  ['git.inspect', new Set(['job.started', 'job.progress', 'job.cancel_acknowledged', 'job.cancelled', 'job.succeeded', 'job.failed', 'content_withheld'])],
+  ['agent.start', EVENT_TYPES],
+  ['agent.turn', EVENT_TYPES],
+  ['agent.stop', EVENT_TYPES],
+  ['evidence.collect', new Set(['job.started', 'job.progress', 'job.cancel_acknowledged', 'job.cancelled', 'job.succeeded', 'job.failed', 'evidence.available', 'content_withheld'])],
+]);
+for (const type of HUB_JOB_TYPES) JOB_EVENT_TYPES.set(type, new Set(['job.started', 'job.succeeded', 'job.failed']));
+const PROCESS_JOB_TYPES = new Set(['agent.start', 'agent.turn']);
+// The cloud requeues a hub action whose lease lapsed. Its new attempt replaces the old one here and keeps it as `prior`,
+// so the handler can tell whether the hub may already have taken the write (startedAt set) and never post twice.
+const RECLAIMABLE_JOB_TYPES = new Set(HUB_JOB_TYPES);
+
+function initialState() {
+  return {
+    schemaVersion: SCHEMA_VERSION,
+    nextSequence: 1,
+    cloudCursor: 0,
+    localCursor: 0,
+    acceptedLocalCursor: 0,
+    outbox: [],
+    attempts: {},
+  };
+}
+
+/**
+ * The highest local sequence the cloud has accepted. localCursor counts every event queued, uploaded or not, and the
+ * cloud refuses a session whose cursor is ahead of what it holds (event_cursor_invalid), so only this is reported.
+ * A ledger written before the field existed is read as everything below its oldest pending event.
+ */
+function acceptedLocalCursor(state) {
+  if (Number.isSafeInteger(state.acceptedLocalCursor)) return state.acceptedLocalCursor;
+  return state.outbox.length ? Math.min(...state.outbox.map((event) => event.sequence)) - 1 : state.localCursor;
+}
+
+function clone(value) {
+  return structuredClone(value);
+}
+
+function validateTuple(tuple) {
+  if (!UUID.test(String(tuple.jobId || ''))) {
+    throw new HubError('HUB_ATTEMPT_INVALID', 'jobId must be a UUID');
+  }
+  if (!Number.isInteger(tuple.attemptNo) || tuple.attemptNo < 1) {
+    throw new HubError('HUB_ATTEMPT_INVALID', 'attemptNo must be positive');
+  }
+  if (!Number.isSafeInteger(tuple.fenceToken) || tuple.fenceToken < 1) {
+    throw new HubError('HUB_ATTEMPT_INVALID', 'fenceToken must be positive');
+  }
+}
+
+function validateEvent(event, jobType = event.jobType) {
+  if (
+    typeof event.sourceEventId !== 'string' ||
+    event.sourceEventId.length < 1 ||
+    event.sourceEventId.length > 128
+  ) {
+    throw new HubError('HUB_EVENT_INVALID', 'sourceEventId is invalid');
+  }
+  if (!EVENT_TYPES.has(event.type)) {
+    throw new HubError('HUB_EVENT_INVALID', `Unsupported cloud event type: ${event.type}`);
+  }
+  if (!JOB_EVENT_TYPES.get(jobType)?.has(event.type)) {
+    throw new HubError('HUB_EVENT_INVALID', `Event ${event.type} is not allowed for ${jobType}`);
+  }
+  if (Buffer.byteLength(JSON.stringify(event), 'utf8') > 32 * 1024) {
+    throw new HubError('HUB_EVENT_TOO_LARGE', 'Event exceeds 32 KiB');
+  }
+}
+
+function addEvent(state, event, jobType) {
+  validateEvent(event, jobType);
+  const existing = state.outbox.find((item) => item.sourceEventId === event.sourceEventId);
+  if (existing) return existing;
+  if (state.outbox.length >= MAX_OUTBOX_EVENTS) {
+    throw new HubError('HUB_OUTBOX_FULL', 'Durable outbox reached its local safety limit');
+  }
+  const payload = event.payload === undefined ? null : redactSecretsDeep(event.payload);
+  const record = {
+    ...clone(event),
+    ...(payload === null ? {} : { payload: payload.withheld ? { contentWithheld: true, redactionVersion: 1 } : payload.value }),
+    sequence: state.nextSequence,
+    createdAt: new Date().toISOString(),
+  };
+  state.nextSequence += 1;
+  state.localCursor = record.sequence;
+  state.outbox.push(record);
+  return record;
+}
+
+export class DurableLedger {
+  #queue = Promise.resolve();
+
+  static async open(directory, { write = writeOwnerOnlyJson } = {}) {
+    await ensureOwnerOnlyDirectory(directory);
+    const file = path.join(directory, STATE_FILE);
+    const data = await readOwnerOnlyJson(file, initialState());
+    if (data.schemaVersion !== SCHEMA_VERSION) {
+      throw new HubError('HUB_LEDGER_VERSION_UNSUPPORTED', `Unsupported ledger version: ${data.schemaVersion}`);
+    }
+    if (
+      !Array.isArray(data.outbox) ||
+      !data.attempts ||
+      typeof data.attempts !== 'object' ||
+      Buffer.byteLength(JSON.stringify(data), 'utf8') > MAX_LEDGER_BYTES
+    ) {
+      throw new HubError('HUB_LEDGER_INVALID', 'Ledger shape or size is invalid');
+    }
+    if (
+      data.outbox.length > MAX_OUTBOX_EVENTS ||
+      !Number.isSafeInteger(data.nextSequence) ||
+      data.nextSequence < 1
+    ) {
+      throw new HubError('HUB_LEDGER_INVALID', 'Ledger counters or outbox are invalid');
+    }
+    for (const event of data.outbox) validateEvent(event, event.jobType);
+    data.acceptedLocalCursor = acceptedLocalCursor(data);
+    if (data.acceptedLocalCursor < 0 || data.acceptedLocalCursor > data.localCursor) {
+      throw new HubError('HUB_LEDGER_INVALID', 'Ledger accepted event cursor is invalid');
+    }
+    for (const [jobId, attempt] of Object.entries(data.attempts)) {
+      validateTuple(attempt);
+      if (
+        attempt.jobId !== jobId ||
+        !['read', 'write'].includes(attempt.mode) ||
+        !TRANSITIONS[attempt.state] ||
+        !JOB_EVENT_TYPES.has(attempt.jobType)
+      ) {
+        throw new HubError('HUB_LEDGER_INVALID', 'Persisted attempt is invalid');
+      }
+    }
+    const ledger = new DurableLedger(file, data, write);
+    if (!await readOwnerOnlyJson(file)) await ledger.#save();
+    return ledger;
+  }
+
+  constructor(file, data, write = writeOwnerOnlyJson) {
+    this.file = file;
+    this.data = data;
+    this.write = write;
+  }
+
+  snapshot() {
+    return clone(this.data);
+  }
+
+  attempt(jobId) {
+    const attempt = this.data.attempts[jobId];
+    return attempt ? clone(attempt) : null;
+  }
+
+  attemptForTuple(tuple) {
+    validateTuple(tuple);
+    const attempt = this.data.attempts[tuple.jobId];
+    if (
+      !attempt ||
+      attempt.attemptNo !== tuple.attemptNo ||
+      attempt.fenceToken !== tuple.fenceToken
+    ) {
+      throw new HubError('HUB_STALE_FENCE', `Fence is stale for ${tuple.jobId}`);
+    }
+    return clone(attempt);
+  }
+
+  async #save(data = this.data) {
+    await this.write(this.file, data);
+  }
+
+  async #mutate(operation) {
+    const pending = this.#queue.then(async () => {
+      const draft = clone(this.data);
+      const result = operation(draft);
+      await this.#save(draft);
+      this.data = draft;
+      return clone(result);
+    });
+    this.#queue = pending.catch(() => {});
+    return pending;
+  }
+
+  async enqueueEvent(event) {
+    return this.#mutate((state) => addEvent(state, event));
+  }
+
+  async pendingEvents(limit = 100) {
+    await this.#queue;
+    return clone(this.data.outbox.slice(0, Math.max(0, Math.min(100, limit))));
+  }
+
+  async acknowledgeEvents(acknowledgements) {
+    return this.#mutate((state) => {
+      if (!Array.isArray(acknowledgements) || acknowledgements.length > 100) {
+        throw new HubError('HUB_EVENT_ACK_INVALID', 'Event acknowledgements are invalid');
+      }
+      const pendingIds = new Set(state.outbox.map((event) => event.sourceEventId));
+      const seen = new Set();
+      for (const item of acknowledgements) {
+        if (
+          !pendingIds.has(item.sourceEventId) ||
+          seen.has(item.sourceEventId) ||
+          !Number.isSafeInteger(item.cloudCursor) ||
+          item.cloudCursor < 1
+        ) {
+          throw new HubError('HUB_EVENT_ACK_INVALID', 'Event acknowledgement does not match the sent batch');
+        }
+        seen.add(item.sourceEventId);
+      }
+      const accepted = new Map(
+        acknowledgements.map((item) => [item.sourceEventId, Number(item.cloudCursor)])
+      );
+      for (const event of state.outbox) {
+        if (!accepted.has(event.sourceEventId) || !TERMINAL_STATES.has(event.terminalState)) continue;
+        const attempt = state.attempts[event.jobId];
+        if (attempt && attempt.state === event.terminalState) attempt.terminalUploaded = true;
+      }
+      for (const event of state.outbox) {
+        if (accepted.has(event.sourceEventId)) state.acceptedLocalCursor = Math.max(acceptedLocalCursor(state), event.sequence);
+      }
+      state.outbox = state.outbox.filter((item) => !accepted.has(item.sourceEventId));
+      for (const cursor of accepted.values()) {
+        if (Number.isFinite(cursor)) state.cloudCursor = Math.max(state.cloudCursor, cursor);
+      }
+      return { cloudCursor: state.cloudCursor, pending: state.outbox.length };
+    });
+  }
+
+  async claimAttempt(record) {
+    validateTuple(record);
+    if (!JOB_EVENT_TYPES.has(record.jobType)) {
+      throw new HubError('HUB_ATTEMPT_INVALID', 'jobType is invalid');
+    }
+    if (!['read', 'write'].includes(record.mode)) {
+      throw new HubError('HUB_ATTEMPT_INVALID', 'Attempt mode must be read or write');
+    }
+    return this.#mutate((state) => {
+      const existing = state.attempts[record.jobId];
+      if (
+        existing &&
+        existing.attemptNo === record.attemptNo &&
+        existing.fenceToken === record.fenceToken
+      ) {
+        return existing;
+      }
+      const reclaimable = existing && RECLAIMABLE_JOB_TYPES.has(record.jobType) && existing.jobType === record.jobType;
+      // An attempt that never started says nothing about the hub, so the older attempt it replaced stays the witness.
+      const prior = !reclaimable
+        ? null
+        : !existing.startedAt && !['succeeded', 'failed'].includes(existing.state) && existing.prior
+          ? existing.prior
+          : {
+              attemptNo: existing.attemptNo,
+              state: existing.state,
+              startedAt: existing.startedAt || null,
+              result: clone(existing.result),
+            };
+      if (existing && !prior && TERMINAL_STATES.has(existing.state)) {
+        throw new HubError('HUB_ATTEMPT_TERMINAL', `Job ${record.jobId} is already ${existing.state}`);
+      }
+      if (existing && !prior) {
+        throw new HubError(
+          existing.mode === 'write'
+            ? 'HUB_WRITE_RECONCILIATION_REQUIRED'
+            : 'HUB_ATTEMPT_RECONCILIATION_REQUIRED',
+          `Attempt ${record.jobId} must be reconciled before replacement`
+        );
+      }
+      const attempt = {
+        jobId: record.jobId,
+        attemptNo: record.attemptNo,
+        fenceToken: record.fenceToken,
+        mode: record.mode,
+        jobType: record.jobType,
+        state: 'leased',
+        processRef: null,
+        cancelRequestedAt: null,
+        terminalRace: null,
+        result: null,
+        resultDigest: null,
+        terminalUploaded: false,
+        cloudSettled: false,
+        idempotencyKey: record.idempotencyKey || null,
+        updatedAt: new Date().toISOString(),
+        ...(prior ? { prior } : {}),
+      };
+      state.attempts[record.jobId] = attempt;
+      return attempt;
+    });
+  }
+
+  async transitionAttempt(tuple, transition) {
+    validateTuple(tuple);
+    return this.#mutate((state) => {
+      const existing = state.attempts[tuple.jobId];
+      if (
+        !existing ||
+        existing.attemptNo !== tuple.attemptNo ||
+        existing.fenceToken !== tuple.fenceToken
+      ) {
+        throw new HubError('HUB_STALE_FENCE', `Fence is stale for ${tuple.jobId}`);
+      }
+      if (TERMINAL_STATES.has(existing.state)) {
+        if (
+          transition.state === existing.state &&
+          transition.resultDigest &&
+          transition.resultDigest === existing.resultDigest
+        ) {
+          return existing;
+        }
+        throw new HubError('HUB_ATTEMPT_TERMINAL', `Attempt is already ${existing.state}`);
+      }
+      if (!TRANSITIONS[existing.state]?.has(transition.state)) {
+        throw new HubError(
+          'HUB_ATTEMPT_TRANSITION_INVALID',
+          `Transition ${existing.state} -> ${transition.state} is not allowed`
+        );
+      }
+      if (transition.state === 'running' && PROCESS_JOB_TYPES.has(existing.jobType)) {
+        const identity = transition.processIdentity;
+        if (
+          !identity ||
+          identity.jobId !== existing.jobId ||
+          identity.attemptNo !== existing.attemptNo ||
+          identity.fenceToken !== existing.fenceToken ||
+          !Number.isInteger(identity.pid) ||
+          identity.pgid !== identity.pid ||
+          typeof identity.bootId !== 'string' ||
+          typeof identity.startToken !== 'string'
+        ) {
+          throw new HubError(
+            'HUB_PROCESS_OWNERSHIP_REQUIRED',
+            'Process-backed attempts require an exact durable process identity'
+          );
+        }
+      }
+      if (transition.processIdentity !== undefined) {
+        if (existing.processIdentity && JSON.stringify(existing.processIdentity) !== JSON.stringify(transition.processIdentity)) {
+          throw new HubError('HUB_PROCESS_IDENTITY_IMMUTABLE', 'Process identity is immutable');
+        }
+        existing.processIdentity = clone(transition.processIdentity);
+      }
+      existing.state = transition.state;
+      if (transition.state === 'running') existing.startedAt = new Date().toISOString();
+      if (transition.cancelRequestedAt !== undefined) {
+        existing.cancelRequestedAt = transition.cancelRequestedAt;
+      }
+      if (transition.terminalRace !== undefined) existing.terminalRace = transition.terminalRace;
+      if (transition.result !== undefined) {
+        if (Buffer.byteLength(JSON.stringify(transition.result), 'utf8') > 64 * 1024) {
+          throw new HubError('HUB_RESULT_TOO_LARGE', 'Attempt result exceeds 64 KiB');
+        }
+        existing.result = clone(transition.result);
+      }
+      if (TERMINAL_STATES.has(transition.state)) {
+        if (!/^[0-9a-f]{64}$/.test(String(transition.resultDigest || ''))) {
+          throw new HubError('HUB_RESULT_DIGEST_INVALID', 'Terminal transition requires a result digest');
+        }
+        existing.resultDigest = transition.resultDigest;
+        existing.terminalUploaded = transition.state === 'fenced';
+        existing.cloudSettled = transition.state === 'fenced';
+        existing.settlement = transition.state === 'fenced'
+          ? null
+          : {
+              attemptNo: existing.attemptNo,
+              fenceToken: existing.fenceToken,
+              state: transition.state,
+              resultDigest: transition.resultDigest,
+              idempotencyKey: existing.idempotencyKey,
+              ...(transition.state === 'succeeded' ? { result: clone(existing.result) } : {}),
+              ...(transition.state === 'failed'
+                ? {
+                    errorCode: existing.result?.code || 'HUB_JOB_FAILED',
+                    errorSummary: existing.result?.summary || 'Local job failed.',
+                  }
+                : {}),
+            };
+      }
+      existing.updatedAt = new Date().toISOString();
+      if (transition.event) {
+        addEvent(state, {
+          ...transition.event,
+          jobType: existing.jobType,
+          jobId: tuple.jobId,
+          terminalState: TERMINAL_STATES.has(transition.state) ? transition.state : undefined,
+        }, existing.jobType);
+      }
+      return existing;
+    });
+  }
+
+  recover() {
+    return Object.values(this.data.attempts)
+      .filter(
+        (attempt) =>
+          !attempt.settleFailed &&
+          (!TERMINAL_STATES.has(attempt.state) || !attempt.terminalUploaded || !attempt.cloudSettled)
+      )
+      .map((attempt) => ({
+        jobId: attempt.jobId,
+        attemptNo: attempt.attemptNo,
+        fenceToken: attempt.fenceToken,
+        disposition: TERMINAL_STATES.has(attempt.state)
+          ? 'upload_terminal'
+          : attempt.mode === 'write'
+            ? 'reconcile_write'
+            : 'reconnect_read',
+      }))
+      .sort((left, right) => left.jobId.localeCompare(right.jobId));
+  }
+
+  async markSettled(tuple, resultDigest) {
+    validateTuple(tuple);
+    return this.#mutate((state) => {
+      const attempt = state.attempts[tuple.jobId];
+      if (
+        !attempt ||
+        attempt.attemptNo !== tuple.attemptNo ||
+        attempt.fenceToken !== tuple.fenceToken ||
+        !TERMINAL_STATES.has(attempt.state) ||
+        attempt.resultDigest !== resultDigest
+      ) {
+        throw new HubError('HUB_STALE_FENCE', 'Settlement does not match the durable terminal attempt');
+      }
+      attempt.cloudSettled = true;
+      return attempt;
+    });
+  }
+
+  /**
+   * Drop a job's pending events the cloud refused for good (its fence is gone or the batch is invalid). They never
+   * count toward acceptedLocalCursor, and a terminal attempt has nothing left to upload.
+   */
+  async discardEvents(jobId, code) {
+    return this.#mutate((state) => {
+      const discarded = state.outbox.filter((event) => event.jobId === jobId).length;
+      state.outbox = state.outbox.filter((event) => event.jobId !== jobId);
+      const attempt = state.attempts[jobId];
+      if (attempt && discarded) {
+        attempt.eventsDiscarded = { count: discarded, code, at: new Date().toISOString() };
+        if (TERMINAL_STATES.has(attempt.state)) attempt.terminalUploaded = true;
+      }
+      return { discarded };
+    });
+  }
+
+  /**
+   * Give up settling a terminal attempt the cloud keeps refusing. It leaves reconnect and recovery so it cannot hold up
+   * other work; the cloud lapses the job into connector_no_result.
+   */
+  async markSettleFailed(tuple, code) {
+    validateTuple(tuple);
+    return this.#mutate((state) => {
+      const attempt = state.attempts[tuple.jobId];
+      if (
+        !attempt ||
+        attempt.attemptNo !== tuple.attemptNo ||
+        attempt.fenceToken !== tuple.fenceToken ||
+        !TERMINAL_STATES.has(attempt.state)
+      ) {
+        throw new HubError('HUB_STALE_FENCE', 'Settle failure does not match the terminal attempt');
+      }
+      attempt.settleFailed = { code, at: new Date().toISOString() };
+      attempt.updatedAt = attempt.settleFailed.at;
+      state.outbox = state.outbox.filter((event) => event.jobId !== tuple.jobId);
+      return attempt;
+    });
+  }
+
+  /** Attempts whose settlement Pulse gave up on, newest first, for the health file. */
+  settleFailed() {
+    return Object.values(this.data.attempts)
+      .filter((attempt) => attempt.settleFailed)
+      .map((attempt) => ({ jobId: attempt.jobId, jobType: attempt.jobType, attemptNo: attempt.attemptNo, ...attempt.settleFailed }))
+      .sort((left, right) => right.at.localeCompare(left.at));
+  }
+
+  async markReconciled(tuple, code) {
+    validateTuple(tuple);
+    return this.#mutate((state) => {
+      const attempt = state.attempts[tuple.jobId];
+      if (
+        !attempt ||
+        attempt.attemptNo !== tuple.attemptNo ||
+        attempt.fenceToken !== tuple.fenceToken ||
+        !TERMINAL_STATES.has(attempt.state)
+      ) {
+        throw new HubError('HUB_STALE_FENCE', 'Reconciliation does not match the terminal attempt');
+      }
+      attempt.cloudSettled = true;
+      attempt.terminalUploaded = true;
+      attempt.reconciliationCode = code;
+      attempt.settlement = null;
+      attempt.updatedAt = new Date().toISOString();
+      return attempt;
+    });
+  }
+}

package/src/lib/lifecycle.js

@@ -0,0 +1,123 @@
+import { createHash } from 'node:crypto';
+import { HubError } from './errors.js';
+import { validateJobResult } from './intents.js';
+import { redactText } from './redaction.js';
+
+function eventId(tuple, type) {
+  return createHash('sha256')
+    .update(`${tuple.jobId}\0${tuple.attemptNo}\0${tuple.fenceToken}\0${type}`)
+    .digest('base64url');
+}
+
+export class AttemptCoordinator {
+  constructor({ ledger, supervisor = null }) {
+    this.ledger = ledger;
+    this.supervisor = supervisor;
+  }
+
+  #event(tuple, type, payload = {}) {
+    return {
+      sourceEventId: eventId(tuple, type),
+      type,
+      payload: {
+        jobId: tuple.jobId,
+        attemptNo: tuple.attemptNo,
+        fenceToken: tuple.fenceToken,
+        ...payload,
+      },
+    };
+  }
+
+  #resultDigest(result) {
+    return createHash('sha256').update(JSON.stringify(result ?? null)).digest('hex');
+  }
+
+  async claim(tuple) {
+    return this.ledger.claimAttempt(tuple);
+  }
+
+  async started(tuple) {
+    return this.ledger.transitionAttempt(tuple, {
+      state: 'running',
+      processIdentity: tuple.processIdentity,
+      event: this.#event(tuple, 'job.started'),
+    });
+  }
+
+  async requestCancel(tuple) {
+    return this.ledger.transitionAttempt(tuple, {
+      state: 'cancel_requested',
+      cancelRequestedAt: new Date().toISOString(),
+      event: this.#event(tuple, 'job.cancel_acknowledged'),
+    });
+  }
+
+  async cancel(tuple) {
+    let attempt = this.ledger.attemptForTuple(tuple);
+    if (attempt.state !== 'cancel_requested') {
+      attempt = await this.requestCancel(tuple);
+    }
+    const processBacked = ['agent.start', 'agent.turn'].includes(attempt.jobType);
+    if (processBacked && (!attempt.processIdentity || !this.supervisor)) {
+      throw new HubError('HUB_CANCELLATION_UNPROVEN', 'Durable process ownership is unavailable');
+    }
+    if (attempt.processIdentity) {
+      const outcome = await this.supervisor.cancel(attempt.processIdentity);
+      if (!outcome.cancelled || outcome.verifiedStopped !== true) {
+        throw new HubError(
+          'HUB_CANCELLATION_UNPROVEN',
+          'Owned process termination was not proven'
+        );
+      }
+    }
+    const result = { cancelled: true };
+    return this.ledger.transitionAttempt(tuple, {
+      state: 'cancelled',
+      result,
+      resultDigest: this.#resultDigest(result),
+      event: this.#event(tuple, 'job.cancelled'),
+    });
+  }
+
+  async complete(tuple) {
+    const before = this.ledger.attemptForTuple(tuple);
+    const terminalRace = before?.state === 'cancel_requested' ? 'completed_before_cancel' : null;
+    const result = validateJobResult(before.jobType, tuple.result);
+    return this.ledger.transitionAttempt(tuple, {
+      state: 'succeeded',
+      result,
+      resultDigest: this.#resultDigest(result),
+      terminalRace,
+      event: this.#event(tuple, 'job.succeeded', { terminalRace }),
+    });
+  }
+
+  async fail(tuple) {
+    const result = {
+      code: tuple.code,
+      summary: redactText(tuple.summary, { maxBytes: 2_000 }).text,
+    };
+    return this.ledger.transitionAttempt(tuple, {
+      state: 'failed',
+      result,
+      resultDigest: this.#resultDigest(result),
+      event: this.#event(tuple, 'job.failed', result),
+    });
+  }
+
+  async fence(tuple) {
+    const attempt = this.ledger.attemptForTuple(tuple);
+    if (attempt.processIdentity && this.supervisor) {
+      const outcome = await this.supervisor.cancel(attempt.processIdentity);
+      if (!outcome.verifiedStopped) {
+        throw new HubError('HUB_CANCELLATION_UNPROVEN', 'Fenced process termination was not proven');
+      }
+    }
+    const result = { fenced: true };
+    return this.ledger.transitionAttempt(tuple, {
+      state: 'fenced',
+      result,
+      resultDigest: this.#resultDigest(result),
+    });
+  }
+}