pi2web 0.2.1 → 0.2.8

package/dist/collab/review-flow.js

@@ -12,7 +12,9 @@ export function currentIssueVotes(snapshot) {
         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))
+        if (!previous ||
+            vote.consensusRound > previous.consensusRound ||
+            (vote.consensusRound === previous.consensusRound && vote.createdAt > previous.createdAt))
             latest.set(key, vote);
     }
     return [...latest.values()];
@@ -26,16 +28,36 @@ export function issueConsensus(snapshot, options = {}) {
         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))
+            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') };
+            : {
+                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);
+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();
@@ -43,12 +65,19 @@ function stancesAt(snapshot, issueId, consensusRound) {
         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))
+        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('|');
+    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));
+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
@@ -62,7 +91,8 @@ export function staleContestedIssueIds(snapshot) {
         if (voted < 2)
             return false;
         const current = stancesAt(snapshot, issueId, voted);
-        return current === stancesAt(snapshot, issueId, voted - 1) && current === stancesAt(snapshot, issueId, voted - 2);
+        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. */
@@ -81,26 +111,49 @@ const MAJOR_SEVERITIES = ['blocker', 'critical', 'major'];
  */
 export function resolveContestedIssues(snapshot) {
     const panel = reviewers(snapshot);
-    return issueConsensus(snapshot).filter(entry => entry.rejecters.length > 0).map(entry => {
+    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 };
+        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' };
+            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' };
+        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));
+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)
@@ -108,9 +161,17 @@ export function pendingCrossVoters(snapshot) {
     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);
+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 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')
@@ -134,29 +195,55 @@ export function assertPhase(snapshot, phases, action) {
 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);
+        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 '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));
+            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));
+            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 [];
+        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));
+    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;
@@ -191,14 +278,23 @@ export function nextPhase(snapshot, options = {}) {
     // 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 };
+        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 };
+        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 '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 };
@@ -206,41 +302,88 @@ export function nextPhase(snapshot, options = {}) {
             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'))
+            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: '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 '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 };
+                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 };
+                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 };
+            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 };
+        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`);
+        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 };
+    return {
+        stalled: pending.length > 0 && overdueBySec >= snapshot.policy.overdueWarningSec,
+        waitingOn: pending,
+        overdueBySec
+    };
 }
 export function assertCanFileFinding(snapshot, participantId) {
     const participant = findParticipant(snapshot, participantId);
@@ -285,7 +428,12 @@ export function approvalSummary(snapshot) {
     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 {
+            participantId: reviewer.participantId,
+            filed: filed.length,
+            unresolved: unresolved.length,
+            approved: unresolved.length === 0
+        };
     });
     return {
         reviewers: approvals,
@@ -299,7 +447,8 @@ export function sessionProgress(snapshot) {
     for (const issue of snapshot.issues)
         counts.set(issue.status, (counts.get(issue.status) ?? 0) + 1);
     return {
-        phase: snapshot.phase, round: snapshot.round,
+        phase: snapshot.phase,
+        round: snapshot.round,
         totalIssues: snapshot.issues.length,
         openIssues: snapshot.issues.filter(isOpenIssue).length,
         byStatus: Object.fromEntries(counts),

package/dist/collab/routes.js

@@ -1,7 +1,10 @@
 import { ValidationError } from './validate.js';
 import { COLLAB_ERRORS } from './types.js';
 const ok = (payload, status = 200) => ({ status, payload: { data: payload } });
-const forbidden = (message) => ({ status: 403, payload: { error: { code: COLLAB_ERRORS.forbidden, message } } });
+const forbidden = (message) => ({
+    status: 403,
+    payload: { error: { code: COLLAB_ERRORS.forbidden, message } }
+});
 /**
  * HTTP surface for the collaboration hub. Two credentials are accepted:
  * the pairing code (a human, full control) and a participant token (one agent, its own session only).
@@ -25,7 +28,13 @@ export class CollabRouter {
                 participant = this.hub.authenticate(token);
             }
             catch {
-                return { status: 401, payload: { error: { code: 'UNAUTHORIZED', message: 'A pairing code or participant token is required' } }, authFailed: true };
+                return {
+                    status: 401,
+                    payload: {
+                        error: { code: 'UNAUTHORIZED', message: 'A pairing code or participant token is required' }
+                    },
+                    authFailed: true
+                };
             }
         }
         try {
@@ -37,20 +46,45 @@ export class CollabRouter {
     }
     async route(ctx) {
         const { method, url, parts, isHuman, participant } = ctx;
-        const human = (action) => { if (!isHuman)
-            throw Object.assign(new Error(`${action} is reserved for humans`), { code: COLLAB_ERRORS.humanOnly, httpStatus: 403 }); };
-        const asParticipant = () => { if (!participant)
-            throw Object.assign(new Error('This endpoint requires a participant token'), { code: COLLAB_ERRORS.forbidden, httpStatus: 403 }); return participant; };
-        const scoped = (sessionId) => { if (participant && participant.sessionId !== sessionId)
-            throw Object.assign(new Error('Collaboration session not found'), { code: COLLAB_ERRORS.sessionNotFound, httpStatus: 404 }); };
-        const collabAgent = (agentId) => { if (typeof agentId !== 'string' || !this.deps.isCollabAgent(agentId))
-            throw Object.assign(new Error('A collaboration seat requires an existing, dedicated collaboration Agent (profile=collab). Create one from the collaboration board, then register or rebind this seat to it.'), { code: COLLAB_ERRORS.forbidden, httpStatus: 403 }); };
-        const number = (name, fallback) => { const raw = url.searchParams.get(name); const value = raw === null ? fallback : Number(raw); return Number.isFinite(value) ? value : fallback; };
+        const human = (action) => {
+            if (!isHuman)
+                throw Object.assign(new Error(`${action} is reserved for humans`), {
+                    code: COLLAB_ERRORS.humanOnly,
+                    httpStatus: 403
+                });
+        };
+        const asParticipant = () => {
+            if (!participant)
+                throw Object.assign(new Error('This endpoint requires a participant token'), {
+                    code: COLLAB_ERRORS.forbidden,
+                    httpStatus: 403
+                });
+            return participant;
+        };
+        const scoped = (sessionId) => {
+            if (participant && participant.sessionId !== sessionId)
+                throw Object.assign(new Error('Collaboration session not found'), {
+                    code: COLLAB_ERRORS.sessionNotFound,
+                    httpStatus: 404
+                });
+        };
+        const collabAgent = (agentId) => {
+            if (typeof agentId !== 'string' || !this.deps.isCollabAgent(agentId))
+                throw Object.assign(new Error('A collaboration seat requires an existing, dedicated collaboration Agent (profile=collab). Create one from the collaboration board, then register or rebind this seat to it.'), { code: COLLAB_ERRORS.forbidden, httpStatus: 403 });
+        };
+        const number = (name, fallback) => {
+            const raw = url.searchParams.get(name);
+            const value = raw === null ? fallback : Number(raw);
+            return Number.isFinite(value) ? value : fallback;
+        };
         // /api/v1/collab/escalations[/{id}/resolve]
         if (parts[3] === 'escalations') {
             if (method === 'GET' && parts.length === 4) {
                 human('Listing escalations');
-                return ok(this.hub.listEscalations({ status: url.searchParams.get('status') ?? undefined, sessionId: url.searchParams.get('sessionId') ?? undefined }));
+                return ok(this.hub.listEscalations({
+                    status: url.searchParams.get('status') ?? undefined,
+                    sessionId: url.searchParams.get('sessionId') ?? undefined
+                }));
             }
             if (method === 'GET' && parts.length === 5) {
                 human('Reading an escalation');
@@ -70,7 +104,12 @@ export class CollabRouter {
         }
         if (method === 'GET' && parts.length === 4) {
             if (isHuman)
-                return ok(this.hub.listSessions({ status: url.searchParams.get('status') ?? undefined, kind: url.searchParams.get('kind') ?? undefined, limit: number('limit', 50), offset: number('offset', 0) }));
+                return ok(this.hub.listSessions({
+                    status: url.searchParams.get('status') ?? undefined,
+                    kind: url.searchParams.get('kind') ?? undefined,
+                    limit: number('limit', 50),
+                    offset: number('offset', 0)
+                }));
             return ok([this.hub.getSession(asParticipant().sessionId)]);
         }
         const sessionId = parts[4];
@@ -83,7 +122,13 @@ export class CollabRouter {
         if (sub && !['participants', 'issues', 'debates'].includes(tail ?? ''))
             return undefined;
         if (method === 'GET' && !tail)
-            return ok({ ...this.hub.getSession(sessionId), progress: this.hub.progress(sessionId), participants: isHuman ? this.hub.participantsForHuman(sessionId) : this.hub.store.listParticipants(sessionId) });
+            return ok({
+                ...this.hub.getSession(sessionId),
+                progress: this.hub.progress(sessionId),
+                participants: isHuman
+                    ? this.hub.participantsForHuman(sessionId)
+                    : this.hub.store.listParticipants(sessionId)
+            });
         if (tail === 'participants') {
             // Sub-resources first: an unguarded register branch would swallow .../participants/{id}/binding and /budget
             // and answer them with "role is required", which is how both repair paths became unreachable over HTTP.
@@ -114,7 +159,9 @@ export class CollabRouter {
                 return ok({ participant: created, participantToken: token, briefing: this.hub.digest(created) }, 201);
             }
             if (method === 'GET')
-                return ok(isHuman ? this.hub.participantsForHuman(sessionId) : this.hub.store.listParticipants(sessionId).map(entry => ({ ...entry })));
+                return ok(isHuman
+                    ? this.hub.participantsForHuman(sessionId)
+                    : this.hub.store.listParticipants(sessionId).map(entry => ({ ...entry })));
         }
         if (method === 'POST' && tail === 'advance') {
             human('Advancing a phase');
@@ -193,22 +240,46 @@ export class CollabRouter {
         if (method === 'GET' && tail === 'report') {
             human('Reading the session report');
             const reportSession = this.hub.getSession(sessionId);
-            return ok({ session: reportSession, progress: this.hub.progress(sessionId), issues: this.hub.store.listIssues(sessionId), reviewSummary: reportSession.kind === 'review' ? this.hub.reviewSummary(sessionId) : undefined, escalations: this.hub.listEscalations({ sessionId }) });
+            return ok({
+                session: reportSession,
+                progress: this.hub.progress(sessionId),
+                issues: this.hub.store.listIssues(sessionId),
+                reviewSummary: reportSession.kind === 'review' ? this.hub.reviewSummary(sessionId) : undefined,
+                escalations: this.hub.listEscalations({ sessionId })
+            });
         }
         return undefined;
     }
     /** Every failure carries a stable code so an agent can branch on it instead of parsing prose. */
     errorResult(error) {
         if (error instanceof ValidationError)
-            return { status: 422, payload: { error: { code: error.code, message: error.message, fieldErrors: error.fieldErrors } } };
+            return {
+                status: 422,
+                payload: { error: { code: error.code, message: error.message, fieldErrors: error.fieldErrors } }
+            };
         const value = error, code = value?.code;
-        const status = Number.isInteger(value?.httpStatus) ? value.httpStatus
-            : code === COLLAB_ERRORS.conflict || code === COLLAB_ERRORS.staleBaseline || code === COLLAB_ERRORS.wrongPhase || code === COLLAB_ERRORS.humanRulingFinal ? 409
-                : code === COLLAB_ERRORS.budgetExhausted ? 429
-                    : code?.endsWith('NOT_FOUND') ? 404 : 400;
-        const extra = code === COLLAB_ERRORS.staleBaseline && value.currentBaseline ? { currentBaseline: value.currentBaseline } : {};
+        const status = Number.isInteger(value?.httpStatus)
+            ? value.httpStatus
+            : code === COLLAB_ERRORS.conflict ||
+                code === COLLAB_ERRORS.staleBaseline ||
+                code === COLLAB_ERRORS.wrongPhase ||
+                code === COLLAB_ERRORS.humanRulingFinal
+                ? 409
+                : code === COLLAB_ERRORS.budgetExhausted
+                    ? 429
+                    : code?.endsWith('NOT_FOUND')
+                        ? 404
+                        : 400;
+        const extra = code === COLLAB_ERRORS.staleBaseline && value.currentBaseline
+            ? { currentBaseline: value.currentBaseline }
+            : {};
         if (status === 403 && !code)
             return forbidden(String(value?.message ?? 'Forbidden'));
-        return { status, payload: { error: { code: code ?? 'BAD_REQUEST', message: String(value?.message ?? 'Request failed'), ...extra } } };
+        return {
+            status,
+            payload: {
+                error: { code: code ?? 'BAD_REQUEST', message: String(value?.message ?? 'Request failed'), ...extra }
+            }
+        };
     }
 }