@codeuxai/codeux 0.8.1 → 0.8.3

package/dist/services/runtime-startup-recovery-service.js

@@ -5,9 +5,11 @@ import { RECOVERED_STALE_QA_SUMMARY_PREFIX } from "../domain/qa-review/qa-review
 const ACTIVE_SPRINT_RUN_STATUSES = ["queued", "running"];
 const ACTIVE_DISPATCH_STATUSES = ["queued", "claimed", "running", "cancel_requested"];
 const TERMINAL_TASK_RUN_STATES = new Set(["COMPLETED", "FAILED", "BLOCKED", "QUOTA"]);
+const TERMINAL_SPRINT_RUN_STATUSES = new Set(["completed", "failed", "cancelled"]);
 const ACTIVE_TASK_RUN_STATES = ["PENDING", "RUNNING", "PAUSED"];
 const TASK_CODING_INVOCATION_TYPES = ["task_coding", "cli_task_coding", "cli_task_followup"];
 const CLI_PROVIDERS = new Set(["gemini", "codex", "claude-code", "qwen-code", "opencode"]);
+const DURABLE_REMOTE_PROVIDERS = new Set(["jules"]);
 const QA_RUN_START_TIMEOUT_MS = 60_000;
 export class RuntimeStartupRecoveryService {
     deps;
@@ -25,6 +27,7 @@ export class RuntimeStartupRecoveryService {
         const reconciledContainerInvocationIds = await this.reconcileInterruptedCliInvocations(new Set(recoveredCliSessionIds));
         const reconciledQaReviewRunIds = await this.reconcileInterruptedQaReviewRuns();
         const reconciledStructuredInvocationIds = await this.reconcileInterruptedStructuredInvocations();
+        const rehydratedSprintRunIds = this.rehydrateDurableProviderSprintRuns();
         const reconciledTaskCodingInvocationIds = await this.reconcileInterruptedTaskCodingInvocations();
         const reconciledTaskCodingProviderIds = this.reconcileOrphanedTaskCodingProviderInvocations();
         const reconciledTaskRunIds = this.reconcileInterruptedTaskRuns();
@@ -39,6 +42,7 @@ export class RuntimeStartupRecoveryService {
             || reconciledStructuredInvocationIds.length > 0
             || reconciledTaskCodingInvocationIds.length > 0
             || reconciledTaskCodingProviderIds.length > 0
+            || rehydratedSprintRunIds.length > 0
             || reconciledTaskRunIds.length > 0
             || reconciledPausedSprintRunIds.length > 0
             || resumedSprintRunIds.length > 0
@@ -53,6 +57,7 @@ export class RuntimeStartupRecoveryService {
                 reconciledStructuredInvocations: reconciledStructuredInvocationIds.length,
                 reconciledTaskCodingInvocations: reconciledTaskCodingInvocationIds.length,
                 reconciledTaskCodingProviders: reconciledTaskCodingProviderIds.length,
+                rehydratedSprintRuns: rehydratedSprintRunIds.length,
                 reconciledTaskRuns: reconciledTaskRunIds.length,
                 reconciledPausedSprintRuns: reconciledPausedSprintRunIds.length,
                 resumedSprintRuns: resumedSprintRunIds.length,
@@ -69,6 +74,7 @@ export class RuntimeStartupRecoveryService {
             reconciledStructuredInvocationIds,
             reconciledTaskCodingInvocationIds,
             reconciledTaskCodingProviderIds,
+            rehydratedSprintRunIds,
             reconciledTaskRunIds,
             reconciledPausedSprintRunIds,
             resumedSprintRunIds,
@@ -426,6 +432,170 @@ export class RuntimeStartupRecoveryService {
         }
         return null;
     }
+    rehydrateDurableProviderSprintRuns() {
+        const executionRepository = this.deps.executionRepository;
+        if (typeof executionRepository.listTaskRunsByStates !== "function"
+            || typeof executionRepository.reassignTaskRunSprintRun !== "function"
+            || typeof executionRepository.reassignTaskDispatchSprintRun !== "function"
+            || typeof executionRepository.associateProviderInvocationRuntime !== "function") {
+            return [];
+        }
+        const durableTaskRuns = executionRepository.listTaskRunsByStates([...ACTIVE_TASK_RUN_STATES])
+            .filter((taskRun) => this.isRecoverableDurableProviderTaskRun(taskRun));
+        if (durableTaskRuns.length === 0) {
+            return [];
+        }
+        const taskRunsBySprintId = new Map();
+        for (const taskRun of durableTaskRuns) {
+            const entries = taskRunsBySprintId.get(taskRun.sprintId) || [];
+            entries.push(taskRun);
+            taskRunsBySprintId.set(taskRun.sprintId, entries);
+        }
+        const now = new Date().toISOString();
+        const rehydratedSprintRunIds = new Set();
+        for (const [sprintId, taskRuns] of taskRunsBySprintId.entries()) {
+            const rawStatus = this.deps.projectManagementRepository.getRawSprintStatus(sprintId);
+            if (rawStatus === null || rawStatus === "completed" || rawStatus === "cancelled") {
+                continue;
+            }
+            const targetRun = this.resolveDurableProviderRecoverySprintRun(taskRuns);
+            if (!targetRun) {
+                continue;
+            }
+            const targetRunWasTerminal = TERMINAL_SPRINT_RUN_STATUSES.has(targetRun.status);
+            if (TERMINAL_SPRINT_RUN_STATUSES.has(targetRun.status)) {
+                this.deps.executionRepository.updateSprintRun(targetRun.id, {
+                    status: "running",
+                    startedAt: targetRun.startedAt || now,
+                    finishedAt: null,
+                    lastHeartbeatAt: now,
+                });
+                this.deps.executionRepository.appendSprintRunEvent(targetRun.id, "sprint_rehydrated", "system", {
+                    reason: "durable_provider_sessions_survived_restart",
+                    previousStatus: targetRun.status,
+                    durableProvider: "jules",
+                    recoveredTaskRunCount: taskRuns.length,
+                }, {
+                    sourceEventKey: `startup-recovery:durable-provider-sprint:${targetRun.id}`,
+                });
+                rehydratedSprintRunIds.add(targetRun.id);
+            }
+            for (const originalTaskRun of taskRuns) {
+                let taskRehydrated = targetRunWasTerminal;
+                const taskRun = originalTaskRun.sprintRunId === targetRun.id
+                    ? originalTaskRun
+                    : executionRepository.reassignTaskRunSprintRun(originalTaskRun.id, targetRun.id);
+                if (originalTaskRun.sprintRunId !== targetRun.id) {
+                    rehydratedSprintRunIds.add(targetRun.id);
+                    taskRehydrated = true;
+                }
+                let dispatchId = taskRun.dispatchId;
+                if (dispatchId) {
+                    const dispatch = this.deps.executionRepository.getTaskDispatch(dispatchId);
+                    if (dispatch) {
+                        if (dispatch.sprintRunId !== targetRun.id) {
+                            executionRepository.reassignTaskDispatchSprintRun(dispatch.id, targetRun.id);
+                            rehydratedSprintRunIds.add(targetRun.id);
+                            taskRehydrated = true;
+                        }
+                        if (!ACTIVE_DISPATCH_STATUSES.includes(dispatch.status)) {
+                            this.deps.executionRepository.updateTaskDispatch(dispatch.id, {
+                                status: this.resolveRehydratedDispatchStatus(taskRun),
+                                startedAt: dispatch.startedAt || taskRun.startedAt || now,
+                                finishedAt: null,
+                                lastHeartbeatAt: now,
+                                errorMessage: null,
+                            });
+                            rehydratedSprintRunIds.add(targetRun.id);
+                            taskRehydrated = true;
+                        }
+                    }
+                    else {
+                        dispatchId = null;
+                    }
+                }
+                if (!taskRehydrated) {
+                    continue;
+                }
+                const sessionKey = this.resolveTaskRunSessionKey(taskRun);
+                const usage = sessionKey
+                    ? this.deps.executionRepository.getLatestProviderInvocationUsageBySession(sessionKey, "task_coding")
+                    : null;
+                if (usage) {
+                    executionRepository.associateProviderInvocationRuntime(usage.id, {
+                        sprintRunId: targetRun.id,
+                        dispatchId,
+                        taskRunId: taskRun.id,
+                    });
+                    if (usage.status !== "running") {
+                        this.deps.executionRepository.updateProviderInvocationUsage(usage.id, {
+                            status: "running",
+                            finishedAt: null,
+                            durationMs: null,
+                        });
+                    }
+                }
+                this.deps.executionRepository.appendTaskRunEvent(taskRun.id, "task_run_rehydrated", "system", {
+                    reason: "durable_provider_session_survived_restart",
+                    previousSprintRunId: originalTaskRun.sprintRunId,
+                    sprintRunId: targetRun.id,
+                    dispatchId,
+                    provider: taskRun.provider,
+                    sessionId: taskRun.sessionId,
+                }, {
+                    sourceEventKey: `startup-recovery:durable-task-run:${taskRun.id}:${targetRun.id}`,
+                });
+            }
+        }
+        return [...rehydratedSprintRunIds];
+    }
+    isRecoverableDurableProviderTaskRun(taskRun) {
+        return DURABLE_REMOTE_PROVIDERS.has(String(taskRun.provider || ""))
+            && taskRun.mode === "jules"
+            && Boolean(this.resolveTaskRunSessionKey(taskRun))
+            && !isTerminalTaskRunState(taskRun);
+    }
+    resolveDurableProviderRecoverySprintRun(taskRuns) {
+        const firstTaskRun = taskRuns[0];
+        if (!firstTaskRun) {
+            return null;
+        }
+        const activeRun = this.deps.executionRepository.findActiveSprintRun(firstTaskRun.projectId, firstTaskRun.sprintId);
+        if (activeRun) {
+            return activeRun;
+        }
+        const candidateRuns = new Map();
+        for (const taskRun of taskRuns) {
+            if (!taskRun.sprintRunId) {
+                continue;
+            }
+            const sprintRun = this.deps.executionRepository.getSprintRun(taskRun.sprintRunId);
+            if (sprintRun) {
+                candidateRuns.set(sprintRun.id, sprintRun);
+            }
+        }
+        return [...candidateRuns.values()].sort((left, right) => (Date.parse(right.createdAt) - Date.parse(left.createdAt)))[0] || null;
+    }
+    resolveRehydratedDispatchStatus(taskRun) {
+        if (taskRun.state === "PENDING") {
+            return "queued";
+        }
+        if (taskRun.state === "PAUSED") {
+            return "paused";
+        }
+        return "running";
+    }
+    resolveTaskRunSessionKey(taskRun) {
+        const sessionId = taskRun.sessionId?.trim();
+        if (sessionId) {
+            return sessionId;
+        }
+        const sessionName = taskRun.sessionName?.trim();
+        if (!sessionName) {
+            return null;
+        }
+        return sessionName.replace(/^sessions\//, "");
+    }
     reconcileInterruptedTaskRuns() {
         const executionRepository = this.deps.executionRepository;
         if (typeof executionRepository.listTaskRunsByStates !== "function") {

package/dist/services/sprint-task-dispatch-service.js

@@ -123,6 +123,13 @@ export class SprintTaskDispatchService {
             state: "RUNNING",
             startedAt: queuedAt,
         });
+        if (julesClaim) {
+            this.executionRepository.associateProviderInvocationRuntime(julesClaim.id, {
+                sprintRunId: args.sprintRunId,
+                dispatchId: dispatch.id,
+                taskRunId: taskRun.id,
+            });
+        }
         this.executionRepository.appendTaskRunEvent(taskRun.id, "dispatch_started", "system", {
             dispatchId: dispatch.id,
             executorType,

package/docs/getting-started/quickstart.md

@@ -4,12 +4,23 @@ This guide gets the MCP server and dashboard running locally with minimal setup.
 
 ## Prerequisites
 
-- Node.js 20+
-- pnpm
+- Node.js 22+
+- pnpm (only for building from source)
 - A valid Jules API key
 - Optional for remote git intelligence: GitHub CLI (`gh`) authenticated
 
-## Install and Build
+## Install from npm (recommended)
+
+Install the runtime globally and run the `codeux` command:
+
+```bash
+npm i -g @codeuxai/codeux
+codeux
+```
+
+This starts the MCP server and dashboard. Skip ahead to [Configure API Key](#configure-api-key); the build steps below are only needed when running from source.
+
+## Install and Build (from source)
 
 ```bash
 pnpm install

package/docs/operations/runbook.md

@@ -120,6 +120,7 @@ Checks:
   - If auth is expected from host login state, is the relevant Docker auth mount enabled and is its mount path valid?
   - Docker mode requires daemon-visible workspace paths. Runtime now prefers repo-scoped worktree paths for Docker sessions.
   - Docker runtime state is stored under `~/.code-ux/runtime/docker/<repo-hash>/` by default (override with `JULES_DOCKER_RUNTIME_ROOT`). Cached setup image build contexts and build locks live under that root so setup-cache images survive dashboard restarts and concurrent post-restart jobs wait on the same build instead of starting duplicate builds.
+  - During Code UX restarts, Docker-backed provider invocations interrupted by a shutdown signal stay recoverable until startup confirms whether the labeled session container still exists.
   - Codex uses per-session container home directories under that runtime root to prevent stale state from previous Codex runs.
   - Runtime cleanup prunes stale `home-codex-*` session homes and stale shared runtime temp directories automatically once those sessions are no longer active.
 - Docker provider launches use readable container names such as `code-ux-codex-<session>` and mount provider arguments through a generated argv file instead of passing the full prompt through the host `docker run` command line. Packaged Windows Electron builds that fail with `spawn ENAMETOOLONG` during provider launch are using an older build or a non-provider launch path that still embeds a large payload in command arguments.
@@ -214,6 +215,7 @@ Transient provider failures are classified and managed in `src/shared/providers/
 - On startup, interrupted local CLI sessions (`cli-*` with `RUNNING`) are auto-recovered to `FAILED` so orchestration can safely retry them.
 - On startup, active `queued` and `running` sprint runs are resumed automatically in place; Code UX now restores the watch loop instead of requiring a manual sprint restart.
 - Local `docker_cli` task dispatches are rewritten to retryable failed state during that recovery, while durable Jules sessions and connected-worker dispatches remain attached to the resumed sprint run.
+- If a restart finds active Jules task runs with persisted session ids but their sprint run was left `failed` or `cancelled` while the sprint is still active, startup recovery rehydrates a single sprint run, moves those durable Jules rows onto it, reopens their dispatch/provider runtime links, and resumes monitoring.
 - Failed CLI sessions can preserve their worktree for manual follow-up or assisted retry, based on CLI Workflow settings.
 - Dashboard task reruns now support a full clean reset:
   - the selected task always clears session, PR, merge, and intervention state before restart

package/docs/settings/configuration-and-storage.md

@@ -77,7 +77,9 @@ Runtime resolution:
 - On startup, Code UX prunes stale Code UX Docker workspace volumes and orphaned helper/login containers. Cached setup-script images are content-addressed and are intentionally preserved across dashboard restarts so provider launches can reuse them until the base image, setup script content, or setup Dockerfile changes.
 - On startup, Code UX also performs automated database maintenance, pruning old completed task runs (and their cascaded child tables), VM activities, attention items, and realtime events according to the configured retention policy, followed by a `VACUUM` operation on database files to reclaim disk space.
 - restart recovery also treats interrupted Docker sessions without a live backing container as failed, so abandoned workspaces are reclaimed instead of waiting forever for a callback that cannot arrive.
+- Docker provider runs interrupted by Code UX process shutdown keep their provider usage rows running when the spawner exits from a restart signal; startup recovery then resumes or fails them based on whether the labeled backing container still exists.
 - startup recovery now also requeues task-level CLI follow-up runs that were left in `in_progress` after QA/repair `Fix` work lost its backing container, so the orchestrator can start the container again instead of leaving the sprint stuck after a server restart.
+- startup recovery treats Jules task sessions as durable remote runtime. If Code UX restarts after a sprint run or task dispatch was incorrectly terminalized while the sprint itself is still active, recovery rehydrates one sprint run, reattaches active Jules task runs/dispatches/provider invocation rows to it, and resumes the watch loop instead of failing the sessions.
 - When Code UX has to create a missing feature branch, it prefers `origin/<defaultBranch>` over the local `<defaultBranch>` ref when the remote-tracking base branch exists.
 - `main` is only the final fallback when no sprint, project, or system base branch is configured. Normal sprint and task flows use the resolved `git.defaultBranch` value from settings and project metadata.
 - the old global `/api/settings` contract is removed in favor of explicit scoped endpoints

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@codeuxai/codeux",
-  "version": "0.8.1",
+  "version": "0.8.3",
   "description": "Containerized environment for running and managing AI sub-agents",
   "author": "Pierre Voss <p.voss@codeux.ai>",
   "license": "MIT",