toolroll 0.9.103 → 0.9.105

package/dist/task-status.js

@@ -1,34 +1,17 @@
-/** One answer per task, then the details (docs/design/task-status.md). Every
- * surface — the Tasks list, the task page, the build page, Crew, the Chat
- * result, the Telegram/Slack/Discord/Teams cards and `toolroll status` — reads
- * its headline, sentence, tone and detail rows from `taskStatusOf`, so the
- * words cannot drift apart again. Pure: it reads facts the existing
- * projections already recorded and never changes a check, approval or
- * completion.
- *
- * Severity: red belongs to the Failed headline alone. A detail problem that
- * doesn't undo the outcome (a pull request that couldn't open, shortened
- * output) is an ink note on its own row with one action; the exact
- * technical reason stays one tap away in `why`. */
 import { DEFAULT_LEAD_NAME } from "./lead-identity.js";
 import { html } from "./html.js";
 import { FAILED_CHECK } from "./result-acts.js";
 import { CODE_READING, NEEDS, needSentence, waitSentence } from "./needs-you.js";
-/** A cancelled task with a successor reads "Replaced by <id>" everywhere, never "Cancelled". */
 export const replacedWords = (successor) => `Replaced by ${successor}`;
 const REPLACED = /^Replaced by \S+/;
-/** Waiting: a reason no person can act on, worded as what it waits for (needs-you.ts). */
 export const HEADLINES = ["Queued", "Planning", "Needs you", "Waiting", "Building", "Ready for review", "Complete", "Failed", "Stopped"];
 export const HEADLINE_TONE = {
     Queued: "neutral", Planning: "live", "Needs you": "attention", Waiting: "neutral", Building: "live",
     "Ready for review": "ready", Complete: "success", Failed: "danger", Stopped: "neutral",
 };
-/** The project's own checks and the pull request's CI are two different things, never one word (Checks beside CI). */
 export const CHECKS_LABEL = "Project checks";
 export const PR_CI_LABEL = "PR CI";
-/** The one verb for opening a saved result, on every surface. */
 export const OPEN_RESULT = "Open result";
-/** A machine-run check under way (a prepared candidate: no agent runs), on every surface that has no richer words. */
 export const MACHINE_CHECK_RUNNING = "Running the check on the prepared version.";
 export const CHECKED_AT_RELEASE = "Checked at release";
 export function releaseStateOf(checks) {
@@ -36,20 +19,9 @@ export function releaseStateOf(checks) {
         return undefined;
     return checks.release != null ? "covered" : "pending";
 }
-/** How the project check stands for requirements that rest on it, read now: `covered` once a check passed on this
- * commit (its own, a follow-up, or a release check containing it), `pending` while checks Off wait for a release. */
 export function checkBackingOf(checks) {
     return checks?.status === "passed" ? "covered" : checksUnderway(checks) ? "running" : releaseStateOf(checks);
 }
-/**
- * Did the approved check pass for this result? The ONE answer the status headline and sentence, the Project checks
- * row, the road's Checks step and the result page all read, so none of them can say "passed" while another says the
- * check couldn't be read. Two records speak to it: the machine verdict sealed when the build finished, and the saved
- * check receipt read now (with any follow-up check on the same commit). Fail closed: the check passed only when the
- * receipt read now says so. A verdict that recorded a pass whose receipt is missing, says nothing ran, or can't be
- * read is unreadable; a verdict that recorded a failure stays failed unless a later check on the same commit passed.
- * `checks` undefined or null: nothing was read. Returns the check as every surface shows it (null: nothing to show).
- */
 export function approvedCheckOf(verdict, reasons, checks) {
     let failedExit = null;
     for (const reason of reasons) {
@@ -69,12 +41,10 @@ export function approvedCheckOf(verdict, reasons, checks) {
     }
     if (read.status === "passed" || read.status === "failed" || read.status === "running")
         return read;
-    // Checks Off covered by a passing release check read as passed (the row says on which commit); nothing to correct.
     if (read.level === "off" && read.release != null && !recordedFail)
         return read;
     if (recordedFail)
         return { ...read, status: "failed", exitCode: failedExit };
-    // The verdict says the check passed, the receipt read now can't show it: the two disagree, so it doesn't count.
     if (recordedPass)
         return { ...read, status: "unavailable", exitCode: null };
     return read;
@@ -82,8 +52,6 @@ export function approvedCheckOf(verdict, reasons, checks) {
 export function approvedCheckStateOf(checks) {
     if (checks == null)
         return null;
-    // A failure stands while a new check runs: only its result can change the answer. A check that couldn't be read (a
-    // result waiting for its batch check has none yet) reads running while one is underway, and never passed.
     if (checks.status === "failed")
         return "failed";
     if (checksUnderway(checks) || checks.status === "running")
@@ -96,19 +64,15 @@ export function approvedCheckStateOf(checks) {
         return checks.release != null ? "passed" : "off";
     return "not-run";
 }
-/** A saved check that can't be read, in the words every surface uses. */
 export const CHECK_UNREADABLE = "The check result couldn't be read.";
 export const CHECK_UNREADABLE_ASK = `${CHECK_UNREADABLE} Run checks on it, or open the result to see why.`;
-/** A saved check whose files are intact but whose command was approved again since it ran. */
 export const CHECK_COMMAND_CHANGED = "The check command changed since this check; run checks again.";
 const unreadableAsk = (checks) => checks?.cause === "command-changed" ? CHECK_COMMAND_CHANGED : CHECK_UNREADABLE_ASK;
-/** "T2", "T2 and T3", "T2, T3 and 2 more": short enough for one line. The full list is on the result. */
 export function peerWords(peers, shown = 2) {
     if (peers.length <= shown)
         return peers.length <= 1 ? peers.join("") : `${peers.slice(0, -1).join(", ")} and ${peers.at(-1)}`;
     return `${peers.slice(0, shown).join(", ")} and ${peers.length - shown} more`;
 }
-/** "Checked together with T2 on 1a2b3c4": every surface says a shared check the same way, naming the commit it tested. */
 export function checkedTogetherWords(batch) {
     const sha = short(batch.tested);
     return batch.state === "together" && batch.peers.length > 0 && sha !== null ? `Checked together with ${peerWords(batch.peers)} on ${sha}` : null;
@@ -118,10 +82,7 @@ const BATCH_WHY = {
     conflict: "It conflicted with another result when merged for a batch check, so it was checked on its own.",
 };
 const short = (sha) => sha !== null && /^[a-f0-9]{7,40}$/.test(sha) ? sha.slice(0, 7) : null;
-/** A check waiting for its batch or running on this commit: the result reads Ready meanwhile, not Needs you. */
 const checksUnderway = (checks) => checks?.batch?.state === "waiting" || checks?.running != null;
-/** A finished result a person still has to act on before it can be complete: an unresolved HIGH finding or unmet
- * requirement, a missing check, or a requirement only they can confirm. Failed checks read Failed instead. */
 function resultAsk(facts) {
     if (facts.report || facts.checks?.status === "failed")
         return null;
@@ -131,7 +92,6 @@ function resultAsk(facts) {
     const req = facts.requirements;
     if (req != null && facts.accepted !== true && req.unverified !== true && (req.yours > 0 || (req.unshown ?? 0) > 0) && req.ask != null)
         return req.ask;
-    // A check that can't be read is never a pass: a person runs it again or looks at why, unless they already accepted.
     if (facts.accepted !== true && approvedCheckStateOf(facts.checks) === "unreadable")
         return unreadableAsk(facts.checks);
     return null;
@@ -150,10 +110,8 @@ export function headlineOf(facts) {
                 return "Ready for review";
             if (facts.checks?.status === "failed")
                 return "Failed";
-            // A requirement a person checks, a missing screenshot, an unmet requirement or a HIGH finding: Needs you, with the ask.
             if (resultAsk(facts) !== null)
                 return "Needs you";
-            // Off: ready like any build; the sentence and the Checks row say it is checked at release.
             return "Ready for review";
         case "complete": return "Complete";
         case "failed": return "Failed";
@@ -166,7 +124,6 @@ function sentenceOf(headline, facts) {
     switch (headline) {
         case "Queued": return reason ?? "Waiting for a builder.";
         case "Planning": return reason ?? "The lead is writing the plan.";
-        // One plain sentence per need (needs-you.ts); a recorded reason only where the need keeps one.
         case "Needs you": return facts.stage === "finished" ? resultAsk(facts) ?? needSentence("review-result", reason, facts.needContext) : needSentence(facts.need ?? "other", reason, facts.needContext);
         case "Waiting": return waitSentence(facts.wait, reason, facts.needContext);
         case "Building": return facts.stage === "checking" ? "Checks are running on the change."
@@ -180,7 +137,6 @@ function sentenceOf(headline, facts) {
             if (facts.checks?.level === "off" && facts.checks.status !== "passed")
                 return "Checked at release. Review the change, then accept it.";
             if (facts.checks?.status === "passed") {
-                // The Checks row names the others and the batch commit; the sentence doesn't repeat them.
                 const peers = facts.checks.batch?.state === "together" ? facts.checks.batch.peers.length : 0;
                 if (peers > 0)
                     return `Checks passed together with ${peers === 1 ? "1 other result" : `${peers} other results`}. Review the change, then accept it.`;
@@ -190,12 +146,10 @@ function sentenceOf(headline, facts) {
                 return "Its full check runs with other results within 10 minutes. Review the change, then accept it.";
             if (facts.checks?.status === "unavailable")
                 return `${facts.checks.cause === "command-changed" ? CHECK_COMMAND_CHANGED : CHECK_UNREADABLE} Review the change, then accept it.`;
-            // Never claim a check that isn't known to have passed.
             if (facts.checks == null)
                 return "Review the change, then accept it.";
             return "Built without a passing project check. Review the change, then accept it.";
         case "Complete": {
-            // Landed work says why once; its merged pull request is that reason, not a second sentence.
             if (facts.landed)
                 return `Accepted automatically: ${facts.landed}.`;
             const by = facts.completedBy ? `Accepted by ${facts.completedBy}.` : "Accepted.";
@@ -209,7 +163,6 @@ function sentenceOf(headline, facts) {
         case "Stopped": return reason ?? "Stopped by a person. The work so far is kept.";
     }
 }
-/** A detail problem: red only under Failed, otherwise an ink note. */
 const problem = (headline) => headline === "Failed" ? "failed" : "note";
 function detailsOf(headline, facts) {
     const rows = [];
@@ -223,7 +176,6 @@ function detailsOf(headline, facts) {
         const batch = checks.batch ?? null;
         const together = batch === null ? null : checkedTogetherWords(batch);
         const batchWhy = batch === null ? null : BATCH_WHY[batch.state] ?? null;
-        // A failure or an unreadable check keeps its words while a new check runs, so the row never reads better than the answer.
         const again = checksUnderway(checks) && checks.status === "failed" ? " · running again" : "";
         if (again !== "")
             row("checks", CHECKS_LABEL, `${quick ? "Quick checks failed" : "Failed"}${checks.exitCode === null ? "" : ` (exit ${checks.exitCode})`}${again}`, problem(headline), headline === "Failed" ? { href: checksHref } : { action: { label: "See what failed", href: checksHref } });
@@ -249,7 +201,6 @@ function detailsOf(headline, facts) {
             row("checks", CHECKS_LABEL, CHECKED_AT_RELEASE, "none", runChecks === null ? {} : { action: runChecks });
         else if (checks.status === "not-run")
             row("checks", CHECKS_LABEL, "Didn't run", "none", runChecks === null ? {} : { action: runChecks });
-        // A saved check that can't be read is run again where that is possible.
         else if (checks.cause === "command-changed")
             row("checks", CHECKS_LABEL, "Check command changed since", "note", { action: runChecks ?? { label: OPEN_RESULT, href: facts.links?.result ?? null }, why: CHECK_COMMAND_CHANGED });
         else
@@ -279,7 +230,6 @@ function detailsOf(headline, facts) {
             row("pull-request", "Pull request", `${name} open`, "none", { href: github });
     }
     const req = facts.requirements;
-    // A failed result names how many it missed, refuted or not: that is what failed.
     if (req != null && req.total > 0 && headline === "Failed" && (req.missed ?? 0) > 0)
         row("requirements", "Requirements", `${req.missed} missed`, "failed");
     else if (req != null && req.total > 0 && req.unverified === true)
@@ -304,25 +254,19 @@ function detailsOf(headline, facts) {
     }
     return rows;
 }
-/** What the lead's claim says, in place of "waits for you" (lead-voice.ts). */
 export const leadOnIt = (name = DEFAULT_LEAD_NAME) => `${name} is on it.`;
 export const leadLapsed = (name = DEFAULT_LEAD_NAME) => `${name} hasn't acted on this for 2 hours, so it's back with you.`;
-/** The headlines a lead's claim speaks for: the ones that would otherwise wait on a person. */
 const LEAD_HEADLINES = new Set(["Needs you", "Failed", "Ready for review", "Stopped"]);
 function leadSentence(headline, facts) {
     const sha = short(facts.checks?.head ?? null);
-    // A failed check stays said: the claim changes who acts next, never the result.
     if (headline === "Failed" && facts.checks?.status === "failed")
         return `${facts.checks.level === "quick" ? "Quick checks" : "Checks"} failed${sha === null ? "" : ` on ${sha}`}. ${leadOnIt(facts.leadName)}`;
     return leadOnIt(facts.leadName);
 }
-/** The one status every surface shows (console list, task and result pages, CLI, chat, phone, `status`). */
 export function statusOf(facts) {
     const read = headlineOf(facts);
     const lead = facts.lead != null && LEAD_HEADLINES.has(read) ? facts.lead : null;
-    // The lead has it: nothing waits on the person, so a Needs you reads Waiting.
     const headline = lead === "on-it" && read === "Needs you" ? "Waiting" : read;
-    // Every Needs you carries the one action that resolves it, worded the same everywhere; a finished result's is Open result.
     const needKey = facts.stage === "finished" ? "review-result" : facts.need ?? "other";
     const need = headline === "Needs you" ? { key: needKey, action: NEEDS[needKey].action } : null;
     const ownWords = need !== null && (need.key === "other" || need.key === "review-result") && facts.action != null;
@@ -331,14 +275,8 @@ export function statusOf(facts) {
     return { headline, tone: HEADLINE_TONE[headline], sentence, details: detailsOf(headline, facts),
         primaryAction, why: [...new Set(facts.why ?? [])].filter(one => one.trim() !== ""), need, check: facts.report ? null : approvedCheckStateOf(facts.checks) };
 }
-/** The name most surfaces already import. */
 export const taskStatusOf = statusOf;
-// ---- reading the existing projections ----------------------------------------
-/** Codes that read Needs you whoever asks (their reason is a person's by nature). Any other need reads Needs you
- * only when the caller says a person is needed; otherwise it waits in the queue. */
 const ALWAYS_NEEDS = new Set(["planner-source", "signed-out", "needs-approval", "waiting-decision", "decision-queue"]);
-/** Queue reasons worth a sentence of their own; any other queued or
- * building reason is scheduler wording, and the default sentence is plainer. */
 const QUEUED_REASONS = new Set(["worker-at-capacity", "waiting-dependency", "retry-scheduled", "updating", "planning-ready", "scouting-ready", "provider-quota"]);
 export function plainReasonOf(stage, code, detail) {
     if (stage === "building" || stage === "checking" || stage === "reviewing" || stage === "planning")
@@ -347,8 +285,6 @@ export function plainReasonOf(stage, code, detail) {
         return QUEUED_REASONS.has(code) ? detail ?? null : null;
     return detail ?? null;
 }
-/** Every dispatch or work-index code, as the stage it means (needs-you.ts CODE_READING, the one table). Unknown
- * codes that wait on a person stay Needs you; everything else waits in the queue. */
 export function stageOfCode(code, options = {}) {
     if (code === "running" && options.planning)
         return { stage: "planning" };
@@ -360,7 +296,6 @@ export function stageOfCode(code, options = {}) {
     }
     return options.needsPerson === false ? { stage: "queued" } : { stage: "needs-you", need: known?.need ?? "other" };
 }
-/** The pull request as the task page's follower reports it, or the bare publication row. */
 export function pullRequestFactOf(publication) {
     if (publication === null)
         return null;
@@ -382,13 +317,9 @@ export function pullRequestFactOf(publication) {
         return { ...base, state: "open" };
     return { ...base, state: "opening" };
 }
-/** The assignment's stage. The work status, when the caller read one, names
- * the exact reason (a running planner, a pause, a failed attempt, a sign-in). */
 export function assignmentStageOf(assignment, work, planning = false) {
-    // A finding held for a person outlives the stage the work is in, a saved result included: only a person closes it.
     if (work?.token === "finding-held" && assignment.state !== "cancelled")
         return { stage: "needs-you", need: "finding" };
-    // The assignment's own reading (a build Toolroll can't confirm stopped) comes first.
     const own = assignment.need ?? null;
     if (own !== null && (assignment.state === "working" || assignment.state === "needs-decision"))
         return "wait" in own ? { stage: "waiting", wait: own.wait } : { stage: "needs-you", need: own.key };
@@ -413,32 +344,22 @@ export function assignmentStageOf(assignment, work, planning = false) {
             if (action === "inspect-findings")
                 return { stage: "needs-you", need: "finding" };
             const token = work?.token ?? "";
-            // A failed attempt is Failed. A saved result that still needs a decision
-            // (its scope, a hold, a process exit) is Needs you, even if its checks
-            // failed: the decision is the next step, and the Checks row says the rest.
             if (token === "failed" || token === "waiting-incident")
                 return { stage: "failed" };
             const read = stageOfCode(token, { needsPerson: true, operatorHold: action === "unhold" });
             if (read.stage === "stopped" || read.stage === "waiting")
                 return read;
-            // A saved result that isn't ready keeps its own reading; a task's dispatch reason names its need.
             return { stage: "needs-you", need: read.need ?? "other" };
         }
     }
 }
-/** Evidence that passed and only awaits the retired assessment step is met. */
 const requirementMet = (row) => row.state === "pass" || (row.assessment?.evidenceState === "pass" && (row.review ?? null) === null);
-/** A requirement whose only gap is the project check: every other kind it needs was shown, none is a person's check. */
 const onlyCheckMissing = (row) => {
     const needs = row.requiredEvidence ?? [];
     const answered = new Set((row.answered ?? []).map(one => one.kind));
     if (row.state !== "missing" || row.review != null || row.assessment?.evidenceState === "failed" ||
         !needs.includes("check") || needs.includes("manual-review") || !needs.every(kind => kind === "check" || answered.has(kind)))
         return false;
-    // `answered` contains claims, not validated evidence. In legacy matrices a missing
-    // check takes precedence over an invalid screenshot/changed path in `state`.
-    // Only the stored validator's check-only gaps establish that every other
-    // reference resolved. Direct assessment keeps these outcomes in its own detail.
     const detail = row.assessment?.detail ?? row.detail ?? [];
     const checkGaps = new Set([
         `criterion "${row.id}" requires check evidence, which the proof does not reference`,
@@ -447,7 +368,6 @@ const onlyCheckMissing = (row) => {
     ]);
     return (needs.every(kind => kind === "check") || detail.length > 0) && detail.every(one => checkGaps.has(one));
 };
-/** A required screenshot nobody captured. */
 const screenshotMissing = (row) => (row.requiredEvidence ?? []).includes("screenshot") && !(row.answered ?? []).some(one => one.kind === "screenshot");
 export function requirementWordOf(row, verdict, release) {
     if (verdict === "refuted")
@@ -465,13 +385,11 @@ const quoted = (statement) => {
     const one = (statement ?? "").replace(/\s+/g, " ").trim();
     return one.length > ASK_STATEMENT ? `${one.slice(0, ASK_STATEMENT - 1)}…` : one;
 };
-/** The ask for one unresolved requirement: what is wrong with it, and the two ways on. */
 function unresolvedAsk(row, word) {
     const what = word === "Not shown yet" && screenshotMissing(row) ? "A screenshot is missing for"
         : word === "Not shown yet" ? "Nothing shows this requirement is met" : word === "Unverified" ? "This requirement couldn't be verified" : "This requirement isn't met";
     return `${what}: ${quoted(row.statement) || row.id || "a requirement"}. Send it back, or accept the result with a reason.`;
 }
-/** Requirements from the stored matrix: met, the ones only a person confirms, and the total. */
 export function requirementsOf(matrix, release) {
     if (!matrix || matrix.length === 0)
         return null;
@@ -486,10 +404,6 @@ export function requirementsOf(matrix, release) {
         ...(unshown.length === 0 ? {} : { unshown: unshown.length }),
         ...(ask === null ? {} : { ask }) };
 }
-/** What refuses Complete, for `task complete`, the console and chat completion and deploy-candidate alike: a failed
- * check; a required check that is missing (checks deliberately Off are not missing: they are checked at release);
- * an unresolved requirement (a person's own check is theirs to give by completing; a recorded acceptance resolves
- * the rest); an unresolved HIGH review finding. A release check that covers the commit counts as passed. */
 export function completionBlockersOf(f) {
     const blockers = [];
     const release = releaseStateOf(f.checks);
@@ -517,39 +431,32 @@ export function completionBlockersOf(f) {
         blockers.push({ key: "high", message: `The automatic review found ${f.high === 1 ? "a high-severity problem" : `${f.high} high-severity problems`}. Send it back before accepting it.` });
     return blockers;
 }
-/** A refuted report verifies none of its requirements, whatever it marked met (a person's acceptance doesn't change that). */
 export function unverifiedWhenRefuted(requirements, verdict) {
     return requirements === null || verdict !== "refuted" ? requirements : { ...requirements, unverified: true };
 }
-/** Saved evidence health from the receipt's artifact list and its caveats. */
 export function evidenceOf(receipt, problems = receipt?.caveats ?? []) {
     if (receipt === null)
         return null;
-    // The check's own reading is the Project checks row's to say (a changed command is not a missing file).
     problems = problems.filter(one => one !== receipt.checks.detail);
     const shortened = receipt.artifacts.filter(one => !one.complete).length + problems.filter(one => /shortened|cut short/.test(one)).length;
     const damaged = problems.filter(one => /unavailable or changed|no longer verif|cannot be read|could not be read|failed capture|altered|damaged/i.test(one)).length;
     const missing = problems.filter(one => /missing|ambiguous|no longer exists/i.test(one) && !/unavailable or changed/.test(one)).length;
     return { shortened, missing, damaged };
 }
-/** A saved check reading as the shared fact (head, level, a follow-up running, a batch, release coverage). */
 export function checksFactOf(checks, head) {
     return { status: checks.status, exitCode: checks.exitCode, head,
         ...(checks.level == null ? {} : { level: checks.level }), ...(checks.running == null ? {} : { running: checks.running }),
         ...(checks.batch == null ? {} : { batch: checks.batch }), ...(checks.release == null ? {} : { release: checks.release }),
         ...(checks.cause == null ? {} : { cause: checks.cause }) };
 }
-/** A receipt's approved check, as every surface reads it (`approvedCheckOf` over its verdict and its saved check). */
 export function receiptChecksOf(receipt) {
     return approvedCheckOf(receipt.proof?.verdict ?? null, receipt.proof?.reasons ?? [], checksFactOf(receipt.checks, receipt.head));
 }
-/** The status facts of one assignment, as every surface reads them. */
 export function assignmentStatusFacts(assignment, options = {}) {
     const { stage, need, wait } = assignmentStageOf(assignment, options.work ?? null, options.planning ?? false);
     const build = assignment.need?.build ?? null;
     const receipt = assignment.receipt;
     const finished = stage === "finished" || stage === "complete";
-    // A saved result's rows show whenever it is the reason a person is needed, too.
     const withResult = finished || stage === "failed" || ((stage === "needs-you" || stage === "waiting") && receipt !== null);
     const report = receipt?.completionKind === "research-report";
     const checks = receipt === null || !withResult ? null : receiptChecksOf(receipt);
@@ -557,7 +464,6 @@ export function assignmentStatusFacts(assignment, options = {}) {
     const pullRequest = options.pullRequest !== undefined ? options.pullRequest
         : publication === null ? (withResult && !report ? { state: "none", number: null, url: null, ci: null, error: null } : null)
             : pullRequestFactOf(publication);
-    // Ready, Complete and Failed speak for themselves; every other stage keeps its recorded reason.
     const reason = stage === "needs-you" || stage === "waiting" || stage === "stopped" || stage === "queued" || (stage === "failed" && checks?.status !== "failed")
         ? stage === "stopped" && assignment.state === "cancelled" ? REPLACED.test(assignment.detail) ? assignment.detail : "Cancelled. Nothing else will run." : plainReasonOf(stage, options.work?.token ?? "", options.work?.detail ?? assignment.detail)
         : null;
@@ -577,8 +483,6 @@ export function assignmentStatusFacts(assignment, options = {}) {
         ...(assignment.lead == null ? {} : { lead: assignment.lead.state }),
     };
 }
-// ---- rendering helpers shared by the server pages and chat cards ------------
-/** The legacy work tone each headline wears where a surface still keys off StatusTone. */
 export function workToneOf(headline) {
     switch (headline) {
         case "Needs you": return "attention";
@@ -590,12 +494,10 @@ export function workToneOf(headline) {
         default: return "muted";
     }
 }
-/** One plain-text line per detail for chat cards: an icon, the label, the words. */
 export function statusDetailLines(status) {
     const icon = { ok: "✓", running: "●", none: "○", note: "⚠", failed: "✕" };
     return status.details.map(one => `${icon[one.mark]} ${one.label} · ${one.text}${one.action === null ? "" : ` — ${one.action.label}`}`);
 }
-/** The headline's emoji for chat cards (colour is never the only signal: the words follow). */
 export function headlineEmoji(headline) {
     return { Queued: "🕓", Planning: "📝", "Needs you": "👋", Waiting: "⏸", Building: "⏳", "Ready for review": "✅", Complete: "✅", Failed: "❌", Stopped: "⏹" }[headline];
 }
@@ -607,7 +509,6 @@ const ICON_PATHS = {
     failed: html `<path d="M18 6 6 18M6 6l12 12"/>`,
 };
 export const statusIconSvg = (mark) => html `<svg class="status-icon status-icon--${mark}" viewBox="0 0 24 24" width="14" height="14" fill="none" stroke="currentColor" stroke-width="2.25" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true">${ICON_PATHS[mark]}</svg>`;
-/** The detail rows as server HTML: quiet rows, colour only on the icon. */
 export function statusDetailsHtml(status) {
     if (status.details.length === 0)
         return html ``;
@@ -617,20 +518,14 @@ export function statusDetailsHtml(status) {
         return html `<li class="status-detail status-detail--${one.mark}" data-status-detail="${one.key}" data-mark="${one.mark}">${statusIconSvg(one.mark)}<span class="status-detail-label">${one.label}</span><span class="status-detail-text"><span>${text}</span>${action}</span></li>`;
     })}</ul>`;
 }
-/** The status card's fold of exact reasons: "More", never a third thing called Details. */
 export const STATUS_MORE = "More";
-/** The technical reasons, one tap away. */
 export function statusWhyHtml(status, extra = [], diagnostics = []) {
     const lines = [...new Set([...status.details.flatMap(one => one.why === null ? [] : [`${one.label}: ${one.why}`]), ...status.why, ...extra])];
     if (lines.length === 0 && diagnostics.length === 0)
         return html ``;
     return html `<details class="status-why"><summary>${STATUS_MORE}</summary>${lines.map(one => html `<p class="meta">${one}</p>`)}${diagnostics.map(one => html `<p class="meta" data-work-diagnostic="${one.token}">${one.label} · ${one.detail}</p>`)}</details>`;
 }
-/** Shared CSS for the server-rendered status: neutral rows, coloured icons. */
 export const TASK_STATUS_CSS = `.status-headline{display:flex;align-items:center;gap:.6rem;margin:0;font-size:1.125rem;font-weight:600;color:var(--foreground)}.status-headline i{width:.625rem;height:.625rem;border-radius:999px;flex-shrink:0;background:var(--muted-foreground)}[data-headline-tone=live] .status-headline i{background:var(--so-info,#0d74ce)}[data-headline-tone=attention] .status-headline i{background:var(--so-attention,var(--attention))}[data-headline-tone=ready] .status-headline i{background:transparent;box-shadow:inset 0 0 0 2px var(--so-success,#218358)}[data-headline-tone=success] .status-headline i{background:var(--so-success,#218358)}[data-headline-tone=danger] .status-headline i{background:var(--so-danger,#c4320a)}.status-sentence{margin:.35rem 0 0;color:var(--muted-foreground)}.status-details{list-style:none;margin:.75rem 0 0;padding:.25rem 0 0;border-top:1px solid var(--so-line,var(--border))}.status-detail{display:grid;grid-template-columns:14px 7.5rem minmax(0,1fr);align-items:center;gap:.6rem;padding:.4rem 0;font-size:.8125rem;color:var(--foreground)}.status-detail .status-icon{align-self:center;color:var(--muted-foreground)}.status-detail--ok .status-icon{color:var(--so-success,#218358)}.status-detail--running .status-icon{color:var(--so-info,#0d74ce)}.status-detail--note .status-icon{color:var(--so-ink)}.status-detail--failed .status-icon{color:var(--so-danger,#c4320a)}.status-detail-label{color:var(--muted-foreground)}.status-detail-text{display:flex;flex-wrap:wrap;align-items:baseline;gap:0 .6rem;min-width:0;overflow-wrap:anywhere}.status-detail-text a{color:inherit}.status-detail-act{font-weight:600;white-space:nowrap}.status-detail--note .status-detail-act{color:var(--so-ink)}@media(max-width:480px){.status-detail{grid-template-columns:14px 6.5rem minmax(0,1fr);min-height:2.75rem;padding:.25rem 0}.status-detail-text a{display:inline-block;padding:.75rem 0;margin:-.75rem 0}}.status-why{border:0;padding:0;margin:.25rem 0 0;background:transparent;box-shadow:none}.status-why>summary{cursor:pointer;min-height:2.75rem;display:list-item;align-content:center;font-size:.8125rem;color:var(--muted-foreground)}.status-why p{margin:.25rem 0 .5rem}.receipt-note{display:flex;align-items:center;gap:.45rem;font-size:.8125rem;color:var(--foreground)}.receipt-note .status-icon{color:var(--so-ink)}`;
-/** A dispatch diagnosis as its stage, for the phone and CLI reads that hold
- * no assignment. A done task is Complete once a person marked its result;
- * a refuted result whose project check failed is Failed. */
 export function stageOfDispatch(d, options = {}) {
     if (d.code === "reviewing")
         return { stage: "reviewing" };
@@ -642,7 +537,6 @@ export function stageOfDispatch(d, options = {}) {
         return { stage: "needs-you", need: "review-result" };
     return stageOfCode(d.code, { needsPerson: d.condition === "waiting" && d.action !== null, planning: d.condition === "running" && d.role === "planner", operatorHold: d.action === "unhold" });
 }
-/** The demo runs no checks: a Checks row that would offer to run one (or open one that never ran) says so instead. */
 export const DEMO_CHECKS = "Can't run in the demo";
 export function demoChecksOf(status) {
     return { ...status, details: status.details.map(one => one.key !== "checks" || one.mark === "ok" || one.mark === "failed" || one.mark === "running" ? one

package/dist/task-text.js

@@ -1,9 +1,3 @@
-/** New task text only. Historical signed terms are read by sealRevision,
- * never re-authored through this validator. Character counts deliberately
- * retain the existing JavaScript/HTML UTF-16 policy (TEXT_LIMITS.goal code units).
- * UTF-8 byte limits remain explicit storage bounds beside that policy. Reading
- * a stored goal never re-validates it, so a longer goal stays readable by a
- * runtime with lower limits. */
 import { hasForbiddenControls, hasDisguisedText } from "./decision.js";
 import { TEXT_LIMITS } from "./text-limits.js";
 export const TASK_TEXT_LIMITS = { title: TEXT_LIMITS.taskTitle, text: TEXT_LIMITS.goal, textBytes: TEXT_LIMITS.goalBytes };
@@ -41,11 +35,6 @@ export function validateTaskText(fields) {
     const bad = validateScopeText(fields);
     return bad === null ? null : refuse("bad-goal", bad.message);
 }
-/**
- * A title that fits: words longer than the title limit are cut at the last whole word that fits, with an ellipsis,
- * never mid-word (one unbroken word longer than half the limit is the only thing cut inside a word). Whitespace runs
- * read as one space. Text within the limit is returned as it is.
- */
 export function titleWithin(text, max = TASK_TEXT_LIMITS.title) {
     if (text.length <= max)
         return text;
@@ -53,7 +42,6 @@ export function titleWithin(text, max = TASK_TEXT_LIMITS.title) {
     if (words.length <= max)
         return words;
     const room = words.slice(0, max - 1);
-    // The room ends at a whole word when the next character is a space; else back to the last space in it.
     const space = words[max - 1] === " " ? room.length : room.lastIndexOf(" ");
     const cut = (space >= Math.floor(max / 2) ? room.slice(0, space) : room).replace(/[\s,;:.\-–—]+$/u, "");
     return `${cut}…`;

package/dist/team-chat-authorization.js

@@ -1,10 +1,7 @@
-/** The live grant shared by team execution, proposal cards and confirmation doors. */
 import { createHash } from 'node:crypto';
 import { ceilingDigestOf } from './principal.js';
 import { credentialKeyOf, isDirectChatProvider, priceForConfig, subscriptionCredentialKey } from './converse.js';
 const hash = (value) => createHash('sha256').update(JSON.stringify(value)).digest('hex');
-/** Subscription-only surfaces can resolve current terms from saved settings.
- * Direct API callers must supply their live key; a stored grant is never proof of it. */
 export function subscriptionTeamChatProvider(store) {
     const config = store.getChatConfig();
     return config && !isDirectChatProvider(config.provider) ? { config, key: null } : null;

package/dist/team-contract.js

@@ -1,8 +1,6 @@
 export const TEAM_OPERATIONS = ['list', 'show', 'create-lead', 'update-lead', 'create-conversation', 'member', 'send', 'edit', 'withdraw', 'read', 'authorize', 'follow', 'stop', 'transfer'];
-/** Whether each operation writes anything (a read receipt included). Exhaustive, so a new operation can't default to read. */
 export const TEAM_MUTATIONS = {
     list: false, show: false, 'create-lead': true, 'update-lead': true, 'create-conversation': true, member: true, send: true, edit: true,
     withdraw: true, read: true, authorize: true, follow: true, stop: true, transfer: true,
 };
-/** Whether this actor may run `operation`: a read-scope token never writes. */
 export const teamScopeAllows = (actor, operation) => !TEAM_MUTATIONS[operation] || actor.principal === undefined || actor.principal.scope === 'act';

package/dist/team-http.js

@@ -2,8 +2,6 @@ import { adapterPolicy } from "./server/route-policy.js";
 import { TEAM_OPERATIONS, TEAM_MUTATIONS, teamScopeAllows } from './team-contract.js';
 import { limitWords } from './request-budget.js';
 export const TEAM_REQUEST_BYTES = 64 * 1024;
-/** How long a password bearer's proof stands on a long live team stream (GET /live?room=team) before its password is
- * checked again. The account, its revocation and its credential generation are still rechecked on every signal. */
 export const TEAM_PASSWORD_REVERIFY_MS = 5 * 60_000;
 const failure = (code, message) => ({ version: 1, ok: false, code, message });
 function send(response, status, value, headers = {}) {
@@ -33,8 +31,6 @@ function valid(value) {
         !!row.args && typeof row.args === 'object' && !Array.isArray(row.args) &&
         !['actor', 'generation', 'authenticatedActor'].some(key => key in row.args);
 }
-/** Authenticated browser and remote CLI share one operation boundary. Live
- * updates come from GET /live?room=team (server/live.ts). */
 export async function handleTeamHttp(request, response, options) {
     const url = new URL(request.url ?? '/', 'http://standing-orders.local');
     if (url.pathname !== '/api/team')

package/dist/team-leads.js

@@ -34,7 +34,6 @@ function role(value) {
         refuse('invalid', 'Choose Viewer, Contributor or Manager.');
     return value;
 }
-/** A failed turn's words for its message: none when the turn said why in the thread itself (it stopped at its deadline). */
 function savedFailure(reason) {
     return reason === 'timeout' || reason === 'crashed' ? null : String(reason ?? 'The saved turn failed.');
 }
@@ -46,7 +45,6 @@ function stable(value) {
         return Object.fromEntries(Object.entries(value).sort(([a], [b]) => a.localeCompare(b)).map(([k, v]) => [k, stable(v)]));
     return value;
 }
-/** One central database owns audiences and queued turns. No model or provider calls here. */
 export class TeamLeads {
     store;
     enrolled;
@@ -55,8 +53,6 @@ export class TeamLeads {
         this.enrolled = enrolled;
     }
     get db() { return this.store.handle; }
-    /** The account as this actor may use it now. An API token's principal narrows it: a read token acts as a viewer, and a
-     * project-limited token sees only its projects. Every role and project check below reads this, never the raw row. */
     account(actor) {
         const account = this.store.accountOf(actor.name);
         if (account === null || account.revokedAt !== null || account.generation !== actor.generation)
@@ -68,7 +64,6 @@ export class TeamLeads {
             refuse('signed-out', 'Sign in again to use this conversation.');
         return { ...account, role: principal.scope === 'act' ? account.role : 'viewer', projects: tokenProjects(account.projects, principal.projects) };
     }
-    /** Whether the actor may use `repo` now: their account's access, narrowed by any token limit. */
     reaches(actor, repo) {
         return this.store.accountCanAccess(actor.name, repo) && projectAccessAllows(this.account(actor).projects, repo);
     }
@@ -129,7 +124,6 @@ export class TeamLeads {
     event(lead, conversation, kind, actor, now) {
         this.db.prepare('INSERT INTO team_event(lead,conversation,kind,actor,created_at) VALUES(?,?,?,?,?)').run(lead, conversation, kind, actor, now.toISOString());
     }
-    /** Permission recheck and a small indexed cursor query; it never rebuilds chat history. */
     cursor(actor, conversationId) {
         try {
             this.account(actor);
@@ -137,7 +131,6 @@ export class TeamLeads {
                 const { lead } = this.access(actor, conversationId);
                 return Number(this.db.prepare('SELECT COALESCE(MAX(id),0) AS n FROM team_event WHERE (conversation=? OR (conversation IS NULL AND lead=?))').get(conversationId, lead.id)?.['n'] ?? 0);
             }
-            // A project-limited token hears only of the leads and conversations it can open, never activity beyond its projects.
             if (actor.principal?.projects != null) {
                 const account = this.account(actor);
                 const leads = this.db.prepare('SELECT l.id FROM team_lead l JOIN team_lead_member m ON m.lead=l.id WHERE m.account=? AND m.active=1').all(actor.name).map(r => String(r['id']))
@@ -198,7 +191,6 @@ export class TeamLeads {
                     refuse('read-only', 'Your token reads only. Use an act token for this.');
                 const requestId = request.args['requestId'];
                 const key = requestId === undefined ? null : str(requestId, 'Request ID', 128);
-                // A token's scope and project limit are part of what was asked: a narrower token never replays a wider one's receipt.
                 const digest = hash(stable(actor.principal === undefined ? request : { request, scope: actor.principal.scope, projects: actor.principal.projects }));
                 if (key) {
                     const seen = this.db.prepare('SELECT payload_hash,response_json FROM team_request WHERE account=? AND generation=? AND request_id=?').get(actor.name, actor.generation, key);
@@ -214,10 +206,9 @@ export class TeamLeads {
                 return response;
             });
             if (request.operation === 'read')
-                return result; // Personal read receipts never rebuild the shared workspace.
+                return result;
             const conversationId = typeof request.args['conversationId'] === 'string' ? request.args['conversationId'] : undefined;
             const leadId = typeof request.args['leadId'] === 'string' ? request.args['leadId'] : undefined;
-            // A membership operation may deliberately remove the caller; its receipt still stands.
             try {
                 return { ...result, snapshot: this.snapshot(actor, conversationId, leadId) };
             }
@@ -472,7 +463,6 @@ export class TeamLeads {
             return true;
         });
     }
-    /** A pre-admission refusal saves a waiting reason. Admitted work is never requeued. */
     defer(claim, error, now = new Date()) {
         return this.store.transact(() => {
             const row = this.claimed(claim);
@@ -488,7 +478,6 @@ export class TeamLeads {
             return true;
         });
     }
-    /** Reconcile only recorded terminal receipts; never infer success from time or rerun a turn. */
     reconcileFinished(now = new Date()) {
         return this.store.transact(() => {
             const rows = this.db.prepare(`SELECT q.*,c.lead,c.thread,t.state AS turn_state,t.failure_reason FROM team_message q
@@ -498,8 +487,6 @@ export class TeamLeads {
         ORDER BY q.message LIMIT 100`).all();
             let changed = 0;
             for (const row of rows) {
-                // An unknown provider outcome remains a stop point even when the account
-                // lost access: permission revocation is not proof an effect did not occur.
                 const uncertain = this.deliveryUncertain(Number(row['turn_id']));
                 const cancelled = Number(row['stop_requested']) === 1 || !this.authorStillAllowed(row);
                 const status = uncertain ? 'uncertain' : cancelled ? 'cancelled' : row['turn_state'] === 'answered' ? 'answered' : 'failed';
@@ -515,7 +502,6 @@ export class TeamLeads {
     }
     deliveryUncertain(turnId) { return this.db.prepare("SELECT 1 FROM chat_turn WHERE mate_turn=? AND (unknown_spend=1 OR state IN ('queued','running') OR settled_microusd IS NULL) LIMIT 1").get(turnId) !== undefined; }
     activeRunners() { return this.db.prepare("SELECT DISTINCT runner FROM team_message WHERE status='running' AND runner IS NOT NULL").all().map(r => String(r['runner'])); }
-    /** Called only after the runtime proves this runner has stopped. Never repeats work. */
     recover(runner, now = new Date()) {
         return this.store.transact(() => {
             const rows = this.db.prepare("SELECT q.*,c.lead FROM team_message q JOIN team_conversation c ON c.id=q.conversation WHERE runner=? AND status='running'").all(runner);
@@ -557,7 +543,6 @@ export class TeamLeads {
         const row = this.db.prepare('SELECT lead,revision,conversation FROM team_task_owner WHERE task_ref=?').get(ref.id);
         return row ? { leadId: String(row['lead']), revision: Number(row['revision']), conversationId: row['conversation'] === null ? null : String(row['conversation']) } : null;
     }
-    /** Attach newly filed work in its original admission transaction. Never steals an existing owner. */
     recordTaskOwner(taskId, leadId, conversationId, actor, now = new Date()) {
         return this.store.transact(() => {
             const lead = this.leadAccess(actor, leadId, 'contributor').lead;