opensquid 0.5.407 → 0.5.426

package/dist/setup/cli/ralph.js

@@ -0,0 +1,168 @@
+/**
+ * GR.4 — the `opensquid loop` CLI: the user-invoked entry that ASSEMBLES the orchestrator's injected deps
+ * and runs the gated-ralph loop. A thin wire — all logic lives in the unit-tested pieces it composes
+ * (runRalphLoop, chatEscalator, parseLapOutcome, the GR.1–3 store ops). The loop is a CLI COMMAND, not a
+ * daemon (opensquid stays an MCP server / tool provider; the agent loop runs inside the spawned harness).
+ *
+ * Commands:
+ *   opensquid loop [--once] [--max-budget-usd <n>]      — run the loop (read ready → claim → lap → repeat)
+ *   opensquid loop resolve <itemId> --misclassified     — the human-override residual-shrink path (GR.4)
+ *
+ * Imports from: commander, node:net, ../../runtime/paths.js, ../../runtime/spawn_lifecycle.js,
+ * ../../runtime/ralph/*, ../../workgraph/*, ../wizard/ralph_writer.js.
+ */
+import { connect } from 'node:net';
+import { join } from 'node:path';
+import { OPENSQUID_HOME, chatDaemonSockPath } from '../../runtime/paths.js';
+import { runOneShotCli } from '../../runtime/spawn_lifecycle.js';
+import { workGraphStore } from '../../workgraph/store.js';
+import { claimAudience } from '../../workgraph/audience.js';
+import { runRalphLoop, resolveParked } from '../../runtime/ralph/orchestrator.js';
+import { parseLapOutcome } from '../../runtime/ralph/lap_outcome.js';
+import { recordMisclassification } from '../../runtime/ralph/decision_classifier.js';
+import { chatEscalator } from '../../runtime/ralph/escalator.js';
+import { readRalphConfig } from '../wizard/ralph_writer.js';
+/** Hydrate the persisted scalar config into the orchestrator's runtime `RalphConfig` (closures rebuilt). */
+export function buildRalphConfig(file, opts) {
+    return {
+        authMode: file.authMode,
+        maxBudgetUsd: opts.maxBudgetUsd ?? file.maxBudgetUsd,
+        claimTtlSec: file.claimTtlSec,
+        once: opts.once,
+        supervise: {
+            maxRetries: file.maxRetries,
+            backoffMs: (attempt) => file.backoffBaseMs * 2 ** attempt, // exponential from the base
+            heartbeat: () => undefined, // a future lease-refresh; liveness tick is a no-op for the CLI run
+        },
+    };
+}
+/** Build the per-lap runner: spawn `claude -p RALPH.md --item <id>`, parse the typed exit. A deadline
+ * overrun (group-SIGKILL) becomes the typed TIMEOUT, NOT a CRASH; a genuine spawn failure rethrows → CRASH. */
+export function makeSpawnLap(cfg, file, runCli = runOneShotCli) {
+    return async (item) => {
+        let stdout;
+        try {
+            stdout = await runCli({
+                cli: file.harness.cli, // Inv 10 — harness is a parameter
+                args: [
+                    '-p',
+                    file.harness.ralphMdPath,
+                    '--item',
+                    item.id,
+                    '--output-format',
+                    'json',
+                    '--max-budget-usd',
+                    String(cfg.maxBudgetUsd),
+                    '--dangerously-skip-permissions',
+                ],
+                prompt: '',
+                timeoutMs: file.wallClockMs,
+                markSubagent: true,
+                timeoutError: () => Object.assign(new Error('lap timeout'), { __timeout: true }),
+            });
+        }
+        catch (e) {
+            if (e.__timeout === true)
+                return { kind: 'TIMEOUT', costUsd: 0 };
+            throw e; // genuine spawn/IO failure → superviseLap maps it to CRASH
+        }
+        const { outcome, costUsd } = parseLapOutcome(stdout);
+        return { ...outcome, costUsd };
+    };
+}
+/** The real chat transport: a one-shot UDS JSON-RPC `send` to the chat-daemon (the live Telegram path
+ * `chat_send` uses). `ok:false` on any unreachable/error so the escalator stays undroppable. */
+export const daemonChatSend = (params) => new Promise((resolve) => {
+    const sock = connect(chatDaemonSockPath());
+    let buf = '';
+    const done = (r) => {
+        try {
+            sock.end();
+        }
+        catch {
+            /* already closed */
+        }
+        resolve(r);
+    };
+    const timer = setTimeout(() => done({ ok: false, reason: 'chat-daemon RPC timeout (5s)' }), 5000);
+    sock.on('error', (e) => {
+        clearTimeout(timer);
+        done({ ok: false, reason: `chat-daemon unreachable: ${e.message}` });
+    });
+    sock.on('data', (d) => {
+        buf += d.toString('utf8');
+        const nl = buf.indexOf('\n');
+        if (nl === -1)
+            return;
+        clearTimeout(timer);
+        try {
+            const res = JSON.parse(buf.slice(0, nl));
+            done(res.error ? { ok: false, reason: res.error.message ?? 'send error' } : { ok: true });
+        }
+        catch (e) {
+            done({ ok: false, reason: e instanceof Error ? e.message : 'bad RPC response' });
+        }
+    });
+    sock.write(JSON.stringify({
+        jsonrpc: '2.0',
+        id: `ralph-${String(Date.now())}`,
+        method: 'send',
+        params: { channel: params.channel, text: params.text },
+    }) + '\n');
+});
+export function registerRalph(program) {
+    const loop = program
+        .command('loop')
+        .description('Run the gated-ralph autonomous loop (composes the work-graph + the coding-flow gate)');
+    loop
+        .option('--once', 'process a single ready item then stop', false)
+        .option('--max-budget-usd <n>', 'API-mode dollar budget for this run (overrides config)')
+        .action(async (opts) => {
+        const file = await readRalphConfig();
+        if (file === null) {
+            process.stderr.write('🦑 loop OFF: no ~/.opensquid/ralph.config.json. Run the wizard first.\n');
+            process.exitCode = 1;
+            return;
+        }
+        const cfg = buildRalphConfig(file, {
+            once: opts.once === true,
+            ...(opts.maxBudgetUsd === undefined ? {} : { maxBudgetUsd: Number(opts.maxBudgetUsd) }),
+        });
+        const wg = workGraphStore({
+            dbUrl: `file:${join(OPENSQUID_HOME(), 'workgraph.db')}`,
+            sourceDir: join(OPENSQUID_HOME(), 'store', 'issues'),
+        });
+        await wg.init();
+        const result = await runRalphLoop(cfg, {
+            wg,
+            claimAudience,
+            runLap: makeSpawnLap(cfg, file),
+            escalate: chatEscalator({ send: daemonChatSend, channel: 'project:telegram' }),
+        });
+        process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+    });
+    loop
+        .command('resolve <itemId>')
+        .description('Resolve a parked HUMAN_REQUIRED item (the human-override residual-shrink path)')
+        .option('--misclassified', 'the escalation was principle-settleable — record + un-wedge for another lap', false)
+        .action(async (itemId, opts) => {
+        if (opts.misclassified !== true) {
+            process.stderr.write('Nothing to do: pass --misclassified to record + un-wedge the item.\n');
+            return;
+        }
+        const wg = workGraphStore({
+            dbUrl: `file:${join(OPENSQUID_HOME(), 'workgraph.db')}`,
+            sourceDir: join(OPENSQUID_HOME(), 'store', 'issues'),
+        });
+        await wg.init();
+        await resolveParked(itemId, {
+            wg,
+            recordMisclassification,
+            sessionId: process.env.CLAUDE_SESSION_ID ?? '<cli>',
+            nowIso: new Date().toISOString(),
+        });
+        process.stdout.write(`resolved ${itemId}: misclassification recorded, item un-wedged → back in ready.\n`);
+    });
+    return loop;
+}
+//# sourceMappingURL=ralph.js.map

package/dist/setup/cli/ralph.js.map

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

package/dist/setup/wizard/ralph_writer.d.ts

@@ -0,0 +1,98 @@
+import { z } from 'zod';
+export declare const RalphConfigFileSchema: z.ZodEffects<z.ZodObject<{
+    /** Auth mode resolves the per-lap bound (Inv 11): API → dollar budget; subscription → wall-clock W. */
+    authMode: z.ZodEnum<["api", "subscription"]>;
+    /** API dollar budget (running sum of the verified total_cost_usd). Ignored in subscription mode. */
+    maxBudgetUsd: z.ZodNumber;
+    /** Per-item claim TTL (GR.1). */
+    claimTtlSec: z.ZodNumber;
+    /** Per-lap wall-clock deadline W (the subscription bound + the TIMEOUT trigger). */
+    wallClockMs: z.ZodNumber;
+    /** Supervisor retry cap R (CRASH/TIMEOUT only) and the backoff base for exponential backoff. */
+    maxRetries: z.ZodNumber;
+    backoffBaseMs: z.ZodNumber;
+    /** Harness is a PARAMETER (Inv 10): the lap CLI + the RALPH.md path it reads. */
+    harness: z.ZodObject<{
+        cli: z.ZodString;
+        ralphMdPath: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        cli: string;
+        ralphMdPath: string;
+    }, {
+        cli: string;
+        ralphMdPath: string;
+    }>;
+}, "strip", z.ZodTypeAny, {
+    authMode: "subscription" | "api";
+    maxBudgetUsd: number;
+    claimTtlSec: number;
+    wallClockMs: number;
+    maxRetries: number;
+    backoffBaseMs: number;
+    harness: {
+        cli: string;
+        ralphMdPath: string;
+    };
+}, {
+    authMode: "subscription" | "api";
+    maxBudgetUsd: number;
+    claimTtlSec: number;
+    wallClockMs: number;
+    maxRetries: number;
+    backoffBaseMs: number;
+    harness: {
+        cli: string;
+        ralphMdPath: string;
+    };
+}>, {
+    authMode: "subscription" | "api";
+    maxBudgetUsd: number;
+    claimTtlSec: number;
+    wallClockMs: number;
+    maxRetries: number;
+    backoffBaseMs: number;
+    harness: {
+        cli: string;
+        ralphMdPath: string;
+    };
+}, {
+    authMode: "subscription" | "api";
+    maxBudgetUsd: number;
+    claimTtlSec: number;
+    wallClockMs: number;
+    maxRetries: number;
+    backoffBaseMs: number;
+    harness: {
+        cli: string;
+        ralphMdPath: string;
+    };
+}>;
+export type RalphConfigFile = z.infer<typeof RalphConfigFileSchema>;
+export declare const ralphMdPath: (home?: string) => string;
+export declare const ralphConfigPath: (home?: string) => string;
+/** Sensible defaults — subscription mode (W-bounded), conservative caps. Overridable by the wizard. */
+export declare function defaultRalphConfig(home?: string): RalphConfigFile;
+type WriteOutcome = 'created' | 'unchanged' | 'replaced';
+export interface RalphInstallResult {
+    home: string;
+    ralphMd: {
+        path: string;
+        outcome: WriteOutcome;
+    };
+    config: {
+        path: string;
+        outcome: WriteOutcome;
+    };
+}
+/**
+ * Install/refresh the RALPH.md directive + loop config. Idempotent + re-runnable (the wizard calls this);
+ * a second run with the same inputs is a no-op diff. Merges `overrides` over the defaults.
+ */
+export declare function installRalph(opts?: {
+    home?: string;
+    overrides?: Partial<RalphConfigFile>;
+}): Promise<RalphInstallResult>;
+/** Read + validate the loop config (fail-loud per the project Zod invariant). Null if absent (loop OFF). */
+export declare function readRalphConfig(home?: string): Promise<RalphConfigFile | null>;
+export {};
+//# sourceMappingURL=ralph_writer.d.ts.map

package/dist/setup/wizard/ralph_writer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ralph_writer.d.ts","sourceRoot":"","sources":["../../../src/setup/wizard/ralph_writer.ts"],"names":[],"mappings":"AAoBA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAKxB,eAAO,MAAM,qBAAqB;IAE9B,uGAAuG;;IAEvG,oGAAoG;;IAEpG,iCAAiC;;IAEjC,oFAAoF;;IAEpF,gGAAgG;;;IAGhG,iFAAiF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAUjF,CAAC;AACL,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,qBAAqB,CAAC,CAAC;AAEpE,eAAO,MAAM,WAAW,GAAI,OAAM,MAAyB,KAAG,MAAgC,CAAC;AAC/F,eAAO,MAAM,eAAe,GAAI,OAAM,MAAyB,KAAG,MACjC,CAAC;AAElC,uGAAuG;AACvG,wBAAgB,kBAAkB,CAAC,IAAI,GAAE,MAAyB,GAAG,eAAe,CAUnF;AAED,KAAK,YAAY,GAAG,SAAS,GAAG,WAAW,GAAG,UAAU,CAAC;AAgBzD,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,YAAY,CAAA;KAAE,CAAC;IACjD,MAAM,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,YAAY,CAAA;KAAE,CAAC;CACjD;AAED;;;GAGG;AACH,wBAAsB,YAAY,CAChC,IAAI,GAAE;IACJ,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,SAAS,CAAC,EAAE,OAAO,CAAC,eAAe,CAAC,CAAC;CACjC,GACL,OAAO,CAAC,kBAAkB,CAAC,CAiB7B;AAED,4GAA4G;AAC5G,wBAAsB,eAAe,CACnC,IAAI,GAAE,MAAyB,GAC9B,OAAO,CAAC,eAAe,GAAG,IAAI,CAAC,CASjC"}

package/dist/setup/wizard/ralph_writer.js

@@ -0,0 +1,114 @@
+/**
+ * GR.4 — the gated-ralph wizard writer (Inv 12: wizard-configured, never hand-wired).
+ *
+ * Installs the two on-disk artifacts the `opensquid loop` orchestrator reads:
+ *   1. `~/.opensquid/RALPH.md`        — the stable per-lap directive (the `RALPH_MD` constant).
+ *   2. `~/.opensquid/ralph.config.json` — the loop config (auth-mode, budget/rate caps, supervisor
+ *      bounds, harness), validated by `RalphConfigFileSchema` on read (fail-loud, the project invariant).
+ *
+ * Both writes are IDEMPOTENT: an identical existing file is a no-op; a divergent one is snapshotted to
+ * `<file>.bak` before the atomic overwrite (same contract as settings-writer). Absent config ⇒ the loop
+ * is OFF (the CLI refuses to run without it) ⇒ today's behavior is unchanged (additive, Inv 12).
+ *
+ * Persisted config stores only SCALARS (no functions) — the CLI reconstructs the orchestrator's
+ * `RalphConfig` (the `backoffMs`/`heartbeat`/`sleep` closures) from these at launch.
+ *
+ * Imports from: node:fs/promises, ../../runtime/atomic_write.js, ../../runtime/paths.js,
+ * ../../runtime/ralph/ralph_template.js, zod.
+ */
+import { readFile, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { z } from 'zod';
+import { atomicWriteFile } from '../../runtime/atomic_write.js';
+import { OPENSQUID_HOME } from '../../runtime/paths.js';
+import { RALPH_MD } from '../../runtime/ralph/ralph_template.js';
+export const RalphConfigFileSchema = z
+    .object({
+    /** Auth mode resolves the per-lap bound (Inv 11): API → dollar budget; subscription → wall-clock W. */
+    authMode: z.enum(['api', 'subscription']),
+    /** API dollar budget (running sum of the verified total_cost_usd). Ignored in subscription mode. */
+    maxBudgetUsd: z.number().positive(),
+    /** Per-item claim TTL (GR.1). */
+    claimTtlSec: z.number().int().positive(),
+    /** Per-lap wall-clock deadline W (the subscription bound + the TIMEOUT trigger). */
+    wallClockMs: z.number().int().positive(),
+    /** Supervisor retry cap R (CRASH/TIMEOUT only) and the backoff base for exponential backoff. */
+    maxRetries: z.number().int().nonnegative(),
+    backoffBaseMs: z.number().int().positive(),
+    /** Harness is a PARAMETER (Inv 10): the lap CLI + the RALPH.md path it reads. */
+    harness: z.object({ cli: z.string().min(1), ralphMdPath: z.string().min(1) }),
+})
+    .refine((c) => c.claimTtlSec * 1000 > c.wallClockMs, {
+    // HARD INVARIANT (S7): the claim TTL T must exceed the lap deadline W — else a legitimately long lap
+    // outruns its own claim, ready() re-surfaces the item mid-run, a second runner's CAS succeeds, and the
+    // loop DOUBLE-SHIPS (the wg-c34349377f81 hazard the claim layer exists to prevent). Fail-loud, not the operator's job.
+    message: 'claimTtlSec*1000 must exceed wallClockMs (T > W) — else a long lap outruns its claim → double-ship',
+    path: ['claimTtlSec'],
+});
+export const ralphMdPath = (home = OPENSQUID_HOME()) => join(home, 'RALPH.md');
+export const ralphConfigPath = (home = OPENSQUID_HOME()) => join(home, 'ralph.config.json');
+/** Sensible defaults — subscription mode (W-bounded), conservative caps. Overridable by the wizard. */
+export function defaultRalphConfig(home = OPENSQUID_HOME()) {
+    return {
+        authMode: 'subscription',
+        maxBudgetUsd: 10,
+        claimTtlSec: 3600, // T = 1h claim TTL — MUST exceed wallClockMs (W = 30m deadline) per S7 (T > W)
+        wallClockMs: 30 * 60 * 1000,
+        maxRetries: 2,
+        backoffBaseMs: 2000,
+        harness: { cli: 'claude', ralphMdPath: ralphMdPath(home) },
+    };
+}
+/** Idempotent atomic write: identical → no-op; divergent → snapshot the old to `<path>.bak` then rename. */
+async function idempotentWrite(path, content) {
+    let existing = null;
+    try {
+        existing = await readFile(path, 'utf8');
+    }
+    catch (e) {
+        if (e.code !== 'ENOENT')
+            throw e;
+    }
+    if (existing === content)
+        return 'unchanged';
+    if (existing !== null)
+        await writeFile(`${path}.bak`, existing); // last line of defense before overwrite
+    await atomicWriteFile(path, content);
+    return existing === null ? 'created' : 'replaced';
+}
+/**
+ * Install/refresh the RALPH.md directive + loop config. Idempotent + re-runnable (the wizard calls this);
+ * a second run with the same inputs is a no-op diff. Merges `overrides` over the defaults.
+ */
+export async function installRalph(opts = {}) {
+    const home = opts.home ?? OPENSQUID_HOME();
+    const config = RalphConfigFileSchema.parse({
+        ...defaultRalphConfig(home),
+        ...opts.overrides,
+        // a partial harness override must not drop the sibling field
+        harness: { ...defaultRalphConfig(home).harness, ...opts.overrides?.harness },
+    });
+    const mdPath = ralphMdPath(home);
+    const cfgPath = ralphConfigPath(home);
+    const mdOutcome = await idempotentWrite(mdPath, RALPH_MD);
+    const cfgOutcome = await idempotentWrite(cfgPath, `${JSON.stringify(config, null, 2)}\n`);
+    return {
+        home,
+        ralphMd: { path: mdPath, outcome: mdOutcome },
+        config: { path: cfgPath, outcome: cfgOutcome },
+    };
+}
+/** Read + validate the loop config (fail-loud per the project Zod invariant). Null if absent (loop OFF). */
+export async function readRalphConfig(home = OPENSQUID_HOME()) {
+    let raw;
+    try {
+        raw = await readFile(ralphConfigPath(home), 'utf8');
+    }
+    catch (e) {
+        if (e.code === 'ENOENT')
+            return null; // not configured ⇒ loop OFF
+        throw e;
+    }
+    return RalphConfigFileSchema.parse(JSON.parse(raw));
+}
+//# sourceMappingURL=ralph_writer.js.map

package/dist/setup/wizard/ralph_writer.js.map

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

package/dist/workgraph/audience.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Derive a claim's audience from the GDC env markers the gate already trusts (the same
+ * `AGENT_ENV_MARKERS` as `setup/cli/gate.ts`: CLAUDECODE / CODEX_THREAD_ID / AI_AGENT). The audience
+ * is stamped at claim time, NEVER taken from caller input — so it reflects the actual harness that
+ * ran the claim. (GR.1 of the gated-ralph loop; the work-graph-item instance of the claim/audience
+ * pattern from wg-c34349377f81.)
+ *
+ * Imported by: src/mcp/tools/workgraph.ts.
+ */
+import type { ClaimAudience } from './types.js';
+export declare function claimAudience(env?: NodeJS.ProcessEnv): ClaimAudience;
+//# sourceMappingURL=audience.d.ts.map

package/dist/workgraph/audience.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"audience.d.ts","sourceRoot":"","sources":["../../src/workgraph/audience.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAEhD,wBAAgB,aAAa,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,aAAa,CAMjF"}

package/dist/workgraph/audience.js

@@ -0,0 +1,10 @@
+export function claimAudience(env = process.env) {
+    const claude = env.CLAUDECODE;
+    if (claude !== undefined && claude !== '')
+        return { source: 'claudecode', version: claude };
+    const codex = env.CODEX_THREAD_ID;
+    if (codex !== undefined && codex !== '')
+        return { source: 'codex', threadId: codex };
+    return { source: 'unknown' };
+}
+//# sourceMappingURL=audience.js.map

package/dist/workgraph/audience.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"audience.js","sourceRoot":"","sources":["../../src/workgraph/audience.ts"],"names":[],"mappings":"AAWA,MAAM,UAAU,aAAa,CAAC,MAAyB,OAAO,CAAC,GAAG;IAChE,MAAM,MAAM,GAAG,GAAG,CAAC,UAAU,CAAC;IAC9B,IAAI,MAAM,KAAK,SAAS,IAAI,MAAM,KAAK,EAAE;QAAE,OAAO,EAAE,MAAM,EAAE,YAAY,EAAE,OAAO,EAAE,MAAM,EAAE,CAAC;IAC5F,MAAM,KAAK,GAAG,GAAG,CAAC,eAAe,CAAC;IAClC,IAAI,KAAK,KAAK,SAAS,IAAI,KAAK,KAAK,EAAE;QAAE,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,QAAQ,EAAE,KAAK,EAAE,CAAC;IACrF,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,CAAC;AAC/B,CAAC"}

package/dist/workgraph/events.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"events.d.ts","sourceRoot":"","sources":["../../src/workgraph/events.ts"],"names":[],"mappings":"AAkBA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,gBAAgB,CAAC;AAE7C,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,YAAY,CAAC;AAevC,gGAAgG;AAChG,eAAO,MAAM,OAAO,GAAI,QAAQ,MAAM,EAAE,MAAM,MAAM,KAAG,MACgC,CAAC;AAExF,+FAA+F;AAC/F,eAAO,MAAM,QAAQ,GAAI,MAAM,MAAM,EAAE,SAAS,OAAO,EAAE,SAAS,MAAM,KAAG,MAK1D,CAAC;AAIlB;;;GAGG;AACH,wBAAsB,OAAO,CAAC,MAAM,EAAE,MAAM,EAAE,EAAE,EAAE,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CA6CrE"}
+{"version":3,"file":"events.d.ts","sourceRoot":"","sources":["../../src/workgraph/events.ts"],"names":[],"mappings":"AAkBA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,gBAAgB,CAAC;AAE7C,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,YAAY,CAAC;AAevC,gGAAgG;AAChG,eAAO,MAAM,OAAO,GAAI,QAAQ,MAAM,EAAE,MAAM,MAAM,KAAG,MACgC,CAAC;AAExF,+FAA+F;AAC/F,eAAO,MAAM,QAAQ,GAAI,MAAM,MAAM,EAAE,SAAS,OAAO,EAAE,SAAS,MAAM,KAAG,MAK1D,CAAC;AAIlB;;;GAGG;AACH,wBAAsB,OAAO,CAAC,MAAM,EAAE,MAAM,EAAE,EAAE,EAAE,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CA+ErE"}

package/dist/workgraph/events.js

@@ -85,6 +85,40 @@ export async function applyOp(client, op) {
                 args: [edgeKey(s(p.from), s(p.to))],
             });
             return;
+        case 'claim_acquired':
+            // GR.1 — exactly-once CAS at the projection: the claim lands ONLY if the item is currently
+            // unclaimed OR its prior claim already expired (claim_expires_at <= this op's ts). Replaying
+            // in lamport order makes exactly one concurrent claim win; the loser's UPDATE matches 0 rows.
+            // Expiry is read at query time (listReady) — no reaper. claim_token is the unique winner mark.
+            await client.execute({
+                sql: `UPDATE wg_issues
+              SET claim_token = ?, claim_audience = ?, claim_expires_at = ?, updated_at = ?
+              WHERE id = ? AND status = 'open'
+                AND (claim_token IS NULL OR claim_expires_at <= ?)`,
+                args: [
+                    s(p.claimToken),
+                    s(p.audience === undefined ? '' : JSON.stringify(p.audience)),
+                    s(p.expiresAt),
+                    s(p.ts),
+                    op.issueId,
+                    s(p.ts),
+                ],
+            });
+            return;
+        case 'wedge_marked':
+            // GR.3 — record the wedge reason; listReady excludes wedge-marked items (escalate, not re-attempt).
+            await client.execute({
+                sql: `UPDATE wg_issues SET wedge_reason = ?, updated_at = ? WHERE id = ?`,
+                args: [s(p.reason), s(p.ts), op.issueId],
+            });
+            return;
+        case 'wedge_cleared':
+            // GR.4 — un-wedge (human-override resolution): the item re-enters listReady for another lap.
+            await client.execute({
+                sql: `UPDATE wg_issues SET wedge_reason = NULL, updated_at = ? WHERE id = ?`,
+                args: [s(p.ts), op.issueId],
+            });
+            return;
     }
 }
 //# sourceMappingURL=events.js.map

package/dist/workgraph/events.js.map

@@ -1 +1 @@
-{"version":3,"file":"events.js","sourceRoot":"","sources":["../../src/workgraph/events.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AACH,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAMzC,MAAM,QAAQ,GAAG,GAAG,CAAC,CAAC,8CAA8C;AAEpE,+FAA+F;AAC/F,SAAS,aAAa,CAAC,CAAU;IAC/B,IAAI,CAAC,KAAK,IAAI,IAAI,OAAO,CAAC,KAAK,QAAQ;QAAE,OAAO,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,IAAI,MAAM,CAAC;IAC5E,IAAI,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC;QAAE,OAAO,IAAI,CAAC,CAAC,GAAG,CAAC,aAAa,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC;IACnE,MAAM,GAAG,GAAG,CAA4B,CAAC;IACzC,OAAO,IAAI,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC;SACxB,IAAI,EAAE;SACN,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,IAAI,aAAa,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;SAC3D,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC;AAClB,CAAC;AAED,gGAAgG;AAChG,MAAM,CAAC,MAAM,OAAO,GAAG,CAAC,MAAc,EAAE,IAAY,EAAU,EAAE,CAC9D,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,GAAG,MAAM,GAAG,QAAQ,GAAG,IAAI,EAAE,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;AAExF,+FAA+F;AAC/F,MAAM,CAAC,MAAM,QAAQ,GAAG,CAAC,IAAY,EAAE,OAAgB,EAAE,OAAe,EAAU,EAAE,CAClF,KAAK;IACL,UAAU,CAAC,QAAQ,CAAC;SACjB,MAAM,CAAC,GAAG,IAAI,KAAK,MAAM,CAAC,OAAO,CAAC,KAAK,aAAa,CAAC,OAAO,CAAC,EAAE,CAAC;SAChE,MAAM,CAAC,KAAK,CAAC;SACb,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;AAElB,MAAM,CAAC,GAAG,CAAC,CAAU,EAAU,EAAE,CAAC,CAAC,OAAO,CAAC,KAAK,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;AAEnE;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,OAAO,CAAC,MAAc,EAAE,EAAQ;IACpD,MAAM,CAAC,GAAG,EAAE,CAAC,OAAO,CAAC;IACrB,QAAQ,EAAE,CAAC,IAAI,EAAE,CAAC;QAChB,KAAK,eAAe;YAClB,yFAAyF;YACzF,MAAM,MAAM,CAAC,OAAO,CAAC;gBACnB,GAAG,EAAE;gDACmC;gBACxC,IAAI,EAAE,CAAC,EAAE,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,OAAO,CAAC;aACxE,CAAC,CAAC;YACH,OAAO;QACT,KAAK,WAAW;YACd,oFAAoF;YACpF,MAAM,MAAM,CAAC,OAAO,CAAC;gBACnB,GAAG,EAAE;;;wCAG2B;gBAChC,IAAI,EAAE;oBACJ,CAAC,CAAC,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC;oBACzC,CAAC,CAAC,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;oBACvC,CAAC,CAAC,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC;oBAC3C,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;oBACP,EAAE,CAAC,OAAO;oBACV,EAAE,CAAC,OAAO;oBACV,EAAE,CAAC,OAAO;iBACX;aACF,CAAC,CAAC;YACH,OAAO;QACT,KAAK,WAAW;YACd,mFAAmF;YACnF,2EAA2E;YAC3E,MAAM,MAAM,CAAC,OAAO,CAAC;gBACnB,GAAG,EAAE;uEAC0D;gBAC/D,IAAI,EAAE,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;aACnE,CAAC,CAAC;YACH,OAAO;QACT,KAAK,aAAa;YAChB,MAAM,MAAM,CAAC,OAAO,CAAC;gBACnB,GAAG,EAAE,yCAAyC;gBAC9C,IAAI,EAAE,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;aACpC,CAAC,CAAC;YACH,OAAO;IACX,CAAC;AACH,CAAC"}
+{"version":3,"file":"events.js","sourceRoot":"","sources":["../../src/workgraph/events.ts"],"names":[],"mappings":"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"}

package/dist/workgraph/store.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"store.d.ts","sourceRoot":"","sources":["../../src/workgraph/store.ts"],"names":[],"mappings":"AAqBA,OAAO,KAAK,EAAsC,cAAc,EAAE,MAAM,YAAY,CAAC;AAoCrF,wBAAgB,cAAc,CAAC,IAAI,EAAE;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,SAAS,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,cAAc,CAqH1F;AAED;;;;GAIG;AACH,wBAAsB,gBAAgB,CAAC,IAAI,EAAE;IAC3C,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,CAAC;CACnB,GAAG,OAAO,CAAC,MAAM,CAAC,CAoClB"}
+{"version":3,"file":"store.d.ts","sourceRoot":"","sources":["../../src/workgraph/store.ts"],"names":[],"mappings":"AAqBA,OAAO,KAAK,EAAqD,cAAc,EAAE,MAAM,YAAY,CAAC;AAyEpG,wBAAgB,cAAc,CAAC,IAAI,EAAE;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,SAAS,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,cAAc,CAwJ1F;AAED;;;;GAIG;AACH,wBAAsB,gBAAgB,CAAC,IAAI,EAAE;IAC3C,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,CAAC;CACnB,GAAG,OAAO,CAAC,MAAM,CAAC,CAoClB"}

package/dist/workgraph/store.js

@@ -24,14 +24,39 @@ const newIssueId = (title) => 'wg-' +
 const str = (r, k) => (typeof r[k] === 'string' ? r[k] : '');
 const num = (v) => (typeof v === 'number' ? v : Number(v ?? 0));
 const toStatus = (s) => (s === 'in_progress' || s === 'closed' ? s : 'open');
-const rowToIssue = (r) => ({
-    id: str(r, 'id'),
-    title: str(r, 'title'),
-    body: str(r, 'body'),
-    status: toStatus(str(r, 'status')),
-    createdAt: str(r, 'created_at'),
-    updatedAt: str(r, 'updated_at'),
-});
+const optStr = (r, k) => {
+    const v = r[k];
+    return typeof v === 'string' && v !== '' ? v : undefined;
+};
+const parseAudience = (r) => {
+    const raw = optStr(r, 'claim_audience');
+    if (raw === undefined)
+        return undefined;
+    try {
+        return JSON.parse(raw);
+    }
+    catch {
+        return undefined;
+    }
+};
+const rowToIssue = (r) => {
+    const claimToken = optStr(r, 'claim_token');
+    const claimAudience = parseAudience(r);
+    const claimExpiresAt = optStr(r, 'claim_expires_at');
+    const wedgeReason = optStr(r, 'wedge_reason');
+    return {
+        id: str(r, 'id'),
+        title: str(r, 'title'),
+        body: str(r, 'body'),
+        status: toStatus(str(r, 'status')),
+        createdAt: str(r, 'created_at'),
+        updatedAt: str(r, 'updated_at'),
+        ...(claimToken === undefined ? {} : { claimToken }),
+        ...(claimAudience === undefined ? {} : { claimAudience }),
+        ...(claimExpiresAt === undefined ? {} : { claimExpiresAt }),
+        ...(wedgeReason === undefined ? {} : { wedgeReason }),
+    };
+};
 async function createSchema(client) {
     await client.execute(`CREATE TABLE IF NOT EXISTS wg_ops (
     id TEXT PRIMARY KEY, issue_id TEXT NOT NULL, lamport INTEGER NOT NULL,
@@ -39,9 +64,24 @@ async function createSchema(client) {
     await client.execute(`CREATE TABLE IF NOT EXISTS wg_issues (
     id TEXT PRIMARY KEY, title TEXT NOT NULL, body TEXT NOT NULL DEFAULT '',
     status TEXT NOT NULL DEFAULT 'open', created_at TEXT NOT NULL, updated_at TEXT NOT NULL,
-    lww INTEGER NOT NULL DEFAULT 0);`);
+    lww INTEGER NOT NULL DEFAULT 0,
+    claim_token TEXT, claim_audience TEXT, claim_expires_at TEXT, wedge_reason TEXT);`);
     await client.execute(`CREATE TABLE IF NOT EXISTS wg_edges (
     edge_key TEXT PRIMARY KEY, from_id TEXT NOT NULL, to_id TEXT NOT NULL, type TEXT NOT NULL);`);
+    // GR.1/GR.3 — additive claim + wedge columns for a pre-existing wg_issues (idempotent; already-migrated throws).
+    for (const ddl of [
+        `ALTER TABLE wg_issues ADD COLUMN claim_token TEXT`,
+        `ALTER TABLE wg_issues ADD COLUMN claim_audience TEXT`,
+        `ALTER TABLE wg_issues ADD COLUMN claim_expires_at TEXT`,
+        `ALTER TABLE wg_issues ADD COLUMN wedge_reason TEXT`,
+    ]) {
+        try {
+            await client.execute(ddl);
+        }
+        catch {
+            /* column already exists */
+        }
+    }
     await client.execute(`DROP TABLE IF EXISTS wg_events;`); // clean cutover from the 1c state-primary store
 }
 export function workGraphStore(opts) {
@@ -131,11 +171,45 @@ export function workGraphStore(opts) {
             await appendOp(fromId, 'dep_added', { from: fromId, to: toId, type });
         },
         async listReady() {
-            const rs = await db().execute(`SELECT * FROM wg_issues WHERE status = 'open' AND id NOT IN (
-        SELECT e.to_id FROM wg_edges e JOIN wg_issues x ON x.id = e.from_id
-        WHERE e.type = 'blocks' AND x.status != 'closed') ORDER BY created_at`);
+            // Open, unblocked, AND not live-claimed. A claim with claim_expires_at <= now is treated as
+            // unclaimed (query-time expiry — no reaper). ISO-8601 UTC sorts lexically == chronologically.
+            const now = new Date().toISOString();
+            const rs = await db().execute({
+                sql: `SELECT * FROM wg_issues WHERE status = 'open'
+          AND (claim_token IS NULL OR claim_expires_at <= ?)
+          AND wedge_reason IS NULL
+          AND id NOT IN (
+            SELECT e.to_id FROM wg_edges e JOIN wg_issues x ON x.id = e.from_id
+            WHERE e.type = 'blocks' AND x.status != 'closed') ORDER BY created_at`,
+                args: [now],
+            });
             return rs.rows.map(rowToIssue);
         },
+        async wedgeMark(id, reason) {
+            if ((await getIssue(id)) === null)
+                throw new Error(`workgraph: no issue ${id}`);
+            await appendOp(id, 'wedge_marked', { reason });
+        },
+        async clearWedge(id) {
+            if ((await getIssue(id)) === null)
+                throw new Error(`workgraph: no issue ${id}`);
+            await appendOp(id, 'wedge_cleared', {});
+        },
+        async claimIssue(id, audience, ttlSec) {
+            if ((await getIssue(id)) === null)
+                throw new Error(`workgraph: no issue ${id}`);
+            const expiresAt = new Date(Date.now() + ttlSec * 1000).toISOString();
+            // Unique per attempt → robust read-back (no two claims collide even at the same ms/expiry).
+            const claimToken = 'clm-' +
+                createHash('sha256')
+                    .update(`${id}\n${String(Date.now())}\n${String(Math.random())}`)
+                    .digest('hex')
+                    .slice(0, 16);
+            await appendOp(id, 'claim_acquired', { claimToken, audience, expiresAt });
+            // applyOp ran the conditional CAS; we won iff OUR token is the one that landed.
+            const cur = await getIssue(id);
+            return { won: cur?.claimToken === claimToken, expiresAt };
+        },
         async listEvents(issueId) {
             const rs = await db().execute({
                 sql: 'SELECT id, issue_id, lamport, type, payload FROM wg_ops WHERE issue_id = ? ORDER BY lamport, id',