wicked-crew 0.7.10 → 0.7.12

package/dist/api/routes.js

@@ -5,7 +5,7 @@ import { readFileSync, existsSync } from 'node:fs';
 import { promises as fsp } from 'node:fs';
 import { isAbsolute, join, relative, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { ChatUnsupportedError, CoreAdapter, ElicitationUnsupportedError, SteeringUnsupportedError, humanGatePhaseIds } from '../core/adapter.js';
+import { CampaignsUnsupportedError, ChatUnsupportedError, CoreAdapter, ElicitationUnsupportedError, SteeringUnsupportedError, humanGatePhaseIds } from '../core/adapter.js';
 import { codeGraphDb, requirementsGraph } from '../core/repoPaths.js';
 import { QeGateCache } from '../qe/gate-events.js';
 import { buildAcceptanceView, resolveRunWorkflow } from '../qe/acceptance.js';
@@ -32,9 +32,10 @@ import { MEMBERSHIP_ATTACHED, membershipAttachedKey } from '../projects/events.j
 import { AuditLog } from './audit.js';
 import { AcpFoldCache, EngineVersionCache, eventsDirOf, installedPackageVersion, listStoreFiles, readStudioBundleVersion, } from './diagnostics.js';
 import { RetryIndex } from './retry-index.js';
+import { GroupIndex } from './group-index.js';
 import { GuidanceIndex } from './guidance-index.js';
-import { DeliveryIndex, deliveryStateWithVacuity, gitRunBranchIsEmpty, gitWorktreeIsClean, prUrlFrom, } from './delivery-index.js';
-import { runDeliverScript } from './post-hoc-deliver.js';
+import { DeliveryIndex, deliveryStateWithVacuity, gitRunBranchIsEmpty, gitWorktreeIsClean, isDeliverConflictStranded, prUrlFrom, } from './delivery-index.js';
+import { gitReprovisionWorktree, runDeliverScript, } from './post-hoc-deliver.js';
 import { LOCAL_ACTOR } from './auth.js';
 // Re-exported so existing `import { API_PREFIX } from './routes.js'` callers keep working; the
 // value lives in the leaf module api-prefix.ts to keep unit-output.ts out of this file's cycle.
@@ -151,9 +152,22 @@ export const LaunchSchema = z.object({
      *  (the route checks the store and 400s with a named error otherwise); persisted via the
      *  `run.launched` audit entry + retry index and echoed as `AgentSession.retry_of`. */
     retryOf: z.string().min(1).optional(),
+    /** wicked-studio#27 (api-types 0.19.0) — attach this AD-HOC run to an EXISTING campaign's
+     *  surface. Validated against the campaign store before anything launches (unknown ⇒ 404,
+     *  engine without campaign bindings ⇒ 501 — never a silently dropped attach); persisted via
+     *  the `run.launched` audit entry + group index, echoed as `AgentSession.campaign_id`, and
+     *  served under `Campaign.attached_runs`. Provenance only: the run is NOT a DAG node. */
+    campaignId: z.string().min(1).optional(),
+    /** wicked-studio#27 (api-types 0.19.0) — ad-hoc label group, created on first use: runs
+     *  sharing a label form one `RunGroup` on `GET /campaigns`. Persisted/echoed like
+     *  `campaignId` (as `AgentSession.group_label`). */
+    groupLabel: z.string().min(1).max(200).optional(),
 }).strict().refine((b) => b.deliver !== 'pr' || b.workflow !== undefined, {
     message: 'deliver: "pr" requires a workflow — a free-text run has no def to append the deliver phase to',
     path: ['deliver'],
+}).refine((b) => b.campaignId === undefined || b.groupLabel === undefined, {
+    message: 'campaignId and groupLabel are mutually exclusive — a run files onto ONE grouping surface (an existing campaign, or a label group)',
+    path: ['groupLabel'],
 });
 export const GateSchema = z.object({
     approve: z.boolean(),
@@ -235,6 +249,7 @@ runtime = {}) {
     const openWithOs = runtime.openWithOs ?? openWithSystemDefault;
     const signedIn = runtime.signedIn ?? signedInHeuristic;
     const retryIndex = runtime.retryIndex ?? new RetryIndex();
+    const groupIndex = runtime.groupIndex ?? new GroupIndex();
     const guidanceIndex = runtime.guidanceIndex ?? new GuidanceIndex();
     const deliveryIndex = runtime.deliveryIndex ?? new DeliveryIndex();
     const worktreeExists = runtime.worktreeExists ?? ((p) => existsSync(p));
@@ -248,6 +263,9 @@ runtime = {}) {
             }),
     };
     const deliverExec = runtime.deliverExec ?? runDeliverScript;
+    const reprovisionWorktree = runtime.reprovisionWorktree ?? gitReprovisionWorktree;
+    /** Repo root for a repo ref, from the registry — shared by the reprovision path below. */
+    const repoRootOf = async (repoRef) => (await adapter.listRepos()).find((r) => r.id === repoRef)?.root_path;
     // The run-DTO joins (DES-UX-001 §8.2/§8.3, DES-UX-002 §7.2): `project_id` from the membership
     // record — `null` = genuinely unfiled, so the field is ALWAYS present on served runs —
     // `retry_of` from the lineage index and `guidance` from the guidance index, each set only
@@ -260,15 +278,59 @@ runtime = {}) {
     // "done" with nothing produced must be LOUD on the wire, never silently green.
     // Applied at DTO assembly on exactly the two endpoints that serve the run DTO
     // (GET /runs + GET /runs/:id); the internal sessionsDetail() consumers are untouched.
+    // crew#418 A: a `failed` run whose ONLY failure was the deliver phase's LIFT collision (a
+    // rebase conflict the changelog union merge could not clear, or a non-fast-forward push) is
+    // reinterpreted on the wire as `completed` + `delivery: 'stranded'` — recoverable, not a hard
+    // failure. The engine's durable record stays `failed` (audit trail); this is a wire derivation,
+    // exactly like `delivery` itself, applied at the SAME three terminal-status decision points so
+    // the run reads consistently across GET /runs(/:id), resume, and POST /runs/:id/deliver. The
+    // deliver unit stays `rejected` with its marker-bearing `denial_reason`, so WHY it stranded is
+    // still on the wire.
+    //
+    // Returns whether this run IS such a strand — the caller uses it for a BRANCH-based `'stranded'`
+    // read: the engine reaps a failed-deliver run's worktree once the deliver phase has committed
+    // the work (a clean tree), so the work lives on the `wicked/<id>` branch, not the worktree — the
+    // worktree-stat derivation would read `'none'` (and flicker as the async reap lands). The
+    // lift-conflict marker is proof the branch carries the work (the deliver script verified it was
+    // ahead of the default branch before it ever attempted the rebase), so the read is a STABLE
+    // `'stranded'` regardless of whether the worktree survived. Idempotent: a second call sees the
+    // already-flipped `completed` and returns false, so the flip never re-fires.
+    const normalizeStranded = (view) => {
+        const conflictStrand = isDeliverConflictStranded(view); // true only while status === 'failed'
+        if (conflictStrand)
+            view.session.status = 'completed';
+        return conflictStrand;
+    };
+    /** The run's delivery state, honest by construction (crew#393/#311/#418): a recorded PR wins
+     *  (`'delivered'`); else a lift-conflict strand reads `'stranded'` from the branch; else the
+     *  worktree-stat derivation (stranded / vacuous / none). */
+    const resolveDelivery = async (view, conflictStrand) => {
+        const url = deliveryIndex.urlFor(view.session.id);
+        if (url !== undefined)
+            return { delivery: 'delivered', deliverUrl: url };
+        if (conflictStrand)
+            return { delivery: 'stranded' };
+        return deliveryStateWithVacuity(view.session, undefined, vacuityProbes);
+    };
     const decorateRun = async (view) => {
+        const conflictStrand = normalizeStranded(view);
         view.session.project_id = projects.index.projectOf(view.session.id) ?? null;
         const retryOf = retryIndex.retryOfFor(view.session.id);
         if (retryOf !== undefined)
             view.session.retry_of = retryOf;
+        // wicked-studio#27 (api-types 0.19.0): the launch-time group attach, from the same durable
+        // trail record as lineage. ABSENT when ungrouped — never null.
+        const attach = groupIndex.attachOf(view.session.id);
+        if (attach !== undefined) {
+            if ('campaignId' in attach)
+                view.session.campaign_id = attach.campaignId;
+            else
+                view.session.group_label = attach.label;
+        }
         const guidance = guidanceIndex.guidanceFor(view.session.id);
         if (guidance !== undefined)
             view.session.guidance = guidance;
-        const state = await deliveryStateWithVacuity(view.session, deliveryIndex.urlFor(view.session.id), vacuityProbes);
+        const state = await resolveDelivery(view, conflictStrand);
         view.session.delivery = state.delivery;
         if (state.deliverUrl !== undefined)
             view.session.deliverUrl = state.deliverUrl;
@@ -628,9 +690,11 @@ runtime = {}) {
             manifest: {
                 requestType: 'LaunchRunBody',
                 responseType: '{ runId: string }',
-                // 404/409: unknown project / archived-or-synthesized project + busy engine (see the
-                // catch below); 400: zod reject or a retryOf naming no existing run.
-                statusCodes: [201, 400, 404, 409],
+                // 404/409: unknown project / unknown campaignId (wicked-studio#27) /
+                // archived-or-synthesized project + busy engine (see the catch below); 400: zod
+                // reject or a retryOf naming no existing run; 501: campaignId attach on an engine
+                // addon without the campaign bindings ("upgrade the engine").
+                statusCodes: [201, 400, 404, 409, 501],
             },
         },
     }, async (req, reply) => {
@@ -716,6 +780,26 @@ runtime = {}) {
                 });
             }
         }
+        // Ad-hoc campaign attach (wicked-studio#27): `campaignId` must name an EXISTING campaign,
+        // checked BEFORE anything launches — an unknown id is a 404 with nothing committed, never a
+        // run silently filed onto a surface that does not exist. An engine addon without the
+        // campaign bindings is a 501 ("upgrade the engine"), the campaigns-surface doctrine. A
+        // `groupLabel` needs no check: a label group is created by its first use.
+        if (b.campaignId !== undefined) {
+            try {
+                if ((await adapter.campaignDetail(b.campaignId)) === null) {
+                    return reply.code(404).send({
+                        error: `campaignId names an unknown campaign: ${b.campaignId} — an ad-hoc run can only attach to an existing campaign (launch one via POST /campaigns, or use groupLabel for a create-on-first-use group)`,
+                    });
+                }
+            }
+            catch (err) {
+                if (err instanceof CampaignsUnsupportedError) {
+                    return reply.code(501).send({ error: message(err) });
+                }
+                throw err;
+            }
+        }
         try {
             const runId = await adapter.launchRun(input);
             // Who launched it — the engine's LaunchOptions carries no actor field
@@ -734,10 +818,18 @@ runtime = {}) {
                     // CREW-UX-3: the trail is the durable record of lineage — the retry index (and a
                     // restarted daemon's hydrate) reads it back from exactly this entry.
                     ...(b.retryOf !== undefined ? { retryOf: b.retryOf } : {}),
+                    // wicked-studio#27: the trail is likewise the durable record of the group attach —
+                    // the group index (and a restarted daemon's hydrate) reads it back from here.
+                    ...(b.campaignId !== undefined ? { campaignId: b.campaignId } : {}),
+                    ...(b.groupLabel !== undefined ? { groupLabel: b.groupLabel } : {}),
                 },
             });
             if (b.retryOf !== undefined)
                 retryIndex.set(runId, b.retryOf);
+            if (b.campaignId !== undefined)
+                groupIndex.set(runId, { campaignId: b.campaignId });
+            else if (b.groupLabel !== undefined)
+                groupIndex.set(runId, { label: b.groupLabel });
             if (b.projectId !== undefined) {
                 // The engine attached the crew.run membership ATOMICALLY with the launch record
                 // (DES-PROJECT-001 §2.2) — this is the post-commit half: tag future /ws frames and
@@ -852,6 +944,30 @@ runtime = {}) {
     // existing worktree. Idempotent: a delivered run answers its recorded URL, never a second PR.
     // Failure is a loud 4xx/5xx carrying the script's own words — never a silent 200.
     const deliverInFlight = new Set();
+    // Per-REPO serialization for the worktree-admin-sensitive region (reprovision → deliver →
+    // cleanup). deliverInFlight is per-RUN and stops the same run double-delivering, but two
+    // DIFFERENT stranded runs in the same repo would both run `git worktree prune/add/remove`
+    // against one `.git/worktrees` admin state and race. Chaining a promise per repo ref serializes
+    // them; different repos still run in parallel. The tail entry is pruned so the map cannot grow.
+    const repoDeliverChain = new Map();
+    const withRepoDeliverLock = async (repoRef, fn) => {
+        const prior = repoDeliverChain.get(repoRef) ?? Promise.resolve();
+        let release;
+        const mine = new Promise((r) => {
+            release = r;
+        });
+        repoDeliverChain.set(repoRef, mine); // WE are now the tail
+        await prior.catch(() => undefined); // wait our turn; a prior failure never blocks ours
+        try {
+            return await fn();
+        }
+        finally {
+            release(); // unblock whoever chained after us
+            // If nothing chained after us, drop the entry so idle repos leave no trace.
+            if (repoDeliverChain.get(repoRef) === mine)
+                repoDeliverChain.delete(repoRef);
+        }
+    };
     /** The last words of a failed deliver script — enough to name the refusal, bounded so a full
      *  git transcript never becomes an error body. */
     const deliverErrorTail = (output) => {
@@ -880,6 +996,10 @@ runtime = {}) {
         const run = views.find((v) => v.session.id === id);
         if (!run)
             return reply.code(404).send({ error: 'Run not found' });
+        // crew#418 A: a run stranded by a deliver-phase lift collision reads `failed` from the
+        // engine but IS liftable post-hoc — normalize its status to `completed` so this route
+        // accepts it, exactly as the run wire and the resume route see it.
+        const conflictStrand = normalizeStranded(run);
         const s = run.session;
         if (s.status !== 'completed') {
             return reply.code(409).send({
@@ -891,22 +1011,55 @@ runtime = {}) {
                 error: `run ${id} is not repo-scoped — there is no worktree to lift into a PR`,
             });
         }
-        if (!worktreeExists(s.workdir)) {
-            return reply.code(409).send({
-                error: `run ${id}'s worktree is gone (${s.workdir}) — nothing left to deliver`,
-            });
-        }
+        // Capture the ref + workdir while the null-check narrowing is fresh — an intervening await
+        // below invalidates property narrowing, so re-reading `s.repo_ref`/`s.workdir` later widens
+        // back to `| null`.
+        const repoRef = s.repo_ref;
+        const initialWorkdir = s.workdir;
         // One delivery per run at a time: the script pushes and opens a PR, so two concurrent
-        // spawns could race gh into two PRs — the exact double-open idempotency forbids.
+        // spawns could race gh into two PRs — the exact double-open idempotency forbids. The guard
+        // wraps the reprovision too, so a reaped run's `wicked/<id>` branch is only ever checked out
+        // by one throwaway worktree at a time.
         if (deliverInFlight.has(id)) {
             return reply.code(409).send({
                 error: `a delivery for run ${id} is already in progress — wait for it to finish`,
             });
         }
         deliverInFlight.add(id);
+        // The worktree the script runs in. Usually the run's own; but the engine REAPS a
+        // failed-deliver run's worktree once its work is committed (crew#418) — the work then lives
+        // on the `wicked/<id>` branch. For such a strand, stand a throwaway worktree back up from
+        // that branch and lift THAT; the branch (the record) is untouched. `cleanupWorktree` tears
+        // the throwaway down after the lift.
         let result;
+        let worktreeGone = false;
         try {
-            result = await deliverExec(s.workdir, s.problem);
+            // The worktree admin (reprovision), the deliver spawn, AND the throwaway teardown all run
+            // under the per-repo lock, so a second stranded run in this repo cannot touch
+            // `.git/worktrees` until this one has stood its worktree up, lifted, and torn it back
+            // down. `cw` is a LOCAL torn down in the lock body's own finally — nothing captured-mutated
+            // crosses the closure boundary.
+            await withRepoDeliverLock(repoRef, async () => {
+                let workdir = initialWorkdir;
+                let cw = null;
+                try {
+                    if (!worktreeExists(workdir)) {
+                        const root = conflictStrand ? await repoRootOf(repoRef) : undefined;
+                        const reprov = root !== undefined ? await reprovisionWorktree(root, id) : null;
+                        if (reprov === null) {
+                            worktreeGone = true;
+                            return;
+                        }
+                        workdir = reprov.workdir;
+                        cw = reprov.cleanup;
+                    }
+                    result = await deliverExec(workdir, s.problem ?? undefined);
+                }
+                finally {
+                    if (cw !== null)
+                        await cw(); // tear the throwaway down whether the lift succeeded or threw
+                }
+            });
         }
         catch (err) {
             return reply.code(500).send({ error: `deliver script could not run: ${message(err)}` });
@@ -914,6 +1067,15 @@ runtime = {}) {
         finally {
             deliverInFlight.delete(id);
         }
+        if (worktreeGone) {
+            return reply.code(409).send({
+                error: `run ${id}'s worktree is gone (${s.workdir}) — nothing left to deliver`,
+            });
+        }
+        if (result === undefined) {
+            // Unreachable: the lock body assigns `result` on every path that is not `worktreeGone`.
+            return reply.code(500).send({ error: `deliver for run ${id} produced no result` });
+        }
         if (result.spawnFailure === true) {
             // The script never reached its own verdict (spawn failure, timeout kill) — an infra
             // fault, not a refusal: 500 so the caller knows a retry is reasonable.
@@ -1288,6 +1450,10 @@ runtime = {}) {
         const run = views.find((v) => v.session.id === id);
         if (!run)
             return reply.code(404).send({ error: 'Run not found' });
+        // crew#418 A: a run stranded by a deliver-phase lift collision reads `failed` from the engine
+        // but its work is complete and liftable — normalize to `completed` so the terminal branch
+        // below refuses resume with the DELIVER recovery (POST /runs/:id/deliver), not a re-entry.
+        const conflictStrand = normalizeStranded(run);
         // A TERMINAL run is refused LOUDLY, with the actual recovery named (crew#311 defect 2).
         // The engine's `resume_run` no-ops on completed/cancelled and answers the status token, so
         // this route used to reply 200 {"status":"cancelled"} — on the exact runs an operator was
@@ -1297,14 +1463,14 @@ runtime = {}) {
         // The 409 body carries the machine-readable pointer (`ResumeRefusal` in api-types).
         const terminal = run.session.status;
         if (terminal === 'completed' || terminal === 'cancelled') {
-            const state = await deliveryStateWithVacuity(run.session, deliveryIndex.urlFor(id), vacuityProbes);
+            const state = await resolveDelivery(run, conflictStrand);
             const recovery = terminal === 'completed' && state.delivery === 'stranded'
                 ? 'deliver'
                 : 'retry';
             const why = terminal === 'cancelled'
                 ? `run ${id} is cancelled — a terminal run cannot be resumed; relaunch the work as a new run with POST /runs {"retryOf":"${id}"}`
                 : state.delivery === 'stranded'
-                    ? `run ${id} is already completed — nothing to resume; its unlifted work is in the worktree: deliver it with POST /runs/${id}/deliver`
+                    ? `run ${id} is already completed — nothing to resume; its unlifted work is on the wicked/${id} branch: deliver it with POST /runs/${id}/deliver`
                     : state.delivery === 'vacuous'
                         ? `run ${id} is already completed, but VACUOUSLY — its units produced no work to resume or deliver; relaunch with POST /runs {"retryOf":"${id}"}`
                         : `run ${id} is already completed — nothing to resume; relaunch the work as a new run with POST /runs {"retryOf":"${id}"}`;
@@ -2380,11 +2546,16 @@ runtime = {}) {
     registerProjectRoutes(app, adapter, { ...projects, settings: projectSettings }, security);
     // ── Campaigns (crew#342 + TH-9) — the engine's durable Run-DAG scheduler over REST ──────────
     // Progress streams as campaign* CoreEvents on the existing allowlist-free /ws relay; these
-    // routes are launch/resume/cancel + the reads a scoreboard builds from.
+    // routes are launch/resume/cancel + the reads a scoreboard builds from. The GET routes join
+    // per-member delivery (wicked-studio#27) with the SAME machinery the run DTOs use — one
+    // sessionsDetail() per request, the shared TTL-memoized vacuity probes, never a per-node fetch.
     registerCampaignRoutes(app, adapter, {
         audit,
         actorOf,
         roster: () => CoreAdapter.roster(),
+        groupIndex,
+        deliveryUrlFor: (runId) => deliveryIndex.urlFor(runId),
+        vacuity: vacuityProbes,
     });
     // ── Governance wiki management (wiki-mgmt) — scoreboard + honest empty-state meta ──────────
     // Browse (`GET /governance/rules` + facets) and retire (`DELETE /governance/rules/:id`) stay