@brainervirus/workit-core 1.0.10 → 1.0.11

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@brainervirus/workit-core",
-  "version": "1.0.10",
+  "version": "1.0.11",
   "private": false,
   "description": "Workit shared core — task, policy, evidence, review, decision, worker, and writer state for agentic coding workflows",
   "keywords": [

package/src/core/external-action-effects.ts

@@ -286,16 +286,29 @@ export const actionProposalQuestion = (
           approvedText: "Reapply the recorded stash.",
         };
       const target = String(payload.target_branch ?? "");
+      // A dirty tree binds stash: the approval carries the stash through,
+      // so the question names it instead of failing later at preflight.
+      const stashes = payload.stash === "yes" && resolved.dirty === true;
       if (resolved.target_exists === true)
-        return {
-          presented: `Workit decision: action — Switch to branch \`${target}\`?`,
-          approvedText: `Switch to \`${target}\`.`,
-        };
+        return stashes
+          ? {
+              presented: `Workit decision: action — Stash the dirty working tree and switch to branch \`${target}\`?`,
+              approvedText: `Stash and switch to \`${target}\`.`,
+            }
+          : {
+              presented: `Workit decision: action — Switch to branch \`${target}\`?`,
+              approvedText: `Switch to \`${target}\`.`,
+            };
       const base = String(resolved.base_branch ?? "the base branch");
-      return {
-        presented: `Workit decision: action — Create branch \`${target}\` from \`${base}\` (currently ${shortSha(resolved.remote_base)})?`,
-        approvedText: `Create \`${target}\` from \`${base}\` at ${shortSha(resolved.remote_base)}.`,
-      };
+      return stashes
+        ? {
+            presented: `Workit decision: action — Stash the dirty working tree and create branch \`${target}\` from \`${base}\` (currently ${shortSha(resolved.remote_base)})?`,
+            approvedText: `Stash and create \`${target}\` from \`${base}\` at ${shortSha(resolved.remote_base)}.`,
+          }
+        : {
+            presented: `Workit decision: action — Create branch \`${target}\` from \`${base}\` (currently ${shortSha(resolved.remote_base)})?`,
+            approvedText: `Create \`${target}\` from \`${base}\` at ${shortSha(resolved.remote_base)}.`,
+          };
     }
     case "git.commit": {
       const paths = Array.isArray(resolved.paths) ? (resolved.paths as string[]) : [];

package/src/core/external-action.ts

@@ -472,24 +472,131 @@ export const approvedExternalAction = (
   operation: string,
 ) => {
   const selected = externalActionState(store, host, actor, operation);
-  if (!selected.ok) return selected;
-  if (selected.data.entry.data.consumption !== null)
+  if (selected.ok) {
+    if (selected.data.entry.data.consumption !== null)
+      return failure(
+        selected.data.entry.data.consumption.state === "uncertain"
+          ? "external_outcome_unknown"
+          : "permission_denied",
+        selected.data.entry.data.consumption.state === "uncertain"
+          ? "previous external action outcome is unknown"
+          : "external action was already settled",
+      );
+    return selected;
+  }
+  // Intent carry for branch setup: an approval binds (target, base) intent,
+  // so unrelated HEAD or dirt moves between approval and execution re-resolve
+  // instead of demanding re-approval. Remote, existence, and target drift
+  // still fail closed through priorResolvedDrift.
+  const intent = approvedBranchSetupIntent(store, host, actor, operation);
+  if (intent.ok) {
+    if (intent.data.entry.data.consumption !== null)
+      return failure(
+        intent.data.entry.data.consumption.state === "uncertain"
+          ? "external_outcome_unknown"
+          : "permission_denied",
+        intent.data.entry.data.consumption.state === "uncertain"
+          ? "previous external action outcome is unknown"
+          : "external action was already settled",
+      );
+    return intent;
+  }
+  return selected;
+};
+
+/** Intent identity for a branch-setup descriptor: target and base bind the
+ * effect; head and dirt are execution-time state that re-resolves. */
+export const branchSetupIntent = (
+  descriptor: string,
+): { target: string; base: string; remoteBase: string | null; targetExists: boolean } | null => {
+  try {
+    const value = JSON.parse(descriptor) as {
+      operation?: unknown;
+      payload?: {
+        target_branch?: unknown;
+        resolved?: {
+          base_branch?: unknown;
+          remote_base?: unknown;
+          target_exists?: unknown;
+        };
+      };
+    };
+    if (value.operation !== "git.branch_setup" || !value.payload) return null;
+    const { target_branch, resolved } = value.payload;
+    if (typeof target_branch !== "string" || !target_branch || !resolved) return null;
+    if (typeof resolved.base_branch !== "string" || typeof resolved.target_exists !== "boolean")
+      return null;
+    return {
+      target: target_branch,
+      base: resolved.base_branch,
+      remoteBase: typeof resolved.remote_base === "string" ? resolved.remote_base : null,
+      targetExists: resolved.target_exists,
+    };
+  } catch {
+    return null;
+  }
+};
+
+/** Find the single unconsumed branch-setup approval with the same intent as
+ * the current descriptor, regardless of head or dirt moves since approval. */
+export const approvedBranchSetupIntent = (
+  store: TaskStore,
+  host: string,
+  actor: string,
+  operation: string,
+) => {
+  const current = branchSetupIntent(operation);
+  if (!current) return failure("permission_denied", "no approved action is bound to this session");
+  const listed = store.listTasks();
+  const workspace = store.readWorkspace();
+  if (!listed.ok || !workspace.ok)
+    return failure("storage_error", "external action state is unavailable");
+  if (!workspace.data) return failure("not_found", "workspace not found");
+  const candidates = listed.data.flatMap((task) => {
+    if (
+      task.status !== "active" ||
+      task.workspaceId !== workspace.data!.id ||
+      task.intent.provenance.session?.kind !== "host" ||
+      task.intent.provenance.session.host !== host ||
+      task.intent.provenance.session.handle !== actor
+    )
+      return [];
+    return task.decisions
+      .filter(
+        (entry) =>
+          entry.data.purpose === "action" &&
+          entry.data.response === "approved" &&
+          entry.data.revoked === null,
+      )
+      .map((entry) => ({ task, entry }));
+  });
+  const matches = candidates.filter(({ entry }) => {
+    const intent = branchSetupIntent(entry.data.binding.approvedContent);
+    return (
+      intent !== null &&
+      intent.target === current.target &&
+      intent.base === current.base &&
+      intent.remoteBase === current.remoteBase &&
+      intent.targetExists === current.targetExists
+    );
+  });
+  if (matches.length !== 1)
     return failure(
-      selected.data.entry.data.consumption.state === "uncertain"
-        ? "external_outcome_unknown"
-        : "permission_denied",
-      selected.data.entry.data.consumption.state === "uncertain"
-        ? "previous external action outcome is unknown"
-        : "external action was already settled",
+      "permission_denied",
+      matches.length === 0
+        ? "no approved action is bound to this session"
+        : "multiple approved actions match this session",
     );
-  return selected;
+  return success(workspace.data.revision, null, { ...matches[0], workspace: workspace.data });
 };
 
 /**
  * Re-resolve guard: when a prior approval exists for the same requested
- * operation/payload, the freshly resolved baseline (source state and remote
- * base) must still match the approved descriptor. Drift returns not_started so
- * the agent re-presents the current state instead of executing a stale effect.
+ * operation/payload, the intent baseline must still match. For branch setup
+ * only (target, base, remote base, existence) bind the effect — head and
+ * dirt moves re-resolve instead of demanding re-approval. Drift names the
+ * moved element and returns not_started so the agent re-presents the
+ * current state instead of executing a stale effect.
  */
 export const priorResolvedDrift = (
   store: TaskStore,
@@ -511,6 +618,38 @@ export const priorResolvedDrift = (
     return success(null, null, null);
   }
   if (baseline === undefined || baseline === null) return success(null, null, null);
+  if (operation === "git.branch_setup") {
+    const before = branchSetupIntent(prior.data.entry.data.binding.approvedContent);
+    let after: ReturnType<typeof branchSetupIntent> = null;
+    try {
+      after = branchSetupIntent(
+        JSON.stringify({
+          operation,
+          payload: { ...(payload as Record<string, unknown>), resolved: currentResolved },
+        }),
+      );
+    } catch {
+      after = null;
+    }
+    if (before && after) {
+      const moved =
+        before.target !== after.target
+          ? "target_branch"
+          : before.base !== after.base
+            ? "base_branch"
+            : before.remoteBase !== after.remoteBase
+              ? "remote_base"
+              : before.targetExists !== after.targetExists
+                ? "target_exists"
+                : null;
+      if (moved === null) return success(null, null, null);
+      return failure(
+        "invalid_input",
+        `repository state changed since approval (${moved} moved); show the current state and approve the action again`,
+        { outcome: "not_started", operation },
+      );
+    }
+  }
   if (canonicalJson(baseline) === canonicalJson(currentResolved)) return success(null, null, null);
   return failure(
     "invalid_input",

package/src/core/route-intent.ts

@@ -1,3 +1,5 @@
+import { TaskStore } from "./task-store";
+
 export type ShellRouteIntent = {
   route: "git.branch_setup" | "hosting.pull_request";
   guidance: string;
@@ -49,3 +51,29 @@ export function shellRouteIntent(command: string): ShellRouteIntent | null {
   }
   return null;
 }
+
+/**
+ * Session-scoped enforcement: the denial protects live Workit coordination,
+ * so it fires only where an active or paused task exists. Any filesystem or
+ * storage failure means "no live task" — never deny on uncertainty.
+ */
+export function hasLiveWorkitTask(dir: string): boolean {
+  try {
+    if (typeof dir !== "string" || dir === "") return false;
+    const listed = new TaskStore(dir).listTasks();
+    if (!listed.ok) return false;
+    return listed.data.some((task) => task.status === "active" || task.status === "paused");
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Single core gate for the shell route denial. Adapters pass their
+ * session/project directory and delete local deny duplication; outside
+ * attributed sessions the command is silently allowed.
+ */
+export function shouldDenyShellRoute(dir: string, command: string): ShellRouteIntent | null {
+  if (!hasLiveWorkitTask(dir)) return null;
+  return shellRouteIntent(command);
+}

package/src/core/task-contract.ts

@@ -455,10 +455,11 @@ export const decisionSchema = z
         approvedContent: text,
         displayed: text.optional(),
         contentRefs: z.array(refSchema),
+        statedChoice: z.object({ ref: text, text: text }).strict().optional(),
       })
       .strict(),
     digest,
-    response: z.enum(["approved", "rejected"]),
+    response: z.enum(["approved", "rejected", "stated"]),
     requirementIds: z.array(digest),
     revoked: z.object({ at: utc, reason: text }).strict().nullable(),
     consumption: z

package/src/core/task-engine.ts

@@ -1189,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>;
@@ -1220,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)

package/src/core/task-evaluation.ts

@@ -413,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 &&
@@ -553,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)

package/src/core.ts

@@ -68,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 {
@@ -86,8 +86,10 @@ export type {
   ExternalActionOperation,
 } from "./core/external-action";
 export {
+  approvedBranchSetupIntent,
   approvedExternalAction,
   approvedPlanCommit,
+  branchSetupIntent,
   planCommitDescriptor,
   planCommitBinding,
   commitMessageFromDescriptor,