toolroll 0.9.6 → 0.9.8

package/dist/flow-triggers.js

@@ -660,6 +660,8 @@ async function fireScript(store, trigger, config, now, io, scheduled) {
     const script = flow === null ? null : store.flowScript(flow.repo, config.script);
     if (flow === null || script === null)
         return done(false, `There's no script called ${config.script} in this project any more.`);
+    if (script.held !== null)
+        return done(false, `The ${script.name} script came with an imported flow. Approve it on the Scripts panel to run it.`);
     const saved = readFlowSecrets(io.dir, flow.repo);
     const missing = (config.secrets ?? []).filter(name => saved[name] === undefined);
     if (missing.length > 0)

package/dist/flows-cli.d.ts

@@ -1,3 +1,4 @@
+import { type FetchLike } from './flow-share.js';
 import { type TriggerIo } from './flow-triggers.js';
 import type { Store } from './store.js';
 export declare const FLOWS_DESCRIPTORS: readonly [{
@@ -187,6 +188,59 @@ export declare const FLOWS_DESCRIPTORS: readonly [{
         readonly takesValue: true;
         readonly meaning: 'a zone id or name';
     }];
+}, {
+    readonly action: 'export';
+    readonly synopsis: 'write a flow as a *.toolroll-flow.json file: zones, paths, trigger settings and scripts; never secrets, webhook addresses, names or cards';
+    readonly mutation: 'none';
+    readonly positionals: readonly ['flow'];
+    readonly flags: readonly [...{
+        name: string;
+        takesValue: boolean;
+        meaning: string;
+    }[], {
+        readonly name: 'out';
+        readonly takesValue: true;
+        readonly meaning: 'write the file here (default: print it)';
+    }];
+}, {
+    readonly action: 'import';
+    readonly synopsis: 'make a flow from a flow file or a gist/GitHub https address; previews in plain words until --yes; triggers arrive off and scripts wait for approval';
+    readonly mutation: 'unkeyed';
+    readonly positionals: readonly ['file'];
+    readonly flags: readonly [...{
+        name: string;
+        takesValue: boolean;
+        meaning: string;
+    }[], {
+        name: string;
+        takesValue: boolean;
+        meaning: string;
+    }, {
+        name: string;
+        takesValue: boolean;
+        meaning: string;
+    }, {
+        readonly name: 'param';
+        readonly takesValue: true;
+        readonly meaning: 'a value the file asks for, as name=value (repeat for more)';
+    }];
+}, {
+    readonly action: 'script approve';
+    readonly synopsis: 'approve a script an imported flow brought, so it runs';
+    readonly mutation: 'identity-idempotent';
+    readonly flags: readonly [...{
+        name: string;
+        takesValue: boolean;
+        meaning: string;
+    }[], {
+        name: string;
+        takesValue: boolean;
+        meaning: string;
+    }, {
+        readonly name: 'name';
+        readonly takesValue: true;
+        readonly meaning: "the script's name";
+    }];
 }, {
     readonly action: 'archive';
     readonly synopsis: 'archive a flow: its cards stop moving and its triggers stop; previews until --yes';
@@ -222,6 +276,8 @@ export type FlowsCliContext = {
     triggerIo: TriggerIo;
     /** Reads a file, or stdin for "-". */
     readInput?: (path: string) => string;
+    /** Fetches a flow file's address (tests stand in for the network). */
+    fetchFlow?: FetchLike;
 };
 type Flags = Map<string, string | true>;
 export declare function runFlowsCommand(positional: readonly string[], flags: Flags, context: FlowsCliContext): Promise<number>;

package/dist/flows-cli.js

@@ -4,12 +4,15 @@
  * addCardToFlow — so a flow made here is checked exactly as one drawn there.
  * Reads need no login; every write is an approver's, proved by --as/--token
  * (or the remembered login), and lands in the ledger as a console request
- * does. create, edit, archive and trigger add preview until --yes. */
-import { readFileSync } from 'node:fs';
+ * does. create, edit, archive, import and trigger add preview until --yes.
+ * export writes a flow file (flow-share.ts); import reads one, from a path
+ * or a gist/GitHub address, and previews it in plain words first. */
+import { readFileSync, statSync, writeFileSync } from 'node:fs';
 import { resolve } from 'node:path';
 import { envelopeJson } from './envelope.js';
 import { addCardToFlow, advanceFlows, flowDefinitionOf } from './flow-engine.js';
 import { saveScript } from './flow-scripts.js';
+import { exportFlow, fetchFlowFile, FLOW_FILE_MAX_BYTES, FlowFileError, importFlow, parseFlowFile, planFlowImport } from './flow-share.js';
 import { STARTER_FLOWS, starterFlowOf, starterOf, startersFor, starterTerms, switchOnStarter } from './flow-starters.js';
 import { addFlowTriggerTo, checkFlowTriggerNow, describeTrigger, removeFlowTrigger, triggerConfigOf, validateTriggerConfig } from './flow-triggers.js';
 import { deciderOf, FLOW_KIND_WORDS, FLOW_TEMPLATES, flowDigest, flowFromSteps, flowTerms, stepsFor } from './flows.js';
@@ -48,10 +51,15 @@ export const FLOWS_DESCRIPTORS = [
             { name: 'title', takesValue: true, meaning: "the card's title" },
             { name: 'description', takesValue: true, meaning: 'its details' },
             { name: 'zone', takesValue: true, meaning: 'a zone id or name' }] },
+    { action: 'export', synopsis: 'write a flow as a *.toolroll-flow.json file: zones, paths, trigger settings and scripts; never secrets, webhook addresses, names or cards', mutation: 'none', positionals: ['flow'], flags: [...read,
+            { name: 'out', takesValue: true, meaning: 'write the file here (default: print it)' }] },
+    { action: 'import', synopsis: 'make a flow from a flow file or a gist/GitHub https address; previews in plain words until --yes; triggers arrive off and scripts wait for approval', mutation: 'unkeyed', positionals: ['file'], flags: [...write, yes, repo,
+            { name: 'param', takesValue: true, meaning: 'a value the file asks for, as name=value (repeat for more)' }] },
+    { action: 'script approve', synopsis: 'approve a script an imported flow brought, so it runs', mutation: 'identity-idempotent', flags: [...write, repo, { name: 'name', takesValue: true, meaning: "the script's name" }] },
     { action: 'archive', synopsis: 'archive a flow: its cards stop moving and its triggers stop; previews until --yes', mutation: 'identity-idempotent', positionals: ['flow'], flags: [...write, yes] },
 ];
 /** `--file` is a value here (a path in the project), where elsewhere it is a switch. */
-export const FLOWS_VALUE_FLAGS = new Set(['file']);
+export const FLOWS_VALUE_FLAGS = new Set(['file', 'param']);
 export async function runFlowsCommand(positional, flags, context) {
     const [first, second] = positional;
     const action = first === 'trigger' || first === 'script' || first === 'card' ? `${first} ${second ?? ''}`.trim() : first ?? 'list';
@@ -93,6 +101,33 @@ export async function runFlowsCommand(positional, flags, context) {
         const shown = describeFlow(store, flow);
         return ok({ flow: shown }, showLines(shown));
     }
+    if (action === 'export') {
+        const flow = flowOf(args[0], context.projects);
+        if (flow === null)
+            return fail('unknown-flow', 'No such flow in your projects. toolroll flows list names them.');
+        let exported;
+        try {
+            exported = exportFlow(store, flow, context.configDir);
+        }
+        catch (error) {
+            return fail('unreadable', error instanceof Error ? error.message : 'This flow can\'t be exported.');
+        }
+        const left = exported.left.length === 0 ? [] : [`Left out: ${exported.left.join('; ')}.`];
+        const out = text('out');
+        if (out === null) {
+            if (context.json)
+                return ok({ file: exported.file, fileName: exported.fileName, left: exported.left }, []);
+            context.write(exported.json.trimEnd());
+            return EXIT.ok;
+        }
+        try {
+            writeFileSync(resolve(out), exported.json);
+        }
+        catch {
+            return fail('unwritable', `Couldn't write ${out}.`, EXIT.failed);
+        }
+        return ok({ path: resolve(out), fileName: exported.fileName, left: exported.left }, [`Wrote ${flow.name} to ${resolve(out)}.`, ...left]);
+    }
     // ---- writes: an approver's, on a project they can reach
     if (context.credentials === null)
         return fail('unauthenticated', 'Changing a flow needs an approver: pass --as <you> --token <your password> (or sign in once with toolroll up).');
@@ -232,6 +267,77 @@ export async function runFlowsCommand(positional, flags, context) {
         settle(project);
         return ok({ applied: true, repo: project, script: store.flowScript(project, String(text('name')).trim().toLowerCase()), said: saved.said }, [saved.said]);
     }
+    if (action === 'import') {
+        const given = text('repo');
+        if (given === null || args[0] === undefined)
+            return fail('usage', 'Use flows import <file|https address> --repo <path> [--param name=value …] [--yes].', EXIT.usage);
+        const project = projectOf(given);
+        if (project === null || !reachable.includes(project))
+            return refuse(null, 'unknown-project', 'That isn\'t one of your projects. toolroll repos lists them.');
+        const source = args[0];
+        const params = {};
+        for (const line of (text('param') ?? '').split('\n').filter(one => one.trim() !== '')) {
+            const equals = line.indexOf('=');
+            if (equals < 1)
+                return fail('usage', `Give --param as name=value, not ${line}.`, EXIT.usage);
+            params[line.slice(0, equals).trim()] = line.slice(equals + 1);
+        }
+        let plan;
+        try {
+            let raw;
+            if (/^[a-z][a-z0-9+.-]*:\/\//i.test(source))
+                raw = await fetchFlowFile(source, context.fetchFlow);
+            else {
+                let size = 0;
+                try {
+                    size = source === '-' ? 0 : statSync(resolve(source)).size;
+                }
+                catch { /* readInput says it can't be read */ }
+                if (size > FLOW_FILE_MAX_BYTES)
+                    throw new FlowFileError(`That file is too big: a flow file is at most ${FLOW_FILE_MAX_BYTES / 1024} KB.`);
+                try {
+                    raw = readInput(source);
+                }
+                catch {
+                    throw new FlowFileError(`${source} couldn't be read.`);
+                }
+            }
+            plan = planFlowImport(store, project, parseFlowFile(raw), params, who);
+        }
+        catch (error) {
+            if (!(error instanceof FlowFileError))
+                throw error;
+            return refuse(project, 'invalid-file', error.message);
+        }
+        if (!flags.has('yes'))
+            return preview(project, plan.title, plan.terms, { name: plan.name, definition: plan.definition, parameters: plan.values });
+        let made;
+        try {
+            made = importFlow(store, plan, who, now, context.configDir);
+        }
+        catch (error) {
+            return refuse(project, 'invalid-file', error instanceof Error ? error.message : 'That flow couldn\'t be imported.');
+        }
+        record(project, 'accepted', `flow #${made.id}`);
+        return ok({ applied: true, flow: describeFlow(store, store.getFlow(made.id)), said: made.said }, [`${made.said} Flow #${made.id}.`]);
+    }
+    if (action === 'script approve') {
+        const given = text('repo'), name = text('name');
+        if (given === null || name === null)
+            return fail('usage', 'Use flows script approve --repo <path> --name <name>.', EXIT.usage);
+        const project = projectOf(given);
+        if (project === null || !reachable.includes(project))
+            return refuse(null, 'unknown-project', 'That isn\'t one of your projects. toolroll repos lists them.');
+        const script = store.flowScript(project, name.trim().toLowerCase());
+        if (script === null)
+            return refuse(project, 'unknown-script', `There's no script called ${name} in ${projectName(project)}.`);
+        if (script.held === null)
+            return ok({ applied: false, repo: project, said: `${script.name} already runs.` }, [`${script.name} already runs.`]);
+        store.approveFlowScript(project, script.name);
+        record(project, 'accepted', `script ${script.name} approved`);
+        settle(project);
+        return ok({ applied: true, repo: project, said: `Approved ${script.name}. Zones that run it go on.` }, [`Approved ${script.name}. Zones that run it go on.`]);
+    }
     // Everything else names a flow in one of this person's projects.
     const flow = flowOf(args[0], reachable);
     if (flow === null)

package/dist/flows-ui.d.ts

@@ -2,9 +2,23 @@
  * (the React view's data, plus a plain fallback page the view replaces). */
 import type { BrowserFlowView } from "./browser-workspace.js";
 import type { FlowRow, Store } from "./store.js";
-export declare const FLOWS_CSS = ".flows{max-width:880px;min-width:0}.flows .card{padding:16px 18px;margin:12px 0}.flows .flow-row{display:flex;justify-content:space-between;align-items:baseline;gap:12px;flex-wrap:wrap}.flows .flow-row h2{font-size:1.05rem;margin:0}.flows .flow-counts{font-size:.85rem;color:var(--so-muted)}.flows form{display:grid;gap:10px;margin:0}.flows label{display:grid;gap:6px}.flows input,.flows select{box-sizing:border-box;width:100%;max-width:100%}.flows button{justify-self:start;min-height:44px}.flows .flow-fallback ol{padding-left:20px}.flows summary{cursor:pointer;min-height:44px;display:flex;align-items:center;font-weight:600}.flows .flow-buttons{display:flex;flex-wrap:wrap;gap:8px;margin:10px 0 0}@media(max-width:600px){.flows input,.flows select{font-size:16px}}@media(max-width:760px){.flows .card{padding:10px 12px;margin:8px 0;position:relative}.flows .flow-row{row-gap:2px}.flows .flow-row h2 a::after{content:\"\";position:absolute;inset:0;border-radius:inherit}.flows .flow-counts{line-height:1.35}}";
+import { type FlowFile, type FlowImportPlan } from "./flow-share.js";
+export declare const FLOWS_CSS = ".flows{max-width:880px;min-width:0}.flows .card{padding:16px 18px;margin:12px 0}.flows .flow-row{display:flex;justify-content:space-between;align-items:baseline;gap:12px;flex-wrap:wrap}.flows .flow-row h2{font-size:1.05rem;margin:0}.flows .flow-counts{font-size:.85rem;color:var(--so-muted)}.flows form{display:grid;gap:10px;margin:0}.flows label{display:grid;gap:6px}.flows input,.flows select{box-sizing:border-box;width:100%;max-width:100%}.flows button{justify-self:start;min-height:44px}.flows .flow-fallback ol{padding-left:20px}.flows summary{cursor:pointer;min-height:44px;display:flex;align-items:center;font-weight:600}.flows .flow-buttons{display:flex;flex-wrap:wrap;align-items:center;gap:8px;margin:10px 0 0}.flows .flow-import{margin-top:18px;padding-top:14px;border-top:1px solid var(--so-line)}.flows .flow-import h3{font-size:.95rem;margin:0}.flows .flow-terms{list-style:none;padding:0;margin:8px 0 16px;display:grid;gap:10px}.flows .flow-terms li{white-space:pre-line;overflow-wrap:anywhere}.flows .flow-terms pre{white-space:pre-wrap;overflow-wrap:anywhere;font-size:.8rem;margin:6px 0 0}.flows .flow-import-preview h2{font-size:1rem;margin:20px 0 4px}.flows .flow-untrusted{font-weight:600}.flows button.primary{background:var(--primary);color:var(--primary-foreground);border-color:var(--primary)}.flows fieldset{border:0;padding:0;margin:0;display:grid;gap:10px;min-width:0}.flows legend{font-weight:600;padding:0;margin-bottom:6px}.flows textarea[hidden]{display:none}.flows button.secondary{background:transparent;color:var(--foreground);border:1px solid var(--border)}@media(max-width:600px){.flows input,.flows select{font-size:16px}}@media(max-width:760px){.flows .card{padding:10px 12px;margin:8px 0;position:relative}.flows .flow-row{row-gap:2px}.flows .flow-row h2 a::after{content:\"\";position:absolute;inset:0;border-radius:inherit}.flows .flow-counts{line-height:1.35}}";
 /** The flows a person can open, with how many cards wait in each, and the new-flow form. */
 export declare function flowsListHtml(store: Store, flows: readonly FlowRow[], projects: readonly string[], csrf: string, canCreate: boolean, problem: string | null): string;
+/** Reads the chosen flow file into the form (the server reads it again, whole, before anything is made). */
+export declare const FLOW_IMPORT_SCRIPT = "(function(){var form=document.querySelector('[data-flow-import]');if(!form)return;var input=form.querySelector('[data-flow-file]'),text=form.querySelector('[data-flow-document]'),note=form.querySelector('[data-flow-file-note]'),address=form.querySelector('[name=url]');function say(words){note.textContent=words;note.hidden=words==='';}var reading=null;input.addEventListener('change',function(){text.value='';say('');var file=input.files&&input.files[0];if(!file){reading=null;return;}if(file.size>262144){say('That file is too big: a flow file is at most 256 KB.');input.value='';reading=null;return;}reading=file.text().then(function(value){text.value=value;});});form.addEventListener('submit',function(event){if(reading!==null&&text.value===''){event.preventDefault();reading.then(function(){form.requestSubmit();});return;}if(text.value===''&&address.value.trim()===''){event.preventDefault();say('Choose a flow file or give its address.');}});})();";
+/** An import's preview: the plan in plain words, what it asks for, and one Import button after the terms. */
+export declare function flowImportHtml(input: {
+    plan: FlowImportPlan | null;
+    file: FlowFile;
+    document: string;
+    repo: string;
+    csrf: string;
+    values: Record<string, string>;
+    previewed: string;
+    problem: string | null;
+}): string;
 /** One flow's canvas for one person. */
 export declare function flowView(store: Store, flow: FlowRow, viewer: {
     name: string;

package/dist/flows-ui.js

@@ -1,11 +1,12 @@
 import { draftFor, flowDefinitionOf } from "./flow-engine.js";
 import { describeTrigger, triggerHeadline, FLOW_TRIGGER_KINDS, FLOW_TRIGGER_WORDS, githubRepoOf, HOOK_PATH, hookReady, readHooksBase, readLinearKey, takesDeliveries, triggerConfigOf } from "./flow-triggers.js";
-import { deciderOf, FLOW_COLORS, FLOW_KIND_WORDS, FLOW_STAGE_KINDS, FLOW_TEMPLATES } from "./flows.js";
+import { deciderOf, FLOW_COLORS, FLOW_KIND_WORDS, FLOW_STAGE_KINDS } from "./flows.js";
 import { flowInsights, troubleWords } from "./flow-insights.js";
 import { parseSortDecision, sortChip } from "./flow-sort.js";
 import { flowSecretNames, readEmailSettings, sendingReady } from "./flow-actions.js";
 import { projectToolsOf, secretsSetFor, toolStanding } from "./project-tools.js";
 import { flowFingerprint } from "./flow-live.js";
+import { FLOW_FILE_MAX_BYTES } from "./flow-share.js";
 import { googleConnected } from "./google-mail.js";
 import { mailboxReady } from "./mailbox.js";
 import { labelOf, nameOf } from "./teammate-admin.js";
@@ -13,7 +14,7 @@ import { callWords, receiptWords } from "./teammate-tools.js";
 import { undoFor } from "./teammate-week.js";
 const e = (value) => String(value ?? "").replace(/[&<>"']/g, c => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;" })[c]);
 const projectName = (repo) => repo.split(/[\\/]/).filter(Boolean).pop() ?? repo;
-export const FLOWS_CSS = `.flows{max-width:880px;min-width:0}.flows .card{padding:16px 18px;margin:12px 0}.flows .flow-row{display:flex;justify-content:space-between;align-items:baseline;gap:12px;flex-wrap:wrap}.flows .flow-row h2{font-size:1.05rem;margin:0}.flows .flow-counts{font-size:.85rem;color:var(--so-muted)}.flows form{display:grid;gap:10px;margin:0}.flows label{display:grid;gap:6px}.flows input,.flows select{box-sizing:border-box;width:100%;max-width:100%}.flows button{justify-self:start;min-height:44px}.flows .flow-fallback ol{padding-left:20px}.flows summary{cursor:pointer;min-height:44px;display:flex;align-items:center;font-weight:600}.flows .flow-buttons{display:flex;flex-wrap:wrap;gap:8px;margin:10px 0 0}@media(max-width:600px){.flows input,.flows select{font-size:16px}}@media(max-width:760px){.flows .card{padding:10px 12px;margin:8px 0;position:relative}.flows .flow-row{row-gap:2px}.flows .flow-row h2 a::after{content:"";position:absolute;inset:0;border-radius:inherit}.flows .flow-counts{line-height:1.35}}`;
+export const FLOWS_CSS = `.flows{max-width:880px;min-width:0}.flows .card{padding:16px 18px;margin:12px 0}.flows .flow-row{display:flex;justify-content:space-between;align-items:baseline;gap:12px;flex-wrap:wrap}.flows .flow-row h2{font-size:1.05rem;margin:0}.flows .flow-counts{font-size:.85rem;color:var(--so-muted)}.flows form{display:grid;gap:10px;margin:0}.flows label{display:grid;gap:6px}.flows input,.flows select{box-sizing:border-box;width:100%;max-width:100%}.flows button{justify-self:start;min-height:44px}.flows .flow-fallback ol{padding-left:20px}.flows summary{cursor:pointer;min-height:44px;display:flex;align-items:center;font-weight:600}.flows .flow-buttons{display:flex;flex-wrap:wrap;align-items:center;gap:8px;margin:10px 0 0}.flows .flow-import{margin-top:18px;padding-top:14px;border-top:1px solid var(--so-line)}.flows .flow-import h3{font-size:.95rem;margin:0}.flows .flow-terms{list-style:none;padding:0;margin:8px 0 16px;display:grid;gap:10px}.flows .flow-terms li{white-space:pre-line;overflow-wrap:anywhere}.flows .flow-terms pre{white-space:pre-wrap;overflow-wrap:anywhere;font-size:.8rem;margin:6px 0 0}.flows .flow-import-preview h2{font-size:1rem;margin:20px 0 4px}.flows .flow-untrusted{font-weight:600}.flows button.primary{background:var(--primary);color:var(--primary-foreground);border-color:var(--primary)}.flows fieldset{border:0;padding:0;margin:0;display:grid;gap:10px;min-width:0}.flows legend{font-weight:600;padding:0;margin-bottom:6px}.flows textarea[hidden]{display:none}.flows button.secondary{background:transparent;color:var(--foreground);border:1px solid var(--border)}@media(max-width:600px){.flows input,.flows select{font-size:16px}}@media(max-width:760px){.flows .card{padding:10px 12px;margin:8px 0;position:relative}.flows .flow-row{row-gap:2px}.flows .flow-row h2 a::after{content:"";position:absolute;inset:0;border-radius:inherit}.flows .flow-counts{line-height:1.35}}`;
 /** The flows a person can open, with how many cards wait in each, and the new-flow form. */
 export function flowsListHtml(store, flows, projects, csrf, canCreate, problem) {
     const rows = flows.map(flow => {
@@ -25,15 +26,39 @@ export function flowsListHtml(store, flows, projects, csrf, canCreate, problem)
         return `<article class="card"><div class="flow-row"><h2><a href="/flows/${flow.id}">${e(flow.name)}</a></h2><span class="flow-counts">${e(projectName(flow.repo))} · ${cards.length} card${cards.length === 1 ? "" : "s"} in progress${waiting > 0 ? ` · ${waiting} waiting for a decision` : ""}${trouble === null ? "" : ` · ${e(trouble)}`}</span></div>` +
             (buttons.length === 0 ? "" : `<p class="flow-buttons">${buttons.map(one => `<a class="button-link" href="/flows/${flow.id}?start=${one.id}">${e(one.label)}</a>`).join(" ")}</p>`) + `</article>`;
     }).join("");
-    const create = canCreate && projects.length > 0 ? `<details class="card"${flows.length === 0 ? " open" : ""}><summary>New flow</summary><form method="post" action="/flows/new"><input type="hidden" name="csrf" value="${e(csrf)}"><label>Name<input name="name" required maxlength="80" placeholder="for example: Bug fixes"></label><label>Project<select name="repo">${projects.map(repo => `<option value="${e(repo)}">${e(projectName(repo))}</option>`).join("")}</select></label><label>Start from<select name="template">${FLOW_TEMPLATES.map(one => `<option value="${e(one.id)}">${e(one.label)}: ${e(one.about)}</option>`).join("")}</select></label><button>Create flow</button></form></details>` : "";
+    const projectField = projects.length === 1 ? `<input type="hidden" name="repo" value="${e(projects[0])}">` : `<label>Project<select name="repo">${projects.map(repo => `<option value="${e(repo)}">${e(projectName(repo))}</option>`).join("")}</select></label>`;
+    // A flow file (flow-share.ts): chosen here or fetched from a gist, previewed in plain words before anything is made.
+    const importForm = `<form method="post" action="/flows/import" class="flow-import" data-flow-import><input type="hidden" name="csrf" value="${e(csrf)}"><h3>Or import a flow file</h3>${projectField}<label>File<input type="file" accept=".json,application/json" data-flow-file></label><textarea name="document" hidden data-flow-document></textarea><label>Or its address<input name="url" type="url" inputmode="url" placeholder="https://gist.github.com/…"></label><p class="problem" role="alert" data-flow-file-note hidden></p><button>Preview import</button></form>`;
+    // A new flow starts from the gallery (Flows → New): templates grouped by what they're for.
+    const create = canCreate && projects.length > 0 ? `<p class="flow-buttons"><a class="button-link" href="/flows/new">New flow</a></p>${importForm}` : "";
     // No flows yet: one click makes a working example with a sample question in it.
     const example = flows.length === 0 && canCreate && projects.length > 0
         ? `<form method="post" action="/flows/example" class="card flow-example"><input type="hidden" name="csrf" value="${e(csrf)}"><h2>See a flow work</h2><p class="meta">Claude drafts a reply to a sample customer question; you approve it here or in your chat app.</p>${projects.length === 1 ? `<input type="hidden" name="repo" value="${e(projects[0])}">` : `<label>Project<select name="repo">${projects.map(repo => `<option value="${e(repo)}">${e(projectName(repo))}</option>`).join("")}</select></label>`}<button>Try an example</button></form>`
         : "";
     const intro = `<p class="meta">A flow is your process drawn as zones. Cards move through them: agents do the work, people approve, and the team hears about it.</p>` +
-        (canCreate && projects.length > 0 ? `<p class="flow-chat">Describe how work should move and your lead drafts the flow for you to confirm, or start from a template below. <a href="/chat?draft=${encodeURIComponent("Make a flow for ")}">Describe it in chat</a></p>` : "") +
+        (canCreate && projects.length > 0 ? `<p class="flow-chat">Describe how work should move and your lead drafts the flow for you to confirm, or start from a template. <a href="/chat?draft=${encodeURIComponent("Make a flow for ")}">Describe it in chat</a></p>` : "") +
         `<p class="flow-chat">AI teammates can decide and handle cards for you, within rules you write. <a href="/teammates">Teammates</a> · or set one up with its flow in one click: <a href="/kits">Starter kits</a></p>`;
-    return `<section class="flows">${problem === null ? "" : `<p class="problem" role="alert">${e(problem)}</p>`}${intro}${rows || example || '<p class="meta">No flows yet.</p>'}${create}</section>`;
+    return `<section class="flows">${problem === null ? "" : `<p class="problem" role="alert">${e(problem)}</p>`}${intro}${create}${rows || example || '<p class="meta">No flows yet.</p>'}</section>`;
+}
+/** Reads the chosen flow file into the form (the server reads it again, whole, before anything is made). */
+export const FLOW_IMPORT_SCRIPT = `(function(){var form=document.querySelector('[data-flow-import]');if(!form)return;var input=form.querySelector('[data-flow-file]'),text=form.querySelector('[data-flow-document]'),note=form.querySelector('[data-flow-file-note]'),address=form.querySelector('[name=url]');function say(words){note.textContent=words;note.hidden=words==='';}var reading=null;input.addEventListener('change',function(){text.value='';say('');var file=input.files&&input.files[0];if(!file){reading=null;return;}if(file.size>${FLOW_FILE_MAX_BYTES}){say('That file is too big: a flow file is at most ${FLOW_FILE_MAX_BYTES / 1024} KB.');input.value='';reading=null;return;}reading=file.text().then(function(value){text.value=value;});});form.addEventListener('submit',function(event){if(reading!==null&&text.value===''){event.preventDefault();reading.then(function(){form.requestSubmit();});return;}if(text.value===''&&address.value.trim()===''){event.preventDefault();say('Choose a flow file or give its address.');}});})();`;
+/** An import's preview: the plan in plain words, what it asks for, and one Import button after the terms. */
+export function flowImportHtml(input) {
+    const { plan, file } = input;
+    const fields = file.parameters.map(one => `<label><span>${e(one.about)}${one.optional === true ? ' <span class="meta">(optional)</span>' : ""}</span><input name="param.${e(one.id)}" value="${e(input.values[one.id] ?? plan?.values[one.id] ?? one.default ?? "")}" maxlength="200" autocomplete="off"></label>`).join("");
+    const list = (items) => items.length === 0 ? "" : `<ul class="flow-terms">${items.map(term => `<li>${e(term)}</li>`).join("")}</ul>`;
+    // The steps, what they mean, the triggers and the scripts; each script's code one tap away, as on the Scripts panel.
+    const terms = plan === null ? "" : (plan.parts.about === null ? "" : `<p>${e(plan.parts.about)}</p>`) +
+        `<p class="flow-untrusted">Its instructions come from the file, not from you: read what each step is asked before you import.</p>` +
+        list(plan.parts.steps) +
+        (plan.parts.triggers.length === 0 ? "" : `<h2>Triggers</h2>${list(plan.parts.triggers)}`) +
+        (plan.parts.scripts.length + plan.parts.kept.length === 0 ? "" : `<h2>Scripts</h2><ul class="flow-terms">${plan.scripts.add.map((one, index) => `<li>${e(plan.parts.scripts[index])}${one.body === undefined ? "" : `<details><summary>Show the script</summary><pre>${e(one.body)}</pre></details>`}</li>`).join("")}${plan.parts.kept.map(one => `<li>${e(one)}</li>`).join("")}</ul>`) +
+        `<h2>Good to know</h2>${list([...plan.parts.notes, ...(plan.parts.needs === null ? [] : [plan.parts.needs])])}`;
+    return `<section class="flows flow-import-preview">${input.problem === null ? "" : `<p class="problem" role="alert">${e(input.problem)}</p>`}` +
+        `<p class="meta">Into ${e(projectName(input.repo))}. Nothing is made until you import it.</p>${terms}` +
+        `<form method="post" action="/flows/import" class="card"><input type="hidden" name="csrf" value="${e(input.csrf)}"><input type="hidden" name="repo" value="${e(input.repo)}"><input type="hidden" name="previewed" value="${e(input.previewed)}"><textarea name="document" hidden>${e(input.document)}</textarea>` +
+        (fields === "" ? "" : `<fieldset class="flow-import-fields"><legend>Fill in</legend>${fields}</fieldset>`) +
+        `<p class="flow-buttons">${plan === null ? "" : '<button name="confirm" value="yes" class="primary">Import flow</button>'}${fields === "" ? "" : `<button name="confirm" value="" class="${plan === null ? "" : "secondary"}">Update preview</button>`}<a href="/flows">Cancel</a></p></form></section>`;
 }
 const historyText = (event, title, sorts = new Set()) => {
     const who = event.actor === "flow" ? "" : ` by ${event.actor}`;
@@ -154,7 +179,7 @@ export function flowView(store, flow, viewer, selectedCard, setup = { dir: null,
         tools: projectToolsOf(store, flow.repo).map(tool => ({ name: tool.name, about: tool.spec.about, functions: tool.lastTest?.ok === true ? tool.lastTest.tools : [],
             ready: toolStanding(tool, secretsSetFor(flow.repo, tool.spec, setup.toolHome)).ready })),
         scripts: store.flowScripts(flow.repo).map(script => ({ name: script.name, about: script.about, body: script.body, timeoutMinutes: script.timeoutMinutes, version: script.version, savedBy: script.savedBy, savedAt: script.savedAt,
-            language: script.language, file: script.file,
+            language: script.language, file: script.file, held: script.held !== null,
             usedHere: stages.filter(stage => stage.kind === "check" && stage.script === script.name).map(stage => stage.title) })),
         start: definition?.start ?? stages[0]?.id ?? "",
         stages,

package/dist/guides.js

@@ -79,6 +79,27 @@ ${AUTHORITY_LINE}
     detail says why; \`toolroll sync\` refreshes trackers.
   - \`contest-open\`: a tournament is running on the task; a person picks.
 
+## Acting as the lead
+
+When you are the person's lead, act under your own identity, never their
+login, so your housekeeping never pings them.
+
+- The person mints it once, behind their password: \`toolroll lead token\`
+  (\`--revoke\` ends it). Pass it on every task, assignment and status
+  command as \`--token <lead token>\`, or set \`TOOLROLL_LEAD_TOKEN\`. It
+  signs in as them; the ledger records you as "lead for <owner>", and the
+  console shows "by the lead".
+- Your work pings nobody: tasks you file, approve, cancel or complete stay
+  on the console and in the evening digest. A person hears about them only
+  when you hand one over, when it fails with nothing left for you to try,
+  or for a security alert.
+- Hand a task to a person: \`task ask <id> --person <name> --why "<what
+  they need to do>"\` — one message, and the task is theirs from then on.
+- Re-filing (a release check re-gated as \`release-<name>b\`): \`task add
+  "<title>" --id <new> --replaces <old>\`, or \`task state <old> cancelled
+  --replaced-by <new>\`. The old task reads "Replaced by <new>", never
+  "Cancelled".
+
 ## Complete, pull request, merge
 
 The console's Complete and Merge, from a terminal. Both are a person's
@@ -122,7 +143,9 @@ applies the console's rules exactly.
 ## What you may never do
 
 - Never approve scopes, answer decisions, or acquire approver tokens —
-  those acts belong to a person, through their own ceremony.
+  those acts belong to a person, through their own ceremony. A lead
+  approves only under the lead token its person minted for it, and never
+  with the person's own password or remembered login.
 - Never steer a task: \`task steer\` takes the operator's credential,
   because a steering note speaks in an agent's brief WITH THE OPERATOR'S
   VOICE (see the \`steering\` guide).
@@ -311,7 +334,9 @@ ${AUTHORITY_LINE}
   their cards appear under "proposed by coordinators".
 - **settings** (\`/settings\`): alerts to this device, provider keys,
   which messaging service pages, the Telegram bot token, and the Telegram
-  digest cadence (away mode).
+  digest cadence (away mode). Notifications → Projects mutes one project's
+  pings (\`toolroll notifications mute|unmute --repo <p>\`); it still shows
+  in Tasks and the evening digest.
 - The rail is four rows — inbox · board · builds · projects — and a
   **more** group: portfolio, task list, fleet, routines, system,
   requirements, people, operating mode, settings. On a phone the same

package/dist/invoke.js

@@ -646,6 +646,11 @@ export async function invokeHeldAgent(store, runId, spec, argv, options) {
                 store.recordRunProcess(runId, pid, clock(), false, heldWitness);
                 runOptions.onSpawn?.(pid);
             },
+            onSpawnFailed: () => {
+                if (heldWitness !== undefined)
+                    store.finishUnspawnedProcess(heldWitness, clock());
+                runOptions.onSpawnFailed?.();
+            },
             onContainer: info => {
                 nativeHeld = true;
                 if (heldWitness !== undefined)

package/dist/lead-context.js

@@ -46,9 +46,13 @@ export function leadBriefHtml(brief) {
         // it says what the person or the crew is doing next.
         const quiet = group.title === 'Finished';
         // A state chip that repeats its group's heading says nothing new.
-        const stateChip = (state) => { const words = STATE_WORDS[state] ?? state; return words === group.title ? '' : `<span class="lead-brief-state lead-brief-state--${state}">${escape(words)}</span>`; };
+        const stateChip = (state, detail) => {
+            // Replaced, never "Cancelled".
+            const words = state === 'cancelled' && /^Replaced by \S+/.test(detail ?? '') ? detail.replace(/\.$/, '') : STATE_WORDS[state] ?? state;
+            return words === group.title ? '' : `<span class="lead-brief-state lead-brief-state--${state}">${escape(words)}</span>`;
+        };
         return [`<section><h3>${group.title}</h3><ul>${entries.map(one => `<li><a href="/chat?task=${encodeURIComponent(one.rootId)}">${escape(one.title)}</a>` +
-                stateChip(one.state) +
+                stateChip(one.state, one.detail) +
                 (quiet ? '' : `<span class="lead-brief-detail">${escape(publicChatText(one.detail || one.outcome || '', 160))}</span>`) + `</li>`).join('')}</ul></section>`];
     });
     return `<section class="lead-brief" aria-label="Project catch-up"><h2>Catch up</h2>${sections.length ? sections.join('') : '<p class="meta">Nothing needs you right now.</p>'}${brief.assignments.length > 3 || brief.omissions.candidateScanLimited || brief.omissions.assignments > 0 ? '<a href="/work">See all tasks</a>' : ''}</section>`;

package/dist/mate-doors.d.ts

@@ -1,19 +1,4 @@
 import { type SharedActionOptions } from './chat-actions.js';
-/**
- * The confirm doors (mate arc §2, ruling 7; v3 §9): a pending proposal —
- * the mate's, or a coordinator's over the gateway — becomes an act only
- * here, as the operator's own act through the plane's existing
- * primitives, in ONE transaction that re-proves everything the card was
- * rendered under. The console and the CLI both call these; the HTTP edge
- * adds csrf and the cookie, the CLI adds the password — neither adds
- * authority the door does not check itself.
- *
- * The door's answer is typed and rendered on the card: `done` with the
- * plain words of what happened, or `refused` with the reason the primitive
- * gave. A stale proposal (the queue moved, the hold changed hands, the
- * scope was rewritten, the decision answered) is a refusal, never a
- * silent re-read.
- */
 import { type CoordinatorProposal, type MateProposal, type Store } from "./store.js";
 import type { VerifiedApprover } from "./principal.js";
 export type ProposalKind = MateProposal["kind"];

package/dist/mate-doors.js

@@ -14,6 +14,7 @@ import { executeSharedAction, sharedActionPayload, sharedActionAllowsChallenge,
  * scope was rewritten, the decision answered) is a refusal, never a
  * silent re-read.
  */
+import { isCheckLevel, setTaskCheckLevel } from "./check-levels.js";
 import { verifiedAuthor } from "./store.js";
 import { isVerifiedApprover, reproveApprover } from "./principal.js";
 import { TeamLeads } from './team-leads.js';
@@ -253,6 +254,9 @@ function executeProposal(store, actor, kind, payload, now, options) {
         }, now);
         if (!filed.ok)
             return refuse("refused", `not filed: ${filed.message}`);
+        const checks = payload["checks"];
+        if (isCheckLevel(checks))
+            setTaskCheckLevel(store, filed.id, checks, actor.name, now);
         return {
             ok: true,
             kind,
@@ -302,7 +306,7 @@ function executeProposal(store, actor, kind, payload, now, options) {
     if (kind === "task_action") {
         // An attended surface (the console, the paired phone) honours the
         // operator's own automatic-approval mode; the CLI keeps its ceremony.
-        const result = applyChatTaskAction(store, actor, payload, now, options.via !== "cli", { held: options.held, deferSignal: options.deferSignal, via: options.via });
+        const result = applyChatTaskAction(store, actor, payload, now, options.via !== "cli", { held: options.held, deferSignal: options.deferSignal, via: options.via, ...(options.evidenceRoot === undefined ? {} : { evidenceRoot: options.evidenceRoot }) });
         return result.ok ? { ok: true, kind, taskId: result.taskId, said: result.said } : refuse("stale", result.message);
     }
     if (kind === "review") {

package/dist/mate-tools.js

@@ -1,4 +1,5 @@
 import { connectionsOf, oneClickOf } from "./mcp-connect.js";
+import { checkLevelFromWords, isCheckLevel } from "./check-levels.js";
 import { policyParts } from "./policy.js";
 import { randomUUID } from 'node:crypto';
 import { dirname, join } from 'node:path';
@@ -451,7 +452,7 @@ export const MATE_TOOLS = [
     },
     {
         name: "propose_task_action",
-        description: "Propose stop/resume/retry/plan/wait_for/stop_waiting for currentExecution. Stop/resume needs get_task control.run; resume requires password review.",
+        description: "Propose stop/resume/retry/plan/wait_for/stop_waiting/run_checks/run_full_checks/add_tests for currentExecution. Stop/resume needs get_task control.run; resume requires password review. run_checks and run_full_checks check the latest result's exact commit; add_tests files a task to write tests for it.",
         inputSchema: schema({ task: TASK_ARG, operation: { type: "string", enum: Object.keys(CHAT_TASK_ACTIONS) }, dependency: TASK_ARG, run: { type: "integer", minimum: 1 } }, ["task", "operation"]),
         handle: (ctx, args) => {
             const task = taskIdOf(args), operation = args["operation"];
@@ -1439,8 +1440,8 @@ export const MATE_TOOLS = [
     },
     {
         name: "propose_task",
-        description: "Draft inferred title/goal/criteria. report:true investigates without code; planning required plans first, skip needs explicit direct-build request, auto is default.",
-        inputSchema: schema({ repo: REPO_ARG, title: { type: "string", maxLength: 200 }, goal: TASK_SCOPE_TEXT_SCHEMA, not: TASK_SCOPE_TEXT_SCHEMA, touches: { type: "array", items: { type: "string", maxLength: 200 }, maxItems: 50 }, acceptance: ACCEPTANCE_ARG_SCHEMA, planning: { type: "string", enum: ["auto", "required", "skip"] }, report: { type: "boolean" } }, ["repo", "title", "goal", "acceptance"]),
+        description: "Draft inferred title/goal/criteria. report:true investigates without code; planning required plans first, skip needs explicit direct-build request, auto is default. checks only when the person asked: off for \"skip the tests\", full for \"run the full checks\", quick for quick checks; omit to use the project's setting.",
+        inputSchema: schema({ repo: REPO_ARG, title: { type: "string", maxLength: 200 }, goal: TASK_SCOPE_TEXT_SCHEMA, not: TASK_SCOPE_TEXT_SCHEMA, touches: { type: "array", items: { type: "string", maxLength: 200 }, maxItems: 50 }, acceptance: ACCEPTANCE_ARG_SCHEMA, planning: { type: "string", enum: ["auto", "required", "skip"] }, report: { type: "boolean" }, checks: { type: "string", maxLength: 80 } }, ["repo", "title", "goal", "acceptance"]),
         handle: (ctx, args) => {
             const repo = repoPathOf(ctx.who, args["repo"]);
             if (repo === null)
@@ -1467,7 +1468,11 @@ export const MATE_TOOLS = [
             if (args["report"] !== undefined && typeof args["report"] !== "boolean")
                 return { ok: false, message: "report is true or false" };
             const report = args["report"] === true;
-            const id = ctx.draft("task", { repo, repoId: args["repo"], title: args["title"], goal: args["goal"], not, touches, acceptance, planning, report });
+            // A level, or the person's own words ("skip the tests", "run the full checks").
+            const checks = args["checks"] === undefined ? null : isCheckLevel(args["checks"]) ? args["checks"] : typeof args["checks"] === "string" ? checkLevelFromWords(args["checks"]) : null;
+            if (args["checks"] !== undefined && checks === null)
+                return { ok: false, message: "checks is quick, full or off" };
+            const id = ctx.draft("task", { repo, repoId: args["repo"], title: args["title"], goal: args["goal"], not, touches, acceptance, planning, report, ...(checks === null || report ? {} : { checks }) });
             if (id === null)
                 return tooMany();
             return { ok: true, body: { proposal: id, kind: "task", repo: args["repo"], deliverable: report ? "report" : "branch", planning: report ? "not needed for a scout" : planning, awaiting: "the operator's confirmation" } };

package/dist/models-ui.js

@@ -53,7 +53,7 @@ export function modelsHtml(view) {
         fresh +
         `<h2>Default agents</h2><p class="meta">New tasks use these. Approved tasks keep the agents they were approved with.</p>` +
         view.roles.map(role => roleForm(role, manage, view.csrf)).join("") +
-        (view.chat === null ? "" : `<h2>Chat</h2><p>${e(view.chat.words)} · <a href="/chat?settings=1#chat-settings">Change</a></p>`) +
+        (view.chat === null ? "" : `<h2>Chat</h2><p>${e(view.chat.words)} · <a href="/settings/lead">Change</a></p>`) +
         watch + `</section>`;
 }
 /** Filters one long picker as you type; the saved choice always stays listed. */

package/dist/modes.d.ts

@@ -29,7 +29,9 @@ export type ModeTerms = {
     planAuto: boolean;
     /** Attended mint without the per-mint password — signer only (D8). */
     quickMint: boolean;
-    /** Historical signed field; new modes leave it false and no worker consumes it. */
+    /** Historical signed field; new modes leave it false and no worker consumes
+     * it. Automatic review is the project's review switch (review-switch.ts),
+     * on by default while a hands-off mode is active. */
     reviewAuto: boolean;
     /** Historical signed retry term, retained for digest and audit compatibility. */
     reviewRetryAuto: boolean;

package/dist/modes.js

@@ -157,7 +157,9 @@ export function modeWords(terms) {
         terms.planAuto
             ? "plans for your pre-authorized filings auto-approve only when the goal, exclusions, paths, acceptance criteria, risk, budget, and agent route remain exactly unchanged; provide a goal, paths and acceptance criteria upfront; amendments and unresolved questions still wait for you"
             : "planner-generated plans wait for your approval",
-        "finished work and saved checks go to the lead or user; no separate model review runs",
+        terms.name === "hands-off"
+            ? "automatic review is on for this project unless you turn it off (`toolroll review off --repo <path>`): each finished build whose check passes (or that finishes, with checks Off) gets one read-only review by the project's review agent; a HIGH finding sends it back once as a revision filed under this mode, a HIGH on that revision comes to you, MEDIUM and LOW findings come to you as suggested follow-ups, and a review that fails or times out never holds the work — it reaches you marked not reviewed"
+            : "finished work and saved checks go to the lead or user; automatic review runs only where a project turns it on (`toolroll review on --repo <path>`)",
         ...(terms.reviewAuto || terms.reviewRetryAuto
             ? ["historical review grants are retained on record but no longer schedule work"] : []),
         terms.perAttemptBudgetMicrousd === null

package/dist/operate.d.ts

@@ -2,6 +2,7 @@ import { type IntegrationIo } from "./integrations.js";
 import { type OnboardIo } from "./agent-onboard.js";
 import { type TriggerIo } from "./flow-triggers.js";
 import { type StepIo } from "./flow-steps.js";
+import type { FetchLike } from "./flow-share.js";
 import { type Store } from "./store.js";
 import { type DispatchAdapter } from "./sync.js";
 import { type TelegramTransport } from "./telegram.js";
@@ -56,6 +57,8 @@ export type OperateOptions = {
     flowTriggerIo?: Partial<TriggerIo>;
     /** Injected by tests: how flow check and update steps run commands and reach GitHub and Linear. */
     flowStepIo?: Partial<StepIo>;
+    /** Injected by tests: how `flows import` fetches a flow file's address. */
+    flowFetch?: FetchLike;
     /** Injected by tests: how `integrations` checks reach services (fetch, gh, sign-in checks, mail servers). */
     integrationIo?: Partial<IntegrationIo>;
     /** Injected by tests: the mate's provider fetch, key environment, and stdin lines. */
@@ -91,7 +94,7 @@ type Args = {
  * exports are behavior, not commentary — and the declared command guide
  * (surface.ts) is tested for exact equality against them.
  */
-export declare const TASK_ACTIONS: readonly ["add", "list", "show", "wait", "state", "block", "unblock", "next", "steer", "assign", "reopen", "scope", "approve", "hold", "unhold", "require", "requeue", "regate", "plan", "review", "accept", "repair", "route", "stop", "resume", "complete", "revise", "merge"];
+export declare const TASK_ACTIONS: readonly ["add", "list", "show", "wait", "state", "block", "unblock", "next", "steer", "assign", "reopen", "scope", "approve", "hold", "unhold", "require", "requeue", "regate", "plan", "review", "accept", "repair", "route", "stop", "resume", "complete", "revise", "merge", "ask", "checks", "add-tests"];
 export declare const PUBLISH_ACTIONS: readonly ["setup", "grant", "revoke", "status", "unblock", "rearm", "merge", "refire"];
 export declare const CONFIG_ACTIONS: readonly ["show", "set", "clear"];
 export declare const APPROVER_ACTIONS: readonly ["list", "add"];