@w3kits-com/plugin-opendesign 0.1.8 → 0.1.9

package/dist/__w3kits/webcontainer-runtime/apps/daemon/dist/critique/rollout.js

@@ -0,0 +1,125 @@
+/**
+ * Critique Theater rollout-flag plumbing (Phase 15).
+ *
+ * The plan's rollout track is M0 dark-launch -> M1 settings toggle ->
+ * M2 default-on per skill -> M3 global default. This module is the
+ * intended single decision point every backend caller will consult
+ * to answer "should the orchestrator wire the critique pipeline for
+ * this run?"
+ *
+ * What ships in Phase 15:
+ *
+ *   - `isCritiqueEnabled` as a pure resolver function plus its
+ *     supporting parsers (`parseRolloutPhase`, `parseEnvEnabled`).
+ *     Full unit coverage of the priority matrix.
+ *
+ * Planned consumers (not yet wired; each lands in a focused
+ * follow-up PR):
+ *
+ *   - The orchestrator entry in `apps/daemon/src/server.ts`, before
+ *     it spawns the critique CLI adapter for a generation. The
+ *     current spawn gate still reads `critiqueCfg.enabled` directly;
+ *     swapping that to `isCritiqueEnabled({...})` is the one-line
+ *     change the wireup PR makes.
+ *   - A future settings endpoint that echoes the resolved value to
+ *     the Settings UI. The endpoint does not ship in Phase 15;
+ *     `setCritiqueTheaterEnabled` on the web side is localStorage-
+ *     only this phase, with daemon persistence deferred to the
+ *     Settings UI PR.
+ *   - The conformance harness, so a nightly cycle can run against an
+ *     adapter even when the human-facing flag is off.
+ *
+ * Operators who want to enable the feature today should set
+ * `OD_CRITIQUE_ENABLED=1` rather than relying on the client toggle,
+ * because the spawn-time gate has not been re-pointed at this
+ * resolver yet. The resolver itself is correct and ready; the wiring
+ * change is the only blocker.
+ *
+ * Resolution order (highest priority first):
+ *
+ *   1. Per-skill override declared in `SKILL.md` frontmatter
+ *      (`od.critique.policy: required | opt-in | opt-out`).
+ *   2. Per-project override stored in the project settings table
+ *      (the M1 Settings toggle will write here once the Settings UI
+ *      follow-up adds the daemon-side write path).
+ *   3. Environment override (`OD_CRITIQUE_ENABLED=1`). Useful for
+ *      power users and CI fixtures.
+ *   4. Global default. M0 / M1 = false. M2 = true for skills tagged
+ *      `od.critique.policy: required`. M3 = true globally.
+ */
+/**
+ * Returns `true` when the orchestrator should run the critique
+ * pipeline for this generation. Returns `false` when it should skip.
+ *
+ * Decision matrix (first row that matches wins):
+ *
+ *   skillPolicy === 'opt-out'         -> false
+ *   skillPolicy === 'required'        -> true
+ *   projectOverride !== null          -> projectOverride
+ *   envOverride !== null              -> envOverride
+ *   phase === 'M0'                    -> false
+ *   phase === 'M1'                    -> false
+ *   phase === 'M2'                    -> skillPolicy === 'opt-in'
+ *   phase === 'M3'                    -> true
+ */
+export function isCritiqueEnabled(input) {
+    // Skill-level vetoes win unconditionally. A skill that explicitly
+    // opts out cannot have critique forced on it by an env var or a
+    // global rollout; a skill that opts in cannot be vetoed.
+    if (input.skillPolicy === 'opt-out')
+        return false;
+    if (input.skillPolicy === 'required')
+        return true;
+    // Project-level override is the M1 Settings toggle. A user who
+    // explicitly enables or disables critique for a project beats the
+    // env default and the global rollout phase.
+    if (input.projectOverride !== null)
+        return input.projectOverride;
+    // Env override is the power-user lane (CI fixtures, beta access).
+    if (input.envOverride !== null)
+        return input.envOverride;
+    // Otherwise fall through to the rollout phase default.
+    switch (input.phase) {
+        case 'M0':
+        case 'M1':
+            return false;
+        case 'M2':
+            return input.skillPolicy === 'opt-in';
+        case 'M3':
+            return true;
+    }
+}
+/**
+ * Parse the `OD_CRITIQUE_ROLLOUT_PHASE` env var into a `RolloutPhase`.
+ * Defaults to `M0` (dark-launch) when the value is missing or unknown
+ * so a fresh install never surprises users with the feature on.
+ */
+export function parseRolloutPhase(raw) {
+    switch ((raw ?? '').trim().toUpperCase()) {
+        case 'M1':
+            return 'M1';
+        case 'M2':
+            return 'M2';
+        case 'M3':
+            return 'M3';
+        default:
+            return 'M0';
+    }
+}
+/**
+ * Parse `OD_CRITIQUE_ENABLED`. Recognises the canonical truthy /
+ * falsy strings; returns `null` when the env var is unset so the
+ * resolver knows to fall through to the rollout phase default
+ * rather than treating "missing" as an explicit `false`.
+ */
+export function parseEnvEnabled(raw) {
+    if (raw === undefined || raw === '')
+        return null;
+    const v = raw.trim().toLowerCase();
+    if (v === '1' || v === 'true' || v === 'yes' || v === 'on')
+        return true;
+    if (v === '0' || v === 'false' || v === 'no' || v === 'off')
+        return false;
+    return null;
+}
+//# sourceMappingURL=rollout.js.map

package/dist/__w3kits/webcontainer-runtime/apps/daemon/dist/critique/rollout.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rollout.js","sourceRoot":"","sources":["../../src/critique/rollout.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgDG;AAoBH;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,iBAAiB,CAAC,KAAoB;IACpD,kEAAkE;IAClE,gEAAgE;IAChE,yDAAyD;IACzD,IAAI,KAAK,CAAC,WAAW,KAAK,SAAS;QAAE,OAAO,KAAK,CAAC;IAClD,IAAI,KAAK,CAAC,WAAW,KAAK,UAAU;QAAE,OAAO,IAAI,CAAC;IAElD,+DAA+D;IAC/D,kEAAkE;IAClE,4CAA4C;IAC5C,IAAI,KAAK,CAAC,eAAe,KAAK,IAAI;QAAE,OAAO,KAAK,CAAC,eAAe,CAAC;IAEjE,kEAAkE;IAClE,IAAI,KAAK,CAAC,WAAW,KAAK,IAAI;QAAE,OAAO,KAAK,CAAC,WAAW,CAAC;IAEzD,uDAAuD;IACvD,QAAQ,KAAK,CAAC,KAAK,EAAE,CAAC;QACpB,KAAK,IAAI,CAAC;QACV,KAAK,IAAI;YACP,OAAO,KAAK,CAAC;QACf,KAAK,IAAI;YACP,OAAO,KAAK,CAAC,WAAW,KAAK,QAAQ,CAAC;QACxC,KAAK,IAAI;YACP,OAAO,IAAI,CAAC;IAChB,CAAC;AACH,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,iBAAiB,CAAC,GAAuB;IACvD,QAAQ,CAAC,GAAG,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,EAAE,CAAC;QACzC,KAAK,IAAI;YACP,OAAO,IAAI,CAAC;QACd,KAAK,IAAI;YACP,OAAO,IAAI,CAAC;QACd,KAAK,IAAI;YACP,OAAO,IAAI,CAAC;QACd;YACE,OAAO,IAAI,CAAC;IAChB,CAAC;AACH,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,eAAe,CAAC,GAAuB;IACrD,IAAI,GAAG,KAAK,SAAS,IAAI,GAAG,KAAK,EAAE;QAAE,OAAO,IAAI,CAAC;IACjD,MAAM,CAAC,GAAG,GAAG,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;IACnC,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC,KAAK,MAAM,IAAI,CAAC,KAAK,KAAK,IAAI,CAAC,KAAK,IAAI;QAAE,OAAO,IAAI,CAAC;IACxE,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC,KAAK,OAAO,IAAI,CAAC,KAAK,IAAI,IAAI,CAAC,KAAK,KAAK;QAAE,OAAO,KAAK,CAAC;IAC1E,OAAO,IAAI,CAAC;AACd,CAAC"}

package/dist/__w3kits/webcontainer-runtime/apps/daemon/dist/critique/run-registry.d.ts

@@ -0,0 +1,59 @@
+/**
+ * In-process registry of in-flight critique runs. The daemon process is the
+ * single owner of all critique state; the registry exists so the interrupt
+ * endpoint can cascade an AbortController to the orchestrator that owns the
+ * spawned CLI. The registry is intentionally NOT persisted: a daemon restart
+ * mid-run is handled by reconcileStaleRuns on boot, not by recovering live
+ * AbortControllers.
+ *
+ * All lookup operations require BOTH projectId and runId. The composite key
+ * prevents a request to interrupt project p1's runId from accidentally
+ * aborting project p2's run that happens to share the same id (defense in
+ * depth on top of the HTTP handler's own DB-row projectId check).
+ *
+ * @see specs/current/critique-theater.md § Failure modes (interrupt)
+ */
+/** Handle for a single in-flight critique run. */
+export interface RunHandle {
+    runId: string;
+    projectId: string;
+    abort: AbortController;
+    startedAt: number;
+}
+/** Public surface of the in-process run registry. */
+export interface RunRegistry {
+    /**
+     * Register a new in-flight handle. Throws if a handle for the same
+     * (projectId, runId) is already registered (indicates a bug in the caller,
+     * not a user error).
+     */
+    register(handle: RunHandle): void;
+    /**
+     * Returns the handle if the (projectId, runId) pair is registered; null
+     * otherwise. A runId from a different project will not match.
+     */
+    get(projectId: string, runId: string): RunHandle | null;
+    /**
+     * Signals the AbortController for the given (projectId, runId).
+     * Returns true if the pair was found and aborted; false otherwise. A
+     * runId-only match against a different project does NOT abort.
+     */
+    interrupt(projectId: string, runId: string, reason?: string): boolean;
+    /**
+     * Removes the entry for the given (projectId, runId). Called by the server
+     * after the orchestrator settles. No-op if the pair is not registered.
+     */
+    unregister(projectId: string, runId: string): void;
+    /**
+     * Snapshot for diagnostics only. Returns a defensive copy so callers cannot
+     * mutate the registry's internal state.
+     */
+    list(): RunHandle[];
+}
+/**
+ * Creates an in-memory RunRegistry backed by a Map.
+ * Node is single-threaded; no locking is needed.
+ *
+ * @see specs/current/critique-theater.md § interrupt endpoint (Task 6.1)
+ */
+export declare function createRunRegistry(): RunRegistry;

package/dist/__w3kits/webcontainer-runtime/apps/daemon/dist/critique/run-registry.js

@@ -0,0 +1,58 @@
+/**
+ * In-process registry of in-flight critique runs. The daemon process is the
+ * single owner of all critique state; the registry exists so the interrupt
+ * endpoint can cascade an AbortController to the orchestrator that owns the
+ * spawned CLI. The registry is intentionally NOT persisted: a daemon restart
+ * mid-run is handled by reconcileStaleRuns on boot, not by recovering live
+ * AbortControllers.
+ *
+ * All lookup operations require BOTH projectId and runId. The composite key
+ * prevents a request to interrupt project p1's runId from accidentally
+ * aborting project p2's run that happens to share the same id (defense in
+ * depth on top of the HTTP handler's own DB-row projectId check).
+ *
+ * @see specs/current/critique-theater.md § Failure modes (interrupt)
+ */
+/**
+ * Builds the internal composite key for a (projectId, runId) pair. Pipe is
+ * not a legal character in either projectId or runId per the daemon's id
+ * generation rules, so collisions across pairs are impossible.
+ */
+function compositeKey(projectId, runId) {
+    return `${projectId}|${runId}`;
+}
+/**
+ * Creates an in-memory RunRegistry backed by a Map.
+ * Node is single-threaded; no locking is needed.
+ *
+ * @see specs/current/critique-theater.md § interrupt endpoint (Task 6.1)
+ */
+export function createRunRegistry() {
+    const store = new Map();
+    return {
+        register(handle) {
+            const key = compositeKey(handle.projectId, handle.runId);
+            if (store.has(key)) {
+                throw new Error(`RunRegistry: duplicate (projectId="${handle.projectId}", runId="${handle.runId}"); unregister before re-registering`);
+            }
+            store.set(key, handle);
+        },
+        get(projectId, runId) {
+            return store.get(compositeKey(projectId, runId)) ?? null;
+        },
+        interrupt(projectId, runId, reason) {
+            const handle = store.get(compositeKey(projectId, runId));
+            if (handle === undefined)
+                return false;
+            handle.abort.abort(reason);
+            return true;
+        },
+        unregister(projectId, runId) {
+            store.delete(compositeKey(projectId, runId));
+        },
+        list() {
+            return [...store.values()];
+        },
+    };
+}
+//# sourceMappingURL=run-registry.js.map

package/dist/__w3kits/webcontainer-runtime/apps/daemon/dist/critique/run-registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"run-registry.js","sourceRoot":"","sources":["../../src/critique/run-registry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AA6CH;;;;GAIG;AACH,SAAS,YAAY,CAAC,SAAiB,EAAE,KAAa;IACpD,OAAO,GAAG,SAAS,IAAI,KAAK,EAAE,CAAC;AACjC,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,iBAAiB;IAC/B,MAAM,KAAK,GAAG,IAAI,GAAG,EAAqB,CAAC;IAE3C,OAAO;QACL,QAAQ,CAAC,MAAiB;YACxB,MAAM,GAAG,GAAG,YAAY,CAAC,MAAM,CAAC,SAAS,EAAE,MAAM,CAAC,KAAK,CAAC,CAAC;YACzD,IAAI,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC;gBACnB,MAAM,IAAI,KAAK,CACb,sCAAsC,MAAM,CAAC,SAAS,aAAa,MAAM,CAAC,KAAK,sCAAsC,CACtH,CAAC;YACJ,CAAC;YACD,KAAK,CAAC,GAAG,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC;QACzB,CAAC;QAED,GAAG,CAAC,SAAiB,EAAE,KAAa;YAClC,OAAO,KAAK,CAAC,GAAG,CAAC,YAAY,CAAC,SAAS,EAAE,KAAK,CAAC,CAAC,IAAI,IAAI,CAAC;QAC3D,CAAC;QAED,SAAS,CAAC,SAAiB,EAAE,KAAa,EAAE,MAAe;YACzD,MAAM,MAAM,GAAG,KAAK,CAAC,GAAG,CAAC,YAAY,CAAC,SAAS,EAAE,KAAK,CAAC,CAAC,CAAC;YACzD,IAAI,MAAM,KAAK,SAAS;gBAAE,OAAO,KAAK,CAAC;YACvC,MAAM,CAAC,KAAK,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;YAC3B,OAAO,IAAI,CAAC;QACd,CAAC;QAED,UAAU,CAAC,SAAiB,EAAE,KAAa;YACzC,KAAK,CAAC,MAAM,CAAC,YAAY,CAAC,SAAS,EAAE,KAAK,CAAC,CAAC,CAAC;QAC/C,CAAC;QAED,IAAI;YACF,OAAO,CAAC,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC,CAAC;QAC7B,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/__w3kits/webcontainer-runtime/apps/daemon/dist/critique/scoreboard.d.ts

@@ -0,0 +1,39 @@
+import type { CritiqueConfig, PanelistRole, RoundDecision } from '@open-design/contracts/critique';
+/**
+ * Per-round scores indexed by panelist role. Absent roles are undefined.
+ * @see specs/current/critique-theater.md § Composite score formula
+ */
+export type RoleScores = Partial<Record<PanelistRole, number>>;
+/**
+ * Accumulated state for a single round's scoring pass.
+ * @see specs/current/critique-theater.md § Composite score formula
+ */
+export interface RoundState {
+    n: number;
+    scores: RoleScores;
+    mustFix: number;
+    composite: number;
+}
+/**
+ * Computes the weighted composite score for a set of panelist scores.
+ * Absent roles are excluded; weights redistribute proportionally over
+ * present roles only. Returns 0 when no role has a score.
+ *
+ * @see specs/current/critique-theater.md § Composite score formula
+ */
+export declare function computeComposite(scores: RoleScores, weights: CritiqueConfig['weights']): number;
+/**
+ * Applies the convergence rule: returns 'ship' when composite >= threshold
+ * (with float epsilon 1e-9) AND mustFix === 0; otherwise 'continue'.
+ *
+ * @see specs/current/critique-theater.md § Convergence rule
+ */
+export declare function decideRound(composite: number, mustFix: number, cfg: CritiqueConfig): RoundDecision;
+/**
+ * Selects the best round according to fallbackPolicy when no <SHIP> arrived.
+ * Returns the elected RoundState or null when the list is empty or policy
+ * is 'fail'.
+ *
+ * @see specs/current/critique-theater.md § Failure modes (recovery)
+ */
+export declare function selectFallbackRound(rounds: RoundState[], policy: CritiqueConfig['fallbackPolicy']): RoundState | null;

package/dist/__w3kits/webcontainer-runtime/apps/daemon/dist/critique/scoreboard.js

@@ -0,0 +1,62 @@
+/**
+ * Computes the weighted composite score for a set of panelist scores.
+ * Absent roles are excluded; weights redistribute proportionally over
+ * present roles only. Returns 0 when no role has a score.
+ *
+ * @see specs/current/critique-theater.md § Composite score formula
+ */
+export function computeComposite(scores, weights) {
+    const roles = Object.keys(scores);
+    const present = roles.filter((r) => scores[r] !== undefined);
+    if (present.length === 0)
+        return 0;
+    const totalWeight = present.reduce((s, r) => s + weights[r], 0);
+    if (totalWeight < 1e-9)
+        return 0;
+    return present.reduce((s, r) => {
+        const score = scores[r];
+        if (score === undefined)
+            return s;
+        return s + (weights[r] / totalWeight) * score;
+    }, 0);
+}
+/**
+ * Applies the convergence rule: returns 'ship' when composite >= threshold
+ * (with float epsilon 1e-9) AND mustFix === 0; otherwise 'continue'.
+ *
+ * @see specs/current/critique-theater.md § Convergence rule
+ */
+export function decideRound(composite, mustFix, cfg) {
+    if (composite >= cfg.scoreThreshold - 1e-9 && mustFix === 0) {
+        return 'ship';
+    }
+    return 'continue';
+}
+/**
+ * Selects the best round according to fallbackPolicy when no <SHIP> arrived.
+ * Returns the elected RoundState or null when the list is empty or policy
+ * is 'fail'.
+ *
+ * @see specs/current/critique-theater.md § Failure modes (recovery)
+ */
+export function selectFallbackRound(rounds, policy) {
+    if (rounds.length === 0)
+        return null;
+    if (policy === 'fail')
+        return null;
+    if (policy === 'ship_last') {
+        const last = rounds[rounds.length - 1];
+        return last ?? null;
+    }
+    // ship_best: highest composite; tie-break by highest round number
+    let best = null;
+    for (const r of rounds) {
+        if (best === null ||
+            r.composite > best.composite + 1e-9 ||
+            (Math.abs(r.composite - best.composite) < 1e-9 && r.n > best.n)) {
+            best = r;
+        }
+    }
+    return best;
+}
+//# sourceMappingURL=scoreboard.js.map

package/dist/__w3kits/webcontainer-runtime/apps/daemon/dist/critique/scoreboard.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"scoreboard.js","sourceRoot":"","sources":["../../src/critique/scoreboard.ts"],"names":[],"mappings":"AAmBA;;;;;;GAMG;AACH,MAAM,UAAU,gBAAgB,CAC9B,MAAkB,EAClB,OAAkC;IAElC,MAAM,KAAK,GAAG,MAAM,CAAC,IAAI,CAAC,MAAM,CAAmB,CAAC;IACpD,MAAM,OAAO,GAAG,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,MAAM,CAAC,CAAC,CAAC,KAAK,SAAS,CAAC,CAAC;IAC7D,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,CAAC,CAAC;IAEnC,MAAM,WAAW,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;IAChE,IAAI,WAAW,GAAG,IAAI;QAAE,OAAO,CAAC,CAAC;IAEjC,OAAO,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE;QAC7B,MAAM,KAAK,GAAG,MAAM,CAAC,CAAC,CAAC,CAAC;QACxB,IAAI,KAAK,KAAK,SAAS;YAAE,OAAO,CAAC,CAAC;QAClC,OAAO,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,GAAG,WAAW,CAAC,GAAG,KAAK,CAAC;IAChD,CAAC,EAAE,CAAC,CAAC,CAAC;AACR,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,WAAW,CACzB,SAAiB,EACjB,OAAe,EACf,GAAmB;IAEnB,IAAI,SAAS,IAAI,GAAG,CAAC,cAAc,GAAG,IAAI,IAAI,OAAO,KAAK,CAAC,EAAE,CAAC;QAC5D,OAAO,MAAM,CAAC;IAChB,CAAC;IACD,OAAO,UAAU,CAAC;AACpB,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,mBAAmB,CACjC,MAAoB,EACpB,MAAwC;IAExC,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IACrC,IAAI,MAAM,KAAK,MAAM;QAAE,OAAO,IAAI,CAAC;IACnC,IAAI,MAAM,KAAK,WAAW,EAAE,CAAC;QAC3B,MAAM,IAAI,GAAG,MAAM,CAAC,MAAM,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;QACvC,OAAO,IAAI,IAAI,IAAI,CAAC;IACtB,CAAC;IACD,kEAAkE;IAClE,IAAI,IAAI,GAAsB,IAAI,CAAC;IACnC,KAAK,MAAM,CAAC,IAAI,MAAM,EAAE,CAAC;QACvB,IACE,IAAI,KAAK,IAAI;YACb,CAAC,CAAC,SAAS,GAAG,IAAI,CAAC,SAAS,GAAG,IAAI;YACnC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,SAAS,GAAG,IAAI,CAAC,SAAS,CAAC,GAAG,IAAI,IAAI,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC,CAAC,EAC/D,CAAC;YACD,IAAI,GAAG,CAAC,CAAC;QACX,CAAC;IACH,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC"}

package/dist/__w3kits/webcontainer-runtime/apps/daemon/dist/critique/spawn-inputs.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Spawn-input glue for the rollout resolver (Phase 15 wireup).
+ *
+ * The resolver in `rollout.ts` is exhaustively covered by
+ * `tests/critique-rollout.test.ts` against direct
+ * `{ phase, skillPolicy, projectOverride, envOverride }` shapes. The
+ * spawn-time gate in `server.ts` constructs those four inputs inline
+ * from runtime state (env vars, skill frontmatter, the project's
+ * metadata blob). This file lifts the metadata-narrowing step out so it
+ * can be pinned in isolation; the other three inputs are either pure
+ * (`parseRolloutPhase`, `parseEnvEnabled` live in rollout.ts) or
+ * already covered (`normalizeCritiquePolicy` is exported from
+ * skills.ts).
+ *
+ * Carved out for PerishCode P3 on PR #1338: the daemon-side glue
+ * (boolean narrowing on a free-form JSON blob) was previously inline
+ * in the spawn handler and not covered by any test, so a refactor that
+ * loosens the `typeof === 'boolean'` guard could silently let a
+ * string `'true'` or a `1` accidentally activate the feature.
+ */
+/**
+ * Narrow the `critiqueTheaterEnabled` field on a project's metadata
+ * blob to `boolean | null`. The metadata blob round-trips through
+ * SQLite as a free-form JSON blob, so callers cannot trust its type
+ * at compile time; a boolean wins outright, any other type (missing
+ * key, malformed value, string `'true'`, number `1`, `null`, nested
+ * object) collapses to `null` so the resolver falls through to the
+ * env / phase tiers exactly the way it did when the toggle had never
+ * been touched. The fall-through is the load-bearing safety property:
+ * a corrupt metadata write must never accidentally activate the
+ * feature.
+ */
+export declare function narrowProjectCritiqueOverride(metadata: unknown): boolean | null;

package/dist/__w3kits/webcontainer-runtime/apps/daemon/dist/critique/spawn-inputs.js

@@ -0,0 +1,40 @@
+/**
+ * Spawn-input glue for the rollout resolver (Phase 15 wireup).
+ *
+ * The resolver in `rollout.ts` is exhaustively covered by
+ * `tests/critique-rollout.test.ts` against direct
+ * `{ phase, skillPolicy, projectOverride, envOverride }` shapes. The
+ * spawn-time gate in `server.ts` constructs those four inputs inline
+ * from runtime state (env vars, skill frontmatter, the project's
+ * metadata blob). This file lifts the metadata-narrowing step out so it
+ * can be pinned in isolation; the other three inputs are either pure
+ * (`parseRolloutPhase`, `parseEnvEnabled` live in rollout.ts) or
+ * already covered (`normalizeCritiquePolicy` is exported from
+ * skills.ts).
+ *
+ * Carved out for PerishCode P3 on PR #1338: the daemon-side glue
+ * (boolean narrowing on a free-form JSON blob) was previously inline
+ * in the spawn handler and not covered by any test, so a refactor that
+ * loosens the `typeof === 'boolean'` guard could silently let a
+ * string `'true'` or a `1` accidentally activate the feature.
+ */
+/**
+ * Narrow the `critiqueTheaterEnabled` field on a project's metadata
+ * blob to `boolean | null`. The metadata blob round-trips through
+ * SQLite as a free-form JSON blob, so callers cannot trust its type
+ * at compile time; a boolean wins outright, any other type (missing
+ * key, malformed value, string `'true'`, number `1`, `null`, nested
+ * object) collapses to `null` so the resolver falls through to the
+ * env / phase tiers exactly the way it did when the toggle had never
+ * been touched. The fall-through is the load-bearing safety property:
+ * a corrupt metadata write must never accidentally activate the
+ * feature.
+ */
+export function narrowProjectCritiqueOverride(metadata) {
+    if (!metadata || typeof metadata !== 'object')
+        return null;
+    const raw = metadata
+        .critiqueTheaterEnabled;
+    return typeof raw === 'boolean' ? raw : null;
+}
+//# sourceMappingURL=spawn-inputs.js.map

package/dist/__w3kits/webcontainer-runtime/apps/daemon/dist/critique/spawn-inputs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"spawn-inputs.js","sourceRoot":"","sources":["../../src/critique/spawn-inputs.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,6BAA6B,CAC3C,QAAiB;IAEjB,IAAI,CAAC,QAAQ,IAAI,OAAO,QAAQ,KAAK,QAAQ;QAAE,OAAO,IAAI,CAAC;IAC3D,MAAM,GAAG,GAAI,QAAiD;SAC3D,sBAAsB,CAAC;IAC1B,OAAO,OAAO,GAAG,KAAK,SAAS,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC;AAC/C,CAAC"}

package/dist/__w3kits/webcontainer-runtime/apps/daemon/dist/critique/transcript.d.ts

@@ -0,0 +1,30 @@
+import type { PanelEvent } from '@open-design/contracts/critique';
+/**
+ * Write a sequence of PanelEvents as newline-delimited JSON to a transcript
+ * file under the artifact directory. Files larger than gzipThresholdBytes
+ * are gzipped to .ndjson.gz; smaller files stay as plain .ndjson. The
+ * threshold is applied to the cumulative UTF-8 byte size of the serialized
+ * payload, not the array length, so multibyte transcripts size correctly.
+ *
+ * Backpressure-aware: events are streamed via Node streams, so the writer
+ * never holds the full transcript in memory.
+ *
+ * Returns the path written (relative to artifactDir). Caller persists the
+ * relative path on the critique_runs row.
+ *
+ * @see specs/current/critique-theater.md § Persistence (transcript files)
+ */
+export declare function writeTranscript(artifactDir: string, events: AsyncIterable<PanelEvent> | Iterable<PanelEvent>, opts?: {
+    gzipThresholdBytes?: number;
+}): Promise<{
+    path: string;
+    bytes: number;
+    gzipped: boolean;
+}>;
+/**
+ * Inverse of writeTranscript. Streams a transcript file (.ndjson or .ndjson.gz)
+ * back out as PanelEvents. Used by replay paths and by Phase 11 e2e.
+ *
+ * @see specs/current/critique-theater.md § Persistence (transcript files)
+ */
+export declare function readTranscript(artifactDir: string, fileName: string): AsyncIterable<PanelEvent>;

package/dist/__w3kits/webcontainer-runtime/apps/daemon/dist/critique/transcript.js

@@ -0,0 +1,153 @@
+import { createReadStream, createWriteStream } from 'node:fs';
+import { mkdir, rename, rm, open } from 'node:fs/promises';
+import { createGzip, createGunzip } from 'node:zlib';
+import { createInterface } from 'node:readline';
+import { join } from 'node:path';
+import { pipeline } from 'node:stream/promises';
+/**
+ * Default gzip threshold (256 KiB). Files whose cumulative UTF-8 byte size
+ * exceeds this value are written as .ndjson.gz; smaller files stay plain.
+ * @see specs/current/critique-theater.md § Persistence (transcript files)
+ */
+const DEFAULT_GZIP_THRESHOLD_BYTES = 256 * 1024;
+/**
+ * Write a sequence of PanelEvents as newline-delimited JSON to a transcript
+ * file under the artifact directory. Files larger than gzipThresholdBytes
+ * are gzipped to .ndjson.gz; smaller files stay as plain .ndjson. The
+ * threshold is applied to the cumulative UTF-8 byte size of the serialized
+ * payload, not the array length, so multibyte transcripts size correctly.
+ *
+ * Backpressure-aware: events are streamed via Node streams, so the writer
+ * never holds the full transcript in memory.
+ *
+ * Returns the path written (relative to artifactDir). Caller persists the
+ * relative path on the critique_runs row.
+ *
+ * @see specs/current/critique-theater.md § Persistence (transcript files)
+ */
+export async function writeTranscript(artifactDir, events, opts) {
+    if (typeof artifactDir !== 'string' || artifactDir.length === 0) {
+        throw new RangeError('writeTranscript: artifactDir must be a non-empty string');
+    }
+    if (events === null ||
+        events === undefined ||
+        (typeof events !== 'object' && typeof events !== 'function')) {
+        throw new RangeError('writeTranscript: events must be iterable');
+    }
+    // Validate that the value is actually iterable / async-iterable.
+    const hasAsyncIter = Symbol.asyncIterator in events;
+    const hasSyncIter = Symbol.iterator in events;
+    if (!hasAsyncIter && !hasSyncIter) {
+        throw new RangeError('writeTranscript: events must be iterable');
+    }
+    const threshold = opts?.gzipThresholdBytes ?? DEFAULT_GZIP_THRESHOLD_BYTES;
+    await mkdir(artifactDir, { recursive: true });
+    const tempPath = join(artifactDir, `transcript.tmp.${process.pid}.${Date.now()}.ndjson`);
+    const finalNdjson = join(artifactDir, 'transcript.ndjson');
+    const finalGz = join(artifactDir, 'transcript.ndjson.gz');
+    let totalBytes = 0;
+    // Stream events to temp file, accumulating byte count.
+    const ws = createWriteStream(tempPath, { encoding: 'utf8' });
+    try {
+        await new Promise((resolve, reject) => {
+            ws.on('error', reject);
+            ws.on('finish', resolve);
+            (async () => {
+                try {
+                    for await (const event of events) {
+                        const line = JSON.stringify(event) + '\n';
+                        const lineBytes = Buffer.byteLength(line, 'utf8');
+                        totalBytes += lineBytes;
+                        const ok = ws.write(line);
+                        if (!ok) {
+                            // Backpressure: wait for drain before continuing.
+                            await new Promise((res, rej) => {
+                                ws.once('drain', res);
+                                ws.once('error', rej);
+                            });
+                        }
+                    }
+                    ws.end();
+                }
+                catch (err) {
+                    ws.destroy(err instanceof Error ? err : new Error(String(err)));
+                    reject(err);
+                }
+            })();
+        });
+        const gzipped = totalBytes > threshold;
+        if (gzipped) {
+            // Write gzip output to a temp file first, fsync, then atomic-rename.
+            // A crash mid-write leaves the .gz.tmp but never the final .gz, so
+            // partial files can't be mistaken for valid data on the next read.
+            const gzTempPath = join(artifactDir, `transcript.tmp.${process.pid}.${Date.now()}.ndjson.gz.tmp`);
+            try {
+                await pipeline(createReadStream(tempPath), createGzip(), createWriteStream(gzTempPath));
+                // fsync: flush OS write buffers before rename so crash after rename
+                // cannot leave a zero-length .gz.
+                const fh = await open(gzTempPath, 'r+');
+                try {
+                    await fh.sync();
+                }
+                finally {
+                    await fh.close();
+                }
+                await rename(gzTempPath, finalGz);
+            }
+            catch (gzErr) {
+                // Unlink the .gz.tmp so no partial file lingers.
+                await rm(gzTempPath, { force: true });
+                throw gzErr;
+            }
+            await rm(tempPath, { force: true });
+            return { path: 'transcript.ndjson.gz', bytes: totalBytes, gzipped: true };
+        }
+        else {
+            await rename(tempPath, finalNdjson);
+            return { path: 'transcript.ndjson', bytes: totalBytes, gzipped: false };
+        }
+    }
+    catch (err) {
+        // Ensure the write stream has fully closed before unlinking. If the
+        // iterable fails before the lazy open completes, unlinking immediately can
+        // race with createWriteStream and leave a late-created temp file behind.
+        ws.destroy();
+        if (!ws.closed) {
+            await new Promise((resolve) => {
+                ws.once('close', resolve);
+            });
+        }
+        // Ensure temp file is cleaned up on any failure.
+        await rm(tempPath, { force: true });
+        throw err;
+    }
+}
+/**
+ * Inverse of writeTranscript. Streams a transcript file (.ndjson or .ndjson.gz)
+ * back out as PanelEvents. Used by replay paths and by Phase 11 e2e.
+ *
+ * @see specs/current/critique-theater.md § Persistence (transcript files)
+ */
+export async function* readTranscript(artifactDir, fileName) {
+    if (!fileName.endsWith('.ndjson') && !fileName.endsWith('.ndjson.gz')) {
+        throw new RangeError(`readTranscript: unknown extension on "${fileName}", expected .ndjson or .ndjson.gz`);
+    }
+    const filePath = join(artifactDir, fileName);
+    const isGz = fileName.endsWith('.ndjson.gz');
+    const fileStream = createReadStream(filePath);
+    const source = isGz
+        ? fileStream.pipe(createGunzip())
+        : fileStream;
+    const rl = createInterface({
+        input: source,
+        crlfDelay: Infinity,
+    });
+    for await (const line of rl) {
+        const trimmed = line.trim();
+        if (trimmed.length === 0)
+            continue;
+        const event = JSON.parse(trimmed);
+        yield event;
+    }
+}
+//# sourceMappingURL=transcript.js.map

package/dist/__w3kits/webcontainer-runtime/apps/daemon/dist/critique/transcript.js.map

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

package/dist/__w3kits/webcontainer-runtime/apps/daemon/dist/cwd-aliases.d.ts

@@ -0,0 +1,22 @@
+export declare const SKILLS_CWD_ALIAS = ".od-skills";
+export type SkillStagingLogger = (message: string) => void;
+export interface SkillStagingResult {
+    /** True when a usable copy of the source is sitting at `stagedPath`. */
+    staged: boolean;
+    /** Absolute path of the staged directory if staging succeeded. */
+    stagedPath?: string;
+    /** Populated when staging was skipped or failed; never thrown. */
+    reason?: string;
+}
+/**
+ * Copy `<sourceDir>` to `<cwd>/.od-skills/<folderName>/` so an agent can
+ * reach skill side files via a cwd-relative path. Idempotent and
+ * non-throwing — failures are logged and surfaced via the result so the
+ * caller falls back to absolute-path delivery (`--add-dir` for
+ * Claude/Copilot, embedded absolute path in the preamble for others).
+ *
+ * The previous-turn copy is replaced wholesale on every call, which is
+ * the simplest correct way to handle skill-source updates (e.g. the
+ * user just edited a `references/*.md` mid-session).
+ */
+export declare function stageActiveSkill(cwd: string | null | undefined, folderName: string, sourceDir: string, log?: SkillStagingLogger): Promise<SkillStagingResult>;