toolroll 0.9.88 → 0.9.90

package/dist/server/tasks.js

@@ -1,3 +1,4 @@
+import { titleWithin } from "../task-text.js";
 import { parseFeedbackImage, sameFeedbackImage } from "../result-review.js";
 import { archiveTaskFamily, dropFeedbackImage, releaseAuthorityOfTask, restoreTaskFamily, revokeRelease, runLiveCommands } from "../store.js";
 import { applyTidy, approverStandsNow, familyRepoOf, releaseFactsOf, tidyDays, tidyDigest, tidyPreview, TIDY_DEFAULT_DAYS } from "../tidy.js";
@@ -58,14 +59,14 @@ import { structuredHandoffView, terminalDiffView } from "../result-evidence-read
 import { fileAddTestsTask, requestFollowUpChecks } from '../result-follow-ups.js';
 import { commentSourceKey, isRevisionFeedback, parseResultTab, resultReturnTarget } from "../result-review.js";
 import { isAlive as runnerAlive } from "../runner.js";
-import { passwordlessSessionFor, acceptanceLinesToInput, acceptanceToLines, approvalOf, approve as approveScope, freshnessFor, spendingOnlyOnSuccess, ssoNowAvailable, withFreshness, modeFilingCoverage, PLACEHOLDER_RUBRIC, proposeGuarded } from "../scope.js";
+import { passwordlessSessionFor, acceptanceLinesToInput, acceptanceToLines, approvalOf, approve as approveScope, freshnessFor, localApprovalEligible, spendingOnlyOnSuccess, ssoNowAvailable, withFreshness, modeFilingCoverage, PLACEHOLDER_RUBRIC, proposeGuarded } from "../scope.js";
 import { subagentNames as subagentNamesOf } from "../spend.js";
 import { verifiedAuthor } from "../store.js";
 import { runCostWords } from "../summary.js";
 import { requestTaskStop, resumeTaskStop } from "../task-control.js";
 import { templateByName } from "../templates.js";
 import { TEXT_LIMITS } from "../text-limits.js";
-import { agentQuestion, answerAgentQuestion, markAgentSeen } from "../agent-board.js";
+import { AGENT_VIEW_ID, agentQuestion, answerAgentQuestion, holdOwnAgentView, markAgentSeen, releaseOwnAgentView } from "../agent-board.js";
 import { WorkIndexCursorError, workIndexPage } from "../work-index.js";
 import { buildProgressOf, parseWorkView } from "../workspace-ui.js";
 import { requestContext } from "./request-context.js";
@@ -573,10 +574,8 @@ export function createTasksHandlers(runtime) {
             return sendScreen(response, 409, screen("Result changed", html `<h1>Result changed</h1><p>This acceptance link no longer matches the current result. Review the current task before accepting.</p><p class="refusal-back"><a class="button-link" href="/review">Review results</a></p>`, { chrome: chromeFor(project, "runs") }));
         }
         const selected = picked !== null ? picked.selected : selectedRow === null ? null : reviewCockpitViewOf(selectedRow, who, now);
-        // Opening a run's own result page is viewing it: it leaves this person's unread Done on the Agents board — but only
-        // once the run has finished (cockpit §3): a page shown while it was still running saw no finished version.
-        if (wantedId !== null && selected?.run != null && store.getRun(selected.run.id)?.finishedAt != null)
-            markAgentSeen(store, who.name, selected.run.id, now);
+        // Opening a run's own result page is viewing it: the shell says so with a keyed POST /agents/seen (easy-start N1:
+        // a page load never writes), which leaves this person's unread Done once the run has finished.
         const reviewPage = reviewCockpitPage(chromeFor(wantedId === null ? project : chosenProject, "runs"), {
             queue: ranked,
             queueCap: REVIEW_QUEUE_CAP,
@@ -1004,7 +1003,11 @@ export function createTasksHandlers(runtime) {
             }
         }
         const id = (body.get("id") ?? "").trim();
-        const title = body.get("title") ?? "";
+        // The New task box stops at a title's length (render-new-task.ts): the title is all the planner reads of a no-goal
+        // filing. A direct POST longer than that is cut at a whole word, with an ellipsis (task-text.ts titleWithin), as a
+        // belt; a refusal keeps the person's own words (the draft below).
+        const typed = body.get("title") ?? "";
+        const title = titleWithin(typed);
         // The EFFECTIVE placement (repo onboarding, findings 15/35): the
         // trimmed, nonempty posted repo, else the open project — an empty
         // input falls through correctly. In root mode the effective path is
@@ -1021,7 +1024,7 @@ export function createTasksHandlers(runtime) {
         // direct POST with no project open must not mint an unplaced task
         // under a ceiling. Unscoped mode keeps its historic unplaced filings.
         // A refusal from here on is the add page again with the person's own words (the old task list kept them too).
-        const draft = { title, goal: body.get("goal") ?? "", not: body.get("not") ?? "", touches: body.get("touches") ?? "", acceptance: body.get("acceptance") ?? "", values: body.sent };
+        const draft = { title: typed, goal: body.get("goal") ?? "", not: body.get("not") ?? "", touches: body.get("touches") ?? "", acceptance: body.get("acceptance") ?? "", values: body.sent };
         if (!unscopedMode && effective === "") {
             return newTaskScreen(ctx, 400, "name a repository — no project is open, so the task must say where it belongs", draft);
         }
@@ -2473,7 +2476,9 @@ export function createTasksHandlers(runtime) {
                 }
                 // An empty password stands for an explicit identity-provider re-check not yet spent, or (cockpit B2) a password
                 // remembered on this session; approve() decides whether these terms may stand on a remembered one.
-                if (token === "" && !passwordlessSessionFor(store, who.name) && !ssoNowAvailable(who.name) && withFreshness("approve-standard", () => freshnessFor(who.name)) === null) {
+                // Easy-start C5: a laptop's local owner approves eligible work with no password (approve() proves it again).
+                if (token === "" && !passwordlessSessionFor(store, who.name) && !ssoNowAvailable(who.name) && withFreshness("approve-standard", () => freshnessFor(who.name)) === null
+                    && !(who.authority === "local-owner" && localApprovalEligible(store, who.name, taskId).ok)) {
                     return approvalProblem("approval requires your password, typed again", 400);
                 }
                 const scopeRow = store.getScope(taskId);
@@ -3087,6 +3092,7 @@ export function createTasksHandlers(runtime) {
     }
     const registrations = handlersOf("tasks", {
         ...tidyHandlers,
+        ...createAgentSignalHandlers(runtime),
         "code.page": showCode("workspace"),
         "code.session": showCode("session"),
         "code.state": showCode("state"),
@@ -3261,3 +3267,47 @@ export function retiredTasksAddress(route, url) {
 }
 /** How many cards a Board column shows; the column's count covers them all and its "View all" opens the list. */
 export const BOARD_COLUMN_LIMIT = 40;
+/**
+ * Easy-start C1 (N1): the two writes a page load used to make, as keyed POSTs the shell sends (wave 1c wires the
+ * browser). `agents.seen`: a finished result this person opened leaves their unread Done. `agents.watch`: hold (on each
+ * keep-alive) or release (on unload) the short lease that quiets chat pings while this person's page shows the agent.
+ * Each re-proves the run is in the person's projects; a reply carries nothing else.
+ */
+export function createAgentSignalHandlers(runtime) {
+    const { store, runVisible } = runtime;
+    const answer = (response, status, ok) => respond(response, status, "application/json", JSON.stringify({ ok }));
+    const visibleRun = (who, raw) => {
+        const id = raw !== null && /^[1-9][0-9]{0,14}$/.test(raw) ? Number(raw) : null;
+        const run = id === null ? null : store.getRun(id);
+        const repo = run === null ? null : store.refForId(run.taskRef)?.repo ?? null;
+        return run === null || !runVisible(run) || !store.accountCanAccess(who.name, repo) ? null : run;
+    };
+    async function agentSeen(ctx) {
+        const { who, response, now, posted } = ctx;
+        const run = visibleRun(who, readForm(posted, CONSOLE_FORMS.agentSeen).get("run"));
+        if (run === null)
+            return answer(response, 404, false);
+        // Only once it finished: a page shown while it ran saw no finished version (cockpit §3).
+        if (run.finishedAt === null)
+            return answer(response, 409, false);
+        markAgentSeen(store, who.name, run.id, now);
+        return answer(response, 200, true);
+    }
+    async function agentWatch(ctx) {
+        const { who, response, now, posted } = ctx;
+        const body = readForm(posted, CONSOLE_FORMS.agentWatch);
+        const view = body.get("view") ?? "", op = body.get("op");
+        if (!AGENT_VIEW_ID.test(view) || (op !== "hold" && op !== "release"))
+            return answer(response, 400, false);
+        if (op === "release") {
+            releaseOwnAgentView(store, view, who.name, now);
+            return answer(response, 200, true);
+        }
+        const run = visibleRun(who, body.get("run"));
+        if (run === null)
+            return answer(response, 404, false);
+        const held = holdOwnAgentView(store, view, who.name, run.id, now);
+        return answer(response, held ? 200 : 409, held);
+    }
+    return { "agents.seen": agentSeen, "agents.watch": agentWatch };
+}

package/dist/server/terminals.js

@@ -17,6 +17,7 @@
 import { randomBytes } from "node:crypto";
 import { STATUS_CODES } from "node:http";
 import { dirname, join } from "node:path";
+import { KEY_PROTOCOL } from "./mutation-key.js";
 import { WebSocketServer } from "ws";
 import { readForm, CONSOLE_FORMS } from "../contracts/console-api.js";
 import { html, htmlString } from "../html.js";
@@ -55,9 +56,14 @@ export function createTerminalHandlers(runtime, deps) {
     const transportOfRequest = (request) => transportOf({ peer: request.socket.remoteAddress, joinSource: deps.forwardedSourceOf(request),
         forwardedProto: request.headers["x-forwarded-proto"], forwarded: request.headers["forwarded"] });
     const sockets = new Set();
-    const wss = new WebSocketServer({ noServer: true, maxPayload: MAX_FRAME_BYTES, perMessageDeflate: false });
+    // Easy-start C2: a page offers `toolroll` and, on a protected loopback install, `toolroll.key.<key>`; only `toolroll` is
+    // ever selected, so the key is never echoed.
+    const wss = new WebSocketServer({ noServer: true, maxPayload: MAX_FRAME_BYTES, perMessageDeflate: false,
+        handleProtocols: protocols => protocols.has(KEY_PROTOCOL) ? KEY_PROTOCOL : false });
     /** An operator signed in with a browser, of the generation they signed in with; else null. */
-    const operatorOf = (who) => who?.via === "cookie" && who.role === "approver" && !store.isDemo() && codingActorAllowed({ name: who.name, generation: who.session.generation }) ? who : null;
+    const operatorOf = (who) => 
+    // Easy-start C1: never a local owner's session (a laptop's passwordless owner), for a new terminal or an existing one.
+    who?.via === "cookie" && who.authority === "full" && who.role === "approver" && !store.isDemo() && codingActorAllowed({ name: who.name, generation: who.session.generation }) ? who : null;
     /** The project a terminal works in is one the coding workspace admits for this person, now. */
     const projectAllowed = (name, repo) => rowVisible(liveCeiling(), repo) && store.accountCanAccess(name, repo) && codingProjectAllowed(repo);
     const owned = (who, terminal) => terminal !== null && terminal.owner === who.name && terminal.generation === who.session.generation;
@@ -232,6 +238,13 @@ export function createTerminalHandlers(runtime, deps) {
             refuseUpgrade(socket, 401, "Sign in as an installation-wide operator.");
             return true;
         }
+        // Easy-start C2: typing into a terminal is a mutation: on a protected loopback install the socket offers the session's
+        // key (its protocol list), which a cookie holder on another port can't read.
+        const keyed = runtime.browserKeys.check(who, request, null);
+        if (keyed !== null) {
+            refuseUpgrade(socket, keyed.status, keyed.message);
+            return true;
+        }
         const terminal = deps.host?.get(id) ?? null;
         if (!owned(who, terminal) || !projectAllowed(who.name, terminal.repo)) {
             refuseUpgrade(socket, 404, "No such terminal.");

package/dist/server/welcome.d.ts

@@ -1,22 +1,28 @@
-import { type FirstRunStep } from "../first-run.js";
-import { type CheckStep } from "./kit.js";
-import type { ServerRuntime } from "./runtime.js";
+import { type WelcomeModel } from "../first-run.js";
+import { type Html } from "../html.js";
 import { type Chrome, type Screen } from "./chrome.js";
-export type WelcomeFacts = {
-    steps: readonly FirstRunStep[];
-    projects: number;
-    /** This person has a live push enrollment on some device. */
-    alerts: boolean;
+import type { ServerRuntime } from "./runtime.js";
+/** Why the sample project wasn't added, as a fixed key in the address (never words from it). */
+export declare const SAMPLE_PROBLEMS: {
+    readonly "no-root": "There's no project folder to put the sample in. Add a folder instead.";
+    readonly exists: "A folder named toolroll-sample is already there and wasn't made here, so nothing was changed.";
+    readonly failed: "The sample project couldn't be made. Nothing was added. Try again, or add a folder instead.";
+    readonly "not-added": "The sample project was made but couldn't be added. Try again, or add it from Projects.";
 };
-/** The five steps as the page shows them, and which one leads. */
-export declare function welcomeSteps(facts: WelcomeFacts): {
-    steps: CheckStep[];
-    primary: {
-        label: string;
-        href: string;
-    } | null;
+export type SampleProblem = keyof typeof SAMPLE_PROBLEMS;
+/** The page body for one model, and the screen's one primary (for the phone dock). `problem`: why the sample project
+ * wasn't added, from the address. `canAdd`: this person may add projects here. */
+export declare function welcomeBody(model: WelcomeModel, options: {
+    problem?: SampleProblem | null;
+    canAdd: boolean;
+}): {
+    body: Html;
+    primary: Html | null;
 };
-export declare function welcomePage(chrome: Chrome, facts: WelcomeFacts): Screen;
+export declare function welcomePage(chrome: Chrome, model: WelcomeModel, options: {
+    problem?: SampleProblem | null;
+    canAdd: boolean;
+}): Screen;
 export declare function createWelcomeHandlers(runtime: ServerRuntime): {
     registrations: import("./handler-registry.js").Registration[];
 };

package/dist/server/welcome.js

@@ -1,69 +1,167 @@
 /**
- * The first run's own page, /welcome (Wave E, src/design/KIT.md): five guided steps to a first result, each derived
- * from live facts on every render (never a stored cursor), each with the one action that does it. The next required
- * step's action is the screen's one primary (on a fresh install: Add a project); alerts on the phone are optional and
- * never lead. It only reads: every step's action is a link to the page that does it. Once the first result has
- * arrived (or for a project-limited account, or in the demo) the first run is over and the address leads Home.
+ * The first run's own page, /welcome (src/design/KIT.md): three steps to a first result, Agent · Project · First task,
+ * told by first-run.ts's one model (welcomeModel) from live facts on every render, never a stored cursor. The page
+ * reads; its acts are the ones that already own each change: choosing the agent posts to Settings → Lead's own
+ * turn-on (/settings/lead/on), a folder and GitHub link to Projects, and the sample project is made and added here
+ * (POST /welcome/sample) the way Projects adds a folder (project-admission.ts). A first task's starter only drafts its
+ * words into New task's box: nothing is filed until the person sends it. Once the first result has arrived (or for a
+ * project-limited account, or in the demo) the address leads Home.
  */
+import { resolvePhaseAgent } from "../agentconfig.js";
+import { CONSOLE_FORMS, readForm } from "../contracts/console-api.js";
 import { builderReadyFor, firstRunBuilderRepo } from "../dispatch.js";
-import { withBuilderStep } from "../first-run.js";
-import { html } from "../html.js";
+import { firstTaskSuggestions, SAMPLE_FIRST_TASKS, SAMPLE_PROJECT_NAME, welcomeModel, withBuilderStep } from "../first-run.js";
+import { html, joinHtml, postForm } from "../html.js";
 import { START_BUILDER_HREF } from "../needs-you.js";
+import { admitProject } from "../project-admission.js";
+import { authorizedProject } from "../project.js";
+import { createSampleProject, registerSampleCheck } from "../sample-project.js";
+import { refuse, screen } from "./chrome.js";
 import { handlersOf } from "./handler-registry.js";
 import { redirect } from "./http.js";
-import { btn, checklist, dock, pageHeader } from "./kit.js";
-import { screen } from "./chrome.js";
+import { btn, chip, codeLine, dock, note, notice, pageHeader, settingsRecord } from "./kit.js";
+/** Why the sample project wasn't added, as a fixed key in the address (never words from it). */
+export const SAMPLE_PROBLEMS = {
+    "no-root": "There's no project folder to put the sample in. Add a folder instead.",
+    exists: `A folder named ${SAMPLE_PROJECT_NAME} is already there and wasn't made here, so nothing was changed.`,
+    failed: "The sample project couldn't be made. Nothing was added. Try again, or add a folder instead.",
+    "not-added": "The sample project was made but couldn't be added. Try again, or add it from Projects.",
+};
+const isSampleProblem = (value) => value !== null && Object.hasOwn(SAMPLE_PROBLEMS, value);
 const plural = (n, one, many) => `${n} ${n === 1 ? one : many}`;
-/** The five steps as the page shows them, and which one leads. */
-export function welcomeSteps(facts) {
-    const step = (key) => facts.steps.find(one => one.key === key);
-    const agent = step("agent"), builder = step("builder"), task = step("task");
-    const projectDone = facts.projects > 0;
-    const agentDone = (agent?.done ?? false) && (builder?.done ?? true);
-    const command = agent?.action?.kind === "command" ? agent.action.command : null;
-    const agentState = agentDone ? "done" : agent?.checking === true ? "checking" : "open";
-    const agentText = agentDone ? "An agent is signed in and a builder is ready."
-        : agent?.checking === true ? "Checking for a signed-in agent on this computer…"
-            : agent !== undefined && !agent.done && command !== null ? html `On the computer running Toolroll, run <code class="k-mono">${command}</code>.`
-                : "Start a builder so tasks can run.";
-    const agentLink = agentDone || agent?.checking === true ? null
-        : agent !== undefined && !agent.done ? { label: "Agent settings", href: "/settings/models" } : { label: "Start a builder", href: START_BUILDER_HREF };
-    const taskDone = task?.done ?? false;
-    // The next required step leads (alerts are optional and never do).
-    const order = [
-        { key: "project", open: !projectDone, link: { label: "Add a project", href: "/projects" } },
-        { key: "agent", open: agentState === "open", link: agentLink },
-        { key: "task", open: !taskDone && projectDone, link: { label: "New task", href: "/tasks/new" } },
-    ];
-    const lead = order.find(one => one.open && one.link !== null) ?? null;
-    const action = (key, link) => link === null ? null : btn(link.label, { sm: true, href: link.href, ...(lead?.key === key ? { variant: "primary", docked: true } : {}) });
-    const steps = [
-        { key: "password", title: "Your password", text: "You're signed in. Your first login is saved on the computer running Toolroll.", state: "done" },
-        { key: "project", title: "Add a project", text: projectDone ? plural(facts.projects, "project added.", "projects added.") : "A git repository agents work in.", state: projectDone ? "done" : "open", action: action("project", order[0].link) },
-        { key: "agent", title: "Agent and models", text: agentText, state: agentState, action: action("agent", agentLink) },
-        { key: "phone", title: "Alerts on your phone", text: facts.alerts ? "Alerts are on." : "Optional. Hear when something needs you.", state: facts.alerts ? "done" : "open", action: btn("Set up alerts", { sm: true, href: "/settings/alerts#this-device" }) },
-        { key: "task", title: "Your first task", text: taskDone ? "Filed. Its plan waits for your approval." : "Describe a change and approve its plan.", state: taskDone ? "done" : "open",
-            action: projectDone ? action("task", order[2].link) : null },
-    ];
-    return { steps, primary: lead?.link ?? null };
+const AGENT_WORDS = { "signed-in": "Signed in", "signed-out": "Not signed in", "not-installed": "Not installed", checking: "Checking…" };
+const PROJECTS_SHOWN = 3;
+const ADD_FOLDER = "/projects?return=%2Fwelcome";
+/** One step: its number and name, Done once it is, then its body. */
+function step(key, index, title, done, body) {
+    return html `<section class="k-sec welcome-step" id="welcome-${key}" data-step="${key}" data-done="${done ? "1" : "0"}" aria-labelledby="welcome-${key}-h">\
+<div class="k-secthead"><h3 id="welcome-${key}-h">${index}. ${title}</h3>${done ? chip("Done", "done") : ""}</div>${body}</section>`;
 }
-export function welcomePage(chrome, facts) {
-    const { steps, primary } = welcomeSteps(facts);
-    const left = steps.filter(one => one.state !== "done").length;
-    const body = html `${pageHeader("Welcome")}<div class="k-doc"><div class="k-hello"><h2>Get to your first result.</h2><p>${left === 0 ? "Setup is done." : `${plural(left, "step", "steps")} left.`}</p></div>\
-${checklist(steps, "Setup steps")}</div>${dock(primary === null ? null : btn(primary.label, { variant: "primary", href: primary.href }))}`;
-    return screen("Welcome", body, { chrome });
+/** "Use this one": Settings → Lead's own turn-on, for exactly this agent, back here. */
+const useForm = (agent, button) => postForm("/settings/lead/on", button, { hidden: { agent, return: "/welcome" } });
+function agentRow(agent, leads) {
+    const sub = agent.command === null ? AGENT_WORDS[agent.state]
+        : html `${AGENT_WORDS[agent.state]}. To sign in, run this on the computer running Toolroll:${codeLine(agent.command)}`;
+    const action = agent.inUse ? chip("In use", "", { dot: false })
+        : agent.canUse ? useForm(agent.id, btn("Use this one", { sm: true, type: "submit", ...(leads ? { variant: "primary", docked: true } : {}) }))
+            : "";
+    return settingsRecord({ title: agent.name, sub, action, attrs: { "data-agent": agent.id, "data-state": agent.state } });
 }
+/** The page body for one model, and the screen's one primary (for the phone dock). `problem`: why the sample project
+ * wasn't added, from the address. `canAdd`: this person may add projects here. */
+export function welcomeBody(model, options) {
+    const lead = model.next;
+    let primary = null;
+    const agentLead = lead === "agent" ? model.agent.agents.find(one => one.canUse) ?? null : null;
+    if (agentLead !== null)
+        primary = useForm(agentLead.id, btn(`Use ${agentLead.name}`, { variant: "primary", type: "submit" }));
+    const agentNote = model.agent.checking ? note("Checking for a signed-in agent on this computer…")
+        : !model.agent.done ? note("Sign in to one of these, then come back to this page.")
+            : model.agent.buildsWith !== null ? note(html `Tasks are built with ${model.agent.buildsWith}. <a class="k-link" href="/settings/models">Change</a>`) : "";
+    const agent = step("agent", 1, "Agent", model.agent.done, html `<p class="k-note">The AI coding agent that plans and builds your tasks.</p>\
+<div class="welcome-rows">${model.agent.agents.map(one => agentRow(one, agentLead?.id === one.id))}</div>${agentNote}`);
+    const projects = model.project.projects;
+    const listed = projects.slice(0, PROJECTS_SHOWN).map(one => settingsRecord({ title: one.name, sub: html `<span class="k-mono">${one.path}</span>`, attrs: { "data-project": "" } }));
+    const more = projects.length > PROJECTS_SHOWN ? note(html `And ${plural(projects.length - PROJECTS_SHOWN, "more project", "more projects")} in <a class="k-link" href="/projects">Projects</a>.`) : "";
+    const working = lead === "project" && model.project.notTakingWork;
+    const folderLeads = lead === "project" && !working;
+    const folderLabel = projects.length === 0 ? "Add a folder" : "Add another folder";
+    if (folderLeads)
+        primary = btn(folderLabel, { variant: "primary", href: ADD_FOLDER });
+    if (working)
+        primary = btn("Start taking work", { variant: "primary", href: START_BUILDER_HREF });
+    const adds = joinHtml([
+        model.project.notTakingWork ? btn("Start taking work", { sm: true, href: START_BUILDER_HREF, ...(working ? { variant: "primary", docked: true } : {}) }) : "",
+        btn(folderLabel, { sm: true, href: ADD_FOLDER, ...(folderLeads ? { variant: "primary", docked: true } : {}) }),
+        options.canAdd ? btn("From GitHub", { sm: true, href: "/projects/github" }) : "",
+        options.canAdd && model.project.sample !== null ? postForm("/welcome/sample", btn("Try a sample project", { sm: true, type: "submit" }), { attrs: { class: "welcome-form" } }) : "",
+    ]);
+    const projectLine = projects.length === 0 ? "A git repository on this computer for agents to work in."
+        : model.project.notTakingWork ? `${plural(projects.length, "project added", "projects added")}. Tasks can't start yet: this computer isn't taking work for them.`
+            : plural(projects.length, "project added.", "projects added.");
+    const sampleWhere = projects.length === 0 && options.canAdd && model.project.sample !== null
+        ? note(html `The sample is a tiny repository, made at <span class="k-mono">${model.project.sample}</span>.`) : "";
+    const project = step("project", 2, "Project", model.project.done, html `<p class="k-note">${projectLine}</p>\
+${listed.length === 0 ? "" : html `<div class="welcome-rows">${listed}</div>`}${more}${options.problem ? notice(SAMPLE_PROBLEMS[options.problem]) : ""}\
+<div class="k-acts welcome-acts">${adds}</div>${sampleWhere}`);
+    const taskLeads = lead === "task";
+    if (taskLeads)
+        primary = btn("Write a task", { variant: "primary", href: "/tasks/new" });
+    const taskBody = model.task.done ? html `<p class="k-note">Filed. Its plan waits for your approval in <a class="k-link" href="/work">Tasks</a>.</p>`
+        : !model.task.open ? html `<p class="k-note">Add a project first.</p>`
+            : html `<p class="k-note">Describe a change in a sentence or two. Nothing starts until you approve its plan.</p>\
+${model.task.starters.length === 0 ? "" : html `<div class="k-ideas" aria-label="Ideas to start from" data-starters>${model.task.starters.map(one => html `<a class="k-btn k-btn-outline k-idea" href="${one.href}">${one.label}</a>`)}</div>`}\
+<div class="k-acts">${btn("Write a task", { sm: true, href: "/tasks/new", ...(taskLeads ? { variant: "primary", docked: true } : {}) })}</div>`;
+    const task = step("task", 3, "First task", model.task.done, taskBody);
+    const hello = html `<div class="k-hello"><h2>Get to your first result.</h2><p>${model.left === 0 ? "Setup is done." : `${plural(model.left, "step", "steps")} left.`}</p></div>`;
+    return { body: html `${hello}${agent}${project}${task}`, primary };
+}
+export function welcomePage(chrome, model, options) {
+    const { body, primary } = welcomeBody(model, options);
+    return screen("Welcome", html `${pageHeader("Welcome")}<div class="k-doc welcome" data-welcome>${body}</div>${dock(primary)}`, { chrome });
+}
+const AGENT_OF = { "claude-subscription": "claude", "codex-subscription": "codex" };
 export function createWelcomeHandlers(runtime) {
-    const { store, sendScreen, chromeFor, firstRunStepsNow, managedRepos, visible } = runtime;
+    const { store, sendScreen, chromeFor, firstRunStepsNow, managedRepos, visible, liveCeiling, identities, deletedRepos, options, sessions } = runtime;
     async function showWelcome(ctx) {
-        const { who, response, now, project } = ctx;
+        const { who, response, now, project, url } = ctx;
         const steps = withBuilderStep(firstRunStepsNow(now), builderReadyFor(store, firstRunBuilderRepo(store, project, visible, managedRepos()), now));
         // The first run is over (a first result, a project-limited account, the demo): the address leads Home.
         if (steps === null)
             return redirect(response, "/");
-        const alerts = who.via === "cookie" && store.listPushSubscriptions(who.name).some(one => one.retiredAt === null);
-        return sendScreen(response, 200, welcomePage(chromeFor(project, "work"), { steps, projects: managedRepos().length, alerts }));
+        // The projects the sidebar lists (a sample added here included).
+        const chrome = chromeFor(project, "work");
+        const projects = (chrome.projects ?? []).map(one => ({ name: one.name, path: one.path }));
+        const repo = project ?? projects[0]?.path ?? null;
+        const root = liveCeiling().roots[0] ?? null;
+        const sample = root === null ? null : `${root.replace(/\/+$/, "")}/${SAMPLE_PROJECT_NAME}`;
+        const starters = repo === null ? [] : repo === sample ? SAMPLE_FIRST_TASKS : runtime.firstTasks.get(repo)?.found ?? firstTaskSuggestions({ issues: [], todos: [] });
+        const states = runtime.localSignIn?.states ?? null;
+        const build = resolvePhaseAgent(store, "build", repo, {});
+        const approver = who.via === "cookie" && who.role === "approver";
+        const model = welcomeModel({
+            agents: { claude: states?.claude ?? null, codex: states?.codex ?? null },
+            inUse: AGENT_OF[store.getChatConfig()?.provider ?? ""] ?? null,
+            buildsOn: build.ok ? build.spec.provider : null,
+            canChoose: approver,
+            projects, projectRoot: root,
+            ready: steps.find(one => one.key === "builder")?.done ?? false,
+            hasTask: steps.find(one => one.key === "task")?.done ?? false,
+            starters, platform: options.platform ?? process.platform,
+        });
+        const asked = url.searchParams.get("sample");
+        return sendScreen(response, 200, welcomePage(chrome, model, { problem: isSampleProblem(asked) ? asked : null, canAdd: approver && !store.isDemo() }));
+    }
+    /** Try a sample project: made in the project folder (or found again when it is ours), then added the way Projects
+     * adds a folder, and opened. A refusal comes back to the welcome as a fixed key. */
+    async function addSample(ctx) {
+        const { who, response, now, posted } = ctx;
+        readForm(posted, CONSOLE_FORMS.welcomeSample);
+        if (who.via !== "cookie")
+            return refuse(response, who, 403, "adding a project is a browser session's act");
+        if (store.isDemo())
+            return refuse(response, who, 403, "the sandbox never makes projects");
+        const back = (problem) => redirect(response, `/welcome?sample=${problem}#welcome-project`);
+        const made = await createSampleProject(liveCeiling().roots[0] ?? null);
+        if (!made.ok)
+            return back(made.reason);
+        // Added exactly as Projects adds a folder: inside what this console serves, visible to this person, a git repository.
+        const decidedOn = identities.generation();
+        const canonical = await identities.resolveNow(made.path);
+        if (canonical === null || canonical === "no-answer" || !(await authorizedProject(liveCeiling(), canonical)) || !visible(canonical))
+            return back("not-added");
+        const stillAllowed = (repo) => identities.generation() === decidedOn && visible(repo);
+        const admitted = await admitProject(store, { registryFile: options.registryPath ?? null, path: canonical, actor: { label: who.name, origin: "console" }, now, stillAllowed, resolveFolder: identities.resolveNow });
+        if (!admitted.ok || !stillAllowed(admitted.repo))
+            return back("not-added");
+        // Its own fixed check (sample-project.ts), so the first result reads checked rather than "Checks not run": only for a
+        // sample this request just made, never one found again.
+        registerSampleCheck(store, made, admitted.repo, who.name, now);
+        deletedRepos.delete(admitted.repo);
+        who.session.project = admitted.repo;
+        who.session.projectRevision++;
+        sessions.persist(who.session);
+        return redirect(response, "/welcome");
     }
-    return { registrations: handlersOf("tasks", { welcome: showWelcome }) };
+    return { registrations: handlersOf("tasks", { welcome: showWelcome, "welcome.sample": addSample }) };
 }

package/dist/settings-groups-ui.d.ts

@@ -134,6 +134,13 @@ export type SettingsFacts = {
         failed: boolean;
         words: string;
     } | null;
+    /** Easy-start: local mode is on for this laptop install. `owner`: this is the local owner's own session (no password);
+     * `passwordSet`: the owner has set one; `canTurnOff`: a full session of an instance operator. Absent when it is off. */
+    local?: {
+        owner: boolean;
+        passwordSet: boolean;
+        canTurnOff: boolean;
+    } | null;
 };
 declare const groupHref: (slug: string) => string;
 export type NeedsItem = {
@@ -146,7 +153,6 @@ export type NeedsItem = {
 export declare function settingsNeeds(facts: SettingsFacts): NeedsItem[];
 /** Which groups have something waiting, for the section nav's dot and the overview's rows. */
 export declare function needsByGroup(items: readonly NeedsItem[]): Record<string, number>;
-/** The overview: what waits on this person, then one row per group with its state. Viewers see the groups they can open. */
 export declare function settingsHub(facts: SettingsFacts): Html;
 /** The hub's old anchors, forwarded to their group (fragments never reach the server). */
 export declare const HUB_ANCHORS: Readonly<Record<string, string>>;

package/dist/settings-groups-ui.js

@@ -84,6 +84,26 @@ function systemWords(facts) {
     return [facts.backup?.failed ? "The last backup failed" : null, version, "backups, storage, retention, monitoring"].filter(Boolean).join(" · ");
 }
 /** The overview: what waits on this person, then one row per group with its state. Viewers see the groups they can open. */
+/**
+ * Easy-start C5: local mode, said once. The local owner without a password is offered the one way to more ("Let agents
+ * work on their own" → /password/set); a full session of an operator sees it on, and can turn it off (a step-up, confirmed).
+ */
+function localModeSection(facts) {
+    const local = facts.local;
+    if (local === undefined || local === null)
+        return html ``;
+    if (local.owner) {
+        return local.passwordSet ? html `` : settingsSection({ id: "set-password", title: "Let agents work on their own",
+            lead: "Agents can work on their own, merge and release only after you set a password.",
+            body: html `<div class="k-acts">${btn("Set a password", { sm: true, href: "/password/set?next=%2Fsettings" })}</div>` });
+    }
+    if (!local.canTurnOff)
+        return html ``;
+    return settingsSection({ id: "local-mode", title: "Local mode", state: " · on",
+        lead: "A browser on this computer can file tasks, approve plans and add projects without your password.",
+        body: kitSectionForm({ proof: "local-mode-off", action: "/settings/local-mode/off", id: "local-mode-form", save: { label: "Turn off", variant: "outline" },
+            confirm: "Turn off local mode", body: html `` }) });
+}
 export function settingsHub(facts) {
     const items = settingsNeeds(facts);
     const counts = needsByGroup(items);
@@ -104,6 +124,7 @@ export function settingsHub(facts) {
         body: joinHtml([
             answered(facts),
             panel,
+            facts.local?.owner === true ? localModeSection(facts) : "",
             settingsLinks(null, shown.map(([label, slug, href]) => settingsLink({ href, title: label, status: words[slug] ?? "", icon: SETTINGS_GROUP_ICONS[slug], needs: counts[slug] ?? 0 }))),
         ]),
     });
@@ -144,7 +165,7 @@ export function generalGroup(facts, flags) {
         id: "your-password", title: "Your password",
         body: joinHtml([
             formRow("Where it is", "If you started Toolroll with toolroll up, your password is saved on the computer running Toolroll. Toolroll never shows it in a browser. To read it, run this there:", html ``, "wide"),
-            codeLine("cat ~/.config/toolroll/up-login.txt"),
+            codeLine("cat ~/.config/toolroll/.toolroll-secrets/up-login.txt"),
             facts.passwordless === null ? "" : formRow("Passwordless", "Sign in once; most approvals then need no password.", btn(`${facts.passwordless ? "On" : "Off"} · Change`, { sm: true, href: "/settings/passwordless" }), "inline"),
         ]),
     });
@@ -422,7 +443,7 @@ export function accessGroup(facts, flags) {
         ] : []),
     ];
     return settingsShell({ group: "access", title: "People and sign-in", lead: "Who can get in, how they sign in, and the ways in they hold.", flags,
-        body: joinHtml([answered(facts), settingsLinks(null, links, { label: "People and sign-in" })]) });
+        body: joinHtml([answered(facts), localModeSection(facts), settingsLinks(null, links, { label: "People and sign-in" })]) });
 }
 function updatesSection(updates) {
     const latest = updates.latest;

package/dist/settings-proofs.js

@@ -67,6 +67,7 @@ export const PROOF_INVENTORY = [
     { id: "people-close", action: "Cancel an invite or remove a person", routes: ["/people/invite-revoke", "/people/revoke"], form: "peopleRevoke", field: "token", proof: "step-up", ...ACCEPT, role: "any", handlerRole: "an approver", secrets: [], terms: [] },
     { id: "project-setup", action: "Approve project setup", routes: ["/control/setup-approve"], form: "projectSetup", field: "token", proof: "step-up", ...ACCEPT, role: "any", handlerRole: "an approver of the project; models for a new installation need an instance operator", secrets: [], terms: ["repo", "nonce", "fingerprint", "provider", "model", "command", "seconds"], note: "the nonce is spent before the password is checked: after a refusal, review again; the reviewed inputs are previewed again and must match the fingerprint" },
     { id: "project-instructions", action: "Add the agent instructions", routes: ["/control/instructions-approve"], form: "projectSetup", field: "token", proof: "step-up", ...ACCEPT, role: "any", handlerRole: "an approver of the project", secrets: [], terms: ["repo", "nonce", "fingerprint"], note: "the nonce is spent before the password is checked" },
+    { id: "local-mode-off", action: "Turn off local mode", routes: ["/settings/local-mode/off"], form: "localModeOff", field: "password", proof: "step-up", ...ACCEPT, role: "operator", handlerRole: "a full session (never the local owner)", secrets: [], terms: [] },
     { id: "mode-sign", action: "Sign an operating mode", routes: ["/mode/sign"], form: "mode", field: "token", proof: "step-up", ...ACCEPT, role: "any", handlerRole: "an approver of the project", secrets: [], terms: MODE_TERMS },
     { id: "mode-sign-chat-approve", action: "Sign an operating mode that lets your chat app approve", routes: ["/mode/sign"], select: { field: "chat-approve", value: "1" }, form: "mode", field: "token", proof: "credential", ...CREDENTIAL, role: "any", handlerRole: "an approver of the project", secrets: [], terms: MODE_TERMS },
     // Credential acts: a password typed now or a one-use re-check; never Passwordless.

package/dist/setup-guide.d.ts

@@ -15,10 +15,10 @@ export declare function detectPreparation(repo: string): {
 } | null;
 /** Browser installation may write only this known file inside its project. */
 export declare function previewProjectInstructions(repo: string): {
-    content?: never;
     ok: false;
     message: string;
     plan?: never;
+    content?: never;
     fingerprint?: never;
     installed?: never;
 } | {
@@ -30,10 +30,10 @@ export declare function previewProjectInstructions(repo: string): {
     installed: boolean;
 };
 export declare function addProjectInstructions(repo: string, fingerprint: string): {
-    content?: never;
     ok: false;
     message: string;
     plan?: never;
+    content?: never;
     fingerprint?: never;
     installed?: never;
 } | import("./skills.js").InstallResult;

package/dist/setup-guide.js

@@ -6,6 +6,7 @@ import { homedir } from "node:os";
 import { join } from "node:path";
 import { validModelId } from "./provider.js";
 import { planInstall, applyInstall, skillContent, SKILL_DIR, SKILL_FILE } from "./skills.js";
+import { folderAnswers } from "./folder-gate.js";
 export const ASSISTANTS = withAcp({
     claude: { name: "Claude", description: "Use Claude Code for your tasks." },
     codex: { name: "Codex", description: "Use your OpenAI coding assistant." },
@@ -37,6 +38,9 @@ export function modelChoices(provider, configured, home = homedir()) {
     return choices;
 }
 export function detectPreparation(repo) {
+    // In the console, a folder that hasn't answered a look lately is not read on its thread (folder-gate.ts).
+    if (!folderAnswers(repo))
+        return null;
     const has = (file) => existsSync(join(repo, file));
     if (has("package.json")) {
         if (has("pnpm-lock.yaml"))
@@ -59,6 +63,8 @@ export function detectPreparation(repo) {
 }
 /** Browser installation may write only this known file inside its project. */
 export function previewProjectInstructions(repo) {
+    if (!folderAnswers(repo))
+        return { ok: false, message: "This project folder didn't answer. Try again in a moment." };
     try {
         if (!lstatSync(repo).isDirectory())
             return { ok: false, message: "This project folder is unavailable. Reconnect it before adding instructions." };