@brainervirus/workit-core 1.0.9 → 1.0.11

package/src/core/task-engine.ts

@@ -58,6 +58,7 @@ import {
 } from "./task-context";
 import {
   assertProductWriteAllowed,
+  isUncertainWorker,
   type CallerContext,
   type NativeWorkerObservation,
   type NativeWorkerVerification,
@@ -360,11 +361,16 @@ const applyWorkerLifecycle = (input: ObserveWorkerLifecycleInput): Result<Entry<
     return failure("invalid_transition", "worker has not started");
   if (input.state === "running" && entry.data.state === "stopped")
     return failure("invalid_transition", "stopped worker cannot run again");
+  const terminalCancel = entry.data.state === "cancelling" && input.state === "running";
   const nextEntry = {
     ...entry,
     recordedAt: input.now ?? entry.recordedAt,
     provenance: authority.provenance,
-    data: { ...entry.data, state: input.state, session: input.session },
+    data: {
+      ...entry.data,
+      state: terminalCancel ? ("cancelling" as const) : input.state,
+      session: input.session,
+    },
   } satisfies Entry<Worker>;
   const shouldClear =
     input.state === "stopped" &&
@@ -381,7 +387,7 @@ const applyWorkerLifecycle = (input: ObserveWorkerLifecycleInput): Result<Entry<
   // revision bump per event livelocks worker sessions — each call would
   // invalidate the revision the previous call returned.
   if (
-    entry.data.state === input.state &&
+    entry.data.state === nextEntry.data.state &&
     sameValue(entry.data.session, input.session) &&
     !shouldClear &&
     !shouldUncertain
@@ -823,11 +829,7 @@ export class WorkitCore {
   ) {
     if (workspace.writer)
       return failure("recovery_required", "writer ownership must be released first");
-    if (
-      task.workers.some((entry) =>
-        ["dispatching", "running", "cancelling", "unknown"].includes(entry.data.state),
-      )
-    )
+    if (task.workers.some((entry) => isUncertainWorker(entry.data.state)))
       return failure("recovery_required", "worker state requires reconciliation");
     return null;
   }
@@ -1063,18 +1065,6 @@ export class WorkitCore {
       (this.context.workerId ?? null) === null ? null : this.helperEntry(task.data, true, true);
     if (helper && !helper.ok) return helper as Result<never>;
     const evidence = input.evidence as Evidence;
-    if (helper?.ok) {
-      const assignment = helper.data.data.assignment;
-      if (
-        evidence.requirementIds.some((id: string) => !assignment.requirementIds.includes(id)) ||
-        (assignment.candidateId !== null &&
-          evidence.candidateId !== assignment.candidateId &&
-          evidence.beforeCandidateId !== assignment.candidateId) ||
-        !refsWithinScope(evidence.refs, assignment.scope) ||
-        !refsWithinScope(evidence.refs, task.data.intent.data.scope)
-      )
-        return failure("permission_denied", "evidence is outside the worker assignment");
-    }
     if (
       (evidence.result === "missing" || evidence.result === "skipped") &&
       !evidence.summary.trim()
@@ -1100,6 +1090,18 @@ export class WorkitCore {
       evidence.beforeCandidateId ??= null;
       evidence.candidateId ??= null;
     }
+    if (helper?.ok) {
+      const assignment = helper.data.data.assignment;
+      if (
+        evidence.requirementIds.some((id: string) => !assignment.requirementIds.includes(id)) ||
+        (assignment.candidateId !== null &&
+          evidence.candidateId !== assignment.candidateId &&
+          evidence.beforeCandidateId !== assignment.candidateId) ||
+        !refsWithinScope(evidence.refs, assignment.scope) ||
+        !refsWithinScope(evidence.refs, task.data.intent.data.scope)
+      )
+        return failure("permission_denied", "evidence is outside the worker assignment");
+    }
     const knownCandidates = new Set(task.data.candidates.map((candidate) => candidate.id));
     for (const candidateId of [evidence.beforeCandidateId, evidence.candidateId]) {
       if (
@@ -1187,7 +1189,15 @@ export class WorkitCore {
         "permission_denied",
         "native observation is only valid for recording decisions",
       );
-    if (nativeRequired && nativeObservation === undefined)
+    // Stated choices carry user-settled decisions without a native receipt.
+    // They never authorize mutating actions; native verification is skipped
+    // and provenance stays agent-reported.
+    const stated = input.action === "record" && input.response === "stated";
+    if (stated && input.purpose === "action")
+      return failure("permission_denied", "stated choices cannot authorize mutating actions");
+    if (stated && !input.binding?.statedChoice)
+      return failure("invalid_input", "stated choices require binding.statedChoice");
+    if (nativeRequired && nativeObservation === undefined && !stated)
       return failure("permission_denied", "native decision observation is required");
     const task = this.store.readTask(input.taskId);
     if (!task.ok) return task as Result<never>;
@@ -1218,26 +1228,27 @@ export class WorkitCore {
         consumption: null,
       } satisfies Omit<Decision, "digest">;
       const data: Decision = { ...base, digest: decisionDigest(base) };
-      const native = nativeRequired
-        ? verifyNativeDecision(
-            this.context.nativeAuthority,
-            {
-              observation: nativeObservation,
-              expected: {
-                taskId: task.data.id,
-                workspaceId: workspace.data.id,
-                purpose: input.purpose,
-                response: input.response,
-                binding: input.binding,
-                bindingBytes: canonicalJson(input.binding),
-                digest: data.digest,
-                requirementIds: [...input.requirementIds],
+      const native =
+        nativeRequired && !stated
+          ? verifyNativeDecision(
+              this.context.nativeAuthority,
+              {
+                observation: nativeObservation,
+                expected: {
+                  taskId: task.data.id,
+                  workspaceId: workspace.data.id,
+                  purpose: input.purpose,
+                  response: input.response,
+                  binding: input.binding,
+                  bindingBytes: canonicalJson(input.binding),
+                  digest: data.digest,
+                  requirementIds: [...input.requirementIds],
+                },
+                caller: this.context.caller,
               },
-              caller: this.context.caller,
-            },
-            { owner: this.authorityOwner, store: this.store, root: this.store.root },
-          )
-        : null;
+              { owner: this.authorityOwner, store: this.store, root: this.store.root },
+            )
+          : null;
       if (native && !native.ok) return native as Result<never>;
       const nativeProvenance = native?.ok ? retireNativeAuthority(native.data) : null;
       if (native?.ok && !nativeProvenance)
@@ -2242,6 +2253,9 @@ export class WorkitCore {
       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,
@@ -2344,9 +2358,7 @@ export class WorkitCore {
     const base = reconcileResumeContext(effectiveView);
     if (!base.ok) return base;
     const needsReconciliation = view.task.workers.some((entry) =>
-      ["dispatching", "running", "cancelling", "unknown"].includes(
-        observedStates.get(entry.id) ?? entry.data.state,
-      ),
+      isUncertainWorker(observedStates.get(entry.id) ?? entry.data.state),
     );
     const blockers = [...base.data.blockers];
     if (
@@ -2438,8 +2450,8 @@ export class WorkitCore {
             !current.candidates.some((candidate) => candidate.id === resumeCandidate!.id)
               ? [...current.candidates, resumeCandidate]
               : current.candidates,
-          progress:
-            status === "paused" ? { ...current.progress, summary: input.reason } : current.progress,
+          progress: current.progress,
+          pauseReason: status === "paused" ? (input.reason ?? null) : null,
         }),
     });
     if (!changed.ok) return changed as Result<never>;
@@ -2475,7 +2487,10 @@ 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");
-    if (workspace.data.writer || task.data.workers.some((entry) => entry.data.state !== "stopped"))
+    if (
+      workspace.data.writer ||
+      task.data.workers.some((entry) => isUncertainWorker(entry.data.state))
+    )
       return failure(
         "recovery_required",
         "scope revision requires worker ownership reconciliation",

package/src/core/task-evaluation.ts

@@ -154,14 +154,23 @@ const scopeRoots = (root: string, scope: Scope): Result<string[]> => {
   const roots: string[] = [];
   for (const item of scope.paths.length ? scope.paths : ["."]) {
     const target = path.resolve(root, item);
-    if (!inside(root, target)) return failure("invalid_input", "candidate scope escapes checkout");
+    if (!inside(root, target))
+      return failure(
+        "invalid_input",
+        `candidate scope escapes checkout: ${item} — keep one task per repository and coordinate a separate linked task in the other checkout`,
+        { fields: [{ path: "scope.paths", reason: `${item} is outside the checkout` }] },
+      );
     let ancestor = target;
     while (!fs.existsSync(ancestor) && ancestor !== root) ancestor = path.dirname(ancestor);
     try {
       if (!inside(root, fs.realpathSync(ancestor)))
-        return failure("invalid_input", "candidate scope escapes checkout");
+        return failure(
+          "invalid_input",
+          `candidate scope escapes checkout through a symlink: ${item} — keep one task per repository and coordinate a separate linked task in the other checkout`,
+          { fields: [{ path: "scope.paths", reason: `${item} resolves outside the checkout` }] },
+        );
     } catch {
-      return failure("invalid_input", "candidate scope cannot be inspected");
+      return failure("invalid_input", `candidate scope cannot be inspected: ${item}`);
     }
     roots.push(target);
   }
@@ -180,7 +189,12 @@ export function captureCandidate(
     return failure("invalid_input", "candidate root does not exist");
   }
   const normalizedScope = canonicalScope(scope);
-  if (!normalizedScope) return failure("invalid_input", "candidate scope is invalid");
+  if (!normalizedScope)
+    return failure(
+      "invalid_input",
+      "candidate scope is invalid: paths must be checkout-relative — to work in another repository, keep this task here and coordinate a separate linked task in that checkout",
+      { fields: [{ path: "scope.paths", reason: "must be checkout-relative" }] },
+    );
   const roots = scopeRoots(checkout, normalizedScope);
   if (!roots.ok) return roots;
   const git = gitPaths(checkout);
@@ -399,7 +413,7 @@ const applicableRequirementDecision = (
       ({ data, provenance }) =>
         provenance.kind !== "imported" &&
         data.purpose !== "limitation" &&
-        data.response === "approved" &&
+        (data.response === "approved" || data.response === "stated") &&
         data.revoked === null &&
         data.binding.taskId === task.id &&
         data.binding.workspaceId === workspace.id &&
@@ -461,7 +475,10 @@ export function evaluateRequirements(
       const reviewSession = sessionFromRef(entry.data.reviewContext);
       const sameImplementation = sameSession(reviewSession, task.intent.provenance.session);
       const sameEvidenceSession = task.evidence.some(
-        (other) => other.id !== entry.id && sameSession(reviewSession, other.provenance.session),
+        (other) =>
+          other.id !== entry.id &&
+          other.data.kind === "review" &&
+          sameSession(reviewSession, other.provenance.session),
       );
       return (
         entry.data.kind === "review" &&
@@ -536,7 +553,7 @@ export function evaluateRequirements(
         status: "satisfied" as const,
         evidenceIds: [],
         decisionIds: decisions.map((decision) => decision.id),
-        reason: "an applicable approved decision satisfies the requirement",
+        reason: "an applicable approved or stated decision satisfies the requirement",
       };
     const limitations = requirement.acceptanceAllowed
       ? applicableDecision(task, workspace, requirement, checkoutRoot)
@@ -641,6 +658,18 @@ export function evaluateClosure(
   if (requestedOutcome !== "stopped" && blocking.length)
     return failure("requirements_unsatisfied", "applicable requirements are unsatisfied", {
       requirementIds: blocking.map((item) => item.requirementId),
+      requirements: blocking.map((item) => {
+        const requirement = view.task.policy?.requirements.find(
+          (candidate) => candidate.id === item.requirementId,
+        );
+        return {
+          requirementId: item.requirementId,
+          ruleId: requirement?.ruleId ?? "unknown",
+          reason: item.reason,
+          satisfaction: requirement?.satisfaction ?? "",
+          dependentAction: requirement?.dependentAction ?? null,
+        };
+      }),
     });
   const accepted = evaluations.filter((item) => item.status === "accepted_limitation");
   if (requestedOutcome === "verified" && accepted.length)

package/src/core/task-store.ts

@@ -3,6 +3,7 @@ import * as fs from "node:fs";
 import { hostname } from "node:os";
 import path from "node:path";
 import * as z from "zod";
+import { packageRoot } from "./package-root";
 import {
   acquireFileLockSync,
   type FileLockSyncHandle,
@@ -109,6 +110,43 @@ export type RecoveryCandidate = {
 };
 
 const now = (): Utc => new Date().toISOString().replace(/\.\d{3}Z$/, "Z");
+
+let cachedRuntimeVersion: string | null = null;
+/** Version of the package that hosts this runtime; recorded with state so a
+ * bug report can identify the writer version without reading raw .workit. */
+export const runtimeVersion = (): string => {
+  if (cachedRuntimeVersion === null) {
+    try {
+      const pkg = JSON.parse(fs.readFileSync(path.join(packageRoot(), "package.json"), "utf8")) as {
+        version?: unknown;
+      };
+      cachedRuntimeVersion = typeof pkg.version === "string" && pkg.version ? pkg.version : "0.0.0";
+    } catch {
+      cachedRuntimeVersion = "0.0.0";
+    }
+  }
+  return cachedRuntimeVersion;
+};
+
+const stampNew = (record: { runtime?: { createdWith: string | null } }) => ({
+  createdWith: record.runtime?.createdWith ?? null,
+  updatedWith: runtimeVersion(),
+});
+
+const isNewerVersion = (candidate: string, current: string): boolean => {
+  const parts = (value: string) =>
+    value
+      .split("-")[0]
+      .split(".")
+      .map((item) => Number.parseInt(item, 10) || 0);
+  const [next, now] = [parts(candidate), parts(current)];
+  for (let index = 0; index < 3; index += 1) {
+    const left = next[index] ?? 0;
+    const right = now[index] ?? 0;
+    if (left !== right) return left > right;
+  }
+  return false;
+};
 const jsonBytes = (value: unknown): string => `${canonicalJson(value)}\n`;
 const digestBytes = (value: string | Buffer): string =>
   createHash("sha256").update(value).digest("hex");
@@ -221,10 +259,14 @@ export class TaskStore {
           ? value.expectedWorkspaceRevision !== current.data.revision
           : value.expectedWorkspaceRevision !== null
       ) {
-        return failure("revision_conflict", "workspace revision does not match", {
-          expectedWorkspaceRevision: value.expectedWorkspaceRevision,
-          actualWorkspaceRevision: current.data?.revision ?? null,
-        });
+        return failure(
+          "revision_conflict",
+          "workspace revision does not match; omit expectedWorkspaceRevision to use the current record",
+          {
+            expectedWorkspaceRevision: value.expectedWorkspaceRevision,
+            actualWorkspaceRevision: current.data?.revision ?? null,
+          },
+        );
       }
       if (!value.provenance) return failure("invalid_input", "provenance is required");
       if (
@@ -236,12 +278,18 @@ export class TaskStore {
       if (current.data && !previousWorkspaceBytes)
         return failure("storage_error", "workspace snapshot disappeared during creation");
       const workspace: WorkspaceRecord = current.data
-        ? { ...current.data, revision: newRevision(), root: this.root }
+        ? {
+            ...current.data,
+            revision: newRevision(),
+            root: this.root,
+            runtime: stampNew(current.data),
+          }
         : {
             schemaVersion: SCHEMA_VERSION,
             id: newId(),
             revision: newRevision(),
             root: this.root,
+            runtime: { createdWith: runtimeVersion(), updatedWith: runtimeVersion() },
             writer: null,
           };
       const timestamp = value.now ?? now();
@@ -263,6 +311,7 @@ export class TaskStore {
         status: "active",
         closure: null,
         progress: { summary: "", nextAction: null, blockers: [] },
+        runtime: { createdWith: runtimeVersion(), updatedWith: runtimeVersion() },
         assessments: [],
         policy: null,
         policyChanges: [],
@@ -312,21 +361,31 @@ export class TaskStore {
           ? input.expectedWorkspaceRevision !== current.data.revision
           : input.expectedWorkspaceRevision !== null
       )
-        return failure("revision_conflict", "workspace revision does not match", {
-          expectedWorkspaceRevision: input.expectedWorkspaceRevision,
-          actualWorkspaceRevision: current.data?.revision ?? null,
-        });
+        return failure(
+          "revision_conflict",
+          "workspace revision does not match; omit expectedWorkspaceRevision to use the current record",
+          {
+            expectedWorkspaceRevision: input.expectedWorkspaceRevision,
+            actualWorkspaceRevision: current.data?.revision ?? null,
+          },
+        );
       const previousWorkspaceBytes = current.data ? this.snapshotBytes(this.workspacePath) : null;
       if (current.data && !previousWorkspaceBytes)
         return failure("storage_error", "workspace snapshot disappeared during import");
       const timestamp = input.now ?? now();
       const workspace: WorkspaceRecord = current.data
-        ? { ...current.data, revision: newRevision(), root: this.root }
+        ? {
+            ...current.data,
+            revision: newRevision(),
+            root: this.root,
+            runtime: stampNew(current.data),
+          }
         : {
             schemaVersion: SCHEMA_VERSION,
             id: input.workspaceId ?? newId(),
             revision: newRevision(),
             root: this.root,
+            runtime: { createdWith: runtimeVersion(), updatedWith: runtimeVersion() },
             writer: null,
           };
       const task = {
@@ -335,6 +394,10 @@ export class TaskStore {
         revision: newRevision(),
         createdAt: timestamp,
         updatedAt: timestamp,
+        runtime: {
+          createdWith: input.task.runtime?.createdWith ?? null,
+          updatedWith: runtimeVersion(),
+        },
       };
       const validTask = taskRecordSchema.safeParse(task);
       if (!validTask.success)
@@ -402,6 +465,7 @@ export class TaskStore {
         createdAt: current.data.createdAt,
         revision: context.revision,
         updatedAt: context.now,
+        runtime: stampNew(current.data),
       };
       const valid = taskRecordSchema.safeParse(record);
       if (!valid.success)
@@ -433,6 +497,7 @@ export class TaskStore {
         id: current.data.id,
         root: this.root,
         revision: context.revision,
+        runtime: stampNew(current.data),
       };
       const valid = workspaceRecordSchema.safeParse(record);
       if (!valid.success)
@@ -472,6 +537,7 @@ export class TaskStore {
         id: workspace.data.id,
         root: this.root,
         revision: workspaceContext.revision,
+        runtime: stampNew(workspace.data),
       });
       if (!nextWorkspace.success)
         return failure("invalid_input", "workspace mutation produced an invalid record");
@@ -508,6 +574,7 @@ export class TaskStore {
         createdAt: task.data.createdAt,
         revision: taskContext.revision,
         updatedAt: taskContext.now,
+        runtime: stampNew(task.data),
       });
       if (!nextTask.success) {
         this.markUncertain(nextWorkspace.data);
@@ -785,6 +852,7 @@ export class TaskStore {
       ...workspace,
       writer: { ...workspace.writer, state: "uncertain" as const },
       revision: newRevision(),
+      runtime: stampNew(workspace),
     };
     this.replaceSnapshot(this.workspacePath, value, workspace);
   }
@@ -1027,9 +1095,17 @@ export class TaskStore {
     if (isObject(value) && "schemaVersion" in value && value.schemaVersion !== SCHEMA_VERSION)
       return failure("unsupported_version", "unsupported snapshot schema version");
     const parsed = schema.safeParse(value);
-    return parsed.success
-      ? success(null, null, parsed.data)
-      : failure("recovery_required", "snapshot does not satisfy its schema");
+    if (parsed.success) return success(null, null, parsed.data);
+    const writerVersion =
+      isObject(value) && isObject((value as { runtime?: unknown }).runtime)
+        ? (value as { runtime: { updatedWith?: unknown } }).runtime.updatedWith
+        : null;
+    if (typeof writerVersion === "string" && isNewerVersion(writerVersion, runtimeVersion()))
+      return failure(
+        "recovery_required",
+        `snapshot was written by workit ${writerVersion}; upgrade Workit before mutating this checkout`,
+      );
+    return failure("recovery_required", "snapshot does not satisfy its schema");
   }
 
   private processStart(pid: number): string | null {
@@ -1041,10 +1117,14 @@ export class TaskStore {
   }
 
   private conflict(expected: Revision, actual: Revision): Result<never> {
-    return failure("revision_conflict", "snapshot revision does not match", {
-      expectedRevision: expected,
-      actualRevision: actual,
-    });
+    return failure(
+      "revision_conflict",
+      "snapshot revision does not match; omit expectedRevision to use the current record",
+      {
+        expectedRevision: expected,
+        actualRevision: actual,
+      },
+    );
   }
 
   private taskPath(taskId: Id) {

package/src/core/workers.ts

@@ -93,6 +93,12 @@ const same = (left: unknown, right: unknown): boolean => {
   }
 };
 
+/** The one shared definition of active or uncertain worker state used by
+ * close, revise, resume, and replacement-launch checks. */
+export const UNCERTAIN_WORKER_STATES = ["dispatching", "running", "cancelling", "unknown"] as const;
+export const isUncertainWorker = (state: string): boolean =>
+  (UNCERTAIN_WORKER_STATES as readonly string[]).includes(state);
+
 const callerSession = (caller: CallerContext): HostSession =>
   caller.session ?? { kind: "host", host: caller.host, handle: caller.actor };
 

package/src/core.ts

@@ -22,6 +22,8 @@ export {
   decisionDigest,
   candidateDigest,
   requirementId,
+  BINDING_QUESTION_BUDGET,
+  workitBindingQuestionIssue,
 } from "./core/task-contract";
 export type {
   OperationFamily,
@@ -55,7 +57,7 @@ export type {
   ExportBundle,
   Result as ContractResult,
 } from "./core/task-contract";
-export { TaskStore } from "./core/task-store";
+export { TaskStore, runtimeVersion } from "./core/task-store";
 export type { MetadataLock, ProcessEvidence, RecoveryInput } from "./core/task-store";
 export { compactTaskContext, reconcileResume } from "./core/task-context";
 export type {
@@ -66,7 +68,7 @@ export type {
 } from "./core/task-context";
 export { METHODS, invariantBootstrap, selectMethods } from "./core/methods";
 export type { MethodId, SelectedMethod } from "./core/methods";
-export { shellRouteIntent } from "./core/route-intent";
+export { hasLiveWorkitTask, shellRouteIntent, shouldDenyShellRoute } from "./core/route-intent";
 export type { ShellRouteIntent } from "./core/route-intent";
 export { applicableDecision, reserveAction, settleAction, reconcileAction } from "./core/authority";
 export {
@@ -84,9 +86,16 @@ export type {
   ExternalActionOperation,
 } from "./core/external-action";
 export {
+  approvedBranchSetupIntent,
   approvedExternalAction,
+  approvedPlanCommit,
+  branchSetupIntent,
+  planCommitDescriptor,
+  planCommitBinding,
+  commitMessageFromDescriptor,
   externalActionState,
   priorExternalAction,
+  priorResolvedDrift,
   externalActionRef,
   externalActionDescriptor,
   externalActionHelp,