ultra-builder-pro-cli 0.24.2 → 0.25.0

package/mcp-server/lib/worker-packet.cjs

@@ -121,13 +121,13 @@ function abandonWorkerPacket(db, id, reason) {
   return ops.tx(db, () => {
     const row = db.prepare('SELECT * FROM worker_packets WHERE id = ?').get(id);
     if (!row || row.status === 'abandoned') return row || null;
-    if (row.status !== 'pending') return row;
+    if (!['pending', 'assigned'].includes(row.status)) return row;
     db.prepare(
       `UPDATE worker_packets
        SET status = 'abandoned',
            abandoned_at = strftime('%Y-%m-%dT%H:%M:%fZ', 'now'),
            abandon_reason = ?
-       WHERE id = ? AND status = 'pending'`,
+       WHERE id = ? AND status IN ('pending', 'assigned')`,
     ).run(String(reason || 'session acquisition failed'), id);
     ops.appendEventInTx(db, {
       type: 'worker_packet_abandoned',

package/mcp-server/server.cjs

@@ -68,6 +68,24 @@ function errorResponse(code, message, retriable = false, details = undefined) {
   };
 }
 
+function publicToolError(error) {
+  const code = String(error?.code || 'STATE_DB_ERROR');
+  if (code.startsWith('SQLITE_')) {
+    return {
+      code: 'STATE_DB_ERROR',
+      message: 'Ultra state persistence failed',
+      retriable: code === 'SQLITE_BUSY' || code === 'SQLITE_LOCKED',
+      details: undefined,
+    };
+  }
+  return {
+    code,
+    message: error?.message || 'Ultra state operation failed',
+    retriable: Boolean(error?.retriable),
+    details: error?.details,
+  };
+}
+
 function isInitializeCall(name, input = {}) {
   return name === 'ultra.record'
     && Array.isArray(input.entries)
@@ -313,11 +331,12 @@ function startServer({
     } catch (error) {
       toolError = error.code || 'STATE_DB_ERROR';
       emitTelemetry();
+      const visibleError = publicToolError(error);
       return errorResponse(
-        toolError,
-        error.message,
-        Boolean(error.retriable),
-        error.details,
+        visibleError.code,
+        visibleError.message,
+        visibleError.retriable,
+        visibleError.details,
       );
     }
   });

package/orchestrator/parallel-orchestrator.cjs

@@ -27,6 +27,8 @@ const { isDeepStrictEqual } = require('node:util');
 const planStore = require('../mcp-server/lib/plan-store.cjs');
 const ops = require('../mcp-server/lib/state-ops.cjs');
 const checkpoints = require('../mcp-server/lib/stage-checkpoints.cjs');
+const gitBootstrap = require('../mcp-server/lib/git-bootstrap.cjs');
+const runtimePaths = require('../mcp-server/lib/runtime-paths.cjs');
 const workerPackets = require('../mcp-server/lib/worker-packet.cjs');
 const runner = require('./session-runner.cjs');
 const dispatchRules = require('./dispatch-rules.cjs');
@@ -460,6 +462,10 @@ function reservePreparedTask(db, repoRoot, prepared, ctx) {
   const { onError } = ctx;
   let handle;
   let packet = null;
+  let authority = null;
+  const priorContextIds = new Set(
+    db.prepare('SELECT id FROM context_envelopes').all().map((row) => row.id),
+  );
   try {
     if (!task.change_id) {
       throw planError(
@@ -467,36 +473,44 @@ function reservePreparedTask(db, repoRoot, prepared, ctx) {
         `orchestrator task ${task.id} must belong to the accepted Change`,
       );
     }
-    packet = workerPackets.createWorkerPacket(db, {
-      role: 'implement',
-      task_id: task.id,
-      runtime: decision.runtime,
-      output_path: `.ultra/changes/active/${task.change_id}/delivery/${task.id}-outcome.json`,
-      output_schema: {
-        type: 'object',
-        required: ['packet_digest'],
-        properties: {
-          packet_digest: { type: 'string', pattern: '^[0-9a-f]{64}$' },
+    authority = runtimePaths.ensureRuntimeState(repoRoot, {
+      admitStorageBoundary: () => gitBootstrap.ensureExistingProjectStorageBoundary(repoRoot),
+    });
+    ops.tx(db, () => {
+      packet = workerPackets.createWorkerPacket(db, {
+        role: 'implement',
+        task_id: task.id,
+        runtime: decision.runtime,
+        output_path: `.ultra/changes/active/${task.change_id}/delivery/${task.id}-outcome.json`,
+        output_schema: {
+          type: 'object',
+          required: ['packet_digest'],
+          properties: {
+            packet_digest: { type: 'string', pattern: '^[0-9a-f]{64}$' },
+          },
         },
-      },
-    }, { rootDir: repoRoot });
-    handle = runner.spawnSession({
-      db, repoRoot,
-      task_id: task.id,
-      runtime: decision.runtime,
-      command: ctx.deferStart ? null : command,
-      args: ctx.deferStart ? [] : args,
-      mark_task_started: true,
-      kernel_mode: true,
-      packet_digest: packet.packet_digest,
+      }, { rootDir: repoRoot });
+      workerPackets.markWorkerPacketAssigned(db, packet.id);
+      handle = runner.spawnSession({
+        db, repoRoot,
+        task_id: task.id,
+        runtime: decision.runtime,
+        authority,
+        command: null,
+        args: [],
+        mark_task_started: true,
+        kernel_mode: true,
+        packet_digest: packet.packet_digest,
+      });
+      handle.task_id = task.id;
+      handle.packet = packet;
     });
-    handle.task_id = task.id;
-    workerPackets.markWorkerPacketAssigned(db, packet.id);
-    handle.packet = packet;
   } catch (err) {
-    if (packet?.id) {
-      workerPackets.abandonWorkerPacket(db, packet.id, err.code || err.message);
-    }
+    rollbackFailedReservation(db, repoRoot, {
+      handle,
+      packet,
+      priorContextIds,
+    });
     const authorityBlocked = authorityBlockedResult(err, task.id, {
       reservationFailed: true,
     });
@@ -523,6 +537,69 @@ function reservePreparedTask(db, repoRoot, prepared, ctx) {
   };
 }
 
+function rollbackFailedReservation(db, repoRoot, {
+  handle,
+  packet,
+  priorContextIds,
+}) {
+  if (handle?.worktree_path) {
+    try {
+      runner._internal.reconcileRemovedWorktree(
+        repoRoot,
+        handle.worktree_path,
+        { sid: handle.sid },
+      );
+    } catch { /* the caller preserves the original reservation error */ }
+  }
+  if (handle?.artifact_dir) {
+    const expected = path.resolve(
+      repoRoot,
+      '.ultra',
+      '.runtime',
+      'sessions',
+      handle.sid,
+    );
+    const actual = path.resolve(handle.artifact_dir);
+    if (actual === expected) {
+      try { fs.rmSync(actual, { recursive: true, force: true }); }
+      catch { /* the caller preserves the original reservation error */ }
+    }
+  }
+  if (packet?.created && !db.prepare(
+    'SELECT 1 FROM worker_packets WHERE id = ?',
+  ).get(packet.id)) {
+    const expected = path.resolve(
+      repoRoot,
+      '.ultra',
+      '.runtime',
+      'worker-packets',
+      `${packet.id}.json`,
+    );
+    const actual = path.resolve(repoRoot, packet.packet_path);
+    if (actual === expected) {
+      try { fs.rmSync(actual, { force: true }); }
+      catch { /* the caller preserves the original reservation error */ }
+    }
+  }
+  const context = packet?.context_envelope;
+  if (context?.id
+      && !priorContextIds.has(context.id)
+      && !db.prepare('SELECT 1 FROM context_envelopes WHERE id = ?').get(context.id)) {
+    const actual = path.resolve(repoRoot, context.path);
+    const runtimeContextRoot = path.resolve(
+      repoRoot,
+      '.ultra',
+      '.runtime',
+      'contexts',
+    );
+    if (actual.startsWith(`${runtimeContextRoot}${path.sep}`)
+        && path.basename(actual) === `${context.id}.json`) {
+      try { fs.rmSync(actual, { force: true }); }
+      catch { /* the caller preserves the original reservation error */ }
+    }
+  }
+}
+
 async function runTask(db, repoRoot, task, wave, ctx) {
   const prepared = ctx.prepared || prepareTaskDispatch(task, wave, ctx);
   const reservation = reservePreparedTask(db, repoRoot, prepared, ctx);
@@ -560,6 +637,16 @@ function unwindReservations(db, repoRoot, reservations, ctx) {
       if (ctx.onError) ctx.onError(error);
       continue;
     }
+    try {
+      workerPackets.abandonWorkerPacket(
+        db,
+        handle.packet?.id,
+        'parallel reservation cancelled before execution',
+      );
+    } catch (error) {
+      errors.push(error);
+      if (ctx.onError) ctx.onError(error);
+    }
     const task = ops.readTask(db, handle.task_id);
     if (task?.status === 'in_progress') {
       try {

package/orchestrator/session-runner.cjs

@@ -21,16 +21,6 @@ const runtimePaths = require('../mcp-server/lib/runtime-paths.cjs');
 const gitBootstrap = require('../mcp-server/lib/git-bootstrap.cjs');
 const closeJournal = require('./session-close-journal.cjs');
 
-function legacyContextSpine() {
-  return module.require(path.join(
-    __dirname,
-    '..',
-    'mcp-server',
-    'lib',
-    'context-spine.cjs',
-  ));
-}
-
 const EXPECTED_EXECUTION_GATE_CODES = new Set([
   'TASK_EXECUTION_CONTRACT_INCOMPLETE',
   'WORKFLOW_TASK_NOT_EXECUTABLE',
@@ -559,77 +549,12 @@ function mintSessionId() {
 function assertSessionTaskReady(db, repoRoot, taskId) {
   const task = ops.readTask(db, taskId);
   if (!task) return null; // admissionCheck reports the canonical TASK_NOT_FOUND error.
-  // Unbound rows remain readable for legacy recovery, but every current
-  // change-owned task must pass the same plan gate as a dev workflow.
-  if (!task.change_id) return task;
-  ops.assertTaskExecutionContract(task);
   if (!['pending', 'in_progress', 'blocked'].includes(task.status) || task.stale) {
     throw new SessionRunnerError(
       'TASK_NOT_EXECUTABLE',
       `task ${task.id} is not executable from status ${task.status}${task.stale ? ' (stale)' : ''}`,
     );
   }
-  const incompleteDependencies = (task.deps || []).filter((id) => {
-    const dependency = ops.readTask(db, id);
-    return !dependency || !['completed', 'expanded'].includes(dependency.status);
-  });
-  if (incompleteDependencies.length > 0) {
-    throw new SessionRunnerError(
-      'TASK_DEPENDENCIES_INCOMPLETE',
-      `task ${task.id} has incomplete dependencies: ${incompleteDependencies.join(', ')}`,
-    );
-  }
-  const plan = checkpoints.currentCheckpoint(
-    db,
-    'plan',
-    { change_id: task.change_id },
-    { includeDraft: false },
-  );
-  if (!plan || checkpoints.checkpointDigest(plan) !== plan.digest) {
-    throw new SessionRunnerError(
-      'PLAN_CHECKPOINT_REQUIRED',
-      `task ${task.id} requires an accepted Plan checkpoint`,
-    );
-  }
-  const implementationContext = legacyContextSpine().validateContextSnapshot(db, {
-    change_id: task.change_id,
-    task_id: task.id,
-    role: 'implement',
-    gate: 'implementation',
-  }, {
-    rootDir: repoRoot,
-    require_current_checkout: true,
-  });
-  if (!implementationContext.snapshot) {
-    throw new SessionRunnerError(
-      'IMPLEMENTATION_CONTEXT_REQUIRED',
-      `task ${task.id} requires a ready implementation Context before session admission`,
-      { blockers: implementationContext.blockers },
-    );
-  }
-  if (implementationContext.blockers.length > 0) {
-    throw new SessionRunnerError(
-      'IMPLEMENTATION_CONTEXT_STALE',
-      `task ${task.id} implementation Context is stale`,
-      { blockers: implementationContext.blockers },
-    );
-  }
-  const planningContext = legacyContextSpine().validateContextSnapshot(db, {
-    change_id: task.change_id,
-    task_id: null,
-    role: 'plan',
-    gate: 'planning',
-  }, {
-    rootDir: repoRoot,
-    require_current_checkout: true,
-  });
-  if (!planningContext.snapshot || planningContext.blockers.length > 0) {
-    throw new SessionRunnerError(
-      'PLAN_CONTEXT_STALE',
-      `change ${task.change_id} planning Context is stale at session admission`,
-      { blockers: planningContext.blockers },
-    );
-  }
   return task;
 }
 
@@ -638,65 +563,26 @@ function assertKernelSessionTaskReady(db, repoRoot, taskId, packetDigest) {
   if (!task) {
     throw new SessionRunnerError('TASK_NOT_FOUND', `task ${taskId} not found`);
   }
-  ops.assertTaskExecutionContract(task);
   if (!['pending', 'in_progress', 'blocked'].includes(task.status) || task.stale) {
     throw new SessionRunnerError(
       'TASK_NOT_EXECUTABLE',
       `task ${task.id} is not executable from status ${task.status}${task.stale ? ' (stale)' : ''}`,
     );
   }
-  const incompleteDependencies = (task.deps || []).filter((id) => {
-    const dependency = ops.readTask(db, id);
-    return !dependency || !['completed', 'expanded'].includes(dependency.status);
-  });
-  if (incompleteDependencies.length > 0) {
+  const packet = packetDigest
+    ? db.prepare(
+      `SELECT id FROM worker_packets
+       WHERE packet_digest = ? AND scope_type = 'task' AND scope_id = ?
+         AND status IN ('pending', 'assigned')`,
+    ).get(packetDigest, task.id)
+    : null;
+  if (!packet) {
     throw new SessionRunnerError(
-      'TASK_DEPENDENCIES_INCOMPLETE',
-      `task ${task.id} has incomplete dependencies: ${incompleteDependencies.join(', ')}`,
+      'WORKER_PACKET_REQUIRED',
+      `task ${task.id} requires the exact Worker Packet prepared for this session`,
     );
   }
-  if (task.change_id) {
-    const plan = checkpoints.currentCheckpoint(
-      db,
-      'plan',
-      { change_id: task.change_id },
-      { includeDraft: false },
-    );
-    if (!plan) {
-      throw new SessionRunnerError(
-        'PLAN_CHECKPOINT_REQUIRED',
-        `task ${task.id} requires an accepted Plan checkpoint`,
-      );
-    }
-    const plannedDigest = plan.payload?.plan?.task_contract_digests?.[task.id];
-    if (!plannedDigest) {
-      throw new SessionRunnerError(
-        'PLAN_TASK_CONTRACT_MISSING',
-        `accepted Plan checkpoint does not bind task ${task.id}`,
-      );
-    }
-    const packet = packetDigest
-      ? db.prepare(
-        `SELECT id, task_digest FROM worker_packets
-         WHERE packet_digest = ? AND scope_type = 'task' AND scope_id = ?
-           AND status IN ('pending', 'assigned')`,
-      ).get(packetDigest, task.id)
-      : null;
-    if (!packet) {
-      throw new SessionRunnerError(
-        'WORKER_PACKET_REQUIRED',
-        `task ${task.id} requires the exact Worker Packet prepared for this session`,
-      );
-    }
-    workerPackets.readWorkerPacket(db, packet.id, { rootDir: repoRoot });
-    if (packet.task_digest !== plannedDigest) {
-      throw new SessionRunnerError(
-        'PLAN_TASK_CONTRACT_STALE',
-        `task ${task.id} no longer matches its accepted Plan checkpoint`,
-      );
-    }
-    return task;
-  }
+  workerPackets.readWorkerPacket(db, packet.id, { rootDir: repoRoot });
   return task;
 }
 
@@ -783,6 +669,7 @@ function spawnSession({
   repoRoot,
   task_id,
   runtime,
+  authority: preadmittedAuthority = null,
   takeover = false,
   command = null,
   args = [],
@@ -818,17 +705,19 @@ function spawnSession({
   // or any filesystem mutation creates a new worktree.
   if (kernel_mode) assertKernelSessionTaskReady(db, repoRoot, task_id, packet_digest);
   else assertSessionTaskReady(db, repoRoot, task_id);
-  let authority;
-  try {
-    authority = runtimePaths.ensureRuntimeState(repoRoot, {
-      admitStorageBoundary: () => gitBootstrap.ensureExistingProjectStorageBoundary(repoRoot),
-    });
-  } catch (error) {
-    throw new SessionRunnerError(
-      'WORKTREE_AUTHORITY_NOT_IGNORED',
-      `cannot establish the project Ultra storage boundary: ${error.message}`,
-      { cause: error },
-    );
+  let authority = preadmittedAuthority;
+  if (!authority) {
+    try {
+      authority = runtimePaths.ensureRuntimeState(repoRoot, {
+        admitStorageBoundary: () => gitBootstrap.ensureExistingProjectStorageBoundary(repoRoot),
+      });
+    } catch (error) {
+      throw new SessionRunnerError(
+        'WORKTREE_AUTHORITY_NOT_IGNORED',
+        `cannot establish the project Ultra storage boundary: ${error.message}`,
+        { cause: error },
+      );
+    }
   }
   const pendingClose = closeJournal.findForTask(repoRoot, task_id);
   if (pendingClose) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ultra-builder-pro-cli",
-  "version": "0.24.2",
+  "version": "0.25.0",
   "description": "Explicitly invoked Ultra Builder Pro workflows for Claude Code, OpenCode, Codex CLI, Kimi Code, and Grok Build, with a project-local MCP persistence and safety kernel.",
   "bin": {
     "ultra-builder-pro-cli": "bin/install.js",

package/skills/ultra-change/SKILL.md

@@ -18,7 +18,9 @@ checkpoint accepts the downstream authority.
 4. Convert the request into observable outcome, executable acceptance, non-goals,
    public seams, recovery, verification, documentation impact, risk, and research
    disposition.
-5. Recommend `quick`, `standard`, `major`, or `incident` from evidence. Ask only when
+5. Recommend `quick`, `standard`, `major`, or `incident` from evidence, or record a
+   clearer bounded repository-specific kind when those profiles lose meaning. These
+   are model-owned labels, not SQLite enums. Ask only when
    a choice changes accepted product intent, compatibility, security, material cost,
    external effects, or recovery.
 
@@ -42,6 +44,9 @@ genuinely dependent evidence stale. Readiness is derived, not a stored absorbing
 state. Semantic diagnostics remain advisory; structural, digest, path, or concurrency
 conflicts require repair and retry of the same draft.
 Use `change_contract / cancel` only when the owner intentionally abandons the Change.
+An archived or cancelled Change remains immutable history. When new evidence requires
+continued work, use `change_contract / supersede` to create one linked active successor;
+never patch SQLite, reopen the historical row, or duplicate the relationship manually.
 
 Publish the durable Change contract with `ultra.sync { action: publish }` when it is a
 useful team handoff. Recommend bounded `ultra-research` for a real evidence gap or

package/skills/ultra-dev/SKILL.md

@@ -30,7 +30,7 @@ before changing logic. Implement the smallest complete vertical slice. Ask the o
 only when new evidence changes product intent, compatibility, security, material cost,
 external effects, or recovery.
 
-Use typed `ultra.record` entries for `task_outcome / start|block|complete`,
+Use typed `ultra.record` entries for `task_outcome / start|block|complete|attest_commit`,
 `event / append`, `artifact / bind`, `decision / accept`, and corrected
 `task_contract / revise`. Every worker output must repeat the exact `packet_digest`;
 the parent registers it only after packet, output path, schema, and digest validation.
@@ -49,9 +49,14 @@ reports outcome diagnostics. The model decides whether the implemented slice sat
 the Task; semantic warnings remain visible. A rejection means the declared authority,
 path, digest, or concurrency boundary was unsafe and leaves the draft mutable.
 
-After acceptance, mark the task durably completed, publish with `ultra.sync`, and
-create at most one authorized local task commit containing code and semantic
-artifacts. Record its SHA only in local state; never create a bookkeeping commit.
+After acceptance:
+
+1. Record `task_outcome / complete { id, packet_digest }`; never include a patch or SHA.
+2. Publish the durable completed status with `ultra.sync`.
+3. Create at most one authorized local task commit containing code, semantic
+   artifacts, and the team checkpoint.
+4. Record `task_outcome / attest_commit { id, completion_commit }` with that integrated
+   commit's full SHA. This is local mechanical proof and must not create another commit.
 
 Release the lease through `ultra.session`. Preserve a dirty or unintegrated worktree
 on interruption. Commit, push, tag, publish, deploy, or destructive cleanup require

package/skills/ultra-plan/SKILL.md

@@ -22,7 +22,12 @@ digests, context, and team checkpoint in one semantic operation.
    for a material unresolved choice.
 6. Design a walking skeleton and vertical slices. Each task owns an observable outcome,
    public seam, verification command, acceptance mapping, target seams, bounded
-   context refs, documentation impact, recovery, owner, and dependencies.
+   context refs, documentation impact, recovery, owner, and dependencies. Set the
+   published `type`, `priority`, optional bounded `complexity`/`estimated_days`,
+   `slice_kind`, and string-array `deps`/`files_modified` deliberately. Prefer the
+   shared vocabulary when it communicates the work, but use a bounded
+   repository-specific label when it is clearer; SQLite validates structure and does
+   not choose business taxonomy.
 
 Large sources stay lazy. Use digest freshness for accepted inputs that must remain
 byte-current, existence for expected implementation targets, and advisory only when
@@ -34,8 +39,11 @@ question.
 ## Record and checkpoint
 
 Use one `ultra.record` batch with `task_contract / define` for new tasks and
-`task_contract / revise` for corrected contracts. Read back the draft with
-`ultra.context`.
+`task_contract / revise` for corrected contracts, including a wrong `title` or `type`,
+before accepting the Plan checkpoint. Read back the draft with `ultra.context`.
+Never write status, session, freshness, runtime tag, generated Context, or
+completion-commit fields through a Task Contract; Task outcomes and the runtime own
+them.
 Never read or write `.ultra/tasks/tasks.json`; use `ultra.sync` for the Git team
 checkpoint, and never edit the local runtime projection directly.
 
@@ -49,7 +57,8 @@ idempotency_key: stable semantic Plan checkpoint id
 ```
 
 The model decides whether decomposition, acceptance coverage, and context are
-sufficient and records any deliberate omission. The checkpoint compiles or reuses the
+sufficient and records any deliberate omission. Missing semantic detail remains a
+visible warning and does not deny an otherwise safe Session lease. The checkpoint compiles or reuses the
 content-addressed Context Envelope, reports advisory coverage diagnostics, exports
 `plan.json` and `plan.md` inside the same recoverable publication, accepts one Plan
 revision, and publishes the team checkpoint. Do not export separately.

package/skills/ultra-plan/references/semantic-preflight.md

@@ -11,8 +11,10 @@ change-bound research records.
    Markdown anchor through `trace_to`.
 5. Check that every task reaches a public consumer and owns its error, documentation,
    verification, and recovery obligations.
-6. Validate dependencies and ensure a quick profile contains exactly one task.
+6. Validate dependencies. A `quick` profile normally has one vertical task, but the
+   model may use the smallest evidence-backed graph that satisfies the accepted Change.
 
-Treat the MCP completion result as the final planning gate. It derives the coverage
-matrix from durable records and rejects unresolved decisions, missing research,
-uncovered acceptance, orphan tasks, incomplete contracts, or invalid topology.
+Treat the MCP result as a persistence receipt plus typed diagnostics. Structural,
+digest, path, concurrency, and exact topology conflicts must be repaired. The model
+owns semantic completeness, acceptance coverage, research sufficiency, and whether a
+warning requires another planning revision before execution.