toolroll 0.9.89 → 0.9.90

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[];

package/dist/surface.js

@@ -431,6 +431,13 @@ const GUIDE_ROWS = [
     operator("up", "console + worker + browser, one command"),
     operator("onboard", "add this repository, report signed-in agents, install or --remove the operator skill (--yes), offer the starter flows (--starter <ids>), and print the handoff"),
     operator("daemon", "install the loop under the OS service manager"),
+    operator("background on", "keep this computer's Toolroll running: a login item that starts `up --laptop` when you log in; hands over from the `up` this terminal runs and puts everything back if the service doesn't answer (--port)"),
+    operator("background off", "stop running in the background: unloads and removes only Toolroll's own login item"),
+    operatorRead("background show", "whether Toolroll runs in the background here, whether it is running now, and any other service on this database"),
+    operator("stop", "stop this computer's Toolroll after its running work is saved: the background service (until the next login), or the `up` running in a terminal"),
+    operator("open", "open this computer's Toolroll at a terminal, signed in: the terminal UI, or the browser with --web (starts it first when it isn't running); never prints a sign-in link"),
+    { ...operatorRead("welcome", "the three steps to a first result (agent, project, first task) as the console's welcome shows them; at a terminal it walks them one at a time"), flags: [jsonFlag, dbFlag] },
+    operator("password set", "set this computer's first password, typed twice at your own terminal (never a flag, file or environment variable); every session signs in again and local mode stays on"),
     { ...operatorRead("doctor", "check that Toolroll's service holds no key, token or password a build could read; names what it finds and the steps to fix it, never a value, and changes nothing"), flags: [jsonFlag] },
 ];
 /**
@@ -450,7 +457,7 @@ const REMOTE_NO = [
     // Workers, the loop and the services that run here.
     "claim", "heartbeat", "worker release", "reap", "tick", "build", "reconcile",
     "runner register", "runner retire", "runner bind", "runner capacity", "coordinator mint", "coordinator revoke", "mcp", "outbox deliver", "peek",
-    "serve", "serve check-public", "watch", "up", "onboard", "daemon", "doctor", "bridge", "setup show", "setup clear",
+    "serve", "serve check-public", "watch", "up", "onboard", "daemon", "background on", "background off", "background show", "stop", "open", "welcome", "password set", "doctor", "bridge", "setup show", "setup clear",
     // Provider keys and model tools on this machine.
     "providers", "keys status", "keys set", "keys clear", "keys verify", "keys auth", "models check", "models update", "models watch",
     // Publication and release.
@@ -497,6 +504,38 @@ export const REMOTE_POLICY = new Map([
 ]);
 /** How many times each invocation was classified — the contract test refuses a row stated twice. */
 export const REMOTE_POLICY_COUNT = REMOTE_NO.length + REMOTE_STEP_UP.length + REMOTE_YES.length;
+/**
+ * Easy-start C3: the commands a laptop's local owner may run through the terminal UI (local-owner.ts runAsLocalOwner),
+ * each with the act it is; every other row (and every command with no row) is refused to the local owner before any
+ * command code runs. Credential, people, policy and infrastructure commands are never here.
+ */
+const LOCAL_ALLOW = {
+    // Reads.
+    pulls: "read", graph: "read", repos: "read", status: "read", ready: "read", gaps: "read", contract: "read", "skills list": "read", "skills get": "read",
+    "task list": "read", "task show": "read", "task state": "read", "task wait": "read", "check-progress": "read", "review show": "read", welcome: "read",
+    // Acts (plan C1's list).
+    "task add": "file-task",
+    chat: "lead-send",
+    "task steer": "lead-send",
+    "task approve": "approve-plan",
+    decide: "answer-question",
+    "task stop": "stop-run",
+    "task pause": "pause-run",
+    "task hold": "pause-run",
+    "task resume": "resume-run",
+    "task continue": "resume-run",
+    "task unhold": "resume-run",
+    "task complete": "complete-task",
+    "task revise": "request-revision",
+    "task archive": "archive-task",
+    "task restore": "archive-task",
+    "repos add": "add-project",
+};
+/** Every guide row's local-owner mark, by invocation: `allow` with its act, else `deny`. Exported for the inventory test. */
+export const LOCAL_POLICY = new Map(GUIDE_ROWS.map(row => [row.invocation,
+    Object.prototype.hasOwnProperty.call(LOCAL_ALLOW, row.invocation) ? { local: "allow", act: LOCAL_ALLOW[row.invocation] } : { local: "deny" }]));
+/** The invocations LOCAL_ALLOW names, for the inventory test (one naming no row is stale). */
+export const LOCAL_ALLOWED_INVOCATIONS = Object.keys(LOCAL_ALLOW);
 /** 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 const COMMAND_ENTRIES = commandEntries(GUIDE_ROWS.map(row => ({ ...row, remote: REMOTE_POLICY.get(row.invocation) ?? "no" })));

package/dist/task-text.d.ts

@@ -23,3 +23,9 @@ export declare function validateTaskText(fields: {
     outOfScope?: string | null;
     touches?: readonly string[];
 }): TaskTextRefusal | null;
+/**
+ * A title that fits: words longer than the title limit are cut at the last whole word that fits, with an ellipsis,
+ * never mid-word (one unbroken word longer than half the limit is the only thing cut inside a word). Whitespace runs
+ * read as one space. Text within the limit is returned as it is.
+ */
+export declare function titleWithin(text: string, max?: number): string;

package/dist/task-text.js

@@ -41,3 +41,20 @@ export function validateTaskText(fields) {
     const bad = validateScopeText(fields);
     return bad === null ? null : refuse("bad-goal", bad.message);
 }
+/**
+ * A title that fits: words longer than the title limit are cut at the last whole word that fits, with an ellipsis,
+ * never mid-word (one unbroken word longer than half the limit is the only thing cut inside a word). Whitespace runs
+ * read as one space. Text within the limit is returned as it is.
+ */
+export function titleWithin(text, max = TASK_TEXT_LIMITS.title) {
+    if (text.length <= max)
+        return text;
+    const words = text.replace(/\s+/g, " ").trim();
+    if (words.length <= max)
+        return words;
+    const room = words.slice(0, max - 1);
+    // The room ends at a whole word when the next character is a space; else back to the last space in it.
+    const space = words[max - 1] === " " ? room.length : room.lastIndexOf(" ");
+    const cut = (space >= Math.floor(max / 2) ? room.slice(0, space) : room).replace(/[\s,;:.\-–—]+$/u, "");
+    return `${cut}…`;
+}

package/dist/telegram-lead.js

@@ -285,6 +285,8 @@ export function applyProposalTap(store, binding, token, message, repos, options,
         return { effects, confirmed: false, ignored: true };
     }
     const outcome = confirmLeadProposal(store, who, proposal.id, now, {
+        // The paired phone speaks for its account's full authority (pairing is a full session's act).
+        authority: "full",
         via: "telegram",
         evidenceRoot: options.evidenceRoot,
         confirm: action.phase === "yes",

package/dist/terminal-text.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Text someone else wrote, made safe to print on a terminal: the one sanitizer the live view, `peek` and the terminal
+ * UI share. Escape sequences in every form go (CSI in 7- or 8-bit form, OSC such as hyperlinks and title changes,
+ * every other ESC sequence), and with them every C0 and C1 control character (a carriage return that would
+ * overwrite a line, a backspace, a bell), every invisible format character and bidi override; a tab becomes a space.
+ * Pure: no imports, so the terminal UI's bundle carries it as is.
+ */
+/** One line: controls, escapes and bidi overrides out; tabs to spaces. A newline is a control here too. */
+export declare function cleanTerminalLine(text: string): string;
+/** Any text for the terminal UI: each line cleaned as above, its newlines kept (a lone carriage return is not one). */
+export declare function terminalText(text: string): string;

package/dist/terminal-text.js

@@ -0,0 +1,26 @@
+/**
+ * Text someone else wrote, made safe to print on a terminal: the one sanitizer the live view, `peek` and the terminal
+ * UI share. Escape sequences in every form go (CSI in 7- or 8-bit form, OSC such as hyperlinks and title changes,
+ * every other ESC sequence), and with them every C0 and C1 control character (a carriage return that would
+ * overwrite a line, a backspace, a bell), every invisible format character and bidi override; a tab becomes a space.
+ * Pure: no imports, so the terminal UI's bundle carries it as is.
+ */
+/** Bidi embedding, override and isolate controls. */
+const BIDI_CONTROLS = /[‪-‮⁦-⁩]/g;
+/** One line: controls, escapes and bidi overrides out; tabs to spaces. A newline is a control here too. */
+export function cleanTerminalLine(text) {
+    return text
+        // Escape sequences in every form: CSI (7- or 8-bit, any parameter bytes including ':'), OSC, and the rest.
+        .replace(/(?:\x1b\[|\u009b)[0-?]*[ -/]*[@-~]/g, "")
+        .replace(/(?:\x1b\]|\u009d)[^\x07\x1b\u009c]*(?:\x07|\x1b\\|\u009c)?/g, "")
+        .replace(/\x1b[ -/]*[0-~]/g, "")
+        .replace(/\t/g, " ")
+        .replace(/[\x00-\x1f\x7f-\x9f]/g, "")
+        // Every invisible format character (zero-width, direction marks and overrides, joiners, BOM): never shown.
+        .replace(/\p{Cf}/gu, "")
+        .replace(BIDI_CONTROLS, "");
+}
+/** Any text for the terminal UI: each line cleaned as above, its newlines kept (a lone carriage return is not one). */
+export function terminalText(text) {
+    return text.split("\n").map(cleanTerminalLine).join("\n");
+}

package/dist/toolroll-update.d.ts

@@ -1,6 +1,7 @@
 import type { DatabaseSync } from "node:sqlite";
 import { type UpdateWaiting } from "./desktop-update.js";
 import { type SupervisorRunner } from "./daemon.js";
+import { type ProcessProbe } from "./runner-process.js";
 import { RUNTIME_PHASES, type RuntimeUpdateJournalRecord } from "./contracts/update-journal.js";
 export declare const PROVENANCE_REPOSITORY = "https://github.com/ap9000/toolroll";
 export declare const PROVENANCE_WORKFLOW = ".github/workflows/publish.yml";
@@ -226,13 +227,19 @@ type Exec = (command: string, args: string[], options?: {
     stderr: string;
 };
 export declare function currentRuntime(version: string): RuntimeRef;
-/** Seams for tests: npm, node and ps (`exec`), launchctl (`run`), process liveness, and launchd's waits (`sleep`). */
+/** Seams for tests: npm, node and ps (`exec`), launchctl or systemctl (`run`), process liveness, and launchd's waits
+ * (`sleep`); for the laptop service on Linux, the platform, process identity (`probe`), the host name its process
+ * record names, and the console proof (`consoleProof`: the database's console is live at that version). */
 export type MachineSeams = {
     exec?: Exec;
     run?: SupervisorRunner;
     alive?: (pid: number) => boolean;
     sleep?: (ms: number) => Promise<void>;
     execPath?: string;
+    platform?: NodeJS.Platform;
+    probe?: ProcessProbe;
+    host?: string;
+    consoleProof?: (databaseFile: string, version: string) => Promise<boolean>;
 };
 export declare function machineSystem(home?: string, env?: Record<string, string | undefined>, seams?: MachineSeams): UpdateSystem;
 /** npm's own Sigstore verifier. Found from npm itself (the `npm` on PATH, then the one beside node), never only from