wicked-crew 0.7.9 → 0.7.11

package/dist/api/group-index.d.ts

@@ -0,0 +1,59 @@
+/**
+ * The run→ad-hoc-group index (wicked-studio#27; api-types 0.19.0).
+ *
+ * Ad-hoc sibling runs launched via `POST /runs` can be filed onto a grouping surface at launch:
+ * `campaignId` attaches the run to an EXISTING engine campaign (validated loudly — an unknown id
+ * fails the launch), `groupLabel` puts it in a label group created on first use. Either way the
+ * attach is daemon-side PROVENANCE only: the engine's run record carries no such field (the run
+ * executes byte-identically to an ungrouped launch, and the campaign scheduler never learns of
+ * it), so — exactly like retry lineage (CREW-UX-3) and the actor trail (task #88) — the durable
+ * record is the `run.launched` audit entry (`detail.campaignId` / `detail.groupLabel`), and this
+ * map is the read-side latency layer that lets `GET /runs` echo `campaign_id`/`group_label` and
+ * `GET /campaigns` serve `attached_runs` + the `groups` rows without a trail scan per request.
+ *
+ * Mirrors `RetryIndex`'s posture: hydrated once at server start (best-effort — a missing or
+ * unreadable trail leaves prior runs ungrouped, the pre-0.19 behavior, not an error) and updated
+ * at the same post-commit point that writes the audit entry, so the map can only lag by a failed
+ * hydrate, never diverge silently.
+ *
+ * SCAN BUDGET: this index consumes the SAME `run.launched` entries `RetryIndex` already scans,
+ * so it exposes {@link GroupIndex.hydrateFromLaunchEntries} and `createServer` feeds both
+ * indexes from ONE `readAll({ action: 'run.launched' })` — boot stays at three full-file trail
+ * scans, not four (the delivery-index consolidation note, crew#321).
+ */
+import type { AuditLog } from './audit.js';
+import type { AuditEntry } from '../core/types.js';
+/** One launch's group attach: exactly one of the two forms (the launch route enforces it). */
+export type GroupAttach = {
+    campaignId: string;
+} | {
+    label: string;
+};
+export declare class GroupIndex {
+    private readonly runToAttach;
+    /** campaignId → attached run ids, launch order. */
+    private readonly campaignRuns;
+    /** label → member run ids, launch order. */
+    private readonly labelRuns;
+    /**
+     * Consume pre-read `run.launched` entries (NEWEST FIRST, `AuditLog.readAll`'s order —
+     * exhaustive, per BRIEF-UX-002 C5). The first entry seen per run wins, like the sibling
+     * indexes; member lists come out in LAUNCH order because insertion happens on a reversed
+     * walk. Idempotent per boot (called once).
+     */
+    hydrateFromLaunchEntries(entries: AuditEntry[]): void;
+    /** Standalone hydrate (tests / direct use) — production shares the scan via `createServer`. */
+    hydrate(audit: AuditLog, log?: (msg: string) => void): Promise<void>;
+    /** Record one launch's attach (post-commit, beside the audit write). */
+    set(runId: string, attach: GroupAttach): void;
+    /** This run's attach, or `undefined` (the DTO spells that as ABSENT fields). */
+    attachOf(runId: string): GroupAttach | undefined;
+    /** Run ids attached to this campaign, launch order (`[]` when none). */
+    attachedTo(campaignId: string): string[];
+    /** Every label group: `{ label, runIds }` in first-use order, members in launch order. */
+    labelGroups(): Array<{
+        label: string;
+        runIds: string[];
+    }>;
+}
+//# sourceMappingURL=group-index.d.ts.map

package/dist/api/group-index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"group-index.d.ts","sourceRoot":"","sources":["../../src/api/group-index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAC3C,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAEnD,8FAA8F;AAC9F,MAAM,MAAM,WAAW,GAAG;IAAE,UAAU,EAAE,MAAM,CAAA;CAAE,GAAG;IAAE,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC;AAErE,qBAAa,UAAU;IACrB,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAkC;IAC9D,mDAAmD;IACnD,OAAO,CAAC,QAAQ,CAAC,YAAY,CAA+B;IAC5D,4CAA4C;IAC5C,OAAO,CAAC,QAAQ,CAAC,SAAS,CAA+B;IAEzD;;;;;OAKG;IACH,wBAAwB,CAAC,OAAO,EAAE,UAAU,EAAE,GAAG,IAAI;IAoBrD,+FAA+F;IACzF,OAAO,CAAC,KAAK,EAAE,QAAQ,EAAE,GAAG,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;IAY1E,wEAAwE;IACxE,GAAG,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,WAAW,GAAG,IAAI;IAc7C,gFAAgF;IAChF,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,WAAW,GAAG,SAAS;IAIhD,wEAAwE;IACxE,UAAU,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,EAAE;IAIxC,0FAA0F;IAC1F,WAAW,IAAI,KAAK,CAAC;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,EAAE,CAAA;KAAE,CAAC;CAM1D"}

package/dist/api/group-index.js

@@ -0,0 +1,100 @@
+/**
+ * The run→ad-hoc-group index (wicked-studio#27; api-types 0.19.0).
+ *
+ * Ad-hoc sibling runs launched via `POST /runs` can be filed onto a grouping surface at launch:
+ * `campaignId` attaches the run to an EXISTING engine campaign (validated loudly — an unknown id
+ * fails the launch), `groupLabel` puts it in a label group created on first use. Either way the
+ * attach is daemon-side PROVENANCE only: the engine's run record carries no such field (the run
+ * executes byte-identically to an ungrouped launch, and the campaign scheduler never learns of
+ * it), so — exactly like retry lineage (CREW-UX-3) and the actor trail (task #88) — the durable
+ * record is the `run.launched` audit entry (`detail.campaignId` / `detail.groupLabel`), and this
+ * map is the read-side latency layer that lets `GET /runs` echo `campaign_id`/`group_label` and
+ * `GET /campaigns` serve `attached_runs` + the `groups` rows without a trail scan per request.
+ *
+ * Mirrors `RetryIndex`'s posture: hydrated once at server start (best-effort — a missing or
+ * unreadable trail leaves prior runs ungrouped, the pre-0.19 behavior, not an error) and updated
+ * at the same post-commit point that writes the audit entry, so the map can only lag by a failed
+ * hydrate, never diverge silently.
+ *
+ * SCAN BUDGET: this index consumes the SAME `run.launched` entries `RetryIndex` already scans,
+ * so it exposes {@link GroupIndex.hydrateFromLaunchEntries} and `createServer` feeds both
+ * indexes from ONE `readAll({ action: 'run.launched' })` — boot stays at three full-file trail
+ * scans, not four (the delivery-index consolidation note, crew#321).
+ */
+export class GroupIndex {
+    runToAttach = new Map();
+    /** campaignId → attached run ids, launch order. */
+    campaignRuns = new Map();
+    /** label → member run ids, launch order. */
+    labelRuns = new Map();
+    /**
+     * Consume pre-read `run.launched` entries (NEWEST FIRST, `AuditLog.readAll`'s order —
+     * exhaustive, per BRIEF-UX-002 C5). The first entry seen per run wins, like the sibling
+     * indexes; member lists come out in LAUNCH order because insertion happens on a reversed
+     * walk. Idempotent per boot (called once).
+     */
+    hydrateFromLaunchEntries(entries) {
+        const seen = new Set();
+        const oldestFirst = [];
+        for (const entry of entries) {
+            if (typeof entry.runId !== 'string')
+                continue;
+            if (seen.has(entry.runId))
+                continue;
+            seen.add(entry.runId);
+            const campaignId = entry.detail?.['campaignId'];
+            const label = entry.detail?.['groupLabel'];
+            if (typeof campaignId === 'string' && campaignId !== '') {
+                oldestFirst.push({ runId: entry.runId, attach: { campaignId } });
+            }
+            else if (typeof label === 'string' && label !== '') {
+                oldestFirst.push({ runId: entry.runId, attach: { label } });
+            }
+        }
+        // The trail reads newest-first; one reverse restores launch order (unshift-in-loop is O(n²)).
+        oldestFirst.reverse();
+        for (const { runId, attach } of oldestFirst)
+            this.set(runId, attach);
+    }
+    /** Standalone hydrate (tests / direct use) — production shares the scan via `createServer`. */
+    async hydrate(audit, log) {
+        try {
+            this.hydrateFromLaunchEntries(await audit.readAll({ action: 'run.launched' }));
+        }
+        catch (err) {
+            log?.(`[runs] group-index hydrate failed (prior runs read as ungrouped until restart): ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
+    /** Record one launch's attach (post-commit, beside the audit write). */
+    set(runId, attach) {
+        if (this.runToAttach.has(runId))
+            return; // launch-time fact — first write wins
+        this.runToAttach.set(runId, attach);
+        if ('campaignId' in attach) {
+            const list = this.campaignRuns.get(attach.campaignId) ?? [];
+            list.push(runId);
+            this.campaignRuns.set(attach.campaignId, list);
+        }
+        else {
+            const list = this.labelRuns.get(attach.label) ?? [];
+            list.push(runId);
+            this.labelRuns.set(attach.label, list);
+        }
+    }
+    /** This run's attach, or `undefined` (the DTO spells that as ABSENT fields). */
+    attachOf(runId) {
+        return this.runToAttach.get(runId);
+    }
+    /** Run ids attached to this campaign, launch order (`[]` when none). */
+    attachedTo(campaignId) {
+        return [...(this.campaignRuns.get(campaignId) ?? [])];
+    }
+    /** Every label group: `{ label, runIds }` in first-use order, members in launch order. */
+    labelGroups() {
+        return [...this.labelRuns.entries()].map(([label, runIds]) => ({
+            label,
+            runIds: [...runIds],
+        }));
+    }
+}
+//# sourceMappingURL=group-index.js.map

package/dist/api/group-index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"group-index.js","sourceRoot":"","sources":["../../src/api/group-index.ts"],"names":[],"mappings":"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"}

package/dist/api/retry-index.d.ts

@@ -13,8 +13,14 @@
  * the audit entry, so the map can only lag by a failed hydrate, never diverge silently.
  */
 import type { AuditLog } from './audit.js';
+import type { AuditEntry } from '../core/types.js';
 export declare class RetryIndex {
     private readonly runToRetryOf;
+    /**
+     * Consume pre-read `run.launched` entries — the seam that lets `createServer` feed this index
+     * and `GroupIndex` from ONE trail scan (the delivery-index consolidation note, crew#321).
+     */
+    hydrateFromLaunchEntries(entries: AuditEntry[]): void;
     /**
      * Load lineage from EVERY `run.launched` entry in the trail — exhaustively, not capped
      * (BRIEF-UX-002 C5: a lineage fact 2,678 launches deep must survive a restart; the newest-1000

package/dist/api/retry-index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"retry-index.d.ts","sourceRoot":"","sources":["../../src/api/retry-index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAE3C,qBAAa,UAAU;IACrB,OAAO,CAAC,QAAQ,CAAC,YAAY,CAA6B;IAE1D;;;;;;OAMG;IACG,OAAO,CAAC,KAAK,EAAE,QAAQ,EAAE,GAAG,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;IAiB1E,GAAG,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI;IAIzC,4FAA4F;IAC5F,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS;CAG9C"}
+{"version":3,"file":"retry-index.d.ts","sourceRoot":"","sources":["../../src/api/retry-index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAC3C,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAEnD,qBAAa,UAAU;IACrB,OAAO,CAAC,QAAQ,CAAC,YAAY,CAA6B;IAE1D;;;OAGG;IACH,wBAAwB,CAAC,OAAO,EAAE,UAAU,EAAE,GAAG,IAAI;IASrD;;;;;;OAMG;IACG,OAAO,CAAC,KAAK,EAAE,QAAQ,EAAE,GAAG,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;IAY1E,GAAG,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI;IAIzC,4FAA4F;IAC5F,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS;CAG9C"}

package/dist/api/retry-index.js

@@ -14,6 +14,18 @@
  */
 export class RetryIndex {
     runToRetryOf = new Map();
+    /**
+     * Consume pre-read `run.launched` entries — the seam that lets `createServer` feed this index
+     * and `GroupIndex` from ONE trail scan (the delivery-index consolidation note, crew#321).
+     */
+    hydrateFromLaunchEntries(entries) {
+        for (const entry of entries) {
+            const retryOf = entry.detail?.['retryOf'];
+            if (typeof entry.runId === 'string' && typeof retryOf === 'string') {
+                this.runToRetryOf.set(entry.runId, retryOf);
+            }
+        }
+    }
     /**
      * Load lineage from EVERY `run.launched` entry in the trail — exhaustively, not capped
      * (BRIEF-UX-002 C5: a lineage fact 2,678 launches deep must survive a restart; the newest-1000
@@ -23,12 +35,7 @@ export class RetryIndex {
      */
     async hydrate(audit, log) {
         try {
-            for (const entry of await audit.readAll({ action: 'run.launched' })) {
-                const retryOf = entry.detail?.['retryOf'];
-                if (typeof entry.runId === 'string' && typeof retryOf === 'string') {
-                    this.runToRetryOf.set(entry.runId, retryOf);
-                }
-            }
+            this.hydrateFromLaunchEntries(await audit.readAll({ action: 'run.launched' }));
         }
         catch (err) {
             log?.(`[runs] retry-index hydrate failed (prior runs read as not-a-retry until restart): ${err instanceof Error ? err.message : String(err)}`);

package/dist/api/retry-index.js.map

@@ -1 +1 @@
-{"version":3,"file":"retry-index.js","sourceRoot":"","sources":["../../src/api/retry-index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAIH,MAAM,OAAO,UAAU;IACJ,YAAY,GAAG,IAAI,GAAG,EAAkB,CAAC;IAE1D;;;;;;OAMG;IACH,KAAK,CAAC,OAAO,CAAC,KAAe,EAAE,GAA2B;QACxD,IAAI,CAAC;YACH,KAAK,MAAM,KAAK,IAAI,MAAM,KAAK,CAAC,OAAO,CAAC,EAAE,MAAM,EAAE,cAAc,EAAE,CAAC,EAAE,CAAC;gBACpE,MAAM,OAAO,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC,SAAS,CAAC,CAAC;gBAC1C,IAAI,OAAO,KAAK,CAAC,KAAK,KAAK,QAAQ,IAAI,OAAO,OAAO,KAAK,QAAQ,EAAE,CAAC;oBACnE,IAAI,CAAC,YAAY,CAAC,GAAG,CAAC,KAAK,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC;gBAC9C,CAAC;YACH,CAAC;QACH,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,GAAG,EAAE,CACH,qFACE,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CACjD,EAAE,CACH,CAAC;QACJ,CAAC;IACH,CAAC;IAED,GAAG,CAAC,KAAa,EAAE,OAAe;QAChC,IAAI,CAAC,YAAY,CAAC,GAAG,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC;IACxC,CAAC;IAED,4FAA4F;IAC5F,UAAU,CAAC,KAAa;QACtB,OAAO,IAAI,CAAC,YAAY,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;IACtC,CAAC;CACF"}
+{"version":3,"file":"retry-index.js","sourceRoot":"","sources":["../../src/api/retry-index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAKH,MAAM,OAAO,UAAU;IACJ,YAAY,GAAG,IAAI,GAAG,EAAkB,CAAC;IAE1D;;;OAGG;IACH,wBAAwB,CAAC,OAAqB;QAC5C,KAAK,MAAM,KAAK,IAAI,OAAO,EAAE,CAAC;YAC5B,MAAM,OAAO,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC,SAAS,CAAC,CAAC;YAC1C,IAAI,OAAO,KAAK,CAAC,KAAK,KAAK,QAAQ,IAAI,OAAO,OAAO,KAAK,QAAQ,EAAE,CAAC;gBACnE,IAAI,CAAC,YAAY,CAAC,GAAG,CAAC,KAAK,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC;YAC9C,CAAC;QACH,CAAC;IACH,CAAC;IAED;;;;;;OAMG;IACH,KAAK,CAAC,OAAO,CAAC,KAAe,EAAE,GAA2B;QACxD,IAAI,CAAC;YACH,IAAI,CAAC,wBAAwB,CAAC,MAAM,KAAK,CAAC,OAAO,CAAC,EAAE,MAAM,EAAE,cAAc,EAAE,CAAC,CAAC,CAAC;QACjF,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,GAAG,EAAE,CACH,qFACE,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CACjD,EAAE,CACH,CAAC;QACJ,CAAC;IACH,CAAC;IAED,GAAG,CAAC,KAAa,EAAE,OAAe;QAChC,IAAI,CAAC,YAAY,CAAC,GAAG,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC;IACxC,CAAC;IAED,4FAA4F;IAC5F,UAAU,CAAC,KAAa;QACtB,OAAO,IAAI,CAAC,YAAY,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;IACtC,CAAC;CACF"}

package/dist/api/routes.d.ts

@@ -11,6 +11,7 @@ import type { DocLedgerSweep } from '../interactive/doc-ledger-sweep.js';
 import { AuditLog } from './audit.js';
 import { type ErrorRing } from './diagnostics.js';
 import { RetryIndex } from './retry-index.js';
+import { GroupIndex } from './group-index.js';
 import { GuidanceIndex } from './guidance-index.js';
 import { DeliveryIndex } from './delivery-index.js';
 import { type DeliverExec } from './post-hoc-deliver.js';
@@ -29,7 +30,7 @@ export { API_PREFIX } from './api-prefix.js';
  * schema does not accept — so `.strict()` is what turns that trip into a 400 instead of an
  * unworkflowed run reported as `201`.
  */
-export declare const LaunchSchema: z.ZodEffects<z.ZodObject<{
+export declare const LaunchSchema: z.ZodEffects<z.ZodEffects<z.ZodObject<{
     problem: z.ZodString;
     sessionId: z.ZodOptional<z.ZodString>;
     clisJson: z.ZodOptional<z.ZodString>;
@@ -52,10 +53,22 @@ export declare const LaunchSchema: z.ZodEffects<z.ZodObject<{
      *  (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.ZodOptional<z.ZodString>;
+    /** 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.ZodOptional<z.ZodString>;
+    /** 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.ZodOptional<z.ZodString>;
 }, "strict", z.ZodTypeAny, {
     problem: string;
     deliver?: "pr" | "none" | undefined;
     projectId?: string | undefined;
+    campaignId?: string | undefined;
+    groupLabel?: string | undefined;
     workflow?: string | undefined;
     repoRef?: string | undefined;
     clisJson?: string | undefined;
@@ -67,6 +80,8 @@ export declare const LaunchSchema: z.ZodEffects<z.ZodObject<{
     problem: string;
     deliver?: "pr" | "none" | undefined;
     projectId?: string | undefined;
+    campaignId?: string | undefined;
+    groupLabel?: string | undefined;
     workflow?: string | undefined;
     repoRef?: string | undefined;
     clisJson?: string | undefined;
@@ -78,6 +93,8 @@ export declare const LaunchSchema: z.ZodEffects<z.ZodObject<{
     problem: string;
     deliver?: "pr" | "none" | undefined;
     projectId?: string | undefined;
+    campaignId?: string | undefined;
+    groupLabel?: string | undefined;
     workflow?: string | undefined;
     repoRef?: string | undefined;
     clisJson?: string | undefined;
@@ -89,6 +106,34 @@ export declare const LaunchSchema: z.ZodEffects<z.ZodObject<{
     problem: string;
     deliver?: "pr" | "none" | undefined;
     projectId?: string | undefined;
+    campaignId?: string | undefined;
+    groupLabel?: string | undefined;
+    workflow?: string | undefined;
+    repoRef?: string | undefined;
+    clisJson?: string | undefined;
+    sessionId?: string | undefined;
+    retryOf?: string | undefined;
+    entityMode?: "shared" | "isolated" | undefined;
+    humanConfirm?: string | undefined;
+}>, {
+    problem: string;
+    deliver?: "pr" | "none" | undefined;
+    projectId?: string | undefined;
+    campaignId?: string | undefined;
+    groupLabel?: string | undefined;
+    workflow?: string | undefined;
+    repoRef?: string | undefined;
+    clisJson?: string | undefined;
+    sessionId?: string | undefined;
+    retryOf?: string | undefined;
+    entityMode?: "shared" | "isolated" | undefined;
+    humanConfirm?: string | undefined;
+}, {
+    problem: string;
+    deliver?: "pr" | "none" | undefined;
+    projectId?: string | undefined;
+    campaignId?: string | undefined;
+    groupLabel?: string | undefined;
     workflow?: string | undefined;
     repoRef?: string | undefined;
     clisJson?: string | undefined;
@@ -162,6 +207,10 @@ export interface RuntimeDeps {
     /** Run→retry-lineage index (CREW-UX-3) — `createServer` hydrates one from the audit trail so
      *  a restarted daemon still echoes `retry_of`; a directly-driven route set gets a fresh one. */
     retryIndex?: RetryIndex;
+    /** Run→ad-hoc-group index (wicked-studio#27) — `createServer` hydrates one from the audit
+     *  trail (the SAME `run.launched` scan as `retryIndex`) so attaches survive a restart; a
+     *  directly-driven route set gets a fresh one. */
+    groupIndex?: GroupIndex;
     /** Run→operator-guidance index (CREW-UX-7) — `createServer` hydrates one from the audit trail
      *  so a restarted daemon still echoes `guidance`; a directly-driven route set gets a fresh one. */
     guidanceIndex?: GuidanceIndex;

package/dist/api/routes.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"routes.d.ts","sourceRoot":"","sources":["../../src/api/routes.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"routes.d.ts","sourceRoot":"","sources":["../../src/api/routes.ts"],"names":[],"mappings":"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"}

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,6 +32,7 @@ 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';
@@ -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));
@@ -265,6 +280,15 @@ runtime = {}) {
         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;
@@ -628,9 +652,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 +742,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 +780,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
@@ -2380,11 +2434,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