toolroll 0.9.88 → 0.9.90

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;

package/dist/store.js

@@ -76,7 +76,8 @@ import { containerEmptiness } from "./container-state.js";
 import { hasDisguisedText, hasForbiddenControls, validateNote } from "./decision.js";
 import { parseReviewContext, reviewContextCustodyProblem } from "./review-context.js";
 import { foldReview, manualReviewOnly } from "./proof.js";
-import { liveReleaseOf } from "./scope.js";
+import { hashPassword, liveReleaseOf } from "./scope.js";
+import { currentLocalOwner, LOCAL_MODE_CONFINES, LOCAL_OWNER_LAPSED, localModeOn, localOwnerInFlight, localOwnerStandsNow } from "./local-owner.js";
 import { nightlyDebtHold } from "./nightly-github.js";
 import { releaseCiHoldOf, releaseCiRunningOf } from "./release-ci-hold.js";
 import { APPROVAL_BASES, approvalOf, machineActing, personProof, proofDetailOf, quarantinedAuthor, sealOriginOf, digestOf, canonicalProfileJson, chainFromJson, profileDigestOf, profileFromJson, scopeAuthorityOf, routeParityProblem, parseAcceptanceCriteria, exactAcceptance, exactStringList, exactSafeIntegerOrNull } from "./scope.js";
@@ -1104,7 +1105,12 @@ const REGISTERED_AT_FILING = "again, as it was filed";
 // deploy_in_flight, flow_step_task; V145_SCHEMA, new tables only).
 // v146 adds, and changes no saved row: each pull request check's own timing as GitHub last reported it for the head the
 // plane observed (ci_check), and each release step's start, end and outcome (release_step; V146_SCHEMA, new tables only).
-export const SCHEMA_VERSION = 146;
+// v147 adds, and changes no saved row (easy-start plan F): local mode (local_mode, one row, absent = off: only
+// `up --laptop` on a new database ever writes it), whether an account has a password (approver.password_set; saved rows
+// read 1), a browser session's authority (web_session.authority; saved rows read 'full'), its local generation, key
+// epoch and key hash (saved rows read NULL: no local binding, and a stale key), and the running console's key epoch
+// (console_instance.key_epoch; NULL). V147_ADDED_COLUMNS.
+export 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 const V118_MERGED_TABLES = Object.freeze({ api_token: "person", coordinator_credential: "coordinator", lead_credential: "lead" });
 /** The foreign keys that named a merged table, exactly as their DDL wrote them; each names `credential(id)` instead. */
@@ -1237,7 +1243,7 @@ const V115_DROPPED_REFERENCES = /\s+REFERENCES (?:contestant|contest|tournament_
  * unchanged), and adds the nullable column in V125_ADDED_COLUMNS, checked the same way. v126 only adds a new table
  * (task_source) and the columns in V126_ADDED_COLUMNS (null or 0), checked the same way.
  */
-export const UPDATE_SAFE_MIGRATIONS = Object.freeze([108, 109, 110, 111, 112, 113, 114, 115, 116, 117, 118, 119, 120, 121, 122, 123, 124, 125, 126, 127, 128, 129, 130, 131, 132, 133, 134, 135, 136, 137, 138, 139, 140, 141, 142, 143, 144, 145, 146]);
+export const UPDATE_SAFE_MIGRATIONS = Object.freeze([108, 109, 110, 111, 112, 113, 114, 115, 116, 117, 118, 119, 120, 121, 122, 123, 124, 125, 126, 127, 128, 129, 130, 131, 132, 133, 134, 135, 136, 137, 138, 139, 140, 141, 142, 143, 144, 145, 146, 147]);
 /** v119: the columns it adds, by table, with the value every row saved before it reads (toolroll-update's HISTORY_RULES). */
 export const V119_ADDED_COLUMNS = Object.freeze({
     task_ref: { planning_generation: { definition: "INTEGER NOT NULL DEFAULT 0", saved: "0" } },
@@ -1463,6 +1469,35 @@ CREATE TABLE IF NOT EXISTS release_step (
 );
 CREATE INDEX IF NOT EXISTS release_step_by_task ON release_step (task_id, updated_at);
 `;
+/** 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 const LOCAL_MODE_SCHEMA = `
+CREATE TABLE IF NOT EXISTS local_mode (
+  id             INTEGER PRIMARY KEY CHECK (id = 1),
+  owner          TEXT NOT NULL REFERENCES approver(name),
+  generation     INTEGER NOT NULL CHECK (generation >= 1),
+  enabled        INTEGER NOT NULL CHECK (enabled IN (0,1)),
+  initialized_at TEXT NOT NULL,
+  changed_at     TEXT NOT NULL
+);
+`;
+/** 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 const V147_ADDED_COLUMNS = Object.freeze({
+    approver: { password_set: { definition: "INTEGER NOT NULL DEFAULT 1 CHECK (password_set IN (0,1))", saved: "1" } },
+    web_session: {
+        authority: { definition: "TEXT NOT NULL DEFAULT 'full' CHECK (authority IN ('full','local-owner'))", saved: "'full'" },
+        local_generation: { definition: "INTEGER CHECK (local_generation IS NULL OR local_generation >= 1)", saved: "NULL" },
+        key_epoch: { definition: "TEXT", saved: "NULL" },
+        key_hash: { definition: "TEXT", saved: "NULL" },
+    },
+    console_instance: { key_epoch: { definition: "TEXT", saved: "NULL" } },
+});
+/** The v147 migration's steps after the epoch, in order: a test seam (OpenOptions.migrationStep) may stop after each. */
+export const V147_STEPS = Object.freeze(["epoch", "local-mode", "password-set", "web-session", "console-instance"]);
 /**
  * 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
@@ -4207,7 +4242,7 @@ export function openStore(file, options = {}) {
     const db = connect(file);
     try {
         waitForConcurrentWriter(db);
-        return initializeStore(db, file);
+        return initializeStore(db, file, options);
     }
     catch (error) {
         // An unsuccessful open must not retain an unfinished migration's lock
@@ -4285,7 +4320,7 @@ CREATE TABLE IF NOT EXISTS team_request (
  response_json TEXT NOT NULL, PRIMARY KEY(account,generation,request_id)
 );
 `;
-function initializeStore(db, file) {
+function initializeStore(db, file, options = {}) {
     // THE PREFLIGHT (v48 integrity): the version is read as EXACTLY ONE
     // safe, supported integer before any DDL — one row, a safe integer,
     // its magnitude between 1 and this build's version. A database with no
@@ -4300,7 +4335,7 @@ function initializeStore(db, file) {
         throw new Error(olderThanBaseline(file, read));
     // A fresh file becomes the v107 baseline first, then takes the same steps an installation from 0.5.0 takes.
     const fresh = read === null;
-    const preflight = fresh ? createBaseline(db, file) : read;
+    const preflight = fresh ? createBaseline(db, file, options.createdBy) : read;
     // History every database since v107 keeps: an open that finds it missing refuses rather than recreate it empty.
     if (!tableExists(db, "service_cursor")) {
         throw new Error(`${file}: service progress is missing; refusing to silently reset worker cursors`);
@@ -4404,6 +4439,8 @@ function initializeStore(db, file) {
             throw new Error(`${file}: refusing to open — the schema version moved from v${preflight} between the preflight and the epoch stamp (another process is migrating it); this build speaks schema v${SCHEMA_VERSION} and alters nothing it cannot name`);
         }
     }
+    const step = options.migrationStep ?? (() => { });
+    step("epoch");
     // v117 renames first, before any step below names a table: they all speak today's names (the lead's, the subagents').
     // A fresh file is the v107 baseline by now, under the old names, so it takes the same renames.
     renameForV117(db);
@@ -4726,6 +4763,19 @@ CREATE INDEX IF NOT EXISTS run_checkpoint_by_task ON run_checkpoint (task_ref, i
     db.exec(V145_SCHEMA);
     // v146: pull request checks' own timing and release steps (new tables only).
     db.exec(V146_SCHEMA);
+    // v147: local mode (a new table) and the password flag, session authority and key columns (V147_ADDED_COLUMNS: saved
+    // rows read their declared values). Each step is idempotent: a crash between them resumes here on the next open.
+    db.exec(LOCAL_MODE_SCHEMA);
+    step("local-mode");
+    for (const [column, { definition }] of Object.entries(V147_ADDED_COLUMNS["approver"]))
+        addColumn(db, "approver", column, definition);
+    step("password-set");
+    for (const [column, { definition }] of Object.entries(V147_ADDED_COLUMNS["web_session"]))
+        addColumn(db, "web_session", column, definition);
+    step("web-session");
+    for (const [column, { definition }] of Object.entries(V147_ADDED_COLUMNS["console_instance"]))
+        addColumn(db, "console_instance", column, definition);
+    step("console-instance");
     // Keep the epoch until reclamation succeeds, including a retry after compaction already committed. A new file has
     // nothing to reclaim.
     if (!fresh)
@@ -4755,7 +4805,7 @@ function olderThanBaseline(file, version) {
  * file is looked at again under the write lock: a second opener that waited
  * on the first finds its tables there and refuses rather than recreating them.
  */
-function createBaseline(db, file) {
+function createBaseline(db, file, createdBy) {
     db.exec("BEGIN IMMEDIATE");
     try {
         if (Number(db.prepare("SELECT COUNT(*) AS n FROM sqlite_master").get()?.["n"]) !== 0) {
@@ -4765,6 +4815,9 @@ function createBaseline(db, file) {
         db.prepare("INSERT INTO schema_version (version) VALUES (?)").run(BASELINE_SCHEMA_VERSION);
         const installedAt = new Date().toISOString();
         db.prepare("INSERT INTO installation_fact (key, value, created_at) VALUES ('installed-at', ?, ?)").run(installedAt, installedAt);
+        // v147: who made this database, in the same transaction as installed-at (initLocalMode starts only from this fact).
+        if (createdBy === "laptop")
+            db.prepare("INSERT INTO installation_fact (key, value, created_at) VALUES ('created-by', 'laptop', ?)").run(installedAt);
         db.exec("COMMIT");
     }
     catch (error) {
@@ -5172,7 +5225,10 @@ function tokenProjectsOf(value) {
 function readWebSession(row) {
     return { idHash: String(row["id_hash"]), account: String(row["account"]), csrf: String(row["csrf"]), role: row["role"] === "viewer" ? "viewer" : "approver", generation: Number(row["generation"]),
         createdAt: Number(row["created_at"]), lastSeen: Number(row["last_seen"]), project: row["project"] == null ? null : String(row["project"]), projectRevision: Number(row["project_revision"]),
-        ssoAt: row["sso_at"] == null ? null : Number(row["sso_at"]), agent: row["agent"] == null ? null : String(row["agent"]), address: row["address"] == null ? null : String(row["address"]) };
+        ssoAt: row["sso_at"] == null ? null : Number(row["sso_at"]), agent: row["agent"] == null ? null : String(row["agent"]), address: row["address"] == null ? null : String(row["address"]),
+        // A value this build can't name is never full authority: it reads local-owner, whose binding (NULL here) stands nowhere.
+        authority: row["authority"] === "full" ? "full" : "local-owner", localGeneration: row["local_generation"] == null ? null : Number(row["local_generation"]),
+        keyEpoch: row["key_epoch"] == null ? null : String(row["key_epoch"]), keyHash: row["key_hash"] == null ? null : String(row["key_hash"]) };
 }
 /**
  * v110: the ledger's source admits 'api' and 'mcp', from the v99 shape; rows, ids and the counter are carried whole, so the v103
@@ -6014,7 +6070,7 @@ export class Store {
             // v102: who filed it, set once with the filing (separation of duties reads it; nothing changes it).
             if (spec.filedBy !== undefined) {
                 this.db.prepare("UPDATE task_ref SET filed_by = ?, filed_by_kind = ? WHERE id = ?").run(spec.filedBy.name, spec.filedBy.kind, ref.id);
-                this.recordAction({ at: stamp, actor: spec.filedBy.name ?? "system", repo: null, taskId: spec.id, runId: null, action: "task filed", outcome: "recorded", source: "work", detail: spec.filedBy.kind === "person" ? null : spec.filedBy.kind });
+                this.recordAction({ at: stamp, actor: spec.filedBy.name ?? "system", repo: null, taskId: spec.id, runId: null, action: "task filed", outcome: "recorded", source: "work", detail: spec.filedBy.kind === "person" ? localFilingProvenance(spec.filedBy.name) : spec.filedBy.kind });
             }
             // The deliverable (v34) lands in the SAME transaction as the filing,
             // and there is no API to change it afterwards.
@@ -6566,6 +6622,11 @@ export class Store {
         this.transacting = true;
         let result;
         try {
+            // Easy-start C1, the write-time re-check: a local owner's chain writes only while it still stands (local mode on
+            // at its generation, the owner active, its session saved), read inside this same transaction.
+            const local = currentLocalOwner();
+            if (local !== null && localOwnerInFlight(local) && !localOwnerStandsNow(this, local))
+                throw new Error(LOCAL_OWNER_LAPSED);
             result = body();
             this.db.exec("COMMIT");
         }
@@ -7684,13 +7745,16 @@ export class Store {
      * generation, revocation — one read, no inference. */
     accountOf(name) {
         const row = this.db
-            .prepare("SELECT credential_hash, role, generation, revoked_at, projects_json FROM approver WHERE name = ?")
+            .prepare("SELECT credential_hash, password_set, role, generation, revoked_at, projects_json FROM approver WHERE name = ?")
             .get(name);
         if (row === undefined)
             return null;
         return {
             projects: readProjectAccess(row["projects_json"]),
             credentialHash: String(row["credential_hash"]),
+            // v147: a local-mode owner has no password yet (0); its stored hash is random and must never verify. Anything
+            // but exactly 1 reads as no password (fail closed).
+            passwordSet: Number(row["password_set"]) === 1,
             role: String(row["role"]) === "viewer" ? "viewer" : "approver",
             generation: Number(row["generation"]),
             revokedAt: row["revoked_at"] === null || row["revoked_at"] === undefined ? null : String(row["revoked_at"]),
@@ -8824,9 +8888,11 @@ export class Store {
         });
     }
     saveWebSession(session) {
-        this.db.prepare(`INSERT INTO web_session (id_hash, account, csrf, role, generation, created_at, last_seen, project, project_revision, sso_at, agent, address) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+        // v147: authority, local generation, key epoch and key hash are set when the session is made and never changed by a
+        // later save of the same id (ON CONFLICT leaves them): a cached copy can't widen or rebind a kept session.
+        this.db.prepare(`INSERT INTO web_session (id_hash, account, csrf, role, generation, created_at, last_seen, project, project_revision, sso_at, agent, address, authority, local_generation, key_epoch, key_hash) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
       ON CONFLICT(id_hash) DO UPDATE SET last_seen = excluded.last_seen, project = excluded.project, project_revision = excluded.project_revision, sso_at = excluded.sso_at`)
-            .run(session.idHash, session.account, session.csrf, session.role, session.generation, session.createdAt, session.lastSeen, session.project, session.projectRevision, session.ssoAt, session.agent, session.address);
+            .run(session.idHash, session.account, session.csrf, session.role, session.generation, session.createdAt, session.lastSeen, session.project, session.projectRevision, session.ssoAt, session.agent, session.address, session.authority, session.localGeneration, session.keyEpoch, session.keyHash);
     }
     webSession(idHash) {
         const row = this.db.prepare("SELECT * FROM web_session WHERE id_hash = ?").get(idHash);
@@ -19078,10 +19144,16 @@ export class Store {
     }
     /** Whether this installation lets an agent run where no OS confinement exists (off unless an operator said so). */
     unfencedAgentsAllowed() {
+        // Easy-start C5: while local mode is on, this installation always confines, whatever is stored (one chokepoint for
+        // every unconfined fallback: agents, the planner, setup and build commands, checks, flow code, project tools).
+        if (localModeOn(this))
+            return false;
         return Number(this.db.prepare("SELECT unfenced_allowed FROM confinement_setting WHERE id = 1").get()?.["unfenced_allowed"] ?? 0) === 1;
     }
     setUnfencedAgentsAllowed(allowed, by, now) {
         this.transact(() => {
+            if (allowed && localModeOn(this))
+                throw new Error(LOCAL_MODE_CONFINES);
             const before = this.unfencedAgentsAllowed();
             this.db.prepare("UPDATE confinement_setting SET unfenced_allowed = ?, updated_at = ?, updated_by = ? WHERE id = 1").run(allowed ? 1 : 0, now.toISOString(), by);
             this.recordPolicy(by, null, "unconfined agents", before ? "allowed" : "refused", allowed ? "allowed" : "refused", now);
@@ -19999,6 +20071,9 @@ export class Store {
                 return null;
             if (widerThan(level, before) && (authority.may !== "widen" || !this.isInstanceOperator(by)))
                 return null;
+            // Easy-start C5: while local mode is on, no project's checks run unsandboxed (callers say "Turn off local mode first").
+            if (level === "unsandboxed" && localModeOn(this))
+                return null;
             this.db.prepare(`INSERT INTO project_check_access (repo, level, updated_at, updated_by) VALUES (?, ?, ?, ?)
         ON CONFLICT (repo) DO UPDATE SET level = excluded.level, updated_at = excluded.updated_at, updated_by = excluded.updated_by`).run(repo, level, now.toISOString(), by);
             const after = this.projectCheckAccess(repo);
@@ -22143,3 +22218,161 @@ export function elapsedSeconds(startedAt, endedAt, now) {
     const start = Date.parse(startedAt), end = endedAt === null ? now.getTime() : Date.parse(endedAt);
     return Number.isFinite(start) && Number.isFinite(end) ? Math.max(0, Math.round((end - start) / 1000)) : null;
 }
+// ---- v147: local mode (easy-start plan F and C4) ------------------------------------------------------------------
+/** Local mode as saved, or null when this installation never had it (absent is off). */
+export function localModeOf(store) {
+    const row = store.handle.prepare("SELECT owner, generation, enabled, initialized_at, changed_at FROM local_mode WHERE id = 1").get();
+    if (row === undefined)
+        return null;
+    const generation = Number(row["generation"]);
+    return { owner: String(row["owner"]), generation: Number.isSafeInteger(generation) ? generation : -1, enabled: Number(row["enabled"]) === 1,
+        initializedAt: String(row["initialized_at"]), changedAt: String(row["changed_at"]) };
+}
+/** Who made this database (installation_fact created-by), or null: every database made before v147, or by `serve`. */
+export function installationCreatedBy(store) {
+    const row = store.handle.prepare("SELECT value FROM installation_fact WHERE key = 'created-by'").get();
+    return row === undefined ? null : String(row["value"]);
+}
+/**
+ * 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 function initLocalMode(store, input) {
+    if (!input.fenceAvailable)
+        return { ok: false, reason: "no-fence" };
+    // Hashed before the transaction (scrypt is slow); the random bytes are never kept anywhere.
+    const unusable = hashPassword(randomBytes(32).toString("hex"));
+    return store.transact(() => {
+        if (installationCreatedBy(store) !== "laptop")
+            return { ok: false, reason: "not-laptop" };
+        if (store.handle.prepare("SELECT 1 FROM local_mode WHERE id = 1").get() !== undefined)
+            return { ok: false, reason: "already" };
+        const stamp = input.now.toISOString();
+        const made = store.handle.prepare(`INSERT INTO approver (name, credential_hash, added_at, generation, password_set)
+      SELECT ?, ?, ?, 1, 0 WHERE NOT EXISTS (SELECT 1 FROM approver) AND NOT EXISTS (SELECT 1 FROM local_mode)`).run(input.owner, unusable, stamp);
+        if (Number(made.changes) !== 1)
+            return { ok: false, reason: "has-accounts" };
+        store.handle.prepare("INSERT INTO local_mode (id, owner, generation, enabled, initialized_at, changed_at) VALUES (1, ?, 1, 1, ?, ?)").run(input.owner, stamp, stamp);
+        store.recordAction({ at: stamp, actor: input.owner, repo: null, taskId: null, runId: null, action: "local mode on", outcome: "initialized", source: "access", detail: "a new laptop install: the owner has no password yet" });
+        return { ok: true, owner: input.owner, generation: 1 };
+    });
+}
+/**
+ * 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 function enrollOwnerPassword(store, owner, credentialHash, expectedLocalGeneration, now) {
+    return store.transact(() => {
+        const account = store.accountOf(owner);
+        if (account === null || account.revokedAt !== null || account.role !== "approver")
+            return { ok: false, reason: "not-owner" };
+        if (account.passwordSet)
+            return { ok: false, reason: "already-set" };
+        const mode = localModeOf(store);
+        if (mode === null || mode.owner !== owner)
+            return { ok: false, reason: "not-owner" };
+        if (!mode.enabled || mode.generation !== expectedLocalGeneration)
+            return { ok: false, reason: "local-mode-changed" };
+        const written = store.handle.prepare(`UPDATE approver SET credential_hash = ?, password_set = 1, generation = generation + 1
+      WHERE name = ? AND password_set = 0 AND revoked_at IS NULL AND role = 'approver'`).run(credentialHash, owner);
+        if (Number(written.changes) !== 1)
+            return { ok: false, reason: "already-set" };
+        store.revokeDerivedAuthority(owner, "credential-rotation", now);
+        store.recordAction({ at: now.toISOString(), actor: owner, repo: null, taskId: null, runId: null, action: "password set", outcome: "enrolled", source: "access", detail: `local mode stays on (generation ${mode.generation})` });
+        return { ok: true, generation: account.generation + 1 };
+    });
+}
+/**
+ * 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 function setLocalModeOff(store, by, now) {
+    if (by.authority !== "full")
+        return { ok: false, reason: "not-allowed" };
+    return store.transact(() => {
+        if (!store.isInstanceOperator(by.name))
+            return { ok: false, reason: "not-allowed" };
+        const stamp = now.toISOString();
+        const moved = store.handle.prepare("UPDATE local_mode SET enabled = 0, generation = generation + 1, changed_at = ? WHERE id = 1 AND enabled = 1").run(stamp);
+        if (Number(moved.changes) !== 1)
+            return { ok: false, reason: "not-on" };
+        store.handle.prepare("DELETE FROM web_session WHERE authority <> 'full'").run();
+        const mode = localModeOf(store);
+        store.recordAction({ at: stamp, actor: by.name, repo: null, taskId: null, runId: null, action: "local mode off", outcome: "changed", source: "access", detail: `generation ${mode.generation}` });
+        return { ok: true, generation: mode.generation };
+    });
+}
+/**
+ * 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 function localOwnerBinding(store) {
+    const mode = localModeOf(store);
+    if (mode === null || !mode.enabled || mode.generation < 1)
+        return null;
+    const account = store.accountOf(mode.owner);
+    if (account === null || account.revokedAt !== null || account.role !== "approver")
+        return null;
+    return { account: mode.owner, localGeneration: mode.generation, accountGeneration: account.generation };
+}
+/** easy-start D: "Keep Toolroll running in the background?" is asked once per installation; this fact records it. */
+export const BACKGROUND_ASKED_FACT = "background-asked";
+/** The person's one answer to the background question and when it was given, or null when it was never asked. */
+export function backgroundAsked(store) {
+    const row = store.handle.prepare("SELECT value, created_at FROM installation_fact WHERE key = ?").get(BACKGROUND_ASKED_FACT);
+    if (row === undefined)
+        return null;
+    const value = String(row["value"]);
+    // A value this build doesn't know still means "asked": never ask again on the strength of a word it can't read.
+    return { answer: value === "yes" ? "yes" : "no", at: String(row["created_at"]) };
+}
+/** Record the answer, once: the first write wins (installation facts are never updated). True when this call recorded it. */
+export function recordBackgroundAsked(store, answer, now) {
+    return store.transact(() => {
+        if (backgroundAsked(store) !== null)
+            return false;
+        store.recordInstallationFact(BACKGROUND_ASKED_FACT, answer, now);
+        return true;
+    });
+}
+/**
+ * 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 function localFilingProvenance(filer) {
+    const local = currentLocalOwner();
+    if (local === null || !localOwnerInFlight(local) || local.account !== filer)
+        return null;
+    return `filed via local-owner · local ${local.localGeneration} ${local.transport}`;
+}
+/**
+ * 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 const LAPTOP_PORT_FACT = "laptop-port";
+/** The saved laptop port, or null (none saved, or a value that isn't a port). */
+export function laptopPortOf(store) {
+    const value = store.installationFact(LAPTOP_PORT_FACT);
+    if (value === null || !/^\d{1,5}$/.test(value))
+        return null;
+    const port = Number(value);
+    return port >= 1 && port < 65536 ? port : null;
+}
+/** Record the laptop port, once (installation facts are never updated). */
+export function recordLaptopPort(store, port, now) {
+    store.recordInstallationFact(LAPTOP_PORT_FACT, String(port), now);
+}

package/dist/surface.d.ts

@@ -16,6 +16,7 @@
  * SURFACE_NOTES.flags says "intended".
  */
 import { type CommandFlag, type CommandRow, type RemotePolicy } from './contracts/cli.js';
+import type { LocalOwnerAct } from './local-owner.js';
 /** A guide row and its flags are derived from their schemas in src/contracts/cli.ts. */
 export type { CommandFlag, CommandRow, RemotePolicy };
 /** The guide's limits, stated machine-readably in every dump. */
@@ -30,6 +31,15 @@ export declare const SURFACE_SCHEMA_VERSION = 1;
 export declare const REMOTE_POLICY: ReadonlyMap<string, RemotePolicy>;
 /** How many times each invocation was classified — the contract test refuses a row stated twice. */
 export declare const REMOTE_POLICY_COUNT: number;
+/** Every guide row's local-owner mark, by invocation: `allow` with its act, else `deny`. Exported for the inventory test. */
+export declare const LOCAL_POLICY: ReadonlyMap<string, {
+    local: "allow";
+    act: LocalOwnerAct;
+} | {
+    local: "deny";
+}>;
+/** The invocations LOCAL_ALLOW names, for the inventory test (one naming no row is stale). */
+export declare const LOCAL_ALLOWED_INVOCATIONS: readonly string[];
 /** Every declared command, in guide order, paired with the schema of its `--json` answer (src/contracts/cli.ts).
  * An unclassified row is "no": nothing runs remotely by omission. */
 export declare const COMMAND_ENTRIES: readonly import("./contracts/cli.js").CommandEntry[];