toolroll 0.9.89 → 0.9.91

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/store.d.ts

@@ -17,6 +17,7 @@ import { type Actor } from "./actor.js";
 import { type LiveActivityKind } from "./live.js";
 import { type CredentialKind, type TokenPurpose } from "./api-tokens.js";
 import { type CriterionMatrixRow, type CriterionJudgementWord } from "./proof.js";
+import { type Authority, type LocalMode } from "./local-owner.js";
 import { type ScopeAuthor, type ExecutionProfile, type UnattendedPermissionMode, type AcceptanceCriterion } from "./scope.js";
 import { type ProviderRoom, type CandidateTier, type TaskSize, type TaskSizing, type PhaseRoute, type PublicationAuthority, type RouteStamp, type ReadinessLookup, type ReadinessObservation, type RouteOverride } from "./phase-routing.js";
 import type { TerminalClass } from "./exhaustion.js";
@@ -233,7 +234,7 @@ export type SealedLedgerEntry = LedgerEntry & {
         hash: string;
     } | null;
 };
-export declare const SCHEMA_VERSION = 146;
+export declare const SCHEMA_VERSION = 147;
 /** v118: the tables merged into `credential`, in the order they move (a person's API tokens keep their ids first). */
 export declare const V118_MERGED_TABLES: Readonly<Record<string, CredentialKind>>;
 /**
@@ -411,6 +412,21 @@ export declare const V145_SCHEMA = "\nCREATE TABLE IF NOT EXISTS task_archive (\
  * started, when it ended and how; recording it never changes the release. Both are read-only history for the Ship and
  * Release views and their CLI twins. */
 export declare const V146_SCHEMA = "\nCREATE TABLE IF NOT EXISTS ci_check (\n  github_repo  TEXT NOT NULL,\n  pr_number    INTEGER NOT NULL,\n  head_sha     TEXT NOT NULL,\n  -- A check's identity: its kind (check run or commit status), its workflow and its name, so two workflows' checks\n  -- with the same name stay two rows (a failing one never hides behind a passing namesake).\n  ident        TEXT NOT NULL,\n  name         TEXT NOT NULL,\n  workflow     TEXT,\n  state        TEXT NOT NULL CHECK (state IN ('queued','running','passed','failed','skipped','cancelled','neutral')),\n  started_at   TEXT,\n  completed_at TEXT,\n  url          TEXT,\n  observed_at  TEXT NOT NULL,\n  PRIMARY KEY (github_repo, pr_number, head_sha, ident)\n);\nCREATE TABLE IF NOT EXISTS release_step (\n  task_id    TEXT NOT NULL,\n  tag        TEXT NOT NULL,\n  version    TEXT NOT NULL,\n  pr         INTEGER,\n  step       TEXT NOT NULL,\n  state      TEXT NOT NULL CHECK (state IN ('running','done','failed','waiting')),\n  started_at TEXT NOT NULL,\n  ended_at   TEXT,\n  detail     TEXT,\n  updated_at TEXT NOT NULL,\n  PRIMARY KEY (task_id, tag, step)\n);\nCREATE INDEX IF NOT EXISTS release_step_by_task ON release_step (task_id, updated_at);\n";
+/** v147 (easy-start plan F): local mode, one row. Absent is off. Written only by initLocalMode (a database `up --laptop`
+ * created, with no account yet) and changed only through enrollOwnerPassword's precondition and setLocalModeOff, each
+ * of which moves `generation` when it changes what a local-owner session may stand on. `enabled` is the plan's `on`
+ * (ON is an SQL keyword). */
+export declare const LOCAL_MODE_SCHEMA = "\nCREATE TABLE IF NOT EXISTS local_mode (\n  id             INTEGER PRIMARY KEY CHECK (id = 1),\n  owner          TEXT NOT NULL REFERENCES approver(name),\n  generation     INTEGER NOT NULL CHECK (generation >= 1),\n  enabled        INTEGER NOT NULL CHECK (enabled IN (0,1)),\n  initialized_at TEXT NOT NULL,\n  changed_at     TEXT NOT NULL\n);\n";
+/** v147: an account's password flag, a browser session's authority and local binding, and the console's key epoch.
+ * Every saved row reads the declared value: an account has a password (1), a session is full ('full') with no local
+ * generation, no key epoch (stale: the next mutation asks to reconnect) and no key; the console record has no epoch. */
+export declare const V147_ADDED_COLUMNS: Readonly<Record<string, Readonly<Record<string, {
+    definition: string;
+    saved: string;
+}>>>>;
+/** The v147 migration's steps after the epoch, in order: a test seam (OpenOptions.migrationStep) may stop after each. */
+export declare const V147_STEPS: readonly ["epoch", "local-mode", "password-set", "web-session", "console-instance"];
+export type MigrationStep = (typeof V147_STEPS)[number];
 /**
  * v135: one approval per release (docs/plans/release-once.md). `release_authority` is the single source of truth for a
  * release a person approved: one row per generation, changed only by compare-and-swap on `rev`, with a lease whose
@@ -503,6 +519,12 @@ export type WebSessionRow = {
     ssoAt: number | null;
     agent: string | null;
     address: string | null;
+    /** v147: the session's authority (saved rows read 'full'); a local owner's local-mode generation; the console start its
+     * mutation key belongs to and a hash of that key (never the key). */
+    authority: Authority;
+    localGeneration: number | null;
+    keyEpoch: string | null;
+    keyHash: string | null;
 };
 /**
  * Every timestamp column holds `Date.prototype.toISOString()` output and
@@ -1861,6 +1883,11 @@ export declare function databasePath(env: Record<string, string | undefined>, ho
 export type OpenOptions = {
     /** Substituted in tests; production opens node:sqlite itself. */
     connect?: (file: string) => Database;
+    /** v147: who created a NEW database. "laptop" (`up --laptop`) records installation_fact created-by=laptop in the same
+     * transaction as installed-at, the one fact initLocalMode starts from. Ignored for a database that already exists. */
+    createdBy?: "laptop";
+    /** Test seam only: told after each v147 migration step (V147_STEPS); a throw stops the open there, as a crash would. */
+    migrationStep?: (step: MigrationStep) => void;
 };
 /** Every connection's wait at SQLite's lock boundary, in milliseconds. */
 export declare const CONCURRENT_WRITER_WAIT_MS = 15000;
@@ -2465,6 +2492,7 @@ export declare class Store {
      * generation, revocation — one read, no inference. */
     accountOf(name: string): {
         credentialHash: string;
+        passwordSet: boolean;
         role: "approver" | "viewer";
         generation: number;
         revokedAt: string | null;
@@ -8241,3 +8269,98 @@ export declare function releaseProgressFor(store: Store, taskId: string): Releas
 export declare function latestReleaseStepTask(store: Store): string | null;
 /** Seconds a step or check took (to its end, or to `now` while it runs); null without a start. */
 export declare function elapsedSeconds(startedAt: string | null, endedAt: string | null, now: Date): number | null;
+/** Local mode as saved, or null when this installation never had it (absent is off). */
+export declare function localModeOf(store: Store): LocalMode | null;
+/** Who made this database (installation_fact created-by), or null: every database made before v147, or by `serve`. */
+export declare function installationCreatedBy(store: Store): string | null;
+export type InitLocalModeResult = {
+    ok: true;
+    owner: string;
+    generation: number;
+} | {
+    ok: false;
+    reason: "not-laptop" | "no-fence" | "has-accounts" | "already";
+};
+/**
+ * Turn local mode on for a database `up --laptop` made, once (plan F). Only when: that database records created-by
+ * laptop, it has no account yet, it never had local mode, and the caller found a fence on this machine (diagnostic
+ * only: it decides whether local mode is offered). One transaction: the owner (no password: a hash of random bytes
+ * that are thrown away, password_set 0), the local_mode row and one ledger line, each inserted only if nothing is
+ * there. A retry or a racing start inserts nothing and writes no second ledger line. Migration and the update
+ * rehearsal never call this.
+ */
+export declare function initLocalMode(store: Store, input: {
+    owner: string;
+    fenceAvailable: boolean;
+    now: Date;
+}): InitLocalModeResult;
+export type EnrollOwnerResult = {
+    ok: true;
+    generation: number;
+} | {
+    ok: false;
+    reason: "already-set" | "local-mode-changed" | "not-owner";
+};
+/**
+ * The local owner sets their first password (plan C4), in one IMMEDIATE transaction: the account still has none,
+ * local mode is on at the generation the caller's session was bound to, and the account is the active owner. Then the
+ * hash is written with password_set 1 and the account's generation moves, every derived authority from before ends
+ * (credential-rotation: every browser session of the account, local-owner ones included), and the ledger says so.
+ * Local mode stays on. A second, concurrent enrollment finds password_set 1 and gets "already-set" ("A password was
+ * just set — sign in"). `credentialHash` is hashPassword's output; the password itself never reaches the store.
+ */
+export declare function enrollOwnerPassword(store: Store, owner: string, credentialHash: string, expectedLocalGeneration: number, now: Date): EnrollOwnerResult;
+export type SetLocalModeOffResult = {
+    ok: true;
+    generation: number;
+} | {
+    ok: false;
+    reason: "not-on" | "not-allowed";
+};
+/**
+ * Turn local mode off (plan C5: one click in Settings for a full session). The caller passes the authority it proved
+ * for this request; only full authority of an active instance operator turns it off. In one transaction: the row reads
+ * off and its generation moves (every local-owner session, link and approval bound to the old one stops standing),
+ * the account's local-owner sessions are deleted, and the ledger says who. Turning it back on is not offered.
+ */
+export declare function setLocalModeOff(store: Store, by: {
+    name: string;
+    authority: Authority;
+}, now: Date): SetLocalModeOffResult;
+/**
+ * What a local sign-in link is bound to, read now (plan C4): local mode on, and its owner an active approver. Null
+ * otherwise. The console's mintLocalLink records this; redemption reads it again and compares every field.
+ */
+export declare function localOwnerBinding(store: Store): {
+    account: string;
+    localGeneration: number;
+    accountGeneration: number;
+} | null;
+/** easy-start D: "Keep Toolroll running in the background?" is asked once per installation; this fact records it. */
+export declare const BACKGROUND_ASKED_FACT = "background-asked";
+export type BackgroundAnswer = "yes" | "no";
+/** The person's one answer to the background question and when it was given, or null when it was never asked. */
+export declare function backgroundAsked(store: Store): {
+    answer: BackgroundAnswer;
+    at: string;
+} | null;
+/** Record the answer, once: the first write wins (installation facts are never updated). True when this call recorded it. */
+export declare function recordBackgroundAsked(store: Store, answer: BackgroundAnswer, now: Date): boolean;
+/**
+ * Easy-start C5 provenance: a task a laptop's local owner files (no password, inside its admitted act) says so in its
+ * filing ledger line — `filed via local-owner · local <generation> <browser|terminal>` — so the record shows which local
+ * mode generation and which road it came by. Null for every other filing (a person with a password, the lead, a
+ * machine), which keeps the line as it was. task_ref.filed_via is left to the road it came by (console, mate, cli…).
+ */
+export declare function localFilingProvenance(filer: string | null): string | null;
+/**
+ * Easy start: the port a NEW laptop install chose when `up`'s default (4180) was already held by something that isn't
+ * this database's console (another Toolroll, the desktop app, any program). Saved once, the first time `up --laptop`
+ * reserves a port on a database `up --laptop` made, so later starts, the background service's unit and `toolroll open`
+ * all find the same address. Installs made any other way never record one: their port stays `up`'s default.
+ */
+export declare const LAPTOP_PORT_FACT = "laptop-port";
+/** The saved laptop port, or null (none saved, or a value that isn't a port). */
+export declare function laptopPortOf(store: Store): number | null;
+/** Record the laptop port, once (installation facts are never updated). */
+export declare function recordLaptopPort(store: Store, port: number, now: Date): void;