oxe-cc 0.9.2 → 1.0.0

package/lib/runtime/context/context-pack-builder.js

@@ -0,0 +1,136 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ContextPackBuilder = void 0;
+// ─── Relevance scoring ────────────────────────────────────────────────────────
+function scoreEvidenceRelevance(evidence, workItem) {
+    let score = 0.5;
+    const eid = evidence.evidence_id.toLowerCase();
+    const title = workItem.title.toLowerCase();
+    const scope = workItem.mutation_scope ?? [];
+    if (scope.some((s) => eid.includes(s.toLowerCase())))
+        score += 0.3;
+    if (title.split(/\s+/).some((w) => w.length > 3 && eid.includes(w)))
+        score += 0.1;
+    if (evidence.type === 'junit_xml')
+        score += 0.05;
+    if (evidence.type === 'diff')
+        score += 0.05;
+    return Math.min(score, 1.0);
+}
+function scoreLessonRelevance(lesson, workItem) {
+    const itemTags = new Set([
+        ...workItem.mutation_scope.map((s) => s.toLowerCase()),
+        ...workItem.title.toLowerCase().split(/\s+/).filter((w) => w.length > 3),
+    ]);
+    const lessonTags = lesson.tags.map((t) => t.toLowerCase());
+    const overlap = lessonTags.filter((t) => itemTags.has(t)).length;
+    const jaccard = overlap / (itemTags.size + lessonTags.length - overlap || 1);
+    return Math.min(0.3 + jaccard * 0.7, 1.0);
+}
+// ─── Redundancy elimination ───────────────────────────────────────────────────
+function cosineSimilarity(a, b) {
+    const wordsA = new Set(a.content.toLowerCase().split(/\W+/).filter((w) => w.length > 3));
+    const wordsB = new Set(b.content.toLowerCase().split(/\W+/).filter((w) => w.length > 3));
+    if (wordsA.size === 0 || wordsB.size === 0)
+        return 0;
+    let intersection = 0;
+    for (const w of wordsA)
+        if (wordsB.has(w))
+            intersection++;
+    return intersection / Math.sqrt(wordsA.size * wordsB.size);
+}
+function deduplicateArtifacts(artifacts, threshold) {
+    const kept = [];
+    let removed = 0;
+    for (const candidate of artifacts) {
+        const isDuplicate = kept.some((existing) => cosineSimilarity(candidate, existing) >= threshold);
+        if (isDuplicate) {
+            removed++;
+        }
+        else {
+            kept.push(candidate);
+        }
+    }
+    return { kept, removed };
+}
+// ─── Token budget estimation ──────────────────────────────────────────────────
+function estimateTokens(text) {
+    return Math.ceil(text.length / 4);
+}
+function applyTokenBudget(artifacts, maxTokens) {
+    let used = 0;
+    const result = [];
+    for (const a of artifacts) {
+        const t = estimateTokens(a.content);
+        if (used + t > maxTokens)
+            break;
+        result.push(a);
+        used += t;
+    }
+    return result;
+}
+// ─── Context Pack Builder ─────────────────────────────────────────────────────
+class ContextPackBuilder {
+    constructor(opts = {}) {
+        this.opts = opts;
+    }
+    build(workItem, state, evidenceItems, evidenceContents, lessons) {
+        const { maxArtifacts = 20, maxTokensEstimate = 8000, deduplicateThreshold = 0.85, } = this.opts;
+        const raw = [];
+        // Score and collect evidence
+        for (const ev of evidenceItems) {
+            const content = evidenceContents.get(ev.evidence_id) ?? '';
+            if (!content)
+                continue;
+            raw.push({
+                id: ev.evidence_id,
+                kind: 'evidence',
+                content,
+                relevanceScore: scoreEvidenceRelevance(ev, workItem),
+                tags: [ev.type, workItem.work_item_id],
+            });
+        }
+        // Score and collect lessons
+        for (const lesson of lessons) {
+            raw.push({
+                id: lesson.lesson_id,
+                kind: 'lesson',
+                content: lesson.content,
+                relevanceScore: scoreLessonRelevance(lesson, workItem),
+                tags: lesson.tags,
+            });
+        }
+        // Add run-level summary if available
+        const completedCount = state.completedWorkItems.size;
+        if (completedCount > 0) {
+            raw.push({
+                id: `run-summary-${workItem.run_id}`,
+                kind: 'summary',
+                content: `Run progress: ${completedCount} completed, ${state.failedWorkItems.size} failed, ${state.blockedWorkItems.size} blocked.`,
+                relevanceScore: 0.4,
+                tags: ['run-context'],
+            });
+        }
+        const totalConsidered = raw.length;
+        // Sort by relevance descending
+        raw.sort((a, b) => b.relevanceScore - a.relevanceScore);
+        // Deduplicate
+        const { kept, removed } = deduplicateArtifacts(raw, deduplicateThreshold);
+        // Apply max artifacts cap
+        const capped = kept.slice(0, maxArtifacts);
+        // Apply token budget
+        const final = applyTokenBudget(capped, maxTokensEstimate);
+        return {
+            work_item_id: workItem.work_item_id,
+            artifacts: final,
+            total_artifacts_considered: totalConsidered,
+            redundancy_removed: removed,
+            built_at: new Date().toISOString(),
+        };
+    }
+    /** Convenience: build with no evidence, just lessons and state summary */
+    buildLightweight(workItem, state, lessons) {
+        return this.build(workItem, state, [], new Map(), lessons);
+    }
+}
+exports.ContextPackBuilder = ContextPackBuilder;

package/lib/runtime/context/index.d.ts

@@ -0,0 +1 @@
+export * from './context-pack-builder';

package/lib/runtime/context/index.js

@@ -0,0 +1,17 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./context-pack-builder"), exports);

package/lib/runtime/delivery/branch-manager.d.ts

@@ -0,0 +1,19 @@
+export interface BranchInfo {
+    name: string;
+    current: boolean;
+    commit: string;
+}
+export declare class BranchManager {
+    private readonly projectRoot;
+    constructor(projectRoot: string);
+    currentBranch(): string;
+    currentCommit(): string;
+    createSessionBranch(sessionId: string): string;
+    createOxeBranch(name: string, base?: string): string;
+    switchTo(branchName: string): void;
+    deleteBranch(name: string, force?: boolean): void;
+    listOxeBranches(): BranchInfo[];
+    mergeWorktreeBranch(worktreeBranch: string, targetBranch: string): void;
+    branchExists(name: string): boolean;
+    private git;
+}

package/lib/runtime/delivery/branch-manager.js

@@ -0,0 +1,78 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BranchManager = void 0;
+const child_process_1 = require("child_process");
+class BranchManager {
+    constructor(projectRoot) {
+        this.projectRoot = projectRoot;
+    }
+    currentBranch() {
+        return this.git(['rev-parse', '--abbrev-ref', 'HEAD']).trim();
+    }
+    currentCommit() {
+        return this.git(['rev-parse', 'HEAD']).trim();
+    }
+    createSessionBranch(sessionId) {
+        const name = `oxe/${sessionId}`;
+        this.git(['checkout', '-b', name]);
+        return name;
+    }
+    createOxeBranch(name, base) {
+        const fullName = name.startsWith('oxe/') ? name : `oxe/${name}`;
+        if (base) {
+            this.git(['checkout', '-b', fullName, base]);
+        }
+        else {
+            this.git(['checkout', '-b', fullName]);
+        }
+        return fullName;
+    }
+    switchTo(branchName) {
+        this.git(['checkout', branchName]);
+    }
+    deleteBranch(name, force = false) {
+        const flag = force ? '-D' : '-d';
+        this.git(['branch', flag, name]);
+    }
+    listOxeBranches() {
+        const raw = this.git(['branch', '--list', 'oxe/*', '--format=%(refname:short) %(objectname:short) %(HEAD)']);
+        return raw
+            .split('\n')
+            .filter(Boolean)
+            .map((line) => {
+            const parts = line.trim().split(/\s+/);
+            return {
+                name: parts[0],
+                commit: parts[1] ?? '',
+                current: parts[2] === '*',
+            };
+        });
+    }
+    mergeWorktreeBranch(worktreeBranch, targetBranch) {
+        const saved = this.currentBranch();
+        try {
+            this.git(['checkout', targetBranch]);
+            this.git(['merge', '--no-ff', worktreeBranch, '-m', `oxe: merge ${worktreeBranch}`]);
+        }
+        finally {
+            try {
+                this.git(['checkout', saved]);
+            }
+            catch { /* best effort */ }
+        }
+    }
+    branchExists(name) {
+        const result = (0, child_process_1.spawnSync)('git', ['rev-parse', '--verify', name], {
+            cwd: this.projectRoot,
+            encoding: 'utf8',
+        });
+        return result.status === 0;
+    }
+    git(args) {
+        return (0, child_process_1.execFileSync)('git', args, {
+            cwd: this.projectRoot,
+            encoding: 'utf8',
+        });
+    }
+}
+exports.BranchManager = BranchManager;

package/lib/runtime/delivery/ci-checks.d.ts

@@ -0,0 +1,34 @@
+import type { EvidenceStore } from '../evidence/evidence-store';
+export type CICheckStatus = 'pass' | 'fail' | 'skip' | 'error';
+export interface CICheckContext {
+    projectRoot: string;
+    sessionId: string | null;
+    runId?: string;
+    evidenceStore?: EvidenceStore;
+}
+export interface CICheckResult {
+    check: string;
+    status: CICheckStatus;
+    message: string;
+    details?: unknown;
+}
+export interface CICheck {
+    name: string;
+    description: string;
+    run(ctx: CICheckContext): Promise<CICheckResult>;
+}
+export declare const planConsistencyCheck: CICheck;
+export declare const verifyAcceptanceCheck: CICheck;
+export declare const policyCheck: CICheck;
+export declare const securityBaselineCheck: CICheck;
+export declare const runtimeEvidenceIntegrityCheck: CICheck;
+export declare const OXE_CI_CHECKS: CICheck[];
+export declare function runCIChecks(ctx: CICheckContext, checks?: CICheck[]): Promise<CICheckResult[]>;
+export declare function summarizeCIResults(results: CICheckResult[]): {
+    total: number;
+    pass: number;
+    fail: number;
+    skip: number;
+    error: number;
+    allPassed: boolean;
+};

package/lib/runtime/delivery/ci-checks.js

@@ -0,0 +1,209 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OXE_CI_CHECKS = exports.runtimeEvidenceIntegrityCheck = exports.securityBaselineCheck = exports.policyCheck = exports.verifyAcceptanceCheck = exports.planConsistencyCheck = void 0;
+exports.runCIChecks = runCIChecks;
+exports.summarizeCIResults = summarizeCIResults;
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+// ─── Check: plan-consistency ─────────────────────────────────────────────────
+exports.planConsistencyCheck = {
+    name: 'oxe-plan-consistency',
+    description: 'Verifies ACTIVE-RUN.json exists and has a compiled ExecutionGraph',
+    async run(ctx) {
+        const activeRunPath = ctx.sessionId
+            ? path_1.default.join(ctx.projectRoot, '.oxe', ctx.sessionId, 'execution', 'ACTIVE-RUN.json')
+            : path_1.default.join(ctx.projectRoot, '.oxe', 'ACTIVE-RUN.json');
+        if (!fs_1.default.existsSync(activeRunPath)) {
+            return { check: this.name, status: 'skip', message: 'No ACTIVE-RUN.json found' };
+        }
+        try {
+            const raw = JSON.parse(fs_1.default.readFileSync(activeRunPath, 'utf8'));
+            const hasGraph = raw.compiled_graph && typeof raw.compiled_graph === 'object';
+            const hasRunId = typeof raw.run_id === 'string';
+            if (!hasRunId) {
+                return { check: this.name, status: 'fail', message: 'ACTIVE-RUN.json missing run_id', details: raw };
+            }
+            if (!hasGraph) {
+                return { check: this.name, status: 'fail', message: 'No compiled ExecutionGraph found in ACTIVE-RUN.json', details: { run_id: raw.run_id } };
+            }
+            return { check: this.name, status: 'pass', message: `Run ${String(raw.run_id)} has compiled graph` };
+        }
+        catch (err) {
+            return { check: this.name, status: 'error', message: `Failed to parse ACTIVE-RUN.json: ${String(err)}` };
+        }
+    },
+};
+// ─── Check: verify-acceptance ────────────────────────────────────────────────
+exports.verifyAcceptanceCheck = {
+    name: 'oxe-verify-acceptance',
+    description: 'Checks that VERIFY.md exists and contains no failed criteria',
+    async run(ctx) {
+        const verifyPath = ctx.sessionId
+            ? path_1.default.join(ctx.projectRoot, '.oxe', ctx.sessionId, 'verification', 'VERIFY.md')
+            : path_1.default.join(ctx.projectRoot, '.oxe', 'VERIFY.md');
+        if (!fs_1.default.existsSync(verifyPath)) {
+            return { check: this.name, status: 'skip', message: 'No VERIFY.md found — run /oxe-verify first' };
+        }
+        const content = fs_1.default.readFileSync(verifyPath, 'utf8');
+        const failLines = content.split('\n').filter((l) => l.includes('✗ FAIL'));
+        const passLines = content.split('\n').filter((l) => l.includes('✓ PASS'));
+        if (failLines.length > 0) {
+            return {
+                check: this.name,
+                status: 'fail',
+                message: `${failLines.length} acceptance criteria failed`,
+                details: { failed: failLines, passed: passLines.length },
+            };
+        }
+        if (passLines.length === 0) {
+            return { check: this.name, status: 'skip', message: 'VERIFY.md has no pass/fail markers' };
+        }
+        return { check: this.name, status: 'pass', message: `${passLines.length} acceptance criteria passed` };
+    },
+};
+// ─── Check: policy ───────────────────────────────────────────────────────────
+exports.policyCheck = {
+    name: 'oxe-policy',
+    description: 'Checks that no gates are pending (unresolved human approval)',
+    async run(ctx) {
+        const gatesPath = ctx.sessionId
+            ? path_1.default.join(ctx.projectRoot, '.oxe', ctx.sessionId, 'execution', 'GATES.json')
+            : path_1.default.join(ctx.projectRoot, '.oxe', 'execution', 'GATES.json');
+        if (!fs_1.default.existsSync(gatesPath)) {
+            return { check: this.name, status: 'pass', message: 'No pending gates' };
+        }
+        try {
+            const gates = JSON.parse(fs_1.default.readFileSync(gatesPath, 'utf8'));
+            const pending = gates.filter((g) => g.status === 'pending');
+            if (pending.length > 0) {
+                return {
+                    check: this.name,
+                    status: 'fail',
+                    message: `${pending.length} unresolved gate(s)`,
+                    details: pending.map((g) => ({ gate_id: g.gate_id, scope: g.scope })),
+                };
+            }
+            return { check: this.name, status: 'pass', message: 'All gates resolved' };
+        }
+        catch (err) {
+            return { check: this.name, status: 'error', message: `Failed to read GATES.json: ${String(err)}` };
+        }
+    },
+};
+// ─── Check: security-baseline ────────────────────────────────────────────────
+const SECRET_PATTERNS = [
+    /(?:password|passwd|secret|api[_-]?key|auth[_-]?token)\s*[:=]\s*['"]?\S{8,}/i,
+    /(?:AKIA|ASIA)[A-Z0-9]{16}/,
+    /-----BEGIN (?:RSA|EC|OPENSSH) PRIVATE KEY-----/,
+];
+exports.securityBaselineCheck = {
+    name: 'oxe-security-baseline',
+    description: 'Scans evidence artifacts for common secret patterns',
+    async run(ctx) {
+        if (!ctx.evidenceStore || !ctx.runId) {
+            return { check: this.name, status: 'skip', message: 'No evidence store or run ID provided' };
+        }
+        const evidenceDir = path_1.default.join(ctx.projectRoot, '.oxe', 'evidence', 'runs', ctx.runId);
+        if (!fs_1.default.existsSync(evidenceDir)) {
+            return { check: this.name, status: 'skip', message: 'No evidence found for this run' };
+        }
+        const findings = [];
+        walkDir(evidenceDir, (filePath) => {
+            if (filePath.endsWith('.json') || filePath.endsWith('.patch') || filePath.endsWith('.txt')) {
+                try {
+                    const content = fs_1.default.readFileSync(filePath, 'utf8');
+                    for (const pattern of SECRET_PATTERNS) {
+                        if (pattern.test(content)) {
+                            findings.push(`${path_1.default.basename(filePath)}: matches pattern ${pattern.source.slice(0, 40)}`);
+                            break;
+                        }
+                    }
+                }
+                catch { /* skip unreadable */ }
+            }
+        });
+        if (findings.length > 0) {
+            return { check: this.name, status: 'fail', message: `Secret patterns detected in ${findings.length} evidence file(s)`, details: findings };
+        }
+        return { check: this.name, status: 'pass', message: 'No secret patterns detected in evidence' };
+    },
+};
+// ─── Check: runtime-evidence-integrity ───────────────────────────────────────
+exports.runtimeEvidenceIntegrityCheck = {
+    name: 'oxe-runtime-evidence-integrity',
+    description: 'Validates that all evidence index files are valid JSON and files exist on disk',
+    async run(ctx) {
+        if (!ctx.runId) {
+            return { check: this.name, status: 'skip', message: 'No run ID provided' };
+        }
+        const runEvidenceDir = path_1.default.join(ctx.projectRoot, '.oxe', 'evidence', 'runs', ctx.runId);
+        if (!fs_1.default.existsSync(runEvidenceDir)) {
+            return { check: this.name, status: 'skip', message: 'No evidence directory for this run' };
+        }
+        const errors = [];
+        let indexCount = 0;
+        let evidenceCount = 0;
+        walkDir(runEvidenceDir, (filePath) => {
+            if (path_1.default.basename(filePath) !== 'index.json')
+                return;
+            indexCount++;
+            try {
+                const items = JSON.parse(fs_1.default.readFileSync(filePath, 'utf8'));
+                for (const item of items) {
+                    evidenceCount++;
+                    const absPath = path_1.default.join(ctx.projectRoot, item.path);
+                    if (!fs_1.default.existsSync(absPath)) {
+                        errors.push(`Missing file for ${item.evidence_id}: ${item.path}`);
+                    }
+                }
+            }
+            catch (err) {
+                errors.push(`Corrupt index at ${filePath}: ${String(err)}`);
+            }
+        });
+        if (errors.length > 0) {
+            return { check: this.name, status: 'fail', message: `${errors.length} integrity error(s)`, details: errors };
+        }
+        return {
+            check: this.name,
+            status: indexCount === 0 ? 'skip' : 'pass',
+            message: `${evidenceCount} evidence artifact(s) across ${indexCount} index(es) — all valid`,
+        };
+    },
+};
+// ─── Suite ───────────────────────────────────────────────────────────────────
+exports.OXE_CI_CHECKS = [
+    exports.planConsistencyCheck,
+    exports.verifyAcceptanceCheck,
+    exports.policyCheck,
+    exports.securityBaselineCheck,
+    exports.runtimeEvidenceIntegrityCheck,
+];
+async function runCIChecks(ctx, checks = exports.OXE_CI_CHECKS) {
+    const results = [];
+    for (const check of checks) {
+        results.push(await check.run(ctx));
+    }
+    return results;
+}
+function summarizeCIResults(results) {
+    const counts = { total: results.length, pass: 0, fail: 0, skip: 0, error: 0 };
+    for (const r of results)
+        counts[r.status]++;
+    return { ...counts, allPassed: counts.fail === 0 && counts.error === 0 };
+}
+// ─── Helpers ─────────────────────────────────────────────────────────────────
+function walkDir(dir, visitor) {
+    if (!fs_1.default.existsSync(dir))
+        return;
+    for (const entry of fs_1.default.readdirSync(dir, { withFileTypes: true })) {
+        const full = path_1.default.join(dir, entry.name);
+        if (entry.isDirectory())
+            walkDir(full, visitor);
+        else
+            visitor(full);
+    }
+}

package/lib/runtime/delivery/index.d.ts

@@ -0,0 +1,3 @@
+export * from './branch-manager';
+export * from './pr-manager';
+export * from './ci-checks';

package/lib/runtime/delivery/index.js

@@ -0,0 +1,19 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./branch-manager"), exports);
+__exportStar(require("./pr-manager"), exports);
+__exportStar(require("./ci-checks"), exports);

package/lib/runtime/delivery/pr-manager.d.ts

@@ -0,0 +1,30 @@
+export interface PRDraftOptions {
+    title: string;
+    body: string;
+    base?: string;
+    head?: string;
+    draft?: boolean;
+}
+export interface PRInfo {
+    number: number;
+    title: string;
+    url: string;
+    state: string;
+    draft: boolean;
+    head: string;
+    base: string;
+}
+export interface PRResult {
+    success: boolean;
+    url?: string;
+    error?: string;
+    pr?: PRInfo;
+}
+export declare class PRManager {
+    private readonly projectRoot;
+    constructor(projectRoot: string);
+    isAvailable(): boolean;
+    createDraft(opts: PRDraftOptions): PRResult;
+    view(prNumberOrUrl: string | number): PRResult;
+    mergePR(prNumber: number, method?: 'merge' | 'squash' | 'rebase'): PRResult;
+}

package/lib/runtime/delivery/pr-manager.js

@@ -0,0 +1,82 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PRManager = void 0;
+const child_process_1 = require("child_process");
+function isGhAvailable(cwd) {
+    const result = (0, child_process_1.spawnSync)('gh', ['--version'], { cwd, encoding: 'utf8' });
+    return result.status === 0;
+}
+class PRManager {
+    constructor(projectRoot) {
+        this.projectRoot = projectRoot;
+    }
+    isAvailable() {
+        return isGhAvailable(this.projectRoot);
+    }
+    createDraft(opts) {
+        if (!this.isAvailable()) {
+            return { success: false, error: 'gh CLI not available — install from https://cli.github.com' };
+        }
+        const args = [
+            'pr', 'create',
+            '--title', opts.title,
+            '--body', opts.body,
+        ];
+        if (opts.draft !== false)
+            args.push('--draft');
+        if (opts.base)
+            args.push('--base', opts.base);
+        if (opts.head)
+            args.push('--head', opts.head);
+        const result = (0, child_process_1.spawnSync)('gh', args, {
+            cwd: this.projectRoot,
+            encoding: 'utf8',
+        });
+        if (result.status !== 0) {
+            return { success: false, error: result.stderr?.trim() ?? 'gh pr create failed' };
+        }
+        const url = result.stdout?.trim();
+        return { success: true, url };
+    }
+    view(prNumberOrUrl) {
+        if (!this.isAvailable()) {
+            return { success: false, error: 'gh CLI not available' };
+        }
+        const result = (0, child_process_1.spawnSync)('gh', ['pr', 'view', String(prNumberOrUrl), '--json', 'number,title,url,state,isDraft,headRefName,baseRefName'], { cwd: this.projectRoot, encoding: 'utf8' });
+        if (result.status !== 0) {
+            return { success: false, error: result.stderr?.trim() };
+        }
+        try {
+            const raw = JSON.parse(result.stdout);
+            return {
+                success: true,
+                url: raw.url,
+                pr: {
+                    number: raw.number,
+                    title: raw.title,
+                    url: raw.url,
+                    state: raw.state.toLowerCase(),
+                    draft: raw.isDraft,
+                    head: raw.headRefName,
+                    base: raw.baseRefName,
+                },
+            };
+        }
+        catch {
+            return { success: false, error: 'Failed to parse gh output' };
+        }
+    }
+    mergePR(prNumber, method = 'merge') {
+        if (!this.isAvailable()) {
+            return { success: false, error: 'gh CLI not available' };
+        }
+        const result = (0, child_process_1.spawnSync)('gh', ['pr', 'merge', String(prNumber), `--${method}`, '--delete-branch'], {
+            cwd: this.projectRoot,
+            encoding: 'utf8',
+        });
+        return result.status === 0
+            ? { success: true }
+            : { success: false, error: result.stderr?.trim() };
+    }
+}
+exports.PRManager = PRManager;

package/lib/runtime/events/bus.d.ts

@@ -0,0 +1,9 @@
+import type { OxeEvent } from './envelope';
+import type { EventType } from './catalog';
+export type EventInput = Partial<Omit<OxeEvent, 'type'>> & {
+    type: EventType;
+};
+export declare function appendEvent(projectRoot: string, sessionId: string | null, input: EventInput, causationId?: string): OxeEvent;
+export declare function readEvents(projectRoot: string, sessionId: string | null): OxeEvent[];
+export declare function filterByRun(events: OxeEvent[], runId: string): OxeEvent[];
+export declare function filterByWorkItem(events: OxeEvent[], workItemId: string): OxeEvent[];