pi2web 0.2.0 → 0.2.1

package/dist/collab/pi-extension.js

@@ -0,0 +1,237 @@
+import { randomUUID } from 'node:crypto';
+import { StringEnum } from '@earendil-works/pi-ai';
+import { Type } from 'typebox';
+export const COLLAB_ACTIONS = ['ready', 'findings', 'issue_votes', 'merge_votes', 'issue_discussions', 'nominations', 'votes', 'scores', 'debate_argument', 'debate_arguments', 'escalate', 'withdraw'];
+const evidence = Type.Object({
+    path: Type.String({ minLength: 1, description: 'Workspace-relative evidence file' }),
+    startLine: Type.Optional(Type.Number({ minimum: 1 })), endLine: Type.Optional(Type.Number({ minimum: 1 })), excerpt: Type.Optional(Type.String({ maxLength: 2000 }))
+}, { additionalProperties: false });
+const location = Type.Object({
+    path: Type.String({ minLength: 1, description: 'Workspace-relative file containing the finding' }),
+    startLine: Type.Optional(Type.Number({ minimum: 1 })), endLine: Type.Optional(Type.Number({ minimum: 1 }))
+}, { additionalProperties: false });
+const finding = Type.Object({
+    externalId: Type.Optional(Type.String({ maxLength: 100 })), title: Type.String({ minLength: 8, maxLength: 200 }),
+    severity: StringEnum(['blocker', 'critical', 'major', 'minor', 'nit']),
+    category: StringEnum(['security', 'correctness', 'performance', 'maintainability', 'style', 'test', 'docs', 'process']),
+    requiredAction: Type.Optional(StringEnum(['must_fix', 'should_fix', 'discuss', 'fyi'])), confidence: Type.Optional(Type.Number({ minimum: 0, maximum: 1 })),
+    location, evidence: Type.String({ minLength: 10, maxLength: 4000 }), impact: Type.Optional(Type.String({ maxLength: 2000 })), suggestion: Type.Optional(Type.String({ maxLength: 4000 }))
+}, { additionalProperties: false });
+const TOOL_FOR_TASK = {
+    implement: 'collab_submit_ready', file_findings: 'collab_submit_findings', file_findings_optional: 'collab_submit_findings', validate_issues: 'collab_submit_issue_votes',
+    vote_on_merges: 'collab_submit_merge_votes', defend_approved_issues: 'collab_submit_issue_discussions', reconsider_issue_votes: 'collab_submit_issue_votes',
+    nominate_criteria: 'collab_submit_nominations', vote_on_criteria: 'collab_submit_votes', score_rubric: 'collab_submit_scores', rescore_contested: 'collab_submit_scores',
+    debate_contested_scores: 'collab_submit_debate_arguments'
+};
+const TASK_FOR_ACTION = {
+    ready: ['implement'], findings: ['file_findings', 'file_findings_optional'], issue_votes: ['validate_issues', 'reconsider_issue_votes'], merge_votes: ['vote_on_merges'],
+    issue_discussions: ['defend_approved_issues'], nominations: ['nominate_criteria'], votes: ['vote_on_criteria'], scores: ['score_rubric', 'rescore_contested'], debate_arguments: ['debate_contested_scores']
+};
+const SUBMIT_TOOLS = [...new Set(Object.values(TOOL_FOR_TASK))];
+const OPTIONAL_TOOLS = ['collab_escalate', 'collab_withdraw_issue'];
+/** Last-resort scrub for text the hub did not write for the tool flow (mostly error strings). */
+const scrub = (text) => text
+    .replace(/(?:POST|GET|PUT|DELETE)s?\s+(?:to\s+)?\S*\/api\/v1\/\S+/gi, 'use the active collaboration submission tool')
+    .replace(/\S*\/api\/v1\/\S+/gi, 'the collaboration tool')
+    .replace(/[0-9a-f]{8}-[0-9a-f-]{16,}/gi, '[internal reference]');
+/** Inline-only Pi extension. It is loaded solely for profile=collab sessions. */
+export function createCollabExtension(agentId, bridge) {
+    return function collabExtension(pi) {
+        let aliases = new Map(), lastTask, baseTools;
+        const reference = (id, kind) => {
+            if (!id)
+                return id;
+            const existing = aliases.get(id);
+            if (existing)
+                return existing;
+            const prefix = kind === 'issue' ? 'issue' : kind === 'criterion' ? 'criterion' : kind === 'proposal' ? 'proposal' : kind === 'debate' ? 'debate' : kind === 'baseline' ? 'base' : kind === 'participant' ? 'reviewer' : 'ref';
+            const value = `${prefix}-${[...aliases.values()].filter(entry => entry.startsWith(`${prefix}-`)).length + 1}`;
+            aliases.set(id, value);
+            return value;
+        };
+        const redact = (value) => {
+            if (Array.isArray(value))
+                return value.map(redact);
+            if (!value || typeof value !== 'object')
+                return typeof value === 'string' && aliases.has(value) ? aliases.get(value) : value;
+            const output = {};
+            for (const [name, entry] of Object.entries(value)) {
+                if (name === 'sessionId')
+                    continue;
+                const ids = typeof entry === 'string' ? [entry] : Array.isArray(entry) && entry.every(item => typeof item === 'string') ? entry : undefined;
+                if (ids && /(Id|Ids)$/.test(name)) {
+                    const kind = /issue/i.test(name) ? 'issue' : /criterion/i.test(name) ? 'criterion' : /proposal/i.test(name) ? 'proposal' : /debate/i.test(name) ? 'debate' : /baseline/i.test(name) ? 'baseline' : /participant|author|reporter|target|raisedBy/i.test(name) ? 'participant' : 'ref';
+                    output[name.replace(/Id(s)?$/, 'Ref$1')] = typeof entry === 'string' ? reference(entry, kind) : ids.map(item => reference(item, kind));
+                }
+                else
+                    output[name] = redact(entry);
+            }
+            return output;
+        };
+        /**
+         * Aliases are assigned before the walk, not during it, for two reasons. Seat refs must line up with the panel
+         * (so "reviewer-2" means the same agent in every turn and in every argument the model writes), and any id the
+         * walk does not recognise as an id-shaped key - `progress.waitingOn` is a plain string array - would otherwise
+         * reach the model as a raw hub uuid. Findings borrow the board's own numbering so a ref survives a new turn.
+         */
+        const seed = (task) => {
+            const counters = new Map();
+            const claim = (id, alias) => { if (typeof id === 'string' && id && !aliases.has(id))
+                aliases.set(id, alias); };
+            for (const seat of Array.isArray(task.panel) ? task.panel : []) {
+                const role = typeof seat.role === 'string' ? seat.role : 'participant', next = (counters.get(role) ?? 0) + 1;
+                counters.set(role, next);
+                claim(seat.participantId, `${role}-${next}`);
+            }
+            const walk = (value) => {
+                if (Array.isArray(value))
+                    return value.forEach(walk);
+                if (!value || typeof value !== 'object')
+                    return;
+                const entry = value;
+                if (typeof entry.issueId === 'string' && typeof entry.number === 'number')
+                    claim(entry.issueId, `issue-${entry.number}`);
+                for (const nested of Object.values(entry))
+                    walk(nested);
+            };
+            walk(task);
+        };
+        /** Hub errors name findings by hub id; the model only knows aliases, so map before falling back to scrubbing. */
+        const explain = (text) => {
+            let output = text;
+            for (const [id, alias] of aliases)
+                output = output.split(id).join(alias);
+            return scrub(output);
+        };
+        const restore = (value) => {
+            if (Array.isArray(value))
+                return value.map(restore);
+            if (!value || typeof value !== 'object') {
+                if (typeof value !== 'string')
+                    return value;
+                for (const [id, alias] of aliases)
+                    if (alias === value)
+                        return id;
+                return value;
+            }
+            // Only alias-carrying keys are translated back to hub ids. `codeRef` is a semantic field whose value is an
+            // object (commit/dirtyHash), so renaming it to `codeId` would make the hub reject a valid ready submission.
+            const isAliasKey = (key, entry) => /Ref(s)?$/.test(key) && (typeof entry === 'string' || (Array.isArray(entry) && entry.every(item => typeof item === 'string')));
+            return Object.fromEntries(Object.entries(value).map(([key, entry]) => [isAliasKey(key, entry) ? key.replace(/Ref(s)?$/, 'Id$1') : key, restore(entry)]));
+        };
+        const taskText = (task) => {
+            const safe = redact(task), context = { ...safe };
+            delete context.task;
+            delete context.instructions;
+            const lines = ['Local code collaboration task.'];
+            if (safe.task)
+                lines.push(`Current action: ${safe.task}.`);
+            if (safe.phase)
+                lines.push(`Phase: ${safe.phase}${safe.round !== undefined ? `, round ${safe.round}` : ''}.`);
+            const subject = safe.subject;
+            if (typeof subject?.value === 'string')
+                lines.push(`User request: ${subject.value}`);
+            if (typeof subject?.notes === 'string')
+                lines.push(`User notes: ${subject.notes}`);
+            if (safe.task !== 'implement')
+                lines.push('Workspace constraint: this task is non-mutating. Do not create, delete, rename, or modify files under the working directory, including scratch files, redirected command output, generated files, caches, or formatter changes. Send inspection output to stdout; use an OS temporary directory outside the workspace only when unavoidable.');
+            if (typeof safe.instructions === 'string')
+                lines.push(`Instructions: ${scrub(safe.instructions)}`);
+            if (Object.keys(context).length)
+                lines.push(`Task context:\n${JSON.stringify(context, null, 2)}`);
+            const submit = TOOL_FOR_TASK[String(safe.task ?? '')];
+            lines.push(submit ? `Complete every required Ref with ${submit}, then end the turn.` : 'No submission is required; end the turn.');
+            return lines.join('\n');
+        };
+        const currentTask = () => String(lastTask?.task ?? '');
+        const normalize = (action, payload) => {
+            const body = restore(payload);
+            if (action === 'findings') {
+                if (!body.baselineId && lastTask?.baseline && typeof lastTask.baseline.baselineId === 'string')
+                    body.baselineId = lastTask.baseline.baselineId;
+                body.reviewComplete = true;
+            }
+            if (action === 'nominations')
+                body.nominationsComplete = true;
+            if (action !== 'withdraw')
+                body.clientRequestId = randomUUID();
+            return body;
+        };
+        const rememberBaseTools = () => { if (!baseTools)
+            baseTools = pi.getActiveTools().filter(name => !SUBMIT_TOOLS.includes(name) && !OPTIONAL_TOOLS.includes(name) && name !== 'collab_get_task'); };
+        const activate = (task) => {
+            rememberBaseTools();
+            const taskName = String(task?.task ?? '');
+            // Tool names are not an integrity boundary: bash can write just as readily as edit/write, while edit/write
+            // may still be useful for scratch work outside the reviewed checkout. Keep the normal tools available,
+            // state the non-mutation contract explicitly, and let the baseline comparison enforce workspace identity.
+            const submit = TOOL_FOR_TASK[taskName], optional = taskName && taskName !== 'wait' ? ['collab_escalate', ...(taskName.includes('issue') || taskName === 'validate_issues' ? ['collab_withdraw_issue'] : [])] : [];
+            pi.setActiveTools([...new Set([...baseTools, 'collab_get_task', ...(submit ? [submit] : []), ...optional])]);
+        };
+        const assertTask = (action) => {
+            const allowed = TASK_FOR_ACTION[action];
+            if (allowed && !allowed.includes(currentTask()))
+                throw new Error(`The active task is ${currentTask() || 'unknown'}, which cannot submit ${action}. Call collab_get_task again.`);
+        };
+        const acceptedText = (result) => `Collaboration submission accepted.${result && typeof result === 'object' ? ` ${JSON.stringify(redact(result))}` : ''}`;
+        const registerSubmit = (definition) => pi.registerTool({
+            name: definition.name, label: definition.label, description: definition.description, promptSnippet: definition.description,
+            promptGuidelines: [`Use ${definition.name} only after collab_get_task requests it, and include every required Ref exactly once.`], parameters: definition.parameters,
+            async execute(_id, input) {
+                try {
+                    assertTask(definition.action);
+                    const result = await bridge.submit(agentId, definition.action, normalize(definition.action, input));
+                    return { content: [{ type: 'text', text: acceptedText(result) }], details: { result: redact(result) }, terminate: definition.terminate ?? true };
+                }
+                catch (error) {
+                    const fields = error.fieldErrors;
+                    throw new Error(explain(`${error.message ?? 'Submission failed'}${fields ? ` ${JSON.stringify(fields)}` : ''}`));
+                }
+            }
+        });
+        pi.on('session_start', () => { baseTools = undefined; lastTask = undefined; aliases = new Map(); activate(); });
+        pi.on('before_agent_start', event => {
+            lastTask = undefined;
+            aliases = new Map();
+            activate();
+            return { systemPrompt: `${event.systemPrompt}\n\n## Local collaboration\nThis is a local software-development workflow. Call collab_get_task first after every collaboration wake-up. Use only the collaboration submission tool activated for that task. Review and scoring are strictly non-mutating: bash may inspect with commands such as git diff/log, but must not write anywhere under the working directory—not through redirection, tee, file-management commands, formatters, generators, package installation, build artifacts, caches, or scratch files. Send command output to stdout, or if temporary storage is unavoidable use the OS temporary directory outside the workspace. Only an implement task may modify the workspace. The tools own transport and credentials: never use curl, invent endpoints or identifiers, sleep, or poll.` };
+        });
+        pi.registerTool({
+            name: 'collab_get_task', label: 'Get Collaboration Task', description: 'Get the complete current collaboration assignment and activate its exact typed submission tool.',
+            promptSnippet: 'Fetch the current collaboration assignment before doing any collaboration work', promptGuidelines: ['Call collab_get_task first after every pi2web collaboration wake-up.'], parameters: Type.Object({}, { additionalProperties: false }),
+            async execute() { aliases = new Map(); lastTask = await bridge.getTask(agentId); seed(lastTask); activate(lastTask); return { content: [{ type: 'text', text: taskText(lastTask) }], details: { task: redact(lastTask) } }; }
+        });
+        registerSubmit({ name: 'collab_submit_ready', label: 'Submit Implementation', action: 'ready', description: 'Declare the assigned implementation complete with an auditable change summary.', parameters: Type.Object({
+                summary: Type.String({ minLength: 10, maxLength: 4000 }), changes: Type.Array(Type.Object({ path: Type.String({ minLength: 1 }), summary: Type.String({ minLength: 5 }) }, { additionalProperties: false }), { maxItems: 100 }),
+                codeRef: Type.Optional(Type.Object({ commit: Type.Optional(Type.String()), dirtyHash: Type.Optional(Type.String()) }, { additionalProperties: false }))
+            }, { additionalProperties: false }) });
+        registerSubmit({ name: 'collab_submit_findings', label: 'Submit Review Findings', action: 'findings', description: 'Submit the complete blind review, including every required recheck and all new evidence-backed findings.', parameters: Type.Object({
+                findings: Type.Array(finding, { maxItems: 50 }), rechecks: Type.Optional(Type.Array(Type.Object({ issueRef: Type.String(), outcome: StringEnum(['resolved', 'still_present']), rationale: Type.String({ minLength: 10, maxLength: 4000 }) }, { additionalProperties: false }), { maxItems: 100 }))
+            }, { additionalProperties: false }) });
+        registerSubmit({ name: 'collab_submit_issue_votes', label: 'Submit Issue Votes', action: 'issue_votes', description: 'Vote on every required issue and optionally propose duplicate groups.', parameters: Type.Object({
+                votes: Type.Array(Type.Object({ issueRef: Type.String(), stance: StringEnum(['approve', 'reject']), rationale: Type.Optional(Type.String({ maxLength: 4000 })) }, { additionalProperties: false }), { maxItems: 200, description: 'One vote per Ref in yourRequiredIssueIds; an empty array is only accepted when you owe none' }),
+                mergeProposals: Type.Optional(Type.Array(Type.Object({ issueRefs: Type.Array(Type.String(), { minItems: 2, maxItems: 20 }), rationale: Type.String({ minLength: 10, maxLength: 2000 }) }, { additionalProperties: false }), { maxItems: 50 }))
+            }, { additionalProperties: false }) });
+        registerSubmit({ name: 'collab_submit_merge_votes', label: 'Submit Merge Votes', action: 'merge_votes', description: 'Vote on every required duplicate-merge proposal.', parameters: Type.Object({ votes: Type.Array(Type.Object({ proposalRef: Type.String(), stance: StringEnum(['approve', 'reject']), rationale: Type.Optional(Type.String({ maxLength: 4000 })) }, { additionalProperties: false }), { minItems: 1, maxItems: 100 }) }, { additionalProperties: false }) });
+        registerSubmit({ name: 'collab_submit_issue_discussions', label: 'Submit Issue Arguments', action: 'issue_discussions', description: 'Defend every required finding with evidence, and withdraw the ones you no longer stand by.', parameters: Type.Object({
+                discussions: Type.Optional(Type.Array(Type.Object({ issueRef: Type.String(), argument: Type.String({ minLength: 20, maxLength: 4000 }), respondingTo: Type.Optional(Type.String()) }, { additionalProperties: false }), { maxItems: 200 })),
+                withdrawals: Type.Optional(Type.Array(Type.Object({ issueRef: Type.String(), rationale: Type.String({ minLength: 10, maxLength: 4000, description: 'Why you no longer stand by your own finding' }) }, { additionalProperties: false }), { maxItems: 200 }))
+            }, { additionalProperties: false }) });
+        registerSubmit({ name: 'collab_submit_nominations', label: 'Submit Criteria Nominations', action: 'nominations', description: 'Submit the complete independent set of proposed scoring criteria.', parameters: Type.Object({ nominations: Type.Array(Type.Object({
+                    externalId: Type.Optional(Type.String()), name: Type.String({ minLength: 2, maxLength: 80 }), definition: Type.String({ minLength: 20, maxLength: 2000 }), weightSuggestion: Type.Optional(Type.Number({ minimum: 0, maximum: 1 })), anchors: Type.Optional(Type.Record(Type.String(), Type.String())), rationale: Type.Optional(Type.String({ maxLength: 2000 }))
+                }, { additionalProperties: false }), { maxItems: 20 }) }, { additionalProperties: false }) });
+        registerSubmit({ name: 'collab_submit_votes', label: 'Submit Criteria Votes', action: 'votes', description: 'Vote exactly once on every required rubric candidate.', parameters: Type.Object({ votes: Type.Array(Type.Object({
+                    criterionRef: Type.String(), stance: StringEnum(['approve', 'reject', 'abstain']), weight: Type.Optional(Type.Number({ minimum: 0, maximum: 1 })), amendment: Type.Optional(Type.String({ maxLength: 1000 })), rationale: Type.Optional(Type.String({ maxLength: 2000 }))
+                }, { additionalProperties: false }), { minItems: 1, maxItems: 40 }) }, { additionalProperties: false }) });
+        registerSubmit({ name: 'collab_submit_scores', label: 'Submit Rubric Scores', action: 'scores', description: 'Score exactly once every required criterion with rationale and file evidence.', parameters: Type.Object({ scores: Type.Array(Type.Object({
+                    criterionRef: Type.String(), score: Type.Number(), rationale: Type.String({ minLength: 20, maxLength: 4000 }), evidence: Type.Array(evidence, { minItems: 1, maxItems: 20 }), confidence: Type.Optional(Type.Number({ minimum: 0, maximum: 1 })), changeReason: Type.Optional(Type.String({ maxLength: 2000 }))
+                }, { additionalProperties: false }), { minItems: 1, maxItems: 40 }) }, { additionalProperties: false }) });
+        registerSubmit({ name: 'collab_submit_debate_arguments', label: 'Submit Score Debate', action: 'debate_arguments', description: 'Submit one evidence-backed position for every required contested-criterion debate.', parameters: Type.Object({ arguments: Type.Array(Type.Object({
+                    debateRef: Type.String(), stance: StringEnum(['raise', 'lower', 'hold']), argument: Type.String({ minLength: 20, maxLength: 4000 }), evidence: Type.Optional(Type.Array(evidence, { maxItems: 20 })), respondingTo: Type.Optional(Type.String())
+                }, { additionalProperties: false }), { minItems: 1, maxItems: 40 }) }, { additionalProperties: false }) });
+        registerSubmit({ name: 'collab_escalate', label: 'Escalate Collaboration', action: 'escalate', description: 'Escalate a genuine blocker or unresolved judgment to the human operator.', terminate: false, parameters: Type.Object({
+                kind: StringEnum(['issue_dispute', 'rubric_dispute', 'score_dispute', 'other']), refRef: Type.Optional(Type.String()), summary: Type.String({ minLength: 20, maxLength: 2000 }), question: Type.String({ minLength: 10, maxLength: 1000 }), options: Type.Optional(Type.Array(Type.String(), { maxItems: 10 })), urgency: Type.Optional(StringEnum(['low', 'normal', 'high']))
+            }, { additionalProperties: false }) });
+        registerSubmit({ name: 'collab_withdraw_issue', label: 'Withdraw Issue', action: 'withdraw', description: 'Withdraw one of your own findings when you no longer stand by it. Does not end your turn.', terminate: false, parameters: Type.Object({ issueRef: Type.String() }, { additionalProperties: false }) });
+    };
+}

package/dist/collab/review-flow.js

@@ -0,0 +1,310 @@
+import { COLLAB_ERRORS, OPEN_ISSUE_STATUSES, can } from './types.js';
+export const flowError = (code, message, httpStatus = 409) => Object.assign(new Error(message), { code, httpStatus });
+const active = (snapshot) => snapshot.participants.filter(participant => participant.state !== 'left');
+const findParticipant = (snapshot, participantId) => snapshot.participants.find(participant => participant.participantId === participantId);
+const unique = (values) => [...new Set(values)];
+const reviewers = (snapshot) => active(snapshot).filter(participant => participant.role === 'reviewer');
+/** Only findings created in this review round need panel validation; older confirmed findings are rechecked separately. */
+const consensusIssues = (snapshot) => snapshot.issues.filter(issue => issue.status === 'open' && issue.round === snapshot.round);
+export function currentIssueVotes(snapshot) {
+    const latest = new Map();
+    for (const vote of snapshot.issueVotes ?? []) {
+        if (vote.round !== snapshot.round)
+            continue;
+        const key = `${vote.issueId}:${vote.participantId}`, previous = latest.get(key);
+        if (!previous || vote.consensusRound > previous.consensusRound || (vote.consensusRound === previous.consensusRound && vote.createdAt > previous.createdAt))
+            latest.set(key, vote);
+    }
+    return [...latest.values()];
+}
+export function issueConsensus(snapshot, options = {}) {
+    const panel = reviewers(snapshot);
+    return (options.includeFinal ? snapshot.issues : consensusIssues(snapshot)).map(issue => {
+        // The audit view includes findings from earlier review rounds, so read each issue's own latest ballot rather
+        // than accidentally showing the current round's (usually absent) votes against every historical issue.
+        const issueVotes = (snapshot.issueVotes ?? []).filter(vote => vote.issueId === issue.issueId && vote.round === issue.round);
+        const latest = new Map();
+        for (const vote of issueVotes) {
+            const previous = latest.get(vote.participantId);
+            if (!previous || vote.consensusRound > previous.consensusRound || (vote.consensusRound === previous.consensusRound && vote.createdAt > previous.createdAt))
+                latest.set(vote.participantId, vote);
+        }
+        const positions = panel.map(reviewer => reviewer.participantId === issue.reporterId
+            ? { participantId: reviewer.participantId, stance: 'approve', implicit: true }
+            : { participantId: reviewer.participantId, stance: latest.get(reviewer.participantId)?.stance, rationale: latest.get(reviewer.participantId)?.rationale, implicit: false });
+        return { issueId: issue.issueId, positions, missing: positions.filter(position => !position.stance).map(position => position.participantId), rejecters: positions.filter(position => position.stance === 'reject').map(position => position.participantId), supporters: positions.filter(position => position.stance === 'approve').map(position => position.participantId), unanimous: positions.length > 0 && positions.every(position => position.stance === 'approve') };
+    });
+}
+export const contestedIssueIds = (snapshot) => issueConsensus(snapshot).filter(entry => entry.rejecters.length > 0).map(entry => entry.issueId);
+/** Latest ballot per reviewer for one issue as it stood at the end of consensus round `consensusRound`. */
+function stancesAt(snapshot, issueId, consensusRound) {
+    const latest = new Map();
+    for (const vote of snapshot.issueVotes ?? []) {
+        if (vote.issueId !== issueId || vote.round !== snapshot.round || vote.consensusRound > consensusRound)
+            continue;
+        const previous = latest.get(vote.participantId);
+        if (!previous || vote.consensusRound > previous.consensusRound || (vote.consensusRound === previous.consensusRound && vote.createdAt > previous.createdAt))
+            latest.set(vote.participantId, vote);
+    }
+    return [...latest.entries()].map(([participantId, vote]) => `${participantId}:${vote.stance}`).sort().join('|');
+}
+const lastVotedRound = (snapshot, issueId) => Math.max(-1, ...(snapshot.issueVotes ?? []).filter(vote => vote.issueId === issueId && vote.round === snapshot.round).map(vote => vote.consensusRound));
+/**
+ * Discussion rounds are only worth their tokens while they still move somebody. An issue whose ballot has been
+ * identical for two consecutive reconsiderations is settled in fact, so the panel stops re-arguing it instead of
+ * burning every remaining round (observed: three rounds of "I keep the rejection" on findings nobody flipped).
+ * Two rounds of silence, not one: a rejecter that needs a second round of evidence is a real convergence path.
+ * Measured against the last round that actually voted, so a round in progress is never judged before its ballots.
+ */
+export function staleContestedIssueIds(snapshot) {
+    return contestedIssueIds(snapshot).filter(issueId => {
+        const voted = lastVotedRound(snapshot, issueId);
+        if (voted < 2)
+            return false;
+        const current = stancesAt(snapshot, issueId, voted);
+        return current === stancesAt(snapshot, issueId, voted - 1) && current === stancesAt(snapshot, issueId, voted - 2);
+    });
+}
+/** Contested findings the panel is still allowed to spend a round on. */
+export function activeContestedIssueIds(snapshot) {
+    const stale = new Set(staleContestedIssueIds(snapshot));
+    return contestedIssueIds(snapshot).filter(issueId => !stale.has(issueId));
+}
+/** Findings a human is actually worth interrupting for; everything below this the panel settles itself. */
+const HUMAN_REVIEW_SEVERITIES = ['blocker', 'critical'];
+const MAJOR_SEVERITIES = ['blocker', 'critical', 'major'];
+/**
+ * Closes out the consensus stage. Escalating every disagreement makes a panel of N a queue of N disputes for the
+ * human (observed: 6 of 18 findings, including two the reporter itself had conceded), so only two situations
+ * genuinely need a ruling: a split panel on a serious finding, and a serious finding the whole panel rejected
+ * over its reporter's objection. Everything else is decided by the panel and recorded.
+ */
+export function resolveContestedIssues(snapshot) {
+    const panel = reviewers(snapshot);
+    return issueConsensus(snapshot).filter(entry => entry.rejecters.length > 0).map(entry => {
+        const issue = snapshot.issues.find(candidate => candidate.issueId === entry.issueId);
+        const severity = issue?.severity ?? 'major';
+        const voters = panel.filter(reviewer => reviewer.participantId !== issue?.reporterId).map(reviewer => reviewer.participantId);
+        const base = { issueId: entry.issueId, severity, supporters: entry.supporters, rejecters: entry.rejecters };
+        // The reporter is the only supporter left: the panel says this is not a defect, and it had every discussion
+        // round to withdraw it or convince somebody. Only a claimed blocker still buys a human's attention. Two
+        // dissenters minimum: on a two-seat panel "everyone else" is one reviewer, which is a tie, not a verdict.
+        if (voters.length > 1 && voters.every(participantId => entry.rejecters.includes(participantId)))
+            return { ...base, disposition: HUMAN_REVIEW_SEVERITIES.includes(severity) ? 'escalate' : 'panel_rejected', reason: 'panel_unanimously_rejected' };
+        if (MAJOR_SEVERITIES.includes(severity))
+            return { ...base, disposition: 'escalate', reason: 'split_panel_on_a_major_finding' };
+        if (entry.rejecters.length > entry.supporters.length)
+            return { ...base, disposition: 'majority_rejected', reason: 'panel_majority_rejected' };
+        // A tie keeps the finding: reporting it costs a line in the report, dropping a real defect costs a release.
+        return { ...base, disposition: 'majority_confirmed', reason: entry.supporters.length === entry.rejecters.length ? 'tie_kept_as_a_recorded_dispute' : 'panel_majority_confirmed' };
+    });
+}
+const currentMergeProposals = (snapshot) => (snapshot.mergeProposals ?? []).filter(proposal => proposal.round === snapshot.round);
+const collectedThisRound = (snapshot) => new Set(snapshot.completions.filter(entry => entry.phase === 'collecting' && entry.round === snapshot.round).map(entry => entry.participantId));
+/** Reviewers who already closed their own blind review but still owe votes on other reviewers' already-filed issues. */
+export function pendingCrossVoters(snapshot) {
+    if (snapshot.phase !== 'collecting' || !snapshot.policy.consensusReview)
+        return [];
+    const collected = collectedThisRound(snapshot);
+    return unique(issueConsensus(snapshot).flatMap(entry => entry.missing)).filter(participantId => collected.has(participantId));
+}
+export const owedIssueVoteIds = (snapshot, participantId) => issueConsensus(snapshot).filter(entry => entry.missing.includes(participantId)).map(entry => entry.issueId);
+/** Statuses nobody may move again without a human: rulings are final. */
+export const FINAL_ISSUE_STATUSES = ['human_ruled', 'wontfix', 'closed', 'duplicate', 'withdrawn'];
+export const isOpenIssue = (issue) => OPEN_ISSUE_STATUSES.includes(issue.status);
+export function assertCapability(participant, capability) {
+    if (participant.state === 'budget_exhausted')
+        throw flowError(COLLAB_ERRORS.budgetExhausted, 'Token budget is exhausted for this participant. A human must raise the budget or replace the agent.', 429);
+    if (participant.state === 'left')
+        throw flowError(COLLAB_ERRORS.forbidden, 'This participant has left the session', 403);
+    if (!can(participant.role, capability))
+        throw flowError(COLLAB_ERRORS.forbidden, `Role ${participant.role} may not perform ${capability}`, 403);
+}
+export function assertPhase(snapshot, phases, action) {
+    if (snapshot.status !== 'active')
+        throw flowError(COLLAB_ERRORS.wrongPhase, `Session is ${snapshot.status}; ${action} is no longer accepted`);
+    if (!phases.includes(snapshot.phase))
+        throw flowError(COLLAB_ERRORS.wrongPhase, `${action} is only accepted in phase ${phases.join(' or ')}, but the session is in ${snapshot.phase}`);
+}
+/**
+ * Participants that must act before the current phase can advance.
+ * Filing findings is required of reviewers only: an implementer's reverse findings are optional,
+ * otherwise every session would deadlock waiting for an implementer with nothing to report.
+ */
+export function requiredActors(snapshot) {
+    const participants = active(snapshot);
+    switch (snapshot.phase) {
+        case 'implementing': return participants.filter(participant => participant.role === 'implementer').map(participant => participant.participantId);
+        case 'collecting': return participants.filter(participant => participant.role === 'reviewer').map(participant => participant.participantId);
+        // A reviewer that owes no ballot is already done. There is no empty submission for it to make, so requiring
+        // one would park the phase on a seat that can never satisfy it.
+        case 'validating': return reviewers(snapshot).filter(participant => owedIssueVoteIds(snapshot, participant.participantId).length).map(participant => participant.participantId);
+        case 'merge_voting': return reviewers(snapshot).filter(participant => currentMergeProposals(snapshot).some(proposal => !proposal.votes.some(vote => vote.participantId === participant.participantId))).map(participant => participant.participantId);
+        case 'issue_discussing': {
+            const contested = new Set(activeContestedIssueIds(snapshot));
+            return unique(issueConsensus(snapshot).filter(entry => contested.has(entry.issueId)).flatMap(entry => entry.supporters));
+        }
+        case 'issue_reconsidering': {
+            const contested = new Set(activeContestedIssueIds(snapshot));
+            return unique(issueConsensus(snapshot).filter(entry => contested.has(entry.issueId)).flatMap(entry => entry.rejecters));
+        }
+        // responding/adjudicating are legacy persisted phases. New reviews finish after panel consensus.
+        default: return [];
+    }
+}
+/** Required actors that have not finished yet. An exhausted or departed participant still blocks: a human must intervene. */
+export function waitingOn(snapshot) {
+    const required = requiredActors(snapshot);
+    if (['collecting', 'implementing', 'validating', 'merge_voting', 'issue_discussing', 'issue_reconsidering'].includes(snapshot.phase)) {
+        const done = new Set(snapshot.completions.filter(entry => entry.phase === snapshot.phase && entry.round === snapshot.round).map(entry => entry.participantId));
+        return required.filter(participantId => !done.has(participantId));
+    }
+    return required;
+}
+export function isReadyToAdvance(snapshot) {
+    if (snapshot.status !== 'active')
+        return false;
+    if (snapshot.phase === 'consolidating')
+        return true;
+    if (snapshot.phase === 'awaiting_human')
+        return snapshot.pendingEscalations === 0;
+    if (['draft', 'finished'].includes(snapshot.phase))
+        return false;
+    return waitingOn(snapshot).length === 0;
+}
+/**
+ * Computes the next phase. `forced` is the human override used to break a stall; it is the only way
+ * to move past participants that never submitted, and the skipped participants are reported for the log.
+ */
+export function nextPhase(snapshot, options = {}) {
+    if (snapshot.status !== 'active')
+        throw flowError(COLLAB_ERRORS.wrongPhase, `Session is ${snapshot.status}`);
+    const pending = waitingOn(snapshot);
+    if (!isReadyToAdvance(snapshot) && !options.forced) {
+        if (snapshot.phase === 'draft')
+            throw flowError(COLLAB_ERRORS.wrongPhase, 'Open the first round before advancing');
+        if (snapshot.phase === 'awaiting_human')
+            throw flowError(COLLAB_ERRORS.wrongPhase, `${snapshot.pendingEscalations} escalation(s) still await a human ruling`);
+        throw flowError(COLLAB_ERRORS.wrongPhase, `Still waiting on ${pending.length} participant(s): ${pending.join(', ')}`);
+    }
+    const skipped = options.forced && pending.length ? { skipped: pending } : {};
+    // A participant may explicitly ask for a human during any consensus step. Finish the current batched step,
+    // then stop before another debate round instead of silently debating past an open escalation.
+    if (snapshot.pendingEscalations > 0 && snapshot.phase !== 'awaiting_human')
+        return { phase: 'awaiting_human', round: snapshot.round, debateRound: snapshot.debateRound, reason: 'participant_escalated', ...skipped };
+    switch (snapshot.phase) {
+        case 'draft': return snapshot.policy.implementationFirst
+            ? { phase: 'implementing', round: snapshot.round, reason: 'implementation_started', ...skipped }
+            : { phase: 'collecting', round: snapshot.round, reason: 'round_opened', ...skipped };
+        // The implementer declares itself done (or a managed agent goes idle); only then are the reviewers called.
+        case 'implementing': return { phase: 'collecting', round: snapshot.round, reason: 'implementation_ready', ...skipped };
+        case 'collecting': return { phase: 'consolidating', round: snapshot.round, reason: 'findings_complete', ...skipped };
+        case 'consolidating': {
+            if (!snapshot.policy.consensusReview)
+                return { phase: 'finished', round: snapshot.round, reason: 'review_complete', ...skipped };
+            // Who still owes a ballot is `waitingOn`'s job, not a second implementation of it here.
+            if (waitingOn({ ...snapshot, phase: 'validating' }).length)
+                return { phase: 'validating', round: snapshot.round, reason: 'issue_validation_started', ...skipped };
+            const proposals = currentMergeProposals(snapshot);
+            if (proposals.length && !snapshot.completions.some(entry => entry.phase === 'merge_voting' && entry.round === snapshot.round && entry.participantId === 'system'))
+                return { phase: 'merge_voting', round: snapshot.round, reason: 'merge_voting_started', ...skipped };
+            return contestedIssueIds(snapshot).length
+                ? { phase: 'issue_discussing', round: snapshot.round, debateRound: Math.max(1, snapshot.debateRound ?? 0), reason: 'issue_votes_contested', ...skipped }
+                : { phase: 'finished', round: snapshot.round, reason: 'review_consensus_complete', ...skipped };
+        }
+        case 'validating': return { phase: 'consolidating', round: snapshot.round, reason: 'issue_validation_complete', ...skipped };
+        case 'merge_voting': return { phase: 'consolidating', round: snapshot.round, reason: 'merge_voting_complete', ...skipped };
+        case 'issue_discussing': return { phase: 'issue_reconsidering', round: snapshot.round, debateRound: snapshot.debateRound ?? 1, reason: 'supporter_arguments_complete', ...skipped };
+        case 'issue_reconsidering': {
+            const contested = contestedIssueIds(snapshot);
+            if (!contested.length)
+                return { phase: 'finished', round: snapshot.round, debateRound: snapshot.debateRound ?? 1, reason: 'review_consensus_complete', ...skipped };
+            const exhausted = (snapshot.debateRound ?? 1) >= snapshot.policy.maxConsensusRounds;
+            if (!exhausted && activeContestedIssueIds(snapshot).length)
+                return { phase: 'issue_discussing', round: snapshot.round, debateRound: (snapshot.debateRound ?? 1) + 1, reason: 'issue_consensus_next_round', ...skipped };
+            // The panel is done arguing, either out of rounds or out of movement. Dispose of every contested finding
+            // here so only the ones a human must actually rule on reach the escalation queue.
+            const resolutions = resolveContestedIssues(snapshot), escalated = resolutions.filter(entry => entry.disposition === 'escalate');
+            return { phase: escalated.length ? 'awaiting_human' : 'finished', round: snapshot.round, debateRound: snapshot.debateRound ?? 1,
+                reason: escalated.length ? (exhausted ? 'issue_consensus_exhausted' : 'issue_consensus_settled_with_disputes') : 'issue_consensus_resolved_by_panel',
+                resolutions, escalateConsensus: escalated.length > 0, ...skipped };
+        }
+        case 'awaiting_human': return { phase: 'consolidating', round: snapshot.round, reason: 'consensus_human_ruled', ...skipped };
+        // Compatibility recovery for sessions persisted by the old mandatory response loop: do not ask Agents for
+        // another response; close the review and let a human start an explicit fix/recheck cycle if desired.
+        case 'responding':
+        case 'adjudicating': return { phase: 'finished', round: snapshot.round, reason: 'legacy_response_loop_removed', ...skipped };
+        default: throw flowError(COLLAB_ERRORS.wrongPhase, `Phase ${snapshot.phase} cannot advance`);
+    }
+}
+/** A stall is informational only: it never changes the phase (see COLLAB_PLAN.md decision 3). */
+export function stallCheck(snapshot, lastProgressAt, nowMs) {
+    const pending = waitingOn(snapshot), overdueBySec = Math.floor((nowMs - lastProgressAt) / 1000);
+    return { stalled: pending.length > 0 && overdueBySec >= snapshot.policy.overdueWarningSec, waitingOn: pending, overdueBySec };
+}
+export function assertCanFileFinding(snapshot, participantId) {
+    const participant = findParticipant(snapshot, participantId);
+    if (!participant)
+        throw flowError(COLLAB_ERRORS.participantNotFound, 'Participant is not part of this session', 404);
+    assertCapability(participant, 'file_finding');
+    assertPhase(snapshot, ['collecting'], 'Filing findings');
+    return participant;
+}
+/** Blind review: until the collecting phase closes, a participant may only see their own findings. */
+export function canSeeOthersFindings(snapshot) {
+    return !snapshot.policy.blindFindings || snapshot.phase !== 'collecting';
+}
+/** Either side may escalate a panel dispute directly instead of spending more consensus rounds. */
+export function applyEscalation(input) {
+    const { issue, actor } = input;
+    assertCapability(actor, 'escalate');
+    if (issue.reporterId !== actor.participantId && issue.targetParticipantId !== actor.participantId)
+        throw flowError(COLLAB_ERRORS.forbidden, 'Only the reporter or the addressed participant may escalate an issue', 403);
+    if (FINAL_ISSUE_STATUSES.includes(issue.status))
+        throw flowError(COLLAB_ERRORS.humanRulingFinal, `Issue is ${issue.status} and can no longer be changed`);
+    return { status: 'escalated', round: issue.round, escalate: true, escalateReason: 'participant_escalated' };
+}
+export function applyWithdraw(input) {
+    const { issue, actor } = input;
+    assertCapability(actor, 'withdraw');
+    if (issue.reporterId !== actor.participantId)
+        throw flowError(COLLAB_ERRORS.forbidden, 'Only the reporter may withdraw an issue', 403);
+    if (FINAL_ISSUE_STATUSES.includes(issue.status))
+        throw flowError(COLLAB_ERRORS.humanRulingFinal, `Issue is ${issue.status} and can no longer be changed`);
+    return { status: 'withdrawn', round: issue.round, escalate: false };
+}
+/** A human ruling is terminal except for an explicit reopen, which hands the issue back to the responder. */
+export function applyHumanRuling(issue, decision) {
+    if (decision === 'reopen')
+        return { status: 'open', round: issue.round + 1, escalate: false };
+    return { status: decision === 'resolved' ? 'human_ruled' : decision, round: issue.round, escalate: false };
+}
+/** Everyone the reviewers have to agree with before a session may finish clean. */
+export function approvalSummary(snapshot) {
+    const reviewers = active(snapshot).filter(participant => participant.role === 'reviewer');
+    const approvals = reviewers.map(reviewer => {
+        const filed = snapshot.issues.filter(issue => issue.reporterId === reviewer.participantId);
+        const unresolved = filed.filter(isOpenIssue);
+        return { participantId: reviewer.participantId, filed: filed.length, unresolved: unresolved.length, approved: unresolved.length === 0 };
+    });
+    return {
+        reviewers: approvals,
+        // "Approved" means every reviewer's own findings are settled and nothing needed a human ruling.
+        unanimous: approvals.length > 0 && approvals.every(entry => entry.approved),
+        humanRuledCount: snapshot.issues.filter(issue => issue.status === 'human_ruled' || issue.status === 'wontfix' || issue.status === 'closed').length
+    };
+}
+export function sessionProgress(snapshot) {
+    const counts = new Map();
+    for (const issue of snapshot.issues)
+        counts.set(issue.status, (counts.get(issue.status) ?? 0) + 1);
+    return {
+        phase: snapshot.phase, round: snapshot.round,
+        totalIssues: snapshot.issues.length,
+        openIssues: snapshot.issues.filter(isOpenIssue).length,
+        byStatus: Object.fromEntries(counts),
+        waitingOn: waitingOn(snapshot),
+        pendingCrossVotes: pendingCrossVoters(snapshot),
+        readyToAdvance: isReadyToAdvance(snapshot)
+    };
+}