@the-open-engine/zeroshot 6.23.0 → 6.25.0

package/task-lib/commands/resume.js

@@ -2,14 +2,56 @@ import chalk from 'chalk';
 import { createRequire } from 'module';
 import { getTask } from '../store.js';
 import { spawnTask } from '../runner.js';
+import { validateOwnedByTask } from '../omp-session-ownership-schema.js';
 
 const require = createRequire(import.meta.url);
 const { providerSupportsCapability } = require('../../lib/provider-names.js');
 
+/**
+ * Manual standalone resume (`zeroshot task resume <id>`) reuses the *exact* persisted partition
+ * under the storage root recorded on the owner row, and asserts the complete committed tuple —
+ * including the partition identity, which the cluster path can only learn from the row itself.
+ * `state === 'committed'` is required: a provisional or cleanup-required record never durably
+ * proved a resumable session, so anything less fails closed to a fresh context.
+ */
+function buildOmpResumeTaskOptions(task) {
+  const ownership = validateOwnedByTask(task.ompSessionOwnership, task.id);
+  if (!ownership) {
+    throw new Error(`Task ${task.id} has no valid OMP session ownership record; refusing resume.`);
+  }
+  if (ownership.state !== 'committed' || !ownership.session || !ownership.partitionIdentity) {
+    throw new Error(
+      `Task ${task.id} OMP session ownership is '${ownership.state}', not a committed resumable session; refusing resume.`
+    );
+  }
+  return {
+    cwd: ownership.canonicalWorkspace,
+    provider: task.provider,
+    storageRoot: ownership.storageRoot,
+    clusterId: ownership.owner.clusterId,
+    agentId: ownership.owner.agentId,
+    ompResume: {
+      priorOwnerTaskId: task.id,
+      partitionId: ownership.partitionId,
+      sessionFileName: ownership.session.fileName,
+      expectedSessionId: ownership.session.sessionId,
+      expectedPartitionIdentity: ownership.partitionIdentity,
+      expectedSessionFileIdentity: ownership.session.fileIdentity,
+      expectedArtifactManifestDigest: ownership.session.artifactManifestDigest,
+      expectedExecutionFingerprint: ownership.session.executionFingerprint,
+      expectedSelectedProvider: ownership.session.selectedProvider,
+      expectedSelectedModel: ownership.session.selectedModel,
+    },
+  };
+}
+
 export function buildResumeTaskOptions(task) {
   if (!providerSupportsCapability(task.provider, 'sessionResume')) {
     throw new Error(`Provider ${task.provider} does not support safe session resume.`);
   }
+  if (task.provider === 'omp') {
+    return buildOmpResumeTaskOptions(task);
+  }
   if (
     task.requestedResumeSessionId &&
     (task.status !== 'completed' || task.resumeIdentityVerified !== true)

package/task-lib/commands/run.js

@@ -1,6 +1,70 @@
 import chalk from 'chalk';
 import { shouldUseAttachableWatcher, spawnTask } from '../runner.js';
 
+// Every field the agent's `providerSession.ompSession` snapshot carries, plus the outer tuple's
+// session ID and the prior owner's task id. All are required: the descriptor is only ever built
+// from a complete committed record, and task-lib/runner.js re-checks every one of them against
+// that record before a task row exists. Missing/extra/mistyped fields fail closed here.
+const OMP_RESUME_STRING_FIELDS = [
+  'priorOwnerTaskId',
+  'partitionId',
+  'sessionFileName',
+  'expectedSessionId',
+  'expectedArtifactManifestDigest',
+  'expectedExecutionFingerprint',
+  'expectedSelectedProvider',
+  'expectedSelectedModel',
+];
+const OMP_RESUME_IDENTITY_FIELDS = ['expectedSessionFileIdentity'];
+const OMP_RESUME_OPTIONAL_IDENTITY_FIELDS = ['expectedPartitionIdentity'];
+const OMP_RESUME_ALLOWED_FIELDS = new Set([
+  ...OMP_RESUME_STRING_FIELDS,
+  ...OMP_RESUME_IDENTITY_FIELDS,
+  ...OMP_RESUME_OPTIONAL_IDENTITY_FIELDS,
+]);
+
+function isIdentityShape(value) {
+  return (
+    value !== null &&
+    typeof value === 'object' &&
+    !Array.isArray(value) &&
+    /^(0|[1-9][0-9]*)$/.test(String(value.device)) &&
+    /^(0|[1-9][0-9]*)$/.test(String(value.inode))
+  );
+}
+
+export function parseOmpResumeDescriptor(raw) {
+  if (!raw) return undefined;
+  let descriptor;
+  try {
+    descriptor = JSON.parse(raw);
+  } catch (error) {
+    throw new Error(`--omp-resume must be a JSON descriptor: ${error.message}`);
+  }
+  if (!descriptor || typeof descriptor !== 'object' || Array.isArray(descriptor)) {
+    throw new Error('--omp-resume descriptor must be a JSON object.');
+  }
+  const unknown = Object.keys(descriptor).filter((key) => !OMP_RESUME_ALLOWED_FIELDS.has(key));
+  if (unknown.length > 0) {
+    throw new Error(`--omp-resume descriptor has unknown field(s): ${unknown.join(', ')}.`);
+  }
+  const missing = [
+    ...OMP_RESUME_STRING_FIELDS.filter(
+      (field) => typeof descriptor[field] !== 'string' || descriptor[field].length === 0
+    ),
+    ...OMP_RESUME_IDENTITY_FIELDS.filter((field) => !isIdentityShape(descriptor[field])),
+  ];
+  if (missing.length > 0) {
+    throw new Error(`--omp-resume descriptor is missing/invalid field(s): ${missing.join(', ')}.`);
+  }
+  for (const field of OMP_RESUME_OPTIONAL_IDENTITY_FIELDS) {
+    if (descriptor[field] !== undefined && !isIdentityShape(descriptor[field])) {
+      throw new Error(`--omp-resume descriptor field ${field} is not a device/inode identity.`);
+    }
+  }
+  return descriptor;
+}
+
 export async function runTask(prompt, options = {}) {
   if (!prompt || prompt.trim().length === 0) {
     console.log(chalk.red('Error: Prompt is required'));
@@ -36,6 +100,7 @@ export async function runTask(prompt, options = {}) {
     provider: options.provider,
     resume: options.resume,
     continue: options.continue,
+    ompResume: parseOmpResumeDescriptor(options.ompResume),
     outputFormat,
     jsonSchema,
     mcpConfig: options.mcpConfig,

package/task-lib/omp-session-cleanup.js

@@ -0,0 +1,160 @@
+// The single implementation behind all three OMP session-partition cleanup surfaces required by
+// issue #866: standalone task `clean` (task-lib/commands/clean.js), cluster clear
+// (cli/index.js deleteClusterData, also reached by `zeroshot purge`), and global `purge`
+// (cli/index.js, which runs cluster clear then `clean --all`).
+//
+// Three invariants hold on every surface:
+//   * A committed session stays available for resume until its own task record is being removed —
+//     cleanup is driven by the task row, never by scanning the partition tree for orphans.
+//   * A partition is never deleted while any *other* row holds an authoritative claim on it.
+//     Several rows can name one partition at once: a resumed row is inserted before its owner
+//     transfer runs, so two competing resumes of one committed session put three rows on it. The
+//     fence is therefore over every authoritative row (provisional or committed), never over the
+//     committed rows alone — after a transfer the live owner is `provisional` and no row is
+//     committed at all.
+//   * The shared, machine-wide OMP CAS blob root (src/omp-blob-root.js) is never touched. Blobs
+//     are addressed from *other* sessions' JSONL too, so deleting one is data loss for unrelated
+//     work; stageOmpSessionPartitionForDeletion refuses any path that resolves inside it.
+//
+// An unsafe or unresolvable path preserves the owner record with an actionable warning instead of
+// deleting, so the operator can inspect it and the cleanup stays durably retryable.
+import { loadTasks, updateTask, getTaskStoreDatabase } from './store.js';
+import { findAuthoritativeOwnersForPartition } from './omp-session-ownership.js';
+import {
+  serializeOmpSessionOwnership,
+  validateOwnedByTask,
+} from './omp-session-ownership-schema.js';
+import { createRequire } from 'module';
+
+const require = createRequire(import.meta.url);
+const {
+  removeStagedOmpSessionPartition,
+  stageOmpSessionPartitionForDeletion,
+} = require('../src/omp-session-partition.js');
+
+/**
+ * Take the partition away from its canonical name under a task-store write fence, then remove the
+ * staged tree outside it.
+ *
+ * The fence spans exactly three steps: "this row still holds the record cleanup validated", "no
+ * other row holds an authoritative claim on this partition", and "the partition no longer answers
+ * to its canonical name". Without it, a resume could insert its provisional row — or win its
+ * ownership transfer — in the gap between the checks and the rename, and cleanup would move a live
+ * session out from under it. `BEGIN IMMEDIATE` takes the write lock up front, so every competing
+ * ownership write is serialized either wholly before the checks (and is therefore seen by them) or
+ * wholly after the rename, where it lands on a partition that is already gone and fails that turn
+ * closed rather than costing a live one its data.
+ *
+ * The row re-read closes the same race from the caller's side: every cleanup surface iterates a
+ * task snapshot taken by an earlier `loadTasks()`, and a resume that transferred this partition
+ * away in the meantime leaves that snapshot describing a record the row no longer holds — acting
+ * on it would delete the partition on behalf of an owner that has already released it. `store.js`
+ * writes this column only through `serializeOmpSessionOwnership`, whose output is canonical per
+ * record, so comparing the stored bytes is an exact "still the same record" test.
+ *
+ * The recursive removal runs *after* the fence is released, because by then the tree only answers
+ * to an unguessable staging name nothing else knows, and holding a write lock across an
+ * arbitrarily large `rm -r` would stall every other task-store writer.
+ */
+function stageUnderOwnerFence(ownership, taskId) {
+  const database = getTaskStoreDatabase();
+  const expectedRecord = serializeOmpSessionOwnership(ownership);
+  const readRecord = database.prepare(
+    'SELECT omp_session_ownership AS record FROM tasks WHERE id = ?'
+  );
+  const fenced = database.transaction(() => {
+    const row = readRecord.get(taskId);
+    if (!row || row.record !== expectedRecord) {
+      return {
+        staged: false,
+        deleted: false,
+        reason: 'its ownership record changed while cleanup was running',
+      };
+    }
+    const owners = findAuthoritativeOwnersForPartition(ownership.partitionId, taskId, database);
+    if (owners.length > 0) {
+      return {
+        staged: false,
+        deleted: false,
+        reason: `it is still claimed by ${owners.map((o) => `${o.taskId} (${o.state})`).join(', ')}`,
+      };
+    }
+    return stageOmpSessionPartitionForDeletion(ownership);
+  });
+  // BEGIN IMMEDIATE: take the write lock up front so the checks cannot run under a shared lock that
+  // another writer is simultaneously upgrading.
+  return fenced.immediate();
+}
+
+/**
+ * Delete one task's OMP session partition. Returns true when the task row is now safe to remove
+ * (nothing to clean, or the partition is gone).
+ *
+ * @param {object} task task record as returned by the store
+ * @param {(message: string) => void} warn receives an actionable message for a retained partition
+ * @param {{clearRecord?: boolean}} options `clearRecord` NULLs the row's ownership after a
+ *   successful delete — required on surfaces (cluster clear) where the row itself survives.
+ */
+export function cleanupOmpSessionPartitionForTask(task, warn, { clearRecord = false } = {}) {
+  if (!task?.ompSessionOwnership) return true;
+  const ownership = validateOwnedByTask(task.ompSessionOwnership, task.id);
+  if (!ownership) {
+    warn(
+      `Task ${task.id}: retained an OMP session ownership record that failed validation; nothing was deleted.`
+    );
+    return false;
+  }
+
+  // More than one row can name a single partition: a resume inserts its provisional row before its
+  // ownership transfer runs, and two competing resumes of one committed session put three rows on
+  // it. The fence is therefore every *authoritative* (provisional or committed) claim other than
+  // this row's — a crashed-before-transfer resume must not delete the prior owner's still-resumable
+  // session, and a losing competing resume must not delete the winner's live one.
+  const staged = stageUnderOwnerFence(ownership, task.id);
+  if (!staged.staged) {
+    if (staged.deleted) return finishCleanup(task, clearRecord);
+    warn(
+      `Task ${task.id}: retained OMP session partition ${ownership.partitionId} (${staged.reason}).`
+    );
+    return false;
+  }
+
+  const { deleted, reason } = removeStagedOmpSessionPartition(staged.stagingPath);
+  if (!deleted) {
+    warn(`Task ${task.id}: retained OMP session partition ${ownership.partitionId} (${reason}).`);
+    return false;
+  }
+  return finishCleanup(task, clearRecord);
+}
+
+function finishCleanup(task, clearRecord) {
+  if (clearRecord) {
+    updateTask(task.id, { ompSessionOwnership: null });
+  }
+  return true;
+}
+
+/**
+ * Delete every OMP session partition owned by a cluster's agents. Cluster partitions live under
+ * the cluster's own `storageDir`, so this is what makes cluster clear (and therefore purge)
+ * actually reclaim them; the task rows themselves survive and have their ownership cleared.
+ *
+ * @returns {{deleted: string[], retained: string[]}} partition ids
+ */
+export function cleanupOmpSessionPartitionsForCluster(clusterId, warn) {
+  const deleted = [];
+  const retained = [];
+  if (!clusterId) return { deleted, retained };
+
+  for (const task of Object.values(loadTasks())) {
+    const ownership = validateOwnedByTask(task?.ompSessionOwnership ?? null, task?.id);
+    if (!ownership || ownership.owner.kind !== 'cluster-agent') continue;
+    if (ownership.owner.clusterId !== clusterId) continue;
+    if (cleanupOmpSessionPartitionForTask(task, warn, { clearRecord: true })) {
+      deleted.push(ownership.partitionId);
+    } else {
+      retained.push(ownership.partitionId);
+    }
+  }
+  return { deleted, retained };
+}

package/task-lib/omp-session-ownership-schema.js

@@ -0,0 +1,262 @@
+// Pure (no DB, no partition I/O) validation/canonicalization for the closed
+// `task.ompSessionOwnership` JSON shape defined by issue #866. Kept dependency-free of
+// task-lib/store.js so store.js can import this module for parse/serialize without a cycle; the
+// DB-touching transitions (provisional -> committed / cleanup-required, owner transfer) live in
+// task-lib/omp-session-ownership.js.
+//
+// The schema is *closed* in both directions: an unknown key anywhere in the object (top level,
+// `owner`, `session`, or either identity) rejects the whole record, and every known key is
+// re-derived into a canonical form on the way out. A record that does not validate is never
+// partially trusted — callers fail closed to a fresh context.
+import { createHash } from 'crypto';
+import { isAbsolute, resolve as resolvePath } from 'path';
+import { createRequire } from 'module';
+
+const require = createRequire(import.meta.url);
+const { PARTITION_ID_PATTERN, partitionPathFor } = require('../src/omp-session-partition.js');
+
+export const OMP_OWNERSHIP_SCHEMA_VERSION = 1;
+export const OMP_OWNERSHIP_STATES = Object.freeze([
+  'provisional',
+  'committed',
+  'cleanup-required',
+]);
+
+const SHA256_PATTERN = /^sha256:[a-f0-9]{64}$/u;
+const DECIMAL_PATTERN = /^(0|[1-9][0-9]*)$/u;
+const SESSION_FILE_NAME_PATTERN = /^[^/\\]+\.jsonl$/u;
+const STATES = new Set(OMP_OWNERSHIP_STATES);
+const OWNER_KINDS = new Set(['cluster-agent', 'standalone']);
+
+const TOP_LEVEL_KEYS = new Set([
+  'schemaVersion',
+  'state',
+  'partitionId',
+  'storageRoot',
+  'partitionPath',
+  'ownerUid',
+  'storageRootIdentity',
+  'partitionIdentity',
+  'canonicalWorkspace',
+  'owner',
+  'session',
+]);
+const OWNER_KEYS = new Set(['kind', 'clusterId', 'agentId', 'taskId']);
+const SESSION_KEYS = new Set([
+  'sessionId',
+  'fileName',
+  'fileIdentity',
+  'artifactManifestDigest',
+  'executionFingerprint',
+  'selectedProvider',
+  'selectedModel',
+]);
+const IDENTITY_KEYS = new Set(['device', 'inode']);
+
+function hasOnlyKeys(value, allowed) {
+  return Object.keys(value).every((key) => allowed.has(key));
+}
+
+function isPlainObject(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+function isNonEmptyString(value) {
+  return typeof value === 'string' && value.length > 0;
+}
+
+function isDecimalString(value) {
+  return isNonEmptyString(value) && DECIMAL_PATTERN.test(value);
+}
+
+function isDigest(value) {
+  return isNonEmptyString(value) && SHA256_PATTERN.test(value);
+}
+
+/** A canonical absolute path: already fully resolved, so a record can never smuggle in a relative,
+ * `..`-bearing, or trailing-separator path that would resolve differently at cleanup time. */
+function isCanonicalAbsolutePath(value) {
+  return isNonEmptyString(value) && isAbsolute(value) && resolvePath(value) === value;
+}
+
+function normalizeIdentity(value) {
+  if (!isPlainObject(value) || !hasOnlyKeys(value, IDENTITY_KEYS)) return null;
+  if (!isDecimalString(value.device) || !isDecimalString(value.inode)) return null;
+  return { device: value.device, inode: value.inode };
+}
+
+export function canonicalOwnerUid() {
+  return typeof process.getuid === 'function' ? String(process.getuid()) : '0';
+}
+
+/** sha256 over the UTF-8 bytes of a stable JSON encoding (sorted keys) of `fields`. */
+export function computeExecutionFingerprint(fields) {
+  const sortedKeys = Object.keys(fields).sort();
+  const stable = {};
+  for (const key of sortedKeys) stable[key] = fields[key];
+  return `sha256:${createHash('sha256').update(JSON.stringify(stable), 'utf8').digest('hex')}`;
+}
+
+function normalizeOwner(owner) {
+  if (!isPlainObject(owner) || !hasOnlyKeys(owner, OWNER_KEYS)) return null;
+  if (!OWNER_KINDS.has(owner.kind)) return null;
+  if (!isNonEmptyString(owner.taskId)) return null;
+  if (owner.kind === 'cluster-agent') {
+    if (!isNonEmptyString(owner.clusterId) || !isNonEmptyString(owner.agentId)) return null;
+  } else if (owner.clusterId !== null || owner.agentId !== null) {
+    return null;
+  }
+  return {
+    kind: owner.kind,
+    clusterId: owner.clusterId,
+    agentId: owner.agentId,
+    taskId: owner.taskId,
+  };
+}
+
+function normalizeSession(session) {
+  if (!isPlainObject(session) || !hasOnlyKeys(session, SESSION_KEYS)) return null;
+  const fileIdentity = normalizeIdentity(session.fileIdentity);
+  if (
+    !isNonEmptyString(session.sessionId) ||
+    !isNonEmptyString(session.fileName) ||
+    !SESSION_FILE_NAME_PATTERN.test(session.fileName) ||
+    session.fileName === '.jsonl' ||
+    !fileIdentity ||
+    !isDigest(session.artifactManifestDigest) ||
+    !isDigest(session.executionFingerprint) ||
+    !isNonEmptyString(session.selectedProvider) ||
+    !isNonEmptyString(session.selectedModel)
+  ) {
+    return null;
+  }
+  return {
+    sessionId: session.sessionId,
+    fileName: session.fileName,
+    fileIdentity,
+    artifactManifestDigest: session.artifactManifestDigest,
+    executionFingerprint: session.executionFingerprint,
+    selectedProvider: session.selectedProvider,
+    selectedModel: session.selectedModel,
+  };
+}
+
+/**
+ * Validate and canonicalize an arbitrary value as a closed `task.ompSessionOwnership` object.
+ * Returns null on any structural violation.
+ */
+export function validateOmpSessionOwnership(value) {
+  if (!isPlainObject(value) || !hasOnlyKeys(value, TOP_LEVEL_KEYS)) return null;
+  if (value.schemaVersion !== OMP_OWNERSHIP_SCHEMA_VERSION) return null;
+  if (!STATES.has(value.state)) return null;
+  if (!isNonEmptyString(value.partitionId) || !PARTITION_ID_PATTERN.test(value.partitionId)) {
+    return null;
+  }
+  if (!isCanonicalAbsolutePath(value.storageRoot)) return null;
+  if (!isCanonicalAbsolutePath(value.partitionPath)) return null;
+  if (!isCanonicalAbsolutePath(value.canonicalWorkspace)) return null;
+  // The partition path is fully determined by storageRoot + partitionId. Re-deriving it (instead
+  // of trusting the stored string) is what stops a tampered row from pointing cleanup or a resume
+  // at an arbitrary directory that merely *looks* canonical.
+  let derivedPartitionPath;
+  try {
+    derivedPartitionPath = partitionPathFor(value.storageRoot, value.partitionId);
+  } catch {
+    return null;
+  }
+  if (derivedPartitionPath !== value.partitionPath) return null;
+  if (!isDecimalString(value.ownerUid)) return null;
+
+  const storageRootIdentity = normalizeIdentity(value.storageRootIdentity);
+  if (!storageRootIdentity) return null;
+
+  const owner = normalizeOwner(value.owner);
+  if (!owner) return null;
+
+  if (!Object.hasOwn(value, 'partitionIdentity') || !Object.hasOwn(value, 'session')) return null;
+  const hasPartitionIdentity = value.partitionIdentity !== null;
+  const hasSession = value.session !== null;
+  // No partially populated pairs, in any state: an observation of the materialized session is
+  // either complete (both the partition identity and the full session tuple) or absent.
+  if (hasPartitionIdentity !== hasSession) return null;
+  const partitionIdentity = hasPartitionIdentity ? normalizeIdentity(value.partitionIdentity) : null;
+  const session = hasSession ? normalizeSession(value.session) : null;
+  if (hasPartitionIdentity && (!partitionIdentity || !session)) return null;
+  // `committed` is the only state that asserts a resumable session, so it is the only state that
+  // requires the observation to be present.
+  if (value.state === 'committed' && !session) return null;
+
+  return {
+    schemaVersion: OMP_OWNERSHIP_SCHEMA_VERSION,
+    state: value.state,
+    partitionId: value.partitionId,
+    storageRoot: value.storageRoot,
+    partitionPath: value.partitionPath,
+    ownerUid: value.ownerUid,
+    storageRootIdentity,
+    partitionIdentity,
+    canonicalWorkspace: value.canonicalWorkspace,
+    owner,
+    session,
+  };
+}
+
+/**
+ * Validate a record *and* fence it to the task row it was read from: an ownership record whose
+ * `owner.taskId` is not this row's id is not this row's ownership, however well-formed it is.
+ */
+export function validateOwnedByTask(value, taskId) {
+  const validated = validateOmpSessionOwnership(value);
+  if (!validated) return null;
+  if (!isNonEmptyString(taskId) || validated.owner.taskId !== taskId) return null;
+  return validated;
+}
+
+/** Build the initial provisional ownership record. Pure — the directory need not exist yet. */
+export function buildProvisionalOwnership({
+  partitionId,
+  storageRoot,
+  storageRootIdentity,
+  canonicalWorkspace,
+  owner,
+}) {
+  const canonicalStorageRoot = resolvePath(storageRoot);
+  const record = {
+    schemaVersion: OMP_OWNERSHIP_SCHEMA_VERSION,
+    state: 'provisional',
+    partitionId,
+    storageRoot: canonicalStorageRoot,
+    partitionPath: partitionPathFor(canonicalStorageRoot, partitionId),
+    ownerUid: canonicalOwnerUid(),
+    storageRootIdentity,
+    partitionIdentity: null,
+    canonicalWorkspace: resolvePath(canonicalWorkspace),
+    owner,
+    session: null,
+  };
+  const validated = validateOmpSessionOwnership(record);
+  if (!validated) {
+    throw new Error('buildProvisionalOwnership produced an invalid ownership record.');
+  }
+  return validated;
+}
+
+export function parseOmpSessionOwnership(raw) {
+  if (typeof raw !== 'string' || raw === '') return null;
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    return null;
+  }
+  return validateOmpSessionOwnership(parsed);
+}
+
+export function serializeOmpSessionOwnership(value) {
+  if (!value) return null;
+  const validated = validateOmpSessionOwnership(value);
+  if (!validated) {
+    throw new Error('Refusing to persist an invalid ompSessionOwnership record.');
+  }
+  return JSON.stringify(validated);
+}