@brainervirus/workit-core 1.2.0 → 1.3.0

package/src/core/task-engine.ts

@@ -29,6 +29,7 @@ import {
   type Result,
   type Scope,
   type TaskRecord,
+  type TaskListItem,
   type TaskSummary,
   type TaskView,
   type Utc,
@@ -152,6 +153,7 @@ type WorkerAuthority = {
   expectedWorkspaceRevision: string;
   state: NativeWorkerObservation["state"];
   session: NativeWorkerObservation["session"];
+  report: NativeWorkerObservation["report"] | null;
   provenance: Provenance;
   owner: object;
   store: TaskStore;
@@ -280,6 +282,7 @@ const verifyNativeWorker = (
     expectedWorkspaceRevision: expected.expectedWorkspaceRevision,
     state: expected.state,
     session: expected.session,
+    report: expected.report ?? null,
     provenance: result.data,
     ...binding,
   });
@@ -305,7 +308,8 @@ const takeWorker = (
     value.expectedRevision !== expected.expectedRevision ||
     value.expectedWorkspaceRevision !== expected.expectedWorkspaceRevision ||
     value.state !== expected.state ||
-    !sameValue(value.session, expected.session)
+    !sameValue(value.session, expected.session) ||
+    !sameValue(value.report, expected.report ?? null)
   )
     return null;
   return value;
@@ -361,6 +365,8 @@ const applyWorkerLifecycle = (input: ObserveWorkerLifecycleInput): Result<Entry<
     return failure("invalid_transition", "worker already has an observed session");
   if (notStarted && !["dispatching", "cancelling"].includes(entry.data.state))
     return failure("invalid_transition", "worker launch was not claimed");
+  if (input.report && input.state !== "stopped")
+    return failure("invalid_input", "worker reports require a stopped worker");
   if (
     (input.state === "running" ||
       input.state === "cancelling" ||
@@ -383,6 +389,7 @@ const applyWorkerLifecycle = (input: ObserveWorkerLifecycleInput): Result<Entry<
       ...entry.data,
       state: terminalCancel ? ("cancelling" as const) : input.state,
       session: input.session,
+      report: entry.data.report ?? input.report ?? null,
     },
   } satisfies Entry<Worker>;
   const shouldClear =
@@ -402,6 +409,7 @@ const applyWorkerLifecycle = (input: ObserveWorkerLifecycleInput): Result<Entry<
   if (
     entry.data.state === nextEntry.data.state &&
     sameValue(entry.data.session, input.session) &&
+    sameValue(entry.data.report, nextEntry.data.report) &&
     !shouldClear &&
     !shouldUncertain
   )
@@ -504,6 +512,21 @@ const portableTask = (task: TaskRecord): TaskRecord => {
   };
   for (const entry of clone.assessments)
     demote(entry.data.facts, entry.data.signals, entry.data.consequences);
+  const sourceDecisions = new Map(task.decisions.map((entry) => [entry.id, entry]));
+  for (const entry of clone.decisions) {
+    const consumption = sourceDecisions.get(entry.id)?.data.consumption;
+    if (!consumption) continue;
+    entry.data.consumption = {
+      ...consumption,
+      state: consumption.state === "reserved" ? "uncertain" : consumption.state,
+      actionRef: { kind: "record", collection: "decisions", id: entry.id },
+      ...(consumption.historicalActionId
+        ? { historicalActionId: consumption.historicalActionId }
+        : consumption.actionRef.kind === "host"
+          ? { historicalActionId: consumption.actionRef.handle }
+          : {}),
+    };
+  }
   // Candidate metadata can contain environment-derived paths and digests. The destination
   // must recapture its own candidate instead of receiving source checkout material.
   clone.candidates = [];
@@ -641,7 +664,13 @@ const importedTask = (
             taskId: "",
             workspaceId: destinationWorkspaceId,
           },
-          consumption: null,
+          consumption: data.consumption
+            ? {
+                ...data.consumption,
+                state: data.consumption.state === "reserved" ? "uncertain" : data.consumption.state,
+                actionRef: { kind: "record", collection: "decisions", id: entry.id },
+              }
+            : null,
         },
       };
     }),
@@ -858,14 +887,14 @@ export class WorkitCore {
     });
   }
 
-  task(request: unknown): Result<TaskSummary | TaskSummary[] | TaskView> {
+  task(request: unknown): Result<TaskSummary | TaskListItem[] | TaskView> {
     const root = this.contextRootError();
     if (!root.ok) return root as Result<never>;
     const parsed = parseOperation("task", request);
     if (!parsed.ok) return parsed as Result<never>;
     const input = parsed.data as any;
     if ((this.context.workerId ?? null) !== null) {
-      if (input.action !== "inspect")
+      if (input.action !== "inspect" && input.action !== "list")
         return failure("permission_denied", "helpers cannot control task lifecycle or scope");
     }
     switch (input.action) {
@@ -887,20 +916,67 @@ export class WorkitCore {
       case "list": {
         const listed = this.store.listTasks();
         if (!listed.ok) return listed as Result<never>;
-        const summaries: TaskSummary[] = [];
-        for (const task of listed.data) {
-          const summary = this.summary(task);
-          if (!summary.ok) return summary;
-          summaries.push(summary.data);
-        }
-        return success(null, null, summaries);
+        const status = input.status ?? "open";
+        const limit = input.limit ?? 20;
+        const query = input.query?.toLowerCase().split(/\s+/);
+        const selected = listed.data
+          .filter((task) =>
+            status === "all"
+              ? true
+              : status === "closed"
+                ? task.status === "closed"
+                : task.status !== "closed",
+          )
+          .filter(
+            (task) =>
+              !query ||
+              query.every((term: string) =>
+                JSON.stringify({
+                  id: task.id,
+                  workspaceId: task.workspaceId,
+                  origin: task.origin,
+                  createdAt: task.createdAt,
+                  updatedAt: task.updatedAt,
+                  source: task.intent.provenance,
+                  objective: task.intent.data.objective,
+                  progress: task.progress,
+                  decisions: task.decisions.map(({ data }) => data),
+                })
+                  .toLowerCase()
+                  .includes(term),
+              ),
+          )
+          .sort((left, right) => right.updatedAt.localeCompare(left.updatedAt))
+          .slice(0, limit);
+        if (selected.length === 0) return success(null, null, []);
+        const workspace = this.store.readWorkspace();
+        if (!workspace.ok) return workspace as Result<never>;
+        if (!workspace.data) return failure("not_found", "workspace not found");
+        const tasks = selected.map((task): TaskListItem => ({
+          id: task.id,
+          revision: task.revision,
+          workspaceRevision: workspace.data!.revision,
+          createdAt: task.createdAt,
+          updatedAt: task.updatedAt,
+          runtime: task.runtime ?? null,
+          objective: task.intent.data.objective,
+          status: task.status,
+          closure: task.closure,
+          progress: task.progress,
+          writer: task.status === "closed" ? null : workspace.data!.writer,
+          source: {
+            host: task.intent.provenance.host,
+            kind: task.intent.provenance.kind,
+          },
+        }));
+        return success(null, null, tasks);
       }
       case "inspect": {
         const task = this.store.readTask(input.taskId);
         if (!task.ok) return task as Result<never>;
         const helper = this.helperTaskGuard(task.data, true);
         if (!helper.ok) return helper as Result<never>;
-        if (input.view === "summary") return this.summary(task.data);
+        if ((input.view ?? "summary") === "summary") return this.summary(task.data);
         return this.view(task.data);
       }
       case "pause":
@@ -1344,11 +1420,14 @@ export class WorkitCore {
       const evaluations = evaluateEvidence(task.data, current.data);
       const verified = evidence.some((entry) => {
         const evaluation = evaluations.find((item) => item.evidenceId === entry.id);
-        return findingVerificationPasses(finding.data.candidateId, {
-          kind: entry.data.kind,
-          candidateId: entry.data.candidateId,
-          status: evaluation?.status ?? "missing",
-        });
+        return (
+          entry.recordedAt >= finding.recordedAt &&
+          findingVerificationPasses(finding.data.candidateId, {
+            kind: entry.data.kind,
+            candidateId: entry.data.candidateId,
+            status: evaluation?.status ?? "missing",
+          })
+        );
       });
       if (!verified)
         return failure("permission_denied", "fixed findings require passing verification evidence");
@@ -1451,7 +1530,18 @@ export class WorkitCore {
       if (task.data.status !== "active")
         return failure("invalid_transition", "paused or closed tasks cannot assign workers");
       if (!bindingCovers(task.data.intent.data.scope, input.assignment.scope))
-        return failure("permission_denied", "worker assignment is outside task scope");
+        return failure("permission_denied", "worker assignment is outside task scope", {
+          fields: [
+            {
+              path: "assignment.scope",
+              reason: `paths ${JSON.stringify(input.assignment.scope.paths)} must be contained by lead paths ${JSON.stringify(task.data.intent.data.scope.paths)}`,
+            },
+            {
+              path: "task.intent.scope",
+              reason: `lead paths are ${JSON.stringify(task.data.intent.data.scope.paths)}`,
+            },
+          ],
+        });
       if (
         input.assignment.decisionIds.some(
           (id: string) => !task.data.decisions.some((entry) => entry.id === id),
@@ -1739,7 +1829,15 @@ export class WorkitCore {
                   ...item,
                   recordedAt: mutation.now,
                   provenance: attested.data,
-                  data: { ...item.data, state: "dispatching" as const },
+                  data: {
+                    ...item.data,
+                    state: "dispatching" as const,
+                    coordinator: {
+                      kind: "host" as const,
+                      host: this.context.caller.host,
+                      handle: this.context.caller.actor,
+                    },
+                  },
                 }
               : item,
           ),
@@ -1828,6 +1926,7 @@ export class WorkitCore {
         expectedWorkspaceRevision: input.expectedWorkspaceRevision,
         state: "stopped",
         session: null,
+        report: null,
         provenance: attested.data,
         owner: this.authorityOwner,
         store: this.store,
@@ -2205,11 +2304,16 @@ export class WorkitCore {
     const workspace = this.store.readWorkspace();
     if (!workspace.ok) return workspace as Result<never>;
     if (!workspace.data) return failure("not_found", "workspace not found");
-    const current = captureCandidate(this.store.root, task.intent.data.scope, environment());
+    const historical = task.status === "closed" ? task.candidates.at(-1) : undefined;
+    const current = historical
+      ? success(null, null, historical)
+      : captureCandidate(this.store.root, task.intent.data.scope, environment());
     if (!current.ok) return current as Result<never>;
+    const evaluationWorkspace =
+      task.status === "closed" ? { ...workspace.data, writer: null } : workspace.data;
     const requirements = evaluateRequirements(
       task,
-      workspace.data,
+      evaluationWorkspace,
       this.context.capabilities,
       current.data,
       this.store.root,
@@ -2228,7 +2332,7 @@ export class WorkitCore {
       progress: task.progress,
       policy: task.policy,
       requirements,
-      writer: workspace.data.writer,
+      writer: evaluationWorkspace.writer,
     });
   }
 
@@ -2236,11 +2340,16 @@ export class WorkitCore {
     const workspace = this.store.readWorkspace();
     if (!workspace.ok) return workspace as Result<never>;
     if (!workspace.data) return failure("not_found", "workspace not found");
-    const current = captureCandidate(this.store.root, task.intent.data.scope, environment());
+    const historical = task.status === "closed" ? task.candidates.at(-1) : undefined;
+    const current = historical
+      ? success(null, null, historical)
+      : captureCandidate(this.store.root, task.intent.data.scope, environment());
     if (!current.ok) return current as Result<never>;
+    const evaluationWorkspace =
+      task.status === "closed" ? { ...workspace.data, writer: null } : workspace.data;
     const requirements = evaluateRequirements(
       task,
-      workspace.data,
+      evaluationWorkspace,
       this.context.capabilities,
       current.data,
       this.store.root,
@@ -2248,7 +2357,7 @@ export class WorkitCore {
     );
     return success(task.revision, workspace.data.revision, {
       task,
-      workspace: workspace.data,
+      workspace: evaluationWorkspace,
       capabilities: this.context.capabilities,
       requirements,
       evidence: evaluateEvidence(task, current.data),
@@ -2357,8 +2466,6 @@ export class WorkitCore {
       (status === "active" && task.data.status !== "paused")
     )
       return failure("invalid_transition", `cannot transition ${task.data.status} to ${status}`);
-    if (status === "active" && input.authorityRefs.length === 0)
-      return failure("permission_denied", "resuming a task requires authority references");
     const workspace = this.store.readWorkspace();
     if (!workspace.ok) return workspace as Result<never>;
     if (!workspace.data) return failure("not_found", "workspace not found");
@@ -2403,7 +2510,7 @@ export class WorkitCore {
         )
       )
         return failure("recovery_required", "imported task requires resume reconciliation");
-      if (!validResumeApproval(task.data, workspace.data, input.authorityRefs, this.context))
+      if (!validResumeApproval(task.data, workspace.data, input.authorityRefs ?? [], this.context))
         return failure("permission_denied", "imported resume requires native destination approval");
       resumeCandidate = current.data.candidate;
     }
@@ -2552,9 +2659,7 @@ export class WorkitCore {
         success(context.revision, null, {
           ...value,
           status: "closed",
-          candidates: value.candidates.some((item) => item.id === withCandidate.id)
-            ? value.candidates
-            : [...value.candidates, withCandidate],
+          candidates: taskForView.candidates,
           closure: {
             outcome: closure.data.outcome,
             at: context.now,

package/src/core/task-evaluation.ts

@@ -412,17 +412,15 @@ export const resolveBinding = (
   };
 };
 
-/** One shared verification predicate for fixed findings: a passed
- * check/review counts when the finding is unscoped or the evidence is
- * bound to the finding's candidate. Used by the auto-reopen scan, the
- * resolve gate, and closure — one predicate, one error code each. */
+/** Evidence evaluation establishes freshness against the current tree;
+ * the finding's original candidate identifies where the defect was found. */
 export const findingVerificationPasses = (
   findingCandidateId: string | null | undefined,
   evidence: { kind: string; candidateId: string | null | undefined; status: string },
 ): boolean =>
   evidence.status === "passed" &&
   (evidence.kind === "check" || evidence.kind === "review") &&
-  ((findingCandidateId ?? null) === null || evidence.candidateId === findingCandidateId);
+  ((findingCandidateId ?? null) === null || evidence.candidateId != null);
 const applicableDecision = (
   task: TaskRecord,
   workspace: WorkspaceRecord,

package/src/core/task-store.ts

@@ -1,4 +1,5 @@
 import { createHash, randomUUID } from "node:crypto";
+import { AsyncLocalStorage } from "node:async_hooks";
 import * as fs from "node:fs";
 import { hostname } from "node:os";
 import path from "node:path";
@@ -76,6 +77,7 @@ export type MetadataLock = {
   processStart: string | null;
   host: string;
   nonce: string;
+  externalAction?: true;
 };
 export type ProcessEvidence = {
   state: "stopped" | "accounted_for";
@@ -100,6 +102,7 @@ const metadataLockSchema = z
     processStart: z.string().nullable(),
     host: z.string().min(1),
     nonce: z.string().min(1),
+    externalAction: z.literal(true).optional(),
   })
   .strict();
 export type RecoveryCandidate = {
@@ -170,7 +173,35 @@ const sameMetadataLock = (left: unknown, right: MetadataLock): boolean => {
   const parsed = metadataLockSchema.safeParse(left);
   return parsed.success && canonicalJson(parsed.data) === canonicalJson(right);
 };
+export const sameDirectoryIdentity = (left: string, right: string): boolean => {
+  if (!path.isAbsolute(left) || !path.isAbsolute(right)) return false;
+  const normalizedLeft = path.resolve(left);
+  const normalizedRight = path.resolve(right);
+  try {
+    const a = fs.statSync(normalizedLeft, { bigint: true });
+    const b = fs.statSync(normalizedRight, { bigint: true });
+    if (!a.isDirectory() || !b.isDirectory()) return false;
+    if (
+      process.platform === "win32"
+        ? normalizedLeft.toLowerCase() === normalizedRight.toLowerCase()
+        : normalizedLeft === normalizedRight
+    )
+      return true;
+    const canonicalLeft = fs.realpathSync(normalizedLeft);
+    const canonicalRight = fs.realpathSync(normalizedRight);
+    if (
+      process.platform === "win32"
+        ? canonicalLeft.toLowerCase() === canonicalRight.toLowerCase()
+        : canonicalLeft === canonicalRight
+    )
+      return true;
+    return a.dev === b.dev && a.ino !== 0n && a.ino === b.ino;
+  } catch {
+    return false;
+  }
+};
 type LockSnapshot = { raw: string; data: MetadataLock };
+const externalActionLockRoots = new AsyncLocalStorage<ReadonlySet<string>>();
 
 export class TaskStore {
   readonly root: string;
@@ -230,7 +261,11 @@ export class TaskStore {
   readWorkspace(): Result<WorkspaceRecord | null> {
     const item = this.readRecord<WorkspaceRecord>(this.workspacePath, workspaceRecordSchema);
     if (!item.exists) return success(null, null, null);
-    if (item.result.ok && item.result.data.root !== this.root)
+    if (
+      item.result.ok &&
+      item.result.data.root !== this.root &&
+      !sameDirectoryIdentity(item.result.data.root, this.root)
+    )
       return failure("recovery_required", "workspace root binding is invalid", {
         path: this.workspacePath,
       });
@@ -355,6 +390,37 @@ export class TaskStore {
     return this.withLock<TaskRecord>(() => {
       const current = this.readWorkspace();
       if (!current.ok) return current;
+      const origin = input.task.origin;
+      if (current.data && origin) {
+        if (origin.workspaceId === current.data.id) {
+          const source = this.readTask(origin.taskId);
+          if (source.ok) return success(source.data.revision, current.data.revision, source.data);
+          if (source.code !== "not_found") return source as Result<never>;
+          return failure("not_found", "source task is not present in this shared workspace");
+        }
+        const tasks = this.listTasks();
+        if (!tasks.ok) return tasks as Result<never>;
+        const prior = tasks.data.filter(
+          (task) =>
+            task.origin?.workspaceId === origin.workspaceId &&
+            task.origin?.taskId === origin.taskId,
+        );
+        if (prior.length > 1)
+          return failure(
+            "recovery_required",
+            `source task has multiple imported mappings: ${prior.map((task) => task.id).join(", ")}`,
+          );
+        if (prior.length === 1) {
+          const existing = prior[0]!;
+          if (existing.origin!.exportDigest !== origin.exportDigest)
+            return failure(
+              "revision_conflict",
+              "source task export changed; reconcile the mapped destination task before importing",
+              { taskId: existing.id },
+            );
+          return success(existing.revision, current.data.revision, existing);
+        }
+      }
       if (
         current.data
           ? input.expectedWorkspaceRevision !== current.data.revision
@@ -822,6 +888,90 @@ export class TaskStore {
     };
   }
 
+  private externalActionLockOptions(): FileLockSyncAcquireOptions<MetadataLock> {
+    const options = this.metadataLockOptions();
+    return { ...options, payload: () => ({ ...options.payload(), externalAction: true }) };
+  }
+
+  /** Hold the workspace metadata lock across a managed effect in this checkout. */
+  async withExternalActionLock<T>(
+    operation: () => Promise<Result<T>>,
+    reentrant = false,
+  ): Promise<Result<T>> {
+    const activeRoots = externalActionLockRoots.getStore();
+    if (
+      activeRoots &&
+      [...activeRoots].some((root) => root === this.root || sameDirectoryIdentity(root, this.root))
+    )
+      return operation();
+    try {
+      this.initializeMutationStorage();
+    } catch (error) {
+      return failure("storage_error", `unable to initialize store: ${String(error)}`, {
+        path: this.workitDir,
+      });
+    }
+    let handle: FileLockSyncHandle;
+    try {
+      handle = acquireFileLockSync(this.workspacePath, this.externalActionLockOptions());
+    } catch (error) {
+      return this.lockFailure(error);
+    }
+    let result: Result<T>;
+    try {
+      if (!handle.verifyStillHeld())
+        result = failure("recovery_required", "metadata lock was compromised", {
+          path: this.lockPath,
+        });
+      else {
+        try {
+          const run = () => operation();
+          result = await (reentrant
+            ? externalActionLockRoots.run(new Set([...(activeRoots ?? []), this.root]), run)
+            : run());
+        } catch {
+          result = failure("external_outcome_unknown", "external action outcome is unknown", {
+            outcome: "unknown",
+          });
+        }
+        try {
+          if (!handle.verifyStillHeld())
+            result = failure("external_outcome_unknown", "metadata lock was compromised", {
+              outcome: "unknown",
+              path: this.lockPath,
+            });
+        } catch {
+          result = failure("external_outcome_unknown", "metadata lock could not be verified", {
+            outcome: "unknown",
+            path: this.lockPath,
+          });
+        }
+      }
+    } catch {
+      result = failure("external_outcome_unknown", "external action lock operation failed", {
+        outcome: "unknown",
+        path: this.lockPath,
+      });
+    }
+    try {
+      handle.release();
+    } catch (error) {
+      const released = this.lockFailure(error);
+      const releaseError = released.ok ? "metadata lock release failed" : released.error;
+      return result.ok
+        ? failure(
+            "external_outcome_unknown",
+            "external action metadata lock release is uncertain",
+            {
+              outcome: "unknown",
+              path: this.lockPath,
+            },
+          )
+        : failure("recovery_required", `${result.error}; ${releaseError}`, result.details);
+    }
+    return result;
+  }
+
   private recoveryLockOptions(
     observed: LockSnapshot | null,
     evidence: ProcessEvidence,
@@ -912,6 +1062,14 @@ export class TaskStore {
   private lockFailure(error: unknown): Result<never> {
     const value = error as { code?: unknown; message?: unknown };
     const code = typeof value?.code === "string" ? value.code : "";
+    if (code === "EEXIST" || code === "file_lock_timeout") {
+      const lock = this.readLockSnapshot();
+      if (lock.ok && lock.data?.data.externalAction)
+        return failure("writer_conflict", "workspace is reserved by a managed external action", {
+          outcome: "not_started",
+          path: this.lockPath,
+        });
+    }
     const recovery =
       code === "EEXIST" ||
       code === "file_lock_timeout" ||