pi-pstack-native 0.0.0-stage → 1.0.0

package/dist/delivery/frontier.js

@@ -0,0 +1,123 @@
+import { hash, protocol, transact, uid } from "../runtime/protocol.js";
+import { ledgerCurrent } from "../verification/runner.js";
+// GitHub reports CLEAN only when the base and the required checks are settled. Every other merge
+// state, and a missing one, needs a human look before shipping.
+const CLEAN_MERGE_STATE = 'CLEAN';
+export async function refresh(spec, provider) {
+    if (!/^[a-zA-Z0-9._-]+$/.test(spec.id) || ['__proto__', 'constructor', 'prototype'].includes(spec.id))
+        throw new Error('INVALID_STACK_ID');
+    if (!spec.numbers.length || new Set(spec.numbers).size !== spec.numbers.length)
+        throw new Error('INVALID_STACK');
+    const prs = [];
+    for (const number of spec.numbers)
+        prs.push(await provider.read(spec.repo, number));
+    if (prs.some((p, i) => p.repo !== spec.repo || p.number !== spec.numbers[i] || !p.headSha || !p.baseSha))
+        throw new Error('STATE_UNCERTAIN');
+    // A dependent base must equal the preceding head before that predecessor is merged.
+    for (let i = 1; i < prs.length; i++)
+        if (prs[i - 1].state !== 'MERGED' && (prs[i].baseSha !== prs[i - 1].headSha || Boolean(prs[i - 1].headRef && prs[i].baseRef !== prs[i - 1].headRef)))
+            throw new Error('STACK_TOPOLOGY_MISMATCH');
+    return transact('frontier-refreshed', spec.id, 'provider', s => {
+        const old = s.frontiers[spec.id];
+        if (old && (old.owner !== spec.owner || old.repo !== spec.repo || old.repoId !== spec.repoId))
+            throw new Error('STACK_IDENTITY_CONFLICT');
+        for (const e of Object.values(s.ledgers)) {
+            const p = prs.find(p => e.pr?.repoId === spec.repoId && e.pr.number === p.number);
+            if (p && (!e.diffBase || e.diffBase.commitSha !== p.baseSha || e.pr.headSha !== p.headSha))
+                s.invalidations[e.id] = { at: new Date().toISOString(), reason: 'PR_BASE_OR_HEAD_CHANGED' };
+        }
+        // The shipping trunk is operator input, never a property of the PR under test. A persisted
+        // value wins so a later refresh cannot retarget the trunk silently.
+        const rootBase = old?.rootBase ?? spec.rootBase;
+        if (!rootBase)
+            throw new Error('STACK_ROOT_BASE_REQUIRED');
+        if (old?.rootBase && spec.rootBase && spec.rootBase !== old.rootBase)
+            throw new Error('STACK_ROOT_BASE_CHANGED');
+        const digest = hash({ prs, rootBase, requireReview: spec.requireReview !== false, requireBehavior: spec.requireBehavior !== false });
+        const f = { ...spec, rootBase, prs, digest, generation: (old?.generation ?? 0) + (old?.digest === digest ? 0 : 1), checkedAt: new Date().toISOString() };
+        s.frontiers[spec.id] = f;
+        return f;
+    });
+}
+export function eligibility(f) {
+    const s = protocol();
+    let lower = false;
+    return f.prs.map(p => {
+        if (p.state === 'MERGED')
+            return { number: p.number, eligible: false, blockers: ['ALREADY_MERGED'] };
+        const blockers = [];
+        if (lower)
+            blockers.push('LOWER_UNMERGED');
+        else if (f.rootBase && p.baseRef !== f.rootBase)
+            blockers.push('FRONTIER_BASE_NOT_TRUNK');
+        lower = true;
+        if (p.state !== 'OPEN')
+            blockers.push('PR_NOT_OPEN');
+        // Runtime callers can be plain JavaScript, so absent provider fields must still block.
+        if (p.draft !== false)
+            blockers.push('PR_DRAFT');
+        if (p.reviewThreads?.status !== 'checked')
+            blockers.push('REVIEW_THREADS_NOT_CHECKED');
+        else if (p.reviewThreads.unresolved > 0)
+            blockers.push('UNRESOLVED_REVIEW_THREADS');
+        if (p.mergeState !== CLEAN_MERGE_STATE)
+            blockers.push(`MERGE_STATE_${p.mergeState ?? 'MISSING'}`);
+        if (p.mergeable !== 'MERGEABLE')
+            blockers.push(p.mergeable === 'CONFLICTING' ? 'CONFLICT' : 'STATE_UNCERTAIN');
+        if (p.review === 'changes-requested' || f.requireReview !== false && p.review !== 'approved')
+            blockers.push('REVIEW_REQUIRED');
+        if (p.ci !== 'passed')
+            blockers.push('CI_NOT_PASSED');
+        const entries = Object.values(s.ledgers).filter(e => e.pr?.repoId === f.repoId && e.pr.number === p.number && e.pr.headSha === p.headSha && e.fingerprint.kind === 'committed' && e.fingerprint.commitSha === p.headSha);
+        if (!entries.some(e => e.diffBase?.commitSha === p.baseSha && e.contractAccepted && ledgerCurrent(e, e.fingerprint) && (f.requireBehavior === false || e.verdict === 'unit-test-verified')))
+            blockers.push('CURRENT_VERIFICATION_REQUIRED');
+        return { number: p.number, eligible: blockers.length === 0, blockers };
+    });
+}
+export function authorizeMerge(f, number, actor) {
+    if (actor !== 'human-cli')
+        throw new Error('HUMAN_AUTHORIZATION_REQUIRED');
+    const token = uid('approval');
+    transact('merge-authorized', f.id, actor, s => { s.approvals[token] = { stackId: f.id, number, digest: f.digest, generation: f.generation, expiresAt: Date.now() + 5 * 60_000, used: false }; return { token, number }; });
+    return token;
+}
+export async function ship(spec, provider, options = {}) {
+    const f = await refresh(spec, provider);
+    const decisions = eligibility(f);
+    if (options.dryRun !== false)
+        return { frontier: f, decisions, dryRun: true };
+    const approval = options.token ? protocol().approvals[options.token] : undefined;
+    if (!approval || approval.stackId !== f.id || approval.digest !== f.digest || approval.generation !== f.generation || approval.used || approval.expiresAt < Date.now())
+        throw new Error('AUTHORIZATION_MISSING_OR_STALE');
+    const target = f.prs.find(p => p.number === approval.number);
+    if (!decisions.find(d => d.number === target?.number)?.eligible)
+        throw new Error('SHIPPING_BLOCKED');
+    // Query twice, then use provider's server-side expected-head precondition.
+    const checked = await refresh(spec, provider);
+    if (checked.digest !== f.digest || checked.generation !== f.generation)
+        throw new Error('FRONTIER_CHANGED');
+    transact('merge-requested', f.id, 'shipping-gate', s => {
+        const a = s.approvals[options.token];
+        if (a.used)
+            throw new Error('AUTHORIZATION_CONSUMED');
+        a.used = true;
+        return { number: target.number, head: target.headSha };
+    });
+    await provider.merge(target);
+    const actual = await provider.read(spec.repo, target.number);
+    if (actual.state !== 'MERGED')
+        throw new Error('MERGE_UNCONFIRMED');
+    transact('merge-confirmed', f.id, 'provider', () => ({ number: actual.number, head: actual.headSha }));
+    return { merged: actual.number, frontier: await refresh(spec, provider) };
+}
+/** Native snapshot states, not fabricated Cursor watcher verdicts. No merging or polling. */
+export function watchFrontier(f, previous) {
+    const target = f.prs.find(p => p.state !== 'MERGED');
+    if (!target)
+        return { state: 'complete', frontier: null, digest: f.digest };
+    if (target.state === 'CLOSED')
+        return { state: 'closed', frontier: target.number, digest: f.digest };
+    const decision = eligibility(f).find(d => d.number === target.number);
+    const advanced = previous && previous.number !== target.number;
+    return { state: advanced ? 'advance' : decision.eligible ? 'reviewable' : 'waiting', frontier: target.number, headSha: target.headSha, digest: f.digest, blockers: decision.blockers, autoMergeRequested: target.autoMergeRequested ?? false, queueState: 'not-claimed', stopBeforeMerge: true };
+}

package/dist/delivery/git.d.ts

@@ -0,0 +1,2 @@
+export declare function githubRepository(cwd: string): string;
+export declare function assertGitHubRepository(cwd: string, repo: string): void;

package/dist/delivery/git.js

@@ -0,0 +1,12 @@
+import { git } from "../artifacts/fingerprint.js";
+export function githubRepository(cwd) {
+    const remote = git(cwd, ['remote', 'get-url', 'origin']);
+    const match = remote.match(/^(?:https:\/\/(?:[^/@]+@)?github\.com\/|git@github\.com:|ssh:\/\/git@github\.com\/)([\w.-]+\/[\w.-]+?)(?:\.git)?\/?$/);
+    if (!match)
+        throw new Error('GITHUB_REPOSITORY_UNCONFIRMED');
+    return match[1];
+}
+export function assertGitHubRepository(cwd, repo) {
+    if (githubRepository(cwd).toLowerCase() !== repo.toLowerCase())
+        throw new Error('PROVIDER_REPOSITORY_MISMATCH');
+}

package/dist/delivery/prepare.d.ts

@@ -0,0 +1,18 @@
+import type { GitHubCLI } from './provider.js';
+export declare function preparePR(cwd: string, ledgerId: string, options: {
+    repo: string;
+    base: string;
+    head: string;
+    title: string;
+}): {
+    headSha: string;
+    ledgerId: string;
+    evidence: string[];
+    body: string;
+    repo: string;
+    base: string;
+    head: string;
+    title: string;
+    id: string;
+};
+export declare function openPreparedPR(cwd: string, plan: ReturnType<typeof preparePR>, provider: GitHubCLI, approve?: boolean): Promise<unknown>;

package/dist/delivery/prepare.js

@@ -0,0 +1,30 @@
+import { assertGitHubRepository } from "./git.js";
+import { writeFileSync } from 'node:fs';
+import { homePath } from "../runtime/home.js";
+import { protocol, uid, transact } from "../runtime/protocol.js";
+import { fingerprint } from "../artifacts/fingerprint.js";
+import { ledgerCurrent } from "../verification/runner.js";
+export function preparePR(cwd, ledgerId, options) {
+    assertGitHubRepository(cwd, options.repo);
+    const l = protocol().ledgers[ledgerId];
+    const current = fingerprint(cwd, 'committed');
+    if (!l || !l.contractAccepted || l.fingerprint.kind !== 'committed' || !ledgerCurrent(l, current))
+        throw new Error('CURRENT_ACCEPTED_COMMIT_REQUIRED');
+    if (!options.title.trim() || !/^[\w.-]+\/[\w.-]+$/.test(options.repo))
+        throw new Error('INVALID_PR_DETAILS');
+    const plan = { id: uid('prplan'), ...options, headSha: current.commitSha, ledgerId, evidence: l.evidenceRefs, body: `${options.title}\n\nVerified commit: ${current.commitSha}\nVerification: ${l.verdict}\nLedger: ${l.id}\nEvidence: ${l.evidenceRefs.join(', ')}\n` };
+    transact('pr-prepared', plan.id, 'delivery', () => plan);
+    return plan;
+}
+export async function openPreparedPR(cwd, plan, provider, approve = false) {
+    if (!approve)
+        return { plan, dryRun: true };
+    preparePR(cwd, plan.ledgerId, plan);
+    if (await provider.branchHead(plan.repo, plan.head) !== plan.headSha)
+        throw new Error('REMOTE_BRANCH_NOT_VERIFIED');
+    const path = homePath(`${plan.id}.md`);
+    writeFileSync(path, plan.body, { mode: 0o600 });
+    const url = await provider.open(plan.repo, plan.base, plan.head, plan.title, path);
+    transact('pr-opened', plan.id, 'human-cli', () => ({ url, headSha: plan.headSha }));
+    return { url };
+}

package/dist/delivery/provider.d.ts

@@ -0,0 +1,31 @@
+import { type ReviewThreadSummary } from './review-threads.js';
+export interface PullRequest {
+    headRef?: string;
+    draft: boolean;
+    mergeState: string;
+    autoMergeRequested?: boolean;
+    reviewThreads?: ReviewThreadSummary;
+    number: number;
+    repo: string;
+    headSha: string;
+    baseSha: string;
+    baseRef: string;
+    state: 'OPEN' | 'MERGED' | 'CLOSED';
+    mergeable: 'MERGEABLE' | 'CONFLICTING' | 'UNKNOWN';
+    ci: 'passed' | 'failed' | 'pending' | 'unknown';
+    review: 'approved' | 'changes-requested' | 'pending';
+}
+export interface PRProvider {
+    read(repo: string, number: number): Promise<PullRequest>;
+    merge(pr: PullRequest): Promise<void>;
+}
+export declare class GitHubCLI implements PRProvider {
+    private readonly execute?;
+    constructor(execute?: (args: string[]) => string);
+    private gh;
+    read(repo: string, number: number): Promise<PullRequest>;
+    merge(pr: PullRequest): Promise<void>;
+    branchHead(repo: string, branch: string): Promise<string>;
+    find(repo: string, head: string): Promise<number | null>;
+    open(repo: string, base: string, head: string, title: string, bodyFile: string): Promise<string>;
+}

package/dist/delivery/provider.js

@@ -0,0 +1,42 @@
+import { collectReviewThreads, REVIEW_THREADS_QUERY } from "./review-threads.js";
+import { execFileSync } from 'node:child_process';
+export class GitHubCLI {
+    execute;
+    constructor(execute) { this.execute = execute; }
+    gh(args) { if (this.execute)
+        return this.execute(args); return execFileSync('gh', args, { encoding: 'utf8', timeout: 30000, maxBuffer: 4 * 1024 * 1024 }); }
+    async read(repo, number) {
+        if (!/^[\w.-]+\/[\w.-]+$/.test(repo) || !Number.isSafeInteger(number) || number < 1)
+            throw new Error('Invalid GitHub PR');
+        let p = JSON.parse(this.gh(['pr', 'view', String(number), '--repo', repo, '--json', 'number,headRefOid,headRefName,baseRefOid,baseRefName,state,isDraft,mergeable,mergeStateStatus,reviewDecision,statusCheckRollup,autoMergeRequest']));
+        const [owner, name] = repo.split('/');
+        const reviewThreads = await collectReviewThreads(async (cursor) => JSON.parse(this.gh(['api', 'graphql', '-f', `query=${REVIEW_THREADS_QUERY}`, '-F', `owner=${owner}`, '-F', `repo=${name}`, '-F', `number=${number}`, ...(cursor ? ['-f', `after=${cursor}`] : [])])));
+        const confirmed = JSON.parse(this.gh(['pr', 'view', String(number), '--repo', repo, '--json', 'number,headRefOid,headRefName,baseRefOid,baseRefName,state,isDraft,mergeable,mergeStateStatus,reviewDecision,statusCheckRollup,autoMergeRequest']));
+        if (confirmed.headRefOid !== p.headRefOid || confirmed.baseRefOid !== p.baseRefOid || confirmed.state !== p.state)
+            throw new Error('PR_CHANGED_DURING_READ');
+        p = confirmed;
+        const checks = p.statusCheckRollup;
+        const ci = !Array.isArray(checks) || !checks.length ? 'unknown' : checks.some((c) => ['FAILURE', 'ERROR', 'CANCELLED', 'TIMED_OUT', 'ACTION_REQUIRED'].includes(c.conclusion ?? c.state)) ? 'failed' : checks.every((c) => ['SUCCESS'].includes(c.conclusion ?? c.state)) ? 'passed' : 'pending';
+        return { headRef: p.headRefName, draft: p.isDraft, mergeState: p.mergeStateStatus ?? 'UNKNOWN', autoMergeRequested: p.autoMergeRequest != null, reviewThreads, number: p.number, repo, headSha: p.headRefOid, baseSha: p.baseRefOid, baseRef: p.baseRefName, state: p.state, mergeable: p.mergeable, ci, review: p.reviewDecision === 'APPROVED' ? 'approved' : p.reviewDecision === 'CHANGES_REQUESTED' ? 'changes-requested' : 'pending' };
+    }
+    async merge(pr) {
+        this.gh(['pr', 'merge', String(pr.number), '--repo', pr.repo, '--merge', '--match-head-commit', pr.headSha]);
+    }
+    async branchHead(repo, branch) {
+        const r = JSON.parse(this.gh(['api', `repos/${repo}/git/ref/heads/${encodeURIComponent(branch)}`]));
+        if (r.object?.type !== 'commit' || !r.object.sha)
+            throw new Error('REMOTE_BRANCH_UNCERTAIN');
+        return r.object.sha;
+    }
+    async find(repo, head) {
+        if (!/^[\w.-]+\/[\w.-]+$/.test(repo) || !head || head.startsWith('-'))
+            throw new Error('INVALID_PR_LOOKUP');
+        const prs = JSON.parse(this.gh(['pr', 'list', '--repo', repo, '--head', head, '--state', 'all', '--limit', '100', '--json', 'number']));
+        if (!Array.isArray(prs) || prs.length > 1)
+            throw new Error('PR_LOOKUP_AMBIGUOUS');
+        return prs[0]?.number ?? null;
+    }
+    async open(repo, base, head, title, bodyFile) {
+        return this.gh(['pr', 'create', '--repo', repo, '--base', base, '--head', head, '--title', title, '--body-file', bodyFile]).trim();
+    }
+}

package/dist/delivery/review-threads.d.ts

@@ -0,0 +1,18 @@
+export interface ReviewThread {
+    id: string;
+    resolved: boolean;
+    author: string | null;
+    createdAt: string | null;
+}
+export interface ReviewThreadSummary {
+    status: 'checked';
+    unresolved: number;
+    bugbotUnresolved: number;
+    total: number;
+}
+export declare const REVIEW_THREADS_QUERY = "query($owner:String!,$repo:String!,$number:Int!,$after:String){repository(owner:$owner,name:$repo){pullRequest(number:$number){reviewThreads(first:100,after:$after){pageInfo{hasNextPage endCursor} nodes{id isResolved comments(first:1){nodes{createdAt author{login}}}}}}}}";
+export declare function parseReviewThreadPage(value: any): {
+    threads: ReviewThread[];
+    next: string | null;
+};
+export declare function collectReviewThreads(read: (cursor: string | null) => Promise<unknown>): Promise<ReviewThreadSummary>;

package/dist/delivery/review-threads.js

@@ -0,0 +1,39 @@
+export const REVIEW_THREADS_QUERY = `query($owner:String!,$repo:String!,$number:Int!,$after:String){repository(owner:$owner,name:$repo){pullRequest(number:$number){reviewThreads(first:100,after:$after){pageInfo{hasNextPage endCursor} nodes{id isResolved comments(first:1){nodes{createdAt author{login}}}}}}}}`;
+export function parseReviewThreadPage(value) {
+    const page = value?.data?.repository?.pullRequest?.reviewThreads;
+    if (value?.errors?.length || !page || !Array.isArray(page.nodes) || page.nodes.length > 100 || typeof page.pageInfo?.hasNextPage !== 'boolean')
+        throw new Error('REVIEW_THREADS_UNAVAILABLE');
+    const threads = page.nodes.map((node) => {
+        if (typeof node.id !== 'string' || !node.id || typeof node.isResolved !== 'boolean' || !Array.isArray(node.comments?.nodes))
+            throw new Error('REVIEW_THREADS_UNAVAILABLE');
+        const first = node.comments.nodes[0];
+        return { id: node.id, resolved: node.isResolved, author: first?.author?.login ?? null, createdAt: first?.createdAt ?? null };
+    });
+    const next = page.pageInfo.hasNextPage ? page.pageInfo.endCursor : null;
+    if (page.pageInfo.hasNextPage && (typeof next !== 'string' || !next || next.length > 2048))
+        throw new Error('REVIEW_THREADS_CURSOR_INVALID');
+    return { threads, next };
+}
+export async function collectReviewThreads(read) {
+    const cursors = new Set(), threads = new Map();
+    let cursor = null, pages = 0;
+    do {
+        if (++pages > 50)
+            throw new Error('REVIEW_THREADS_PAGE_LIMIT');
+        const page = parseReviewThreadPage(await read(cursor));
+        for (const t of page.threads) {
+            const previous = threads.get(t.id);
+            if (previous && JSON.stringify(previous) !== JSON.stringify(t))
+                throw new Error('REVIEW_THREADS_CHANGED_DURING_SCAN');
+            threads.set(t.id, t);
+        }
+        cursor = page.next;
+        if (cursor) {
+            if (cursors.has(cursor))
+                throw new Error('REVIEW_THREADS_CURSOR_REPEATED');
+            cursors.add(cursor);
+        }
+    } while (cursor !== null);
+    const unresolved = [...threads.values()].filter(t => !t.resolved);
+    return { status: 'checked', total: threads.size, unresolved: unresolved.length, bugbotUnresolved: unresolved.filter(t => /bugbot/i.test(t.author ?? '')).length };
+}

package/dist/delivery/stack.d.ts

@@ -0,0 +1,32 @@
+import type { PullRequest } from './provider.js';
+export interface StackLane {
+    key: string;
+    cwd: string;
+    head: string;
+    ledgerId: string;
+    title: string;
+}
+export interface StackInput {
+    repo: string;
+    rootBase: string;
+    owner: string;
+    lanes: StackLane[];
+}
+export interface StackPlan extends StackInput {
+    id: string;
+    rootSha: string;
+    entries: (StackLane & {
+        base: string;
+        baseSha: string;
+        headSha: string;
+        patchId: string;
+    })[];
+}
+export interface StackProvider {
+    branchHead(repo: string, branch: string): Promise<string>;
+    find(repo: string, head: string): Promise<number | null>;
+    read(repo: string, number: number): Promise<PullRequest>;
+    open(repo: string, base: string, head: string, title: string, bodyFile: string): Promise<string>;
+}
+export declare function prepareStack(input: StackInput, provider: StackProvider): Promise<StackPlan>;
+export declare function openStack(plan: StackPlan, provider: StackProvider, approve?: boolean): Promise<unknown>;

package/dist/delivery/stack.js

@@ -0,0 +1,91 @@
+import { execFileSync } from 'node:child_process';
+import { realpathSync } from 'node:fs';
+import { fingerprint, git } from "../artifacts/fingerprint.js";
+import { hash, protocol, transact } from "../runtime/protocol.js";
+import { preparePR, openPreparedPR } from "./prepare.js";
+function validBranch(branch) { return typeof branch === 'string' && /^[A-Za-z0-9][A-Za-z0-9._/-]*$/.test(branch) && !branch.includes('..') && !branch.includes('//') && !branch.endsWith('/') && !branch.endsWith('.lock'); }
+function laneMatches(pr, repo, lane) {
+    return pr.repo === repo && pr.state === 'OPEN' && pr.baseRef === lane.base && pr.baseSha === lane.baseSha && pr.headSha === lane.headSha && pr.draft === false;
+}
+function patchId(cwd, base, head) {
+    const diff = execFileSync('git', ['-C', cwd, 'diff', '--no-ext-diff', '--no-textconv', '--binary', base, head], { encoding: 'utf8', maxBuffer: 64 * 1024 * 1024 });
+    const result = execFileSync('git', ['patch-id', '--stable'], { input: diff, encoding: 'utf8', maxBuffer: 1024 }).trim().split(/\s/)[0];
+    if (!/^[a-f0-9]{40}$/.test(result))
+        throw new Error('STACK_EMPTY_PATCH');
+    return result;
+}
+export async function prepareStack(input, provider) {
+    if (!/^[\w.-]+\/[\w.-]+$/.test(input.repo) || !validBranch(input.rootBase) || !input.owner?.trim() || !Array.isArray(input.lanes) || !input.lanes.length || input.lanes.length > 32)
+        throw new Error('INVALID_STACK_PLAN');
+    if (new Set(input.lanes.map(l => l.key)).size !== input.lanes.length || new Set(input.lanes.map(l => l.head)).size !== input.lanes.length || input.lanes.some(l => !validBranch(l.head) || l.head === input.rootBase || !l.key || !l.title))
+        throw new Error('INVALID_STACK_LANES');
+    const rootSha = await provider.branchHead(input.repo, input.rootBase);
+    if (!/^[a-f0-9]{40}$/.test(rootSha))
+        throw new Error('STACK_BASE_UNKNOWN');
+    let base = input.rootBase, baseSha = rootSha, repoId;
+    const entries = [], worktrees = new Set();
+    for (const lane of input.lanes) {
+        const cwd = realpathSync(lane.cwd), fp = fingerprint(cwd, 'committed');
+        if (worktrees.has(cwd) || repoId && fp.repoId !== repoId)
+            throw new Error('STACK_WORKTREE_IDENTITY');
+        worktrees.add(cwd);
+        repoId = fp.repoId;
+        if (git(cwd, ['branch', '--show-current']) !== lane.head)
+            throw new Error('STACK_BRANCH_MISMATCH');
+        if (await provider.branchHead(input.repo, lane.head) !== fp.commitSha)
+            throw new Error('REMOTE_BRANCH_NOT_VERIFIED');
+        try {
+            git(cwd, ['merge-base', '--is-ancestor', baseSha, fp.commitSha]);
+        }
+        catch {
+            throw new Error('STACK_TOPOLOGY_MISMATCH');
+        }
+        const prepared = preparePR(cwd, lane.ledgerId, { repo: input.repo, base, head: lane.head, title: lane.title });
+        const ledger = protocol().ledgers[lane.ledgerId];
+        if (ledger.diffBase?.commitSha !== baseSha || ledger.verdict !== 'unit-test-verified')
+            throw new Error('STACK_PARENT_VERIFICATION_REQUIRED');
+        entries.push({ ...lane, cwd, base, baseSha, headSha: prepared.headSha, patchId: patchId(cwd, baseSha, fp.commitSha) });
+        base = lane.head;
+        baseSha = fp.commitSha;
+    }
+    const stable = { repo: input.repo, rootBase: input.rootBase, owner: input.owner, lanes: entries.map(({ key, cwd, head, ledgerId, title }) => ({ key, cwd, head, ledgerId, title })), rootSha, entries }, plan = { ...stable, id: `stack-${hash(stable).slice(0, 20)}` };
+    transact('stack-prepared', plan.id, input.owner, () => ({ repo: plan.repo, rootSha, entries: entries.map(e => ({ key: e.key, base: e.base, head: e.head, headSha: e.headSha, patchId: e.patchId })) }));
+    return plan;
+}
+export async function openStack(plan, provider, approve = false) {
+    const current = await prepareStack({ repo: plan.repo, rootBase: plan.rootBase, owner: plan.owner, lanes: plan.lanes }, provider);
+    if (current.id !== plan.id || hash(current.entries) !== hash(plan.entries))
+        throw new Error('STACK_PLAN_STALE');
+    if (!approve)
+        return { plan: current, dryRun: true, mergeAuthorized: false };
+    const opened = [];
+    for (const lane of plan.entries) {
+        // Recheck both refs immediately before each creation; stop rather than rewrite topology.
+        if (await provider.branchHead(plan.repo, lane.base) !== lane.baseSha || await provider.branchHead(plan.repo, lane.head) !== lane.headSha)
+            throw new Error('STACK_REFS_MOVED');
+        const existing = await provider.find(plan.repo, lane.head);
+        if (existing !== null) {
+            const pr = await provider.read(plan.repo, existing);
+            if (!laneMatches(pr, plan.repo, lane))
+                throw new Error('STACK_EXISTING_PR_MISMATCH');
+            opened.push({ key: lane.key, number: existing, reused: true });
+            continue;
+        }
+        const prepared = preparePR(lane.cwd, lane.ledgerId, { repo: plan.repo, base: lane.base, head: lane.head, title: lane.title });
+        prepared.body = `## Why\n${lane.title}\n\n## What changed\nVerified stack unit ${lane.key}.\n\n## Scope\nOnly this branch relative to ${lane.base}.\n\n## Blast Radius\nReview this unit independently; dependencies land bottom-up. No merge authority.\n\n## Verification\nHead: ${lane.headSha}\nBase: ${lane.baseSha}\nPatch ID: ${lane.patchId}\nLedger: ${lane.ledgerId}\nIndependent semantic review and current remote CI remain required.\n`;
+        const result = await openPreparedPR(lane.cwd, prepared, provider, true);
+        // A ref can move between the last check and creation. Read the new PR back, or this lane's
+        // verification would describe a commit the PR does not hold. Stop the stack and revoke the
+        // lane's ledger when that happens.
+        const created = await provider.find(plan.repo, lane.head);
+        if (created === null)
+            throw new Error('STACK_CREATED_PR_UNREADABLE');
+        if (!laneMatches(await provider.read(plan.repo, created), plan.repo, lane)) {
+            transact('stack-verification-stale', plan.id, plan.owner, s => { s.invalidations[lane.ledgerId] = { at: new Date().toISOString(), reason: 'PR_CREATED_FROM_UNVERIFIED_REFS' }; return { key: lane.key, number: created }; });
+            throw new Error('STACK_CREATED_PR_MISMATCH');
+        }
+        opened.push({ key: lane.key, number: created, ...result, reused: false });
+    }
+    transact('stack-opened', plan.id, plan.owner, () => ({ opened, mergeAuthorized: false }));
+    return { id: plan.id, opened, mergeAuthorized: false };
+}

package/dist/extension.d.ts

@@ -0,0 +1,2 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+export default function piPstackNative(pi: ExtensionAPI): void;