@brainervirus/workit-cli 1.0.8 → 1.0.10

package/dist/index.js

@@ -50927,6 +50927,7 @@ var decisionSchema = object({
     scope: scopeSchema,
     presented: text,
     approvedContent: text,
+    displayed: text.optional(),
     contentRefs: array(refSchema)
   }).strict(),
   digest,
@@ -50939,6 +50940,27 @@ var decisionSchema = object({
     actionRef: refSchema
   }).strict().nullable()
 }).strict();
+var BINDING_QUESTION_BUDGET = 300;
+var bindingQuestionHeader = /^Workit decision: (design|action|limitation|preference)$/;
+var workitBindingQuestionIssue = (questions) => {
+  if (!Array.isArray(questions) || questions.length !== 1)
+    return null;
+  const question = questions[0];
+  if (!question || typeof question !== "object")
+    return null;
+  if (typeof question.header !== "string" || !bindingQuestionHeader.test(question.header.trim()))
+    return null;
+  const over = (label, value) => `invalid_input: ${label} is ${value.length} characters; Workit binding questions must stay within ${BINDING_QUESTION_BUDGET}. present the item in the conversation first, then ask a short scoped question.`;
+  if (typeof question.question === "string" && question.question.length > BINDING_QUESTION_BUDGET)
+    return over("the question text", question.question);
+  if (Array.isArray(question.options))
+    for (const option of question.options) {
+      const description = option.description;
+      if (typeof description === "string" && description.length > BINDING_QUESTION_BUDGET)
+        return over("an option description", description);
+    }
+  return null;
+};
 var findingSchema = object({
   claim: text,
   consequence: text,
@@ -50965,7 +50987,7 @@ var workerReportSchema = object({
 }).strict();
 var workerSchema = object({
   assignment: assignmentSchema,
-  state: _enum(["assigned", "running", "cancelling", "stopped", "unknown"]),
+  state: _enum(["assigned", "dispatching", "running", "cancelling", "stopped", "unknown"]),
   session: refSchema.nullable(),
   report: workerReportSchema.nullable()
 }).strict();
@@ -51005,6 +51027,10 @@ var actionProgressListSchema = array(actionProgressSchema).check((ctx) => {
       path: ["decisionId"]
     });
 });
+var runtimeSchema = object({
+  createdWith: text.nullable(),
+  updatedWith: text
+}).strict();
 var taskRecordSchema = object({
   schemaVersion: literal(1),
   id,
@@ -51018,6 +51044,8 @@ var taskRecordSchema = object({
   status: _enum(["active", "paused", "closed"]),
   closure: closureSchema.nullable(),
   progress: progressSchema,
+  pauseReason: text.nullable().optional(),
+  runtime: runtimeSchema.optional(),
   assessments: array(entrySchema(assessmentSchema)),
   policy: policySchema.nullable(),
   policyChanges: array(policyChangeSchema),
@@ -51033,6 +51061,7 @@ var workspaceRecordSchema = object({
   id,
   revision,
   root: nonEmpty,
+  runtime: runtimeSchema.optional(),
   writer: object({ state: _enum(["held", "uncertain"]), owner: ownerSchema, acquiredAt: utc }).strict().nullable()
 }).strict();
 var capabilitySchema = object({
@@ -51060,6 +51089,9 @@ var taskSummarySchema = object({
   id,
   revision,
   workspaceRevision: revision,
+  createdAt: utc,
+  updatedAt: utc,
+  runtime: runtimeSchema.nullable(),
   objective: text,
   status: _enum(["active", "paused", "closed"]),
   closure: closureSchema.nullable(),
@@ -51130,7 +51162,7 @@ var taskOperations = {
     expectedWorkspaceRevision: revision.optional(),
     outcome: outcomeSchema,
     summary: text,
-    decisionIds: array(id)
+    decisionIds: array(id).optional()
   })
 };
 var policyOperations = {
@@ -51222,14 +51254,15 @@ var writerOperations = {
     ...taskId,
     expectedRevision: revision.optional(),
     expectedWorkspaceRevision: revision.optional(),
-    workerId: nullableId.optional()
+    workerId: nullableId.optional(),
+    reason: text.optional()
   }),
   release: operation({
     action: literal("release"),
     ...taskId,
     expectedRevision: revision.optional(),
     expectedWorkspaceRevision: revision.optional(),
-    reason: text
+    reason: text.optional()
   })
 };
 var stateOperations = {
@@ -57208,6 +57241,33 @@ var metadataLockSchema = object({
   nonce: string2().min(1)
 }).strict();
 var now2 = () => new Date().toISOString().replace(/\.\d{3}Z$/, "Z");
+var cachedRuntimeVersion = null;
+var runtimeVersion = () => {
+  if (cachedRuntimeVersion === null) {
+    try {
+      const pkg = JSON.parse(fs7.readFileSync(path19.join(packageRoot(), "package.json"), "utf8"));
+      cachedRuntimeVersion = typeof pkg.version === "string" && pkg.version ? pkg.version : "0.0.0";
+    } catch {
+      cachedRuntimeVersion = "0.0.0";
+    }
+  }
+  return cachedRuntimeVersion;
+};
+var stampNew = (record) => ({
+  createdWith: record.runtime?.createdWith ?? null,
+  updatedWith: runtimeVersion()
+});
+var isNewerVersion = (candidate, current) => {
+  const parts = (value) => 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;
+};
 var jsonBytes = (value) => `${canonicalJson(value)}
 `;
 var digestBytes2 = (value) => createHash4("sha256").update(value).digest("hex");
@@ -57307,7 +57367,7 @@ class TaskStore {
       if (!current.ok)
         return current;
       if (current.data ? value.expectedWorkspaceRevision !== current.data.revision : value.expectedWorkspaceRevision !== null) {
-        return failure("revision_conflict", "workspace revision does not match", {
+        return failure("revision_conflict", "workspace revision does not match; omit expectedWorkspaceRevision to use the current record", {
           expectedWorkspaceRevision: value.expectedWorkspaceRevision,
           actualWorkspaceRevision: current.data?.revision ?? null
         });
@@ -57319,11 +57379,17 @@ class TaskStore {
       const previousWorkspaceBytes = current.data ? this.snapshotBytes(this.workspacePath) : null;
       if (current.data && !previousWorkspaceBytes)
         return failure("storage_error", "workspace snapshot disappeared during creation");
-      const workspace = current.data ? { ...current.data, revision: newRevision(), root: this.root } : {
+      const workspace = current.data ? {
+        ...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 ?? now2();
@@ -57345,6 +57411,7 @@ class TaskStore {
         status: "active",
         closure: null,
         progress: { summary: "", nextAction: null, blockers: [] },
+        runtime: { createdWith: runtimeVersion(), updatedWith: runtimeVersion() },
         assessments: [],
         policy: null,
         policyChanges: [],
@@ -57375,7 +57442,7 @@ class TaskStore {
       if (!current.ok)
         return current;
       if (current.data ? input.expectedWorkspaceRevision !== current.data.revision : input.expectedWorkspaceRevision !== null)
-        return failure("revision_conflict", "workspace revision does not match", {
+        return failure("revision_conflict", "workspace revision does not match; omit expectedWorkspaceRevision to use the current record", {
           expectedWorkspaceRevision: input.expectedWorkspaceRevision,
           actualWorkspaceRevision: current.data?.revision ?? null
         });
@@ -57383,11 +57450,17 @@ class TaskStore {
       if (current.data && !previousWorkspaceBytes)
         return failure("storage_error", "workspace snapshot disappeared during import");
       const timestamp = input.now ?? now2();
-      const workspace = current.data ? { ...current.data, revision: newRevision(), root: this.root } : {
+      const workspace = current.data ? {
+        ...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 = {
@@ -57395,7 +57468,11 @@ class TaskStore {
         workspaceId: workspace.id,
         revision: newRevision(),
         createdAt: timestamp,
-        updatedAt: timestamp
+        updatedAt: timestamp,
+        runtime: {
+          createdWith: input.task.runtime?.createdWith ?? null,
+          updatedWith: runtimeVersion()
+        }
       };
       const validTask = taskRecordSchema.safeParse(task);
       if (!validTask.success)
@@ -57444,7 +57521,8 @@ class TaskStore {
         workspaceId: current.data.workspaceId,
         createdAt: current.data.createdAt,
         revision: context.revision,
-        updatedAt: context.now
+        updatedAt: context.now,
+        runtime: stampNew(current.data)
       };
       const valid = taskRecordSchema.safeParse(record);
       if (!valid.success)
@@ -57478,7 +57556,8 @@ class TaskStore {
         ...changed.data,
         id: current.data.id,
         root: this.root,
-        revision: context.revision
+        revision: context.revision,
+        runtime: stampNew(current.data)
       };
       const valid = workspaceRecordSchema.safeParse(record);
       if (!valid.success)
@@ -57521,7 +57600,8 @@ class TaskStore {
         ...changedWorkspace.data,
         id: workspace.data.id,
         root: this.root,
-        revision: workspaceContext.revision
+        revision: workspaceContext.revision,
+        runtime: stampNew(workspace.data)
       });
       if (!nextWorkspace.success)
         return failure("invalid_input", "workspace mutation produced an invalid record");
@@ -57546,7 +57626,8 @@ class TaskStore {
         workspaceId: task.data.workspaceId,
         createdAt: task.data.createdAt,
         revision: taskContext.revision,
-        updatedAt: taskContext.now
+        updatedAt: taskContext.now,
+        runtime: stampNew(task.data)
       });
       if (!nextTask.success) {
         this.markUncertain(nextWorkspace.data);
@@ -57766,7 +57847,8 @@ class TaskStore {
     const value = {
       ...workspace,
       writer: { ...workspace.writer, state: "uncertain" },
-      revision: newRevision()
+      revision: newRevision(),
+      runtime: stampNew(workspace)
     };
     this.replaceSnapshot(this.workspacePath, value, workspace);
   }
@@ -57980,7 +58062,12 @@ class TaskStore {
     if (isObject3(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 = isObject3(value) && isObject3(value.runtime) ? value.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");
   }
   processStart(pid) {
     try {
@@ -57990,7 +58077,7 @@ class TaskStore {
     }
   }
   conflict(expected, actual) {
-    return failure("revision_conflict", "snapshot revision does not match", {
+    return failure("revision_conflict", "snapshot revision does not match; omit expectedRevision to use the current record", {
       expectedRevision: expected,
       actualRevision: actual
     });
@@ -58017,6 +58104,61 @@ class TaskStore {
     return path19.join(this.workitDir, ".gitignore");
   }
 }
+// packages/workit-core/src/core/workers.ts
+var same = (left, right) => {
+  try {
+    return canonicalJson(left) === canonicalJson(right);
+  } catch {
+    return false;
+  }
+};
+var UNCERTAIN_WORKER_STATES = ["dispatching", "running", "cancelling", "unknown"];
+var isUncertainWorker = (state) => UNCERTAIN_WORKER_STATES.includes(state);
+var callerSession = (caller) => caller.session ?? { kind: "host", host: caller.host, handle: caller.actor };
+var validPath = (value) => typeof value === "string" && value.length > 0 && ![...value].some((char) => {
+  const code = char.charCodeAt(0);
+  return code < 32 || code === 127;
+}) && !value.split(/[\\/]/).includes("..");
+var callerValue = (value) => ({ host: value.host, actor: value.actor });
+var workerIdOf = (value) => value.workerId ?? null;
+function assertProductWriteAllowed(input) {
+  if (!Array.isArray(input.paths) || input.paths.some((path) => !validPath(path)))
+    return failure("invalid_input", "invalid product write path");
+  if (!input.store)
+    return failure("permission_denied", "write authorization requires core state");
+  const task = input.store.readTask(input.task.id);
+  if (!task.ok)
+    return task;
+  const workspace = input.store.readWorkspace();
+  if (!workspace.ok)
+    return workspace;
+  if (!workspace.data)
+    return failure("not_found", "workspace not found");
+  const workspaceRecord = workspace.data;
+  if (task.data.status !== "active")
+    return failure("invalid_transition", "paused or closed tasks cannot own product writes");
+  if (workspaceRecord.id !== task.data.workspaceId || workspaceRecord.root.length === 0)
+    return failure("recovery_required", "task and workspace bindings are invalid");
+  const writer = workspaceRecord.writer;
+  if (!writer)
+    return failure("permission_denied", "checkout has no writer owner");
+  if (writer.state === "uncertain")
+    return failure("recovery_required", "checkout writer requires recovery", {
+      owner: writer.owner
+    });
+  const caller = callerValue(input.caller);
+  const workerId = workerIdOf(input.caller);
+  const owner = writer.owner;
+  if (owner.taskId !== task.data.id || owner.workerId !== workerId || owner.session.host !== caller.host || owner.session.handle !== caller.actor)
+    return failure("writer_conflict", "checkout is owned by another validated actor", { owner });
+  const worker = workerId === null ? null : task.data.workers.find((entry) => entry.id === workerId);
+  if (workerId !== null && (!worker || worker.data.assignment.role !== "implementer"))
+    return failure("permission_denied", "only implementers can own product writes");
+  if (workerId !== null && (!worker?.data.session || worker.data.state === "cancelling" || worker.data.state === "unknown" || worker.data.state === "stopped" || !same(worker.data.session, callerSession(input.caller))))
+    return failure("recovery_required", "worker session is not an active writer");
+  return success(null, workspaceRecord.revision, owner);
+}
+
 // packages/workit-core/src/core/task-evaluation.ts
 import { createHash as createHash6 } from "node:crypto";
 import * as fs9 from "node:fs";
@@ -58155,7 +58297,11 @@ var verifyDecisionContentAtRoot = (checkoutRoot, binding) => {
       return failure("invalid_input", "document references require a byte digest");
     const target = path20.resolve(root, reference.path);
     if (target !== root && !target.startsWith(`${root}${path20.sep}`))
-      return failure("invalid_input", "document reference escapes checkout");
+      return failure("invalid_input", "document reference escapes checkout; cite it as an external file:// reference instead", {
+        fields: [
+          { path: "contentRefs.path", reason: `${reference.path} is outside the checkout` }
+        ]
+      });
     try {
       const relative = path20.relative(root, target);
       let current = root;
@@ -58166,7 +58312,14 @@ var verifyDecisionContentAtRoot = (checkoutRoot, binding) => {
         const stat = fs8.lstatSync(current);
         const real = fs8.realpathSync(current);
         if (real !== root && !real.startsWith(`${root}${path20.sep}`))
-          return failure("invalid_input", "document reference escapes checkout");
+          return failure("invalid_input", "document reference escapes checkout; cite it as an external file:// reference instead", {
+            fields: [
+              {
+                path: "contentRefs.path",
+                reason: `${reference.path} resolves outside the checkout`
+              }
+            ]
+          });
         if (stat.isSymbolicLink())
           return failure("invalid_input", "document reference uses a symlink");
         if (current === target && !stat.isFile())
@@ -58610,15 +58763,15 @@ var scopeRoots = (root, scope) => {
   for (const item of scope.paths.length ? scope.paths : ["."]) {
     const target = path21.resolve(root, item);
     if (!inside(root, target))
-      return failure("invalid_input", "candidate scope escapes checkout");
+      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 (!fs9.existsSync(ancestor) && ancestor !== root)
       ancestor = path21.dirname(ancestor);
     try {
       if (!inside(root, fs9.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);
   }
@@ -58633,7 +58786,7 @@ function captureCandidate(root, scope, environment = []) {
   }
   const normalizedScope = canonicalScope(scope);
   if (!normalizedScope)
-    return failure("invalid_input", "candidate scope is invalid");
+    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;
@@ -58822,7 +58975,7 @@ function evaluateRequirements(task, workspace, capabilities, candidate, checkout
         return true;
       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));
+      const sameEvidenceSession = task.evidence.some((other) => other.id !== entry.id && other.data.kind === "review" && sameSession(reviewSession, other.provenance.session));
       return entry.data.kind === "review" && reviewSession !== null && sameSession(reviewSession, entry.provenance.session) && (requirement.ruleId === "self-review" || !sameImplementation && !sameEvidenceSession);
     });
     if (passed.length) {
@@ -58918,7 +59071,17 @@ function evaluateClosure(requestedOutcome, view) {
   const blocking = evaluations.filter((item) => item.status === "unsatisfied" || item.status === "unavailable");
   if (requestedOutcome !== "stopped" && blocking.length)
     return failure("requirements_unsatisfied", "applicable requirements are unsatisfied", {
-      requirementIds: blocking.map((item) => item.requirementId)
+      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)
@@ -58945,6 +59108,52 @@ function evaluateClosure(requestedOutcome, view) {
   });
 }
 
+// packages/workit-core/src/core/methods.ts
+var METHODS = {
+  "workit-challenge": { dimensions: ["challenge", "decisions"] },
+  "workit-behavioral-tdd": { dimensions: ["testing"] },
+  "workit-review": { dimensions: ["review"], ruleIds: ["fresh-context-review"] },
+  "workit-plan": { dimensions: ["artifacts", "continuity"] },
+  "workit-implement": { dimensions: ["delegation"] },
+  "workit-debug": { ruleIds: ["root-cause-investigation"] },
+  "workit-handoff": { ruleIds: ["durable-handoff"] },
+  "workit-deslop": { ruleIds: ["pre-pr-cleanup"] }
+};
+var methodMatches = (id, definition, requirement) => definition.dimensions?.includes(requirement.dimension) === true && !(id === "workit-review" && requirement.ruleId === "self-review") || definition.ruleIds?.includes(requirement.ruleId) === true;
+var assuranceFor = (id, definition, capabilities) => {
+  const keys = new Set([
+    id,
+    ...definition.dimensions ?? [],
+    ...definition.ruleIds ?? []
+  ]);
+  const matches = capabilities.filter((capability) => keys.has(capability.name) || keys.has(capability.surface));
+  if (id === "workit-review" && matches.length === 0)
+    return { assurance: "unavailable", reasons: ["independent review capability is unavailable"] };
+  if (matches.some((capability) => capability.assurance === "unavailable"))
+    return {
+      assurance: "unavailable",
+      reasons: matches.filter((capability) => capability.assurance === "unavailable").map((capability) => capability.reason)
+    };
+  if (matches.some((capability) => capability.assurance === "enforced"))
+    return { assurance: "enforced", reasons: matches.map((capability) => capability.reason) };
+  return { assurance: "agent_guided", reasons: matches.map((capability) => capability.reason) };
+};
+function selectMethods(policy, capabilities) {
+  return Object.entries(METHODS).flatMap(([id, definition]) => {
+    const requirements = policy.requirements.filter((requirement) => methodMatches(id, definition, requirement));
+    if (requirements.length === 0)
+      return [];
+    const capability = assuranceFor(id, definition, capabilities);
+    const reasons = [
+      ...new Set(requirements.map((requirement) => requirement.reason)),
+      ...capability.reasons
+    ];
+    if (capability.assurance === "unavailable")
+      reasons.unshift("required capability is unavailable");
+    return [{ id, reason: reasons.join("; "), assurance: capability.assurance }];
+  });
+}
+
 // packages/workit-core/src/core/task-context.ts
 function reconcileResume(view, observations = []) {
   if (observations.length > 0)
@@ -58954,7 +59163,7 @@ function reconcileResume(view, observations = []) {
     return candidate;
   const staleEvidenceIds = evaluateEvidence(view.task, candidate.data).filter((entry) => entry.status === "stale").map((entry) => entry.evidenceId);
   const blockers = [...view.task.progress.blockers];
-  if (view.task.workers.some((entry) => ["running", "cancelling", "unknown"].includes(entry.data.state)))
+  if (view.task.workers.some((entry) => isUncertainWorker(entry.data.state)))
     blockers.push({
       reason: "worker state requires reconciliation",
       dependentAction: "resume",
@@ -59004,6 +59213,11 @@ function compactTaskContext(view) {
     digest: entry.data.digest,
     references: entry.data.binding.contentRefs.slice(0, 1).map(compactReference)
   }));
+  const methods = view.task.policy ? selectMethods(view.task.policy, view.capabilities).map((method) => ({
+    id: method.id,
+    assurance: method.assurance,
+    reason: compactText(method.reason, COMPACT_TEXT_BYTES) ?? ""
+  })) : [];
   const gaps = Array.from(new Set([
     ...view.evidence.filter((entry) => entry.status === "stale").map((entry) => `stale evidence: ${entry.evidenceId}`),
     ...view.requirements.filter((entry) => entry.status !== "satisfied").map((entry) => entry.reason),
@@ -59013,15 +59227,18 @@ function compactTaskContext(view) {
     objective: compactText(view.task.intent.data.objective, COMPACT_TEXT_BYTES) ?? "",
     status: view.task.status,
     decisions,
+    methods,
     gaps,
     nextAction: compactText(view.task.progress.nextAction, COMPACT_TEXT_BYTES)
   };
   let encoded = JSON.stringify(context);
-  while (compactBytes(encoded) > COMPACT_MAX_BYTES && (context.decisions.length || context.gaps.length)) {
+  while (compactBytes(encoded) > COMPACT_MAX_BYTES && (context.decisions.length || context.methods.length || context.gaps.length)) {
     if (context.gaps.length)
       context.gaps.pop();
-    else
+    else if (context.decisions.length)
       context.decisions.pop();
+    else
+      context.methods.pop();
     encoded = JSON.stringify(context);
   }
   if (compactBytes(encoded) > COMPACT_MAX_BYTES) {
@@ -59038,6 +59255,7 @@ var exportDigest = (bundle) => sha256({
   task: bundle.task
 });
 // packages/workit-core/src/core/external-action.ts
+import { execFileSync as execFileSync2 } from "node:child_process";
 var externalActionSchema = discriminatedUnion("operation", [
   object({
     operation: literal("git.branch_setup"),
@@ -59050,7 +59268,11 @@ var externalActionSchema = discriminatedUnion("operation", [
   }).strict(),
   object({
     operation: literal("git.commit"),
-    payload: object({ message: string2().min(1) }).strict()
+    payload: object({
+      message: string2().min(1).optional(),
+      plan_steps: array(string2().min(1)).optional(),
+      plan_branch: string2().min(1).optional()
+    }).strict()
   }).strict(),
   object({
     operation: literal("git.push"),
@@ -59139,7 +59361,7 @@ var externalActionDescriptor = (operation, payload) => canonicalJson({
   payload,
   ...payload && typeof payload === "object" && !Array.isArray(payload) && "resolved" in payload && payload.resolved && typeof payload.resolved === "object" && Array.isArray(payload.resolved.steps) ? { steps: payload.resolved.steps } : {}
 });
-var externalActionHelp = "Fixed actions: git.branch_setup {action?,sdd_dir?,target_branch?,stash?}; git.commit {message}; git.push {branch?}; hosting.pull_request {title,body?,draft?,target_branch?,babysit?}; youtrack.update {issueId,markdown,minutes?}; youtrack.time {issueId,minutes,text?,dateMs?}; youtrack.meeting {issueId,minutes,text}; changelog.apply {entries?,path?,normalize_only?}; context.read {kind,range?,issueId?,issueUrl?,issueRef?,mode?,specPath?,planPath?}. context.read is read-only and needs no approval; all other operations require native approval (CLI uses a TTY; caller-unattested MCP cannot mutate).";
+var externalActionHelp = "Fixed actions: git.branch_setup {action?,sdd_dir?,target_branch(required unless reapply_stash; the working branch to create or switch to),stash?}; git.commit {message}; git.push {branch?}; hosting.pull_request {title,body?,draft?,target_branch?,babysit?}; youtrack.update {issueId,markdown,minutes?}; youtrack.time {issueId,minutes,text?,dateMs?}; youtrack.meeting {issueId,minutes,text}; changelog.apply {entries?,path?,normalize_only?}; context.read {kind,range?,issueId?,issueUrl?,issueRef?,mode?,specPath?,planPath?}. context.read is read-only and needs no approval; all other operations require native approval (CLI uses a TTY; caller-unattested MCP cannot mutate).";
 var externalActionRef = (host, actor, descriptor) => ({
   kind: "host",
   host,
@@ -59190,6 +59412,92 @@ var priorExternalAction = (store, host, actor, operation, payload) => {
     return failure("permission_denied", candidates.length === 0 ? "no prior external action matches this request" : "multiple prior external actions match this request");
   return success(workspace.data.revision, null, { ...candidates[0], workspace: workspace.data });
 };
+var planCommitDescriptor = (content) => {
+  try {
+    const value = JSON.parse(content);
+    if (value.operation !== "git.commit" || !value.payload)
+      return null;
+    const steps = value.payload.plan_steps;
+    const branch = value.payload.plan_branch;
+    if (!Array.isArray(steps) || steps.some((step) => typeof step !== "string" || !step) || typeof branch !== "string" || !branch)
+      return null;
+    return { steps, branch };
+  } catch {
+    return null;
+  }
+};
+var approvedPlanCommit = (store, host, actor, message) => {
+  if (typeof message !== "string" || !message)
+    return failure("invalid_input", "commit message is required");
+  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 matches = listed.data.flatMap((task) => {
+    if (task.status !== "active" || task.workspaceId !== workspace.data.id)
+      return [];
+    if (task.intent.provenance.session?.kind !== "host" || task.intent.provenance.session.host !== host || task.intent.provenance.session.handle !== actor)
+      return [];
+    return task.decisions.flatMap((entry) => {
+      const decision = entry.data;
+      if (decision.purpose !== "action" || decision.response !== "approved" || decision.revoked !== null)
+        return [];
+      if (entry.provenance.kind !== "host_observed" || entry.provenance.receipts.length === 0)
+        return [];
+      const plan = planCommitDescriptor(decision.binding.approvedContent);
+      if (!plan)
+        return [];
+      const completed = task.actionProgress?.find((progress) => progress.decisionId === entry.id)?.completedSteps ?? [];
+      if (plan.steps[completed.length] !== message)
+        return [];
+      return [{ task, entry, steps: plan.steps, branch: plan.branch, completed: [...completed] }];
+    });
+  });
+  if (matches.length !== 1)
+    return failure("permission_denied", matches.length === 0 ? "no plan commit authorization matches this message" : "multiple plan authorizations match this message");
+  return success(workspace.data.revision, null, matches[0]);
+};
+var commitMessageFromDescriptor = (operation) => {
+  try {
+    const descriptor = JSON.parse(operation);
+    return descriptor.operation === "git.commit" && typeof descriptor.payload?.message === "string" ? descriptor.payload.message : undefined;
+  } catch {
+    return;
+  }
+};
+var planCommitBinding = (store, host, actor, operation) => {
+  const message = commitMessageFromDescriptor(operation);
+  if (!message)
+    return null;
+  const plan = approvedPlanCommit(store, host, actor, message);
+  if (!plan.ok)
+    return null;
+  let branch;
+  try {
+    branch = execFileSync2("git", ["branch", "--show-current"], {
+      cwd: store.root,
+      encoding: "utf8",
+      stdio: ["pipe", "pipe", "pipe"]
+    }).trim();
+  } catch {
+    return null;
+  }
+  if (!branch || branch !== plan.data.branch)
+    return null;
+  const workspace = store.readWorkspace();
+  if (!workspace.ok || !workspace.data)
+    return null;
+  return {
+    taskId: plan.data.task.id,
+    decisionId: plan.data.entry.id,
+    binding: plan.data.entry.data.binding,
+    expectedRevision: plan.data.task.revision,
+    expectedWorkspaceRevision: workspace.data.revision,
+    step: message
+  };
+};
 var approvedExternalAction = (store, host, actor, operation) => {
   const selected = externalActionState(store, host, actor, operation);
   if (!selected.ok)
@@ -59198,6 +59506,23 @@ var approvedExternalAction = (store, host, actor, operation) => {
     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;
 };
+var priorResolvedDrift = (store, host, actor, operation, payload, currentResolved) => {
+  const prior = priorExternalAction(store, host, actor, operation, payload);
+  if (!prior.ok)
+    return success(null, null, null);
+  let baseline;
+  try {
+    const parsed = JSON.parse(prior.data.entry.data.binding.approvedContent);
+    baseline = parsed.payload?.resolved;
+  } catch {
+    return success(null, null, null);
+  }
+  if (baseline === undefined || baseline === null)
+    return success(null, null, null);
+  if (canonicalJson(baseline) === canonicalJson(currentResolved))
+    return success(null, null, null);
+  return failure("invalid_input", "repository state changed since approval; show the current state and approve the action again", { outcome: "not_started", operation });
+};
 var createAuthorizedExternalActionRunner = (core, bind) => async (operation, effect) => {
   let steps = [];
   try {
@@ -59456,7 +59781,7 @@ function resolveRequirements(input) {
       ].join(", ")}`,
       satisfaction: "An observed or inferred fact resolves the uncertainty and records its supporting references.",
       before: "dependent_action",
-      dependentAction: "dependent-action",
+      dependentAction: null,
       acceptanceAllowed: false
     }));
   if (signals.productChoiceOpen.value === true)
@@ -59467,7 +59792,7 @@ function resolveRequirements(input) {
       reason: `A consequential product choice remains open: ${signalReason(input, "productChoiceOpen")}`,
       satisfaction: "Present the material alternatives and record the user's decision before the dependent action.",
       before: "dependent_action",
-      dependentAction: "dependent-action",
+      dependentAction: null,
       acceptanceAllowed: false
     }));
   if (signals.behaviorChange.value === true)
@@ -59625,59 +59950,6 @@ function diffPolicy(previous, next, reason, now) {
   return parsed.data;
 }
 
-// packages/workit-core/src/core/workers.ts
-var same = (left, right) => {
-  try {
-    return canonicalJson(left) === canonicalJson(right);
-  } catch {
-    return false;
-  }
-};
-var callerSession = (caller) => caller.session ?? { kind: "host", host: caller.host, handle: caller.actor };
-var validPath = (value) => typeof value === "string" && value.length > 0 && ![...value].some((char) => {
-  const code = char.charCodeAt(0);
-  return code < 32 || code === 127;
-}) && !value.split(/[\\/]/).includes("..");
-var callerValue = (value) => ({ host: value.host, actor: value.actor });
-var workerIdOf = (value) => value.workerId ?? null;
-function assertProductWriteAllowed(input) {
-  if (!Array.isArray(input.paths) || input.paths.some((path) => !validPath(path)))
-    return failure("invalid_input", "invalid product write path");
-  if (!input.store)
-    return failure("permission_denied", "write authorization requires core state");
-  const task = input.store.readTask(input.task.id);
-  if (!task.ok)
-    return task;
-  const workspace = input.store.readWorkspace();
-  if (!workspace.ok)
-    return workspace;
-  if (!workspace.data)
-    return failure("not_found", "workspace not found");
-  const workspaceRecord = workspace.data;
-  if (task.data.status !== "active")
-    return failure("invalid_transition", "paused or closed tasks cannot own product writes");
-  if (workspaceRecord.id !== task.data.workspaceId || workspaceRecord.root.length === 0)
-    return failure("recovery_required", "task and workspace bindings are invalid");
-  const writer = workspaceRecord.writer;
-  if (!writer)
-    return failure("permission_denied", "checkout has no writer owner");
-  if (writer.state === "uncertain")
-    return failure("recovery_required", "checkout writer requires recovery", {
-      owner: writer.owner
-    });
-  const caller = callerValue(input.caller);
-  const workerId = workerIdOf(input.caller);
-  const owner = writer.owner;
-  if (owner.taskId !== task.data.id || owner.workerId !== workerId || owner.session.host !== caller.host || owner.session.handle !== caller.actor)
-    return failure("writer_conflict", "checkout is owned by another validated actor", { owner });
-  const worker = workerId === null ? null : task.data.workers.find((entry) => entry.id === workerId);
-  if (workerId !== null && (!worker || worker.data.assignment.role !== "implementer"))
-    return failure("permission_denied", "only implementers can own product writes");
-  if (workerId !== null && (!worker?.data.session || worker.data.state === "cancelling" || worker.data.state === "unknown" || worker.data.state === "stopped" || !same(worker.data.session, callerSession(input.caller))))
-    return failure("recovery_required", "worker session is not an active writer");
-  return success(null, workspaceRecord.revision, owner);
-}
-
 // packages/workit-core/src/core/task-engine.ts
 var provenance = (context, kind = context.provenanceKind ?? "host_observed") => ({
   kind,
@@ -59796,10 +60068,10 @@ var applyWorkerLifecycle = (input) => {
   const notStarted = input.dispatch === true;
   if (notStarted && (input.state !== "stopped" || input.session !== null))
     return failure("invalid_input", "a never-dispatched worker stops with no session");
-  if (notStarted && (entry.data.state === "stopped" || entry.data.state === "unknown"))
-    return failure("invalid_transition", "worker is no longer awaiting dispatch");
-  if (notStarted && (entry.data.session !== null || entry.data.state === "running"))
+  if (notStarted && entry.data.session !== null)
     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.state === "running" || input.state === "cancelling" || input.state === "stopped" && !notStarted) && !input.session)
     return failure("invalid_input", "running worker observations require a session");
   if (entry.data.session && !sameValue(entry.data.session, input.session))
@@ -59808,15 +60080,20 @@ var applyWorkerLifecycle = (input) => {
     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" : input.state,
+      session: input.session
+    }
   };
   const shouldClear = input.state === "stopped" && workspace.data.writer !== null && workspace.data.writer.owner.taskId === task.data.id && workspace.data.writer.owner.workerId === input.workerId;
   const shouldUncertain = input.state === "unknown" && workspace.data.writer !== null && workspace.data.writer.owner.taskId === task.data.id && workspace.data.writer.owner.workerId === input.workerId;
-  if (entry.data.state === input.state && sameValue(entry.data.session, input.session) && !shouldClear && !shouldUncertain)
+  if (entry.data.state === nextEntry.data.state && sameValue(entry.data.session, input.session) && !shouldClear && !shouldUncertain)
     return success(task.data.revision, workspace.data.revision, entry);
   const changed = input.store.mutateTaskAndWorkspace({
     taskId: task.data.id,
@@ -60186,7 +60463,7 @@ class WorkitCore {
   activeWorkerBlocker(task, workspace) {
     if (workspace.writer)
       return failure("recovery_required", "writer ownership must be released first");
-    if (task.workers.some((entry) => ["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;
   }
@@ -60423,11 +60700,6 @@ class WorkitCore {
     if (helper && !helper.ok)
       return helper;
     const evidence = input.evidence;
-    if (helper?.ok) {
-      const assignment = helper.data.data.assignment;
-      if (evidence.requirementIds.some((id) => !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())
       return failure("invalid_input", "missing or skipped evidence requires a reason");
     if (evidence.kind === "review") {
@@ -60444,6 +60716,11 @@ class WorkitCore {
       evidence.beforeCandidateId ??= null;
       evidence.candidateId ??= null;
     }
+    if (helper?.ok) {
+      const assignment = helper.data.data.assignment;
+      if (evidence.requirementIds.some((id) => !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 (candidateId && candidateId !== currentCandidate.data.id && !knownCandidates.has(candidateId))
@@ -60950,7 +61227,12 @@ class WorkitCore {
           return failure("invalid_transition", "worker is not awaiting dispatch");
         return success(mutation.revision, null, {
           ...current,
-          workers: current.workers.map((item) => item.id === input.workerId ? { ...item, recordedAt: mutation.now, provenance: attested.data } : item)
+          workers: current.workers.map((item) => item.id === input.workerId ? {
+            ...item,
+            recordedAt: mutation.now,
+            provenance: attested.data,
+            data: { ...item.data, state: "dispatching" }
+          } : item)
         });
       }
     });
@@ -61334,6 +61616,9 @@ 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,
@@ -61419,7 +61704,7 @@ class WorkitCore {
     const base = reconcileResume(effectiveView);
     if (!base.ok)
       return base;
-    const needsReconciliation = view.task.workers.some((entry) => ["running", "cancelling", "unknown"].includes(observedStates.get(entry.id) ?? entry.data.state));
+    const needsReconciliation = view.task.workers.some((entry) => isUncertainWorker(observedStates.get(entry.id) ?? entry.data.state));
     const blockers = [...base.data.blockers];
     if (needsReconciliation && !blockers.some((entry) => entry.reason === "worker state requires reconciliation"))
       blockers.push({
@@ -61486,7 +61771,8 @@ class WorkitCore {
         ...current,
         status,
         candidates: resumeCandidate && !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)
@@ -61522,7 +61808,7 @@ class WorkitCore {
       return workspace;
     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");
     this.fillRevisions(input, task.data, workspace.data);
     const changed = this.store.mutateTaskAndWorkspace({
@@ -61670,14 +61956,14 @@ function run(root, executable, args, env = {}) {
 
 // packages/workit-core/src/core/branch.ts
 import { existsSync as existsSync17, mkdirSync as mkdirSync8, readFileSync as readFileSync15, writeFileSync as writeFileSync10 } from "node:fs";
-import { execFileSync as execFileSync3 } from "node:child_process";
+import { execFileSync as execFileSync4 } from "node:child_process";
 import path24 from "node:path";
 
 // packages/workit-core/src/core/git.ts
-import { execFileSync as execFileSync2 } from "node:child_process";
+import { execFileSync as execFileSync3 } from "node:child_process";
 var run2 = (cwd, args) => {
   try {
-    const stdout = execFileSync2("git", args, {
+    const stdout = execFileSync3("git", args, {
       cwd,
       encoding: "utf8",
       stdio: ["pipe", "pipe", "pipe"]
@@ -61940,7 +62226,7 @@ var baseBranch = (cwd) => {
   return { base: String(resolved.defaultTargetBranch ?? "develop") };
 };
 var originBaseReady = (cwd, base) => {
-  const run = (args) => execFileSync3("git", args, { cwd, encoding: "utf8", stdio: ["pipe", "pipe", "pipe"] });
+  const run = (args) => execFileSync4("git", args, { cwd, encoding: "utf8", stdio: ["pipe", "pipe", "pipe"] });
   try {
     try {
       run(["fetch", "origin", base, "--prune"]);
@@ -61948,7 +62234,7 @@ var originBaseReady = (cwd, base) => {
       run(["fetch", "origin", "--prune"]);
     }
     try {
-      execFileSync3("git", ["show-ref", "--verify", "--quiet", `refs/remotes/origin/${base}`], {
+      execFileSync4("git", ["show-ref", "--verify", "--quiet", `refs/remotes/origin/${base}`], {
         cwd,
         stdio: "pipe"
       });
@@ -61967,11 +62253,11 @@ var originBaseReady = (cwd, base) => {
   }
 };
 var fastForwardBase = (cwd, base) => {
-  const run = (args) => execFileSync3("git", args, { cwd, encoding: "utf8", stdio: ["pipe", "pipe", "pipe"] });
+  const run = (args) => execFileSync4("git", args, { cwd, encoding: "utf8", stdio: ["pipe", "pipe", "pipe"] });
   try {
     let hasLocalBase = true;
     try {
-      execFileSync3("git", ["show-ref", "--verify", "--quiet", `refs/heads/${base}`], {
+      execFileSync4("git", ["show-ref", "--verify", "--quiet", `refs/heads/${base}`], {
         cwd,
         stdio: "pipe"
       });
@@ -62012,10 +62298,10 @@ var branchSetup = ({
   log
 }) => {
   const cwd = path24.resolve(workspace_root);
-  const exec = (args) => execFileSync3("git", args, { cwd, encoding: "utf8", stdio: ["pipe", "pipe", "pipe"] });
+  const exec = (args) => execFileSync4("git", args, { cwd, encoding: "utf8", stdio: ["pipe", "pipe", "pipe"] });
   const current = gitContext(cwd).branch;
   if (!current || current === "unknown")
-    return { error: "not in a git repository" };
+    return { error: "not in a git repository", phase: "preflight" };
   const sdd = sdd_dir ?? "docs";
   const manifestPath = path24.isAbsolute(sdd) ? path24.join(sdd, "manifest.json") : path24.join(cwd, sdd, "manifest.json");
   const ensureManifestDir = () => {
@@ -62023,7 +62309,6 @@ var branchSetup = ({
     if (!existsSync17(dir))
       mkdirSync8(dir, { recursive: true, mode: 493 });
   };
-  ensureManifestDir();
   const readManifest = () => {
     try {
       return JSON.parse(readFileSync15(manifestPath, "utf8"));
@@ -62041,13 +62326,16 @@ var branchSetup = ({
     const manifest = readManifest();
     const ref = manifest.stash_ref;
     if (!ref)
-      return { error: "no stash_ref in manifest" };
+      return { error: "no stash_ref in manifest", phase: "preflight" };
     journal(`pre-pop: ${String(ref)}`);
     try {
       exec(["stash", "pop", String(ref)]);
     } catch (error) {
       journal("pop: failed");
-      return { error: error instanceof Error ? error.message : "stash pop failed" };
+      return {
+        error: error instanceof Error ? error.message : "stash pop failed",
+        phase: "post_mutation"
+      };
     }
     journal("pop: ok");
     delete manifest.stash_ref;
@@ -62057,11 +62345,17 @@ var branchSetup = ({
   }
   const target = target_branch ?? "";
   if (!target)
-    return { error: "target branch required" };
+    return {
+      error: "target_branch (the working branch to create or switch to) is required for setup",
+      phase: "preflight"
+    };
   if (isProtected(cwd, target))
-    return { error: `protected branch ${target}` };
+    return { error: `protected branch ${target}`, phase: "preflight" };
   if (!allowedBranch(cwd, target))
-    return { error: `target branch ${target} is not allowed by the branch policy` };
+    return {
+      error: `target branch ${target} is not allowed by the branch policy`,
+      phase: "preflight"
+    };
   let base;
   let targetExists = true;
   try {
@@ -62072,12 +62366,12 @@ var branchSetup = ({
   if (!targetExists) {
     const baseResolved = baseBranch(cwd);
     if ("error" in baseResolved)
-      return { error: baseResolved.error };
+      return { error: baseResolved.error, phase: "preflight" };
     base = baseResolved.base;
   }
   journal(`entry: current=${current} target=${target} base=${base ?? "-"}`);
   let stash_ref;
-  const failAfterStash = (message) => {
+  const failAfterStash = (message, phase = "post_mutation") => {
     let suffix = "";
     if (stash_ref) {
       journal(`pre-pop: ${stash_ref}`);
@@ -62090,27 +62384,31 @@ var branchSetup = ({
         suffix = " (changes preserved in stash)";
       }
     }
-    return { error: `${message}${suffix}` };
+    return { error: `${message}${suffix}`, phase: stash_ref ? "post_mutation" : phase };
   };
   if (current !== target) {
     const dirty = Boolean(gitContext(cwd).status_short.trim());
     if (dirty && stash !== "yes") {
       return {
-        error: "dirty working tree — ask with native question, then call workit_branch_setup with stash=yes"
+        error: "dirty working tree — ask with native question, then call workit_branch_setup with stash=yes",
+        phase: "preflight"
       };
     }
     let validatedBase;
     if (!targetExists && base !== undefined) {
       const ready = originBaseReady(cwd, base);
       if (!ready.ok)
-        return { error: ready.error ?? "ensure-base-branch failed" };
+        return { error: ready.error ?? "ensure-base-branch failed", phase: "preflight" };
       validatedBase = base;
     }
     if (dirty) {
       try {
         exec(["stash", "push", "-u", "-m", `workit: pre-checkout ${target}`]);
       } catch (error) {
-        return { error: error instanceof Error ? error.message : "stash push failed" };
+        return {
+          error: error instanceof Error ? error.message : "stash push failed",
+          phase: "post_mutation"
+        };
       }
       stash_ref = "stash@{0}";
       journal(`stash push: ${stash_ref}`);
@@ -62121,14 +62419,14 @@ var branchSetup = ({
     } catch (error) {
       const message = error instanceof Error ? error.message : "checkout failed";
       if (/worktree/i.test(message)) {
-        return failAfterStash(`branch ${target} is locked by an existing git worktree — remove it first (we do not use worktrees)`);
+        return failAfterStash(`branch ${target} is locked by an existing git worktree — remove it first (we do not use worktrees)`, "preflight");
       }
       try {
         let effectiveBase = base;
         if (effectiveBase === undefined) {
           const lateResolved = baseBranch(cwd);
           if ("error" in lateResolved)
-            return failAfterStash(lateResolved.error);
+            return failAfterStash(lateResolved.error, "preflight");
           effectiveBase = lateResolved.base;
         }
         const baseResult = validatedBase !== undefined ? fastForwardBase(cwd, effectiveBase) : ensureBaseBranch(cwd, effectiveBase);
@@ -63957,6 +64255,94 @@ var safePath = (root, value) => {
     return null;
   }
 };
+var branchCreationBaseline = (root, target, base) => {
+  const exists = gitValue(root, ["rev-parse", "--verify", "--quiet", `refs/heads/${target}`]) !== null;
+  if (exists)
+    return { base_branch: base, target_exists: true, remote_base: null };
+  const remote = run3(root, ["ls-remote", "origin", `refs/heads/${base}`]);
+  const sha = remote.exitCode === 0 ? remote.stdout.trim().split(/\s+/)[0] : "";
+  return {
+    base_branch: base,
+    target_exists: false,
+    remote_base: /^[0-9a-f]{40}$/.test(sha ?? "") ? sha : null
+  };
+};
+var shortSha = (value) => typeof value === "string" && value ? value.slice(0, 8) : "unknown";
+var isProtectedBranch2 = (root, branch) => resolveBranchPolicyFor(root).protected.has(branch.toLowerCase());
+var actionProposalQuestion = (request, descriptorPayload) => {
+  const payload = descriptorPayload ?? {};
+  const resolved = payload.resolved ?? {};
+  const payloadTarget = String(payload.target_branch ?? "");
+  if (request.operation === "git.commit" && Array.isArray(payload.plan_steps)) {
+    const steps = payload.plan_steps;
+    return {
+      presented: `Workit decision: action — Approve committing the plan's ${steps.length} listed tasks on \`${String(payload.plan_branch ?? "")}\`?`,
+      approvedText: `Approve the ${steps.length} listed plan commits.`
+    };
+  }
+  switch (request.operation) {
+    case "git.branch_setup": {
+      if (request.payload.action === "reapply_stash")
+        return {
+          presented: "Workit decision: action — Reapply the pre-checkout stash recorded in the branch manifest?",
+          approvedText: "Reapply the recorded stash."
+        };
+      const target = String(payload.target_branch ?? "");
+      if (resolved.target_exists === true)
+        return {
+          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)}.`
+      };
+    }
+    case "git.commit": {
+      const paths = Array.isArray(resolved.paths) ? resolved.paths : [];
+      return {
+        presented: `Workit decision: action — Commit ${paths.length} staged file(s) as "${String(request.payload.message)}"?`,
+        approvedText: `Commit as "${String(request.payload.message)}".`
+      };
+    }
+    case "git.push":
+      return {
+        presented: `Workit decision: action — Push branch \`${String(payload.branch ?? "")}\` to origin?`,
+        approvedText: `Push \`${String(payload.branch ?? "")}\` to origin.`
+      };
+    case "hosting.pull_request":
+      return {
+        presented: `Workit decision: action — Open a PR from \`${String(resolved.source_branch ?? "")}\` to \`${payloadTarget}\` titled "${String(request.payload.title)}"?`,
+        approvedText: `Open the PR: ${String(resolved.source_branch ?? "")} → ${payloadTarget}, "${String(request.payload.title)}".`
+      };
+    case "changelog.apply":
+      return {
+        presented: `Workit decision: action — Apply changelog changes at \`${String(payload.path ?? "CHANGELOG.md")}\`?`,
+        approvedText: `Apply changelog changes at ${String(payload.path ?? "CHANGELOG.md")}.`
+      };
+    case "youtrack.update":
+      return {
+        presented: `Workit decision: action — Update YouTrack issue ${String(request.payload.issueId)}${request.payload.minutes ? ` and log ${String(request.payload.minutes)}m` : ""}?`,
+        approvedText: `Update YouTrack issue ${String(request.payload.issueId)}.`
+      };
+    case "youtrack.time":
+      return {
+        presented: `Workit decision: action — Log ${String(request.payload.minutes)}m to YouTrack issue ${String(request.payload.issueId)}?`,
+        approvedText: `Log time to YouTrack issue ${String(request.payload.issueId)}.`
+      };
+    case "youtrack.meeting":
+      return {
+        presented: `Workit decision: action — Log meeting time to YouTrack issue ${String(request.payload.issueId)}?`,
+        approvedText: `Log meeting time to YouTrack issue ${String(request.payload.issueId)}.`
+      };
+    default:
+      return {
+        presented: `Workit decision: action — Approve ${request.operation}?`,
+        approvedText: `Approve ${request.operation}.`
+      };
+  }
+};
 var approvedResolvedExternalAction = (content) => {
   try {
     const value = JSON.parse(content);
@@ -64220,24 +64606,35 @@ var resolveExternalActionRequest = (root, request, preservedDateMs) => {
         const sdd_dir = safePath(root, request.payload.sdd_dir ?? "docs");
         if (!sdd_dir)
           return failure("invalid_input", "sdd_dir must stay inside the workspace");
+        const action = request.payload.action ?? "setup";
         const policy = resolveBranchPolicyFor(root);
-        const target_branch = request.payload.target_branch ?? policy.defaultTargetBranch;
+        const target_branch = request.payload.target_branch;
+        if (action !== "reapply_stash" && !target_branch)
+          return failure("invalid_input", "target_branch (the working branch to create or switch to) is required for setup", {
+            outcome: "not_started",
+            fields: [{ path: "target_branch", reason: "required for action=setup" }]
+          });
         const head = gitValue(root, ["rev-parse", "HEAD"]);
         if (!head)
           return failure("storage_error", "current Git commit could not be resolved");
+        const dirty = Boolean((gitRaw(root, ["status", "--short"]) ?? "").trim());
+        const creation = action === "reapply_stash" || !target_branch ? { base_branch: policy.defaultTargetBranch } : branchCreationBaseline(root, target_branch, policy.defaultTargetBranch);
         const normalized = {
           operation: request.operation,
           payload: {
             ...request.payload,
-            action: request.payload.action ?? "setup",
+            action,
             sdd_dir,
             stash: request.payload.stash ?? "no",
-            target_branch
+            ...target_branch ? { target_branch } : {}
           }
         };
         return success(null, null, {
           request: normalized,
-          descriptorPayload: { ...normalized.payload, resolved: { head, target_branch } }
+          descriptorPayload: {
+            ...normalized.payload,
+            resolved: { head, dirty, ...creation }
+          }
         });
       }
       case "git.push": {
@@ -64251,7 +64648,37 @@ var resolveExternalActionRequest = (root, request, preservedDateMs) => {
         }) : failure("invalid_input", "git push requires a resolvable current branch");
       }
       case "git.commit": {
+        const planSteps = request.payload.plan_steps;
+        const planBranch = request.payload.plan_branch;
         const head = gitValue(root, ["rev-parse", "HEAD"]);
+        if (!head)
+          return failure("storage_error", "Git state could not be resolved");
+        const branch = gitValue(root, ["branch", "--show-current"]);
+        if (planSteps !== undefined || planBranch !== undefined) {
+          if (!Array.isArray(planSteps) || planSteps.some((step) => typeof step !== "string" || !step.trim()) || new Set(planSteps).size !== planSteps.length || planSteps.length === 0 || planSteps.length > 32)
+            return failure("invalid_input", "plan_steps must be 1-32 unique non-empty commit messages", {
+              outcome: "not_started",
+              fields: [{ path: "plan_steps", reason: "unique strings" }]
+            });
+          if (typeof planBranch !== "string" || !planBranch.trim() || planBranch !== branch)
+            return failure("invalid_input", "plan_branch must name the current working branch", {
+              outcome: "not_started",
+              fields: [{ path: "plan_branch", reason: "current branch" }]
+            });
+          if (isProtectedBranch2(root, planBranch))
+            return failure("invalid_input", "plan_branch must not be a protected branch", {
+              outcome: "not_started",
+              fields: [{ path: "plan_branch", reason: "protected branch" }]
+            });
+          return success(null, null, {
+            request,
+            descriptorPayload: {
+              plan_steps: planSteps,
+              plan_branch: planBranch,
+              resolved: { head, branch, steps: planSteps }
+            }
+          });
+        }
         const staged = gitRaw(root, [
           "diff",
           "--cached",
@@ -64262,7 +64689,13 @@ var resolveExternalActionRequest = (root, request, preservedDateMs) => {
           "HEAD"
         ]);
         const paths = stagedPaths(root);
-        if (!head || staged === null || paths === null)
+        const message = request.payload.message;
+        if (typeof message !== "string" || !message)
+          return failure("invalid_input", "git.commit requires a commit message", {
+            outcome: "not_started",
+            fields: [{ path: "message", reason: "required unless plan_steps is provided" }]
+          });
+        if (staged === null || paths === null)
           return failure("storage_error", "Git state could not be resolved");
         let policy;
         try {
@@ -64277,13 +64710,13 @@ var resolveExternalActionRequest = (root, request, preservedDateMs) => {
 `).filter(Boolean));
           flavor = detected.flavor ?? "conventional";
         }
-        if (!matchCommitFlavor(request.payload.message, flavor, policy.pattern))
+        if (!matchCommitFlavor(message, flavor, policy.pattern))
           return failure("invalid_input", `Commit message does not match the ${flavor} flavor (commitPolicy.preset)`);
         return success(null, null, {
           request,
           descriptorPayload: {
             ...request.payload,
-            resolved: { head, staged: sha256(staged), paths }
+            resolved: { head, branch, staged: sha256(staged), paths }
           }
         });
       }
@@ -64453,10 +64886,24 @@ var executeConcreteExternalAction = async (request, root, marker, dateMs, step,
         sdd_dir: request.payload.sdd_dir ?? "docs",
         workspace_root: root
       });
-      return result.error ? unknown2(request.operation) : success(null, null, result);
+      if ("error" in result) {
+        if (result.phase === "preflight")
+          return failure("invalid_input", result.error, {
+            outcome: "not_started",
+            operation: request.operation
+          });
+        return unknown2(request.operation);
+      }
+      return success(null, null, result);
     }
     case "git.commit": {
-      const result = run3(root, ["commit", "-m", request.payload.message]);
+      const message = request.payload.message;
+      if (typeof message !== "string" || !message)
+        return failure("invalid_input", "git.commit requires a commit message", {
+          outcome: "not_started",
+          fields: [{ path: "message", reason: "required" }]
+        });
+      const result = run3(root, ["commit", "-m", message]);
       return result.exitCode === 0 ? success(null, null, { stdout: result.stdout.trim() }) : unknown2(request.operation);
     }
     case "git.push": {
@@ -64862,7 +65309,29 @@ async function runTaskCommand(argv, deps = {}) {
   }
   const core = new WorkitCore(new TaskStore(root), contextFor(root, parsed.parsed.actor !== undefined ? { ...deps, actor: parsed.parsed.actor } : deps, observedConfirmation ? "host_observed" : "agent_reported"));
   let result;
-  if (parsed.parsed.handoff) {
+  const decisionBudgetIssue = (() => {
+    if (parsed.parsed.family !== "decision" || parsed.parsed.action !== "record")
+      return null;
+    const request = parsed.parsed.request;
+    if (typeof request.purpose !== "string" || !request.binding)
+      return null;
+    return workitBindingQuestionIssue([
+      {
+        header: `Workit decision: ${request.purpose}`,
+        question: typeof request.binding.presented === "string" ? request.binding.presented : "",
+        options: [
+          {
+            label: "approved",
+            description: typeof request.binding.displayed === "string" ? request.binding.displayed : typeof request.binding.approvedContent === "string" ? request.binding.approvedContent : ""
+          },
+          { label: "rejected", description: "Reject this decision" }
+        ]
+      }
+    ]);
+  })();
+  if (decisionBudgetIssue)
+    result = failure("invalid_input", decisionBudgetIssue);
+  else if (parsed.parsed.handoff) {
     const exported = dispatch(core, "state", parsed.parsed.request);
     if (!exported.ok)
       result = exported;
@@ -64926,8 +65395,34 @@ var cliActionAuthority = (actor, reconciliationTokens = new WeakSet) => ({
 var nativeExternalActionRunner = (root, actor, core, step) => createAuthorizedExternalActionRunner(core, (operationValue) => {
   const store = new TaskStore(root);
   const approved = approvedExternalAction(store, "workit_cli", actor, operationValue);
-  if (!approved.ok)
+  if (!approved.ok) {
+    const plan = planCommitBinding(store, "workit_cli", actor, operationValue);
+    if (plan) {
+      const actionRef = externalActionRef("workit_cli", actor, operationValue);
+      return {
+        taskId: plan.taskId,
+        decisionId: plan.decisionId,
+        actionRef,
+        expectedRevision: plan.expectedRevision,
+        expectedWorkspaceRevision: plan.expectedWorkspaceRevision,
+        binding: plan.binding,
+        step: plan.step,
+        refresh: () => {
+          const task = store.readTask(plan.taskId);
+          const freshWorkspace = store.readWorkspace();
+          if (!task.ok || !freshWorkspace.ok || !freshWorkspace.data)
+            throw new Error("external action state changed");
+          return {
+            expectedRevision: task.data.revision,
+            expectedWorkspaceRevision: freshWorkspace.data.revision
+          };
+        },
+        reserveObservation: nativeExternalActionObservation(actor, actionRef, "reserve"),
+        settleObservation: (outcome, revisions) => nativeExternalActionObservation(actor, actionRef, outcome, actionRef.kind === "host" ? actionRef.handle : "external-action", revisions)
+      };
+    }
     return approved;
+  }
   const actionRef = externalActionRef("workit_cli", actor, operationValue);
   return {
     taskId: approved.data.task.id,
@@ -65124,8 +65619,56 @@ async function runActionCommand(argv, deps = {}) {
       printHuman(result, deps);
     return 1;
   }
+  const drift = normalized.operation === "git.branch_setup" ? priorResolvedDrift(store, "workit_cli", actor, normalized.operation, normalized.payload, resolved.data.descriptorPayload.resolved) : success(null, null, null);
+  if (!drift.ok) {
+    if (json)
+      jsonResult(outOf(deps), drift);
+    else
+      printHuman(drift, deps);
+    return 1;
+  }
+  const localOperation = [
+    "git.branch_setup",
+    "git.commit",
+    "git.push",
+    "hosting.pull_request",
+    "changelog.apply"
+  ].includes(normalized.operation);
+  if (localOperation) {
+    const writer = assertLocalExternalActionWriter(root, { host: "workit_cli", actor });
+    if (!writer.ok) {
+      const result = failure("needs_input", "writer ownership is required before this action", {
+        outcome: "not_started",
+        operation: normalized.operation,
+        guidance: "Acquire checkout writer ownership first (writer.acquire) and retry the action."
+      });
+      if (json)
+        jsonResult(outOf(deps), result);
+      else
+        printHuman(result, deps);
+      return 1;
+    }
+  }
+  const question = actionProposalQuestion(normalized, resolved.data.descriptorPayload);
+  const commitMessage = normalized.operation === "git.commit" ? normalized.payload.message : undefined;
+  const currentBranch = resolved.data.descriptorPayload.resolved?.branch;
+  const plan = typeof commitMessage === "string" && commitMessage ? approvedPlanCommit(store, "workit_cli", actor, commitMessage) : null;
+  if (plan?.ok && plan.data.branch === currentBranch) {
+    const core = new WorkitCore(store, {
+      ...contextFor(root, { ...deps, actor }, "host_observed"),
+      nativeAuthority: cliActionAuthority(actor),
+      workerId: null
+    });
+    const runner = nativeExternalActionRunner(root, actor, core);
+    const result = await runner(descriptor, (step) => executeResolvedExternalAction(resolved.data, root, step, { host: "workit_cli", actor }));
+    if (json)
+      jsonResult(outOf(deps), result);
+    else
+      printHuman(result, deps);
+    return result.ok ? 0 : 1;
+  }
   if (!json)
-    write2(outOf(deps), `External action preview: ${descriptor}`);
+    write2(outOf(deps), question.presented);
   const accepted = await observeConsent(deps);
   if (!accepted.accepted || !accepted.observed) {
     const result = failure("permission_denied", "external action was not confirmed by the terminal");
@@ -65151,8 +65694,9 @@ async function runActionCommand(argv, deps = {}) {
       taskId: task.id,
       workspaceId: workspace.data.id,
       scope: task.intent.data.scope,
-      presented: `Approve ${descriptor}`,
+      presented: question.presented,
       approvedContent: descriptor,
+      displayed: question.approvedText,
       contentRefs: []
     },
     response: "approved",
@@ -65169,6 +65713,15 @@ async function runActionCommand(argv, deps = {}) {
       printHuman(decision, deps);
     return 1;
   }
+  const planSteps = resolved.data.descriptorPayload.plan_steps;
+  if (normalized.operation === "git.commit" && Array.isArray(planSteps)) {
+    const result = success(null, null, { plan_commits: planSteps.length });
+    if (json)
+      jsonResult(outOf(deps), result);
+    else
+      printHuman(result, deps);
+    return 0;
+  }
   const runner = nativeExternalActionRunner(root, actor, core);
   const result = await runner(descriptor, (step) => executeResolvedExternalAction(resolved.data, root, step, { host: "workit_cli", actor }));
   if (json)