@agentshouse/kit 0.2.1-c53a84236c3d9 → 0.2.1-c62e8a5e845ed

package/README.md

@@ -1,14 +1,12 @@
 # House Kit
 
-House Kit connects an Environment, a Linux computer or server, to
-[agents.house](https://agents.house). It runs your Agents' conversations
-through the agent CLIs you chose and gives each Agent the `house` command.
+House Kit connects an Environment, a Linux computer or server, to [agents.house](https://agents.house). It runs
+your Agents' conversations through the agent CLIs you chose and gives each Agent the `house` command.
 
 ## Install
 
-Run `curl -fsSL agents.house/kit | sh`, or `irm agents.house/kit.ps1 | iex` on
-Windows, and again to update; options follow `sh -s --`. On macOS and Linux it
-installs House Kit natively under your own account, without an admin password,
+Run `curl -fsSL agents.house/kit | sh`, or `irm agents.house/kit.ps1 | iex` on Windows, and again to update;
+options follow `sh -s --`. On macOS and Linux it installs House Kit natively under your own account, without an admin password,
 as a service that runs while you are logged in. `kit` and `house` are then on
 your login shell's `PATH`, and your workspace is `~/AgentsHouse` unless you
 pass `--workspace <path>`.
@@ -20,7 +18,7 @@ workspace. On Windows 11 the container is the one choice. Append a `kit` or
 Running the command for the other choice on a connected computer asks you to
 confirm, then replaces its Environment, whose Agents end, with a new one.
 
-On your own Ubuntu 26.04 server, run the Linux command with `--linux` to
+On your own Linux server, run the Linux command with `--linux` to
 install House Kit natively, with its workspace at `/agents/house`; `kit` and
 `house` are then on the server's `PATH`.
 
@@ -33,19 +31,21 @@ them out; running it again without the flag brings them back.
 
 ## Commands
 
-`kit login` opens or prints a link you confirm in any browser, on this
-computer or another, continues on its own and keeps the Environment's
-credential in `~/.house-kit`, or in `$HOUSE_KIT_HOME` when it is set. Pass
-`--environment <id>` to reconnect an Environment you already have. It also
-connects your own agent: outside an Agent conversation, `house <tool>` calls
-House as you and `git` clones and pushes your Apps at `<house>/app/` as you,
-until you revoke that connection on Connections. `house help` lists the Tools.
-`kit logout` disconnects this computer, stops House Kit and ends your own
-agent's connection, so `house` and `git` no longer act as you here; a later
-`kit login` reconnects the same Environment.
+`kit login` opens or prints a link you confirm in any browser, on this computer
+or another, continues on its own and keeps the Environment's credential in
+`~/.house-kit`, or in `$HOUSE_KIT_HOME` when it is set. `--environment <id>`
+reconnects an Environment you already have; `--rooms <ref>[,<ref>...]` gives it
+only those Rooms and `--no-private` every Room but your Private Room; `--code <code>` connects immediately without a link.
+A login also connects your own agent: outside an Agent conversation, `house <tool>` calls
+House as you and `git` clones and pushes your Apps at `<house>/app/` as you, until you revoke
+that connection on Connections. `house help` lists the Tools. Codex sessions started after a
+login run a lone `house` command outside their sandbox. `kit logout` disconnects this
+computer, stops House Kit and ends your own agent's connection, so `house` and `git` no
+longer act as you here; a later `kit login` reconnects the same Environment.
+`kit codex --key <key>` starts Codex with `house` acting as you through a key made on Connections; next time, just `kit codex`.
 
 `kit resident` keeps the Environment connected and, as it connects, copies each
-Room you may sync here as a Git repository in the workspace's `local-copies`.
+Room you chose for it as a Git repository in the workspace's `local-copies`.
 `house fetch` records House's changes on each copy's `refs/house/received`;
 rebase onto it, commit and run `house push --owner` in the copy, through the
 install command in the container. An Agent runs both, without `--owner`.

package/dist/agents.js

@@ -3,8 +3,10 @@ import { readFile, realpath } from 'node:fs/promises';
 import { startAdapter } from './acp.js';
 import { CLIS, KIT_VERSION, below, installAdapter, installCli, locate, run, versionOf } from './clis.js';
 import { agentBase, kitHome } from './home.js';
+import { updatesItself } from './placement.js';
 import { killTree } from './scope.js';
 import { holdTranscription, transcriptionReport } from './transcription.js';
+import { KIT_WIRE } from './wire.js';
 const SIGNED_OUT = { signed_in: false, models: [], modes: [] };
 function select(options, category) {
     const option = options.find((candidate) => candidate.category === category);
@@ -257,7 +259,7 @@ export class Agents {
     }
     async load(kind) {
         const known = this.readings.get(kind);
-        if (known !== undefined && known.failure === null)
+        if (known !== undefined && known.failure === null && known.minimum === undefined)
             return;
         await this.examine(kind, SIGNED_OUT, offer);
     }
@@ -270,6 +272,8 @@ export class Agents {
         const body = {
             os: await operatingSystem(),
             kit_version: KIT_VERSION,
+            wire: KIT_WIRE,
+            updates_itself: await updatesItself(),
             agent_base: agentBase(),
             agents,
             transcription: transcriptionReport(),

package/dist/api.js

@@ -1,8 +1,9 @@
 import { setTimeout as delay } from 'node:timers/promises';
-import { end, SIGN_IN_AGAIN } from './end.js';
+import { signInAgain, updateRequired } from './end.js';
 import { readEnrolment } from './home.js';
 import { retryable } from './refusals.js';
 import { relayed } from './relay.js';
+import { KIT_WIRE, KIT_WIRE_HEADER, tooOld } from './wire.js';
 export class HouseRefusal extends Error {
     status;
     text;
@@ -37,12 +38,15 @@ export async function post(house, path, body, credential, signal) {
         method: 'POST',
         headers: {
             'content-type': 'application/json',
+            [KIT_WIRE_HEADER]: String(KIT_WIRE),
             ...(credential === undefined ? {} : { authorization: `Bearer ${credential}` }),
         },
         body: JSON.stringify(body),
         signal,
     });
     const text = await answer.text();
+    if (!answer.ok && tooOld(text))
+        updateRequired(house);
     if (!answer.ok)
         throw new HouseRefusal(path, answer.status, text);
     return JSON.parse(text);
@@ -54,7 +58,7 @@ async function enrolledPost(path, body, signal) {
     }
     catch (error) {
         if (error instanceof HouseRefusal && error.status === 401)
-            end(SIGN_IN_AGAIN);
+            await signInAgain(credential);
         throw error;
     }
 }

package/dist/bootstrap.json

@@ -1,23 +1,23 @@
 {
   "schemaVersion": 2,
-  "version": "0.2.1-c53a84236c3d9",
+  "version": "0.2.1-c62e8a5e845ed",
   "hosts": {
     "macos": {
       "asset": {
         "name": "connect-linux.sh",
-        "url": "https://github.com/agentshouse/kit/releases/download/v0.2.1-c53a84236c3d9/connect-linux.sh"
+        "url": "https://github.com/agentshouse/kit/releases/download/v0.2.1-c62e8a5e845ed/connect-linux.sh"
       }
     },
     "linux": {
       "asset": {
         "name": "connect-linux.sh",
-        "url": "https://github.com/agentshouse/kit/releases/download/v0.2.1-c53a84236c3d9/connect-linux.sh"
+        "url": "https://github.com/agentshouse/kit/releases/download/v0.2.1-c62e8a5e845ed/connect-linux.sh"
       }
     },
     "windows": {
       "asset": {
         "name": "connect-windows.ps1",
-        "url": "https://github.com/agentshouse/kit/releases/download/v0.2.1-c53a84236c3d9/connect-windows.ps1"
+        "url": "https://github.com/agentshouse/kit/releases/download/v0.2.1-c62e8a5e845ed/connect-windows.ps1"
       }
     }
   }

package/dist/clis.js

@@ -1,9 +1,13 @@
 import { spawn } from 'node:child_process';
 import { constants, readFileSync } from 'node:fs';
-import { access, mkdir, readFile, writeFile } from 'node:fs/promises';
+import { access, mkdir, readFile, rename, writeFile } from 'node:fs/promises';
 import { homedir, userInfo } from 'node:os';
-import { delimiter, isAbsolute, join } from 'node:path';
+import { delimiter, dirname, isAbsolute, join } from 'node:path';
 import { kitHome } from './home.js';
+const HOUSE_EXECUTABLES = /^host_executable\(name = "house", paths = (\[.*\])\)$/m;
+function houseRule(houses) {
+    return `prefix_rule(pattern = ["house"], decision = "allow")\nhost_executable(name = "house", paths = ${JSON.stringify(houses)})\n`;
+}
 const RAW_SUBTYPES = [
     'background_tasks_changed',
     'task_started',
@@ -13,7 +17,7 @@ const RAW_SUBTYPES = [
     'hook_started',
     'hook_response',
 ];
-async function executable(path) {
+export async function executable(path) {
     try {
         await access(path, constants.X_OK);
         return true;
@@ -22,15 +26,37 @@ async function executable(path) {
         return false;
     }
 }
-async function allowHouseInCodex(path) {
+async function listedHouses(file) {
+    let text;
+    try {
+        text = await readFile(file, 'utf8');
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return [];
+        throw error;
+    }
+    try {
+        const listed = JSON.parse(HOUSE_EXECUTABLES.exec(text)?.[1] ?? '[]');
+        return Array.isArray(listed) ? listed.filter((house) => typeof house === 'string') : [];
+    }
+    catch {
+        return [];
+    }
+}
+export async function allowHouseInCodex(path) {
     const candidates = [...new Set(path.split(delimiter).filter((directory) => isAbsolute(directory)))].map((directory) => join(directory, 'house'));
-    const houses = [];
-    for (const candidate of candidates)
-        if (await executable(candidate))
-            houses.push(candidate);
     const rules = join(process.env.CODEX_HOME || join(homedir(), '.codex'), 'rules');
+    const file = join(rules, 'house.rules');
+    const houses = [];
+    for (const house of [...(await listedHouses(file)), ...candidates]) {
+        if (!houses.includes(house) && (await executable(house)))
+            houses.push(house);
+    }
     await mkdir(rules, { recursive: true });
-    await writeFile(join(rules, 'house.rules'), `prefix_rule(pattern = ["house"], decision = "allow")\nhost_executable(name = "house", paths = ${JSON.stringify(houses)})\n`);
+    const temporary = `${file}.${process.pid}`;
+    await writeFile(temporary, houseRule(houses));
+    await rename(temporary, file);
 }
 async function nothing() { }
 function bridgeInClaudeSandbox(bridge) {
@@ -198,6 +224,12 @@ export async function loginPath() {
     const ran = await inLoginShell(`printf "${marker}%s\\n" "$PATH"`);
     return ran.stdout.split('\n').findLast((line) => line.startsWith(marker)).slice(marker.length);
 }
+export async function writeCodexRule() {
+    const shell = await loginPath().catch(() => '');
+    await allowHouseInCodex([dirname(process.execPath), process.env.PATH ?? '', shell].join(delimiter)).catch((error) => {
+        throw new Error(`Codex's rule for house could not be written: ${error.message}`);
+    });
+}
 export async function versionOf(path, signal) {
     return VERSION.exec((await run(path, ['--version'], READ_MS, false, signal)).stdout)?.[0] ?? null;
 }

package/dist/codex.js

@@ -0,0 +1,61 @@
+import { homedir } from 'node:os';
+import { delimiter, join, resolve } from 'node:path';
+import { parseArgs } from 'node:util';
+import { CLIS, executable, writeCodexRule } from './clis.js';
+import { kitHome, readOwnAgent, writeOwnAgent } from './home.js';
+import { accepted, DEFAULT_HOUSE } from './login.js';
+const USAGE = `usage: kit codex [--key <key>] [--house <origin>] [<codex argument>...]
+  --key <key>       a key from New key for a script on Connections, kept for later runs
+  --house <origin>  the House of the key, ${DEFAULT_HOUSE} unless one is stored
+`;
+const VALUED = ['--key', '--house'];
+const KEY_SOURCE = 'New key for a script on Connections';
+function codexArgumentsStart(argv) {
+    let index = 0;
+    while (index < argv.length) {
+        const arg = argv[index];
+        if (VALUED.includes(arg))
+            index += 2;
+        else if (arg === '--help' || VALUED.some((option) => arg.startsWith(`${option}=`)))
+            index += 1;
+        else
+            break;
+    }
+    return index;
+}
+async function onPath(name) {
+    for (const directory of (process.env.PATH ?? '').split(delimiter)) {
+        const path = resolve(directory, name);
+        if (await executable(path))
+            return path;
+    }
+    throw new Error(`${name} is not on your PATH; install it with ${CLIS['codex-acp'].install}`);
+}
+export async function codex(argv) {
+    const start = codexArgumentsStart(argv);
+    const { values } = parseArgs({
+        args: argv.slice(0, start),
+        options: { key: { type: 'string' }, house: { type: 'string' }, help: { type: 'boolean', default: false } },
+    });
+    if (values.help) {
+        process.stdout.write(USAGE);
+        return;
+    }
+    process.env.HOUSE_KIT_HOME = resolve(process.env.HOUSE_KIT_HOME || join(homedir(), '.house-kit-outside'));
+    const stored = await readOwnAgent();
+    if (values.key !== undefined) {
+        const house = values.house ?? stored?.house ?? DEFAULT_HOUSE;
+        if (!(await accepted(house, values.key)))
+            throw new Error(`${house} does not accept this key; pass one from ${KEY_SOURCE}`);
+        await writeOwnAgent({ house, credential: values.key });
+    }
+    else if (values.house !== undefined) {
+        throw new Error('--house names the House of a --key; pass the key with it');
+    }
+    else if (stored === null) {
+        throw new Error(`${kitHome()} holds no House key; pass --key with one from ${KEY_SOURCE}`);
+    }
+    await writeCodexRule();
+    const path = await onPath('codex');
+    process.execve(path, [path, ...argv.slice(start)], process.env);
+}

package/dist/conversations.js

@@ -17,6 +17,7 @@ import { createHowWeWork } from './skills.js';
 import { transcribe } from './transcription.js';
 import { workFor } from './work.js';
 const KILLED = 'the conversation was killed';
+export const CONVERSATION_INPUTS = new Set(['open', 'message', 'interrupt', 'kill', 'option', 'answer']);
 function causeOf(error) {
     return error instanceof Error ? error.message : String(error);
 }
@@ -132,6 +133,9 @@ export class Conversations {
             return false;
         return !conversations.some((conversation) => conversation.running?.scope.working() || [...conversation.leftovers].some((scope) => scope.working()));
     }
+    quiet() {
+        return this.idle() && [...this.conversations.values()].every((conversation) => conversation.open === 0);
+    }
     look() {
         for (const conversation of this.conversations.values()) {
             for (const scope of conversation.leftovers) {
@@ -499,7 +503,7 @@ export class Conversations {
         if (conversation.turn === turn)
             conversation.turn = null;
         const body = Promise.allSettled(turn.uploads).then(() => ({
-            parts: turn.parts.parts,
+            parts: turn.parts.saved(),
             context: turn.parts.context,
             ...failed,
         }));
@@ -644,7 +648,7 @@ export class Conversations {
                 turn.parts.plan(event.entries);
                 return;
             case 'image':
-                turn.uploads.push(this.image(conversation, turn, event.data, event.mediaType));
+                turn.uploads.push(this.image(conversation, turn, turn.parts.reserve(), event.data, event.mediaType));
                 this.kit.changed();
                 return;
         }
@@ -664,7 +668,7 @@ export class Conversations {
         else
             conversation.turn.parts.start(part);
     }
-    async image(conversation, turn, data, mediaType) {
+    async image(conversation, turn, reserved, data, mediaType) {
         const bytes = Buffer.from(data, 'base64');
         const name = `image-${++turn.images}.${mediaType.split('/')[1]}`;
         try {
@@ -677,10 +681,10 @@ export class Conversations {
             const saved = declared.upload === undefined ? declared : await uploadBytes(declared.upload, bytes);
             if (saved.save.status !== 'saved')
                 throw new Error(saved.save.failure ?? saved.save.status);
-            turn.parts.start({ type: 'image', file: saved.version, name, media_type: mediaType });
+            turn.parts.arrive({ type: 'image', file: saved.version, name, media_type: mediaType }, reserved);
         }
         catch (error) {
-            turn.parts.start({ type: 'marker', marker: 'retry', text: `${name} was not saved: ${causeOf(error)}` });
+            turn.parts.arrive({ type: 'marker', marker: 'retry', text: `${name} was not saved: ${causeOf(error)}` }, reserved);
         }
     }
 }

package/dist/copies.js

@@ -42,7 +42,7 @@ function expiredAuthority(error) {
         return undefined;
     try {
         const { error: refused } = JSON.parse(error.text);
-        return refused?.code === 'position_expired' && typeof refused.authority === 'string' ? refused.authority : undefined;
+        return refused?.code === 'expired' && typeof refused.authority === 'string' ? refused.authority : undefined;
     }
     catch {
         return undefined;
@@ -623,7 +623,7 @@ export class LocalCopies {
                 const { upload, ...unstaged } = copy.push;
                 return this.settle(await this.save({ ...copy, push: unstaged }), caller, true);
             }
-            if (outcome.refused.code === 'operation_expired')
+            if (outcome.refused.code === 'expired')
                 return this.recovered(copy);
             const rebased = rebaseFixes(outcome.refused);
             let settled = await this.save(without(copy));

package/dist/end.js

@@ -1,8 +1,22 @@
+import { forgetRejected } from './home.js';
+import { installCommand } from './placement.js';
 import { killDescendants } from './scope.js';
 export const REPLACED = 'another Kit started for this Environment';
-export const SIGN_IN_AGAIN = 'sign in again';
-export function end(reason) {
+function exit(reason, status) {
     process.stderr.write(`kit: ${reason}\n`);
     killDescendants();
-    process.exit(0);
+    process.exit(status);
+}
+export function end(reason) {
+    exit(reason, 0);
+}
+export function restart(reason) {
+    exit(reason, 1);
+}
+export function updateRequired(house) {
+    end(`This Kit is too old for House. Update it: ${installCommand(house)}`);
+}
+export async function signInAgain(rejected) {
+    await forgetRejected(rejected);
+    restart('sign in again');
 }

package/dist/enrol-main.js

@@ -1,4 +1,10 @@
 import { readFileSync } from 'node:fs';
 import { writeEnrolment } from './home.js';
 const [house, environment] = process.argv.slice(2);
-await writeEnrolment({ house: house, environment: environment, credential: readFileSync(0, 'utf8').trim() });
+const relay = process.env.HOUSE_KIT_RELAY || undefined;
+await writeEnrolment({
+    house: house,
+    ...(relay === undefined ? {} : { relay }),
+    environment: environment,
+    credential: readFileSync(0, 'utf8').trim(),
+});

package/dist/home.js

@@ -1,11 +1,13 @@
-import { existsSync } from 'node:fs';
+import { existsSync, linkSync, readFileSync, renameSync, rmSync } from 'node:fs';
 import { mkdir, readFile, rename, rm, writeFile } from 'node:fs/promises';
 import { homedir } from 'node:os';
 import { join } from 'node:path';
+import { selectRelay } from './relay.js';
 const ENROLMENT = 'credential.json';
 const DISCONNECTED = 'disconnected.json';
 const CONFIGURATION = 'kit.json';
 const OWN_AGENT = 'own-agent.json';
+const RESTART = 'restart';
 export function kitHome() {
     return process.env.HOUSE_KIT_HOME ?? join(homedir(), '.house-kit');
 }
@@ -32,8 +34,11 @@ export async function writeHome(name, value) {
     await writeFile(temporary, `${JSON.stringify(value)}\n`, { mode: 0o600 });
     await rename(temporary, join(home, name));
 }
-export function readEnrolment() {
-    return readHome(ENROLMENT);
+export async function readEnrolment() {
+    const enrolment = await readHome(ENROLMENT);
+    if (enrolment !== null)
+        selectRelay(process.env.HOUSE_KIT_RELAY || enrolment.relay);
+    return enrolment;
 }
 export async function writeEnrolment(enrolment) {
     await writeHome(ENROLMENT, enrolment);
@@ -46,9 +51,42 @@ export async function forgetEnrolment({ house, environment }) {
     await writeHome(DISCONNECTED, { house, environment });
     await rm(join(kitHome(), ENROLMENT), { force: true });
 }
+export async function forgetRejected(rejected) {
+    const held = await readHome(ENROLMENT);
+    if (held?.credential !== rejected)
+        return;
+    await writeHome(DISCONNECTED, { house: held.house, environment: held.environment });
+    const enrolment = join(kitHome(), ENROLMENT);
+    const taken = `${enrolment}.${process.pid}`;
+    try {
+        renameSync(enrolment, taken);
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return;
+        throw error;
+    }
+    if (JSON.parse(readFileSync(taken, 'utf8')).credential !== rejected) {
+        try {
+            linkSync(taken, enrolment);
+        }
+        catch (error) {
+            if (error.code !== 'EEXIST')
+                throw error;
+        }
+        rmSync(join(kitHome(), DISCONNECTED), { force: true });
+    }
+    rmSync(taken);
+}
 export function enrolled() {
     return existsSync(join(kitHome(), ENROLMENT));
 }
+export function restartAsked() {
+    return existsSync(join(kitHome(), RESTART));
+}
+export function forgetRestart() {
+    return rm(join(kitHome(), RESTART), { force: true });
+}
 export function readOwnAgent() {
     return readHome(OWN_AGENT);
 }

package/dist/house-main.js

@@ -2,13 +2,13 @@
 import { createHash } from 'node:crypto';
 import { readFile } from 'node:fs/promises';
 import { request, setGlobalProxyFromEnv } from 'node:http';
-import { basename, join } from 'node:path';
+import { extname, join } from 'node:path';
 import { HOUSE_REF } from './git.js';
-import { kitHome, readOwnAgent } from './home.js';
+import { kitHome, readEnrolment, readOwnAgent } from './home.js';
 import { callHouse, rpc, UNREACHABLE } from './mcp.js';
 import { refusalOf } from './refusals.js';
 import { relayed } from './relay.js';
-import { parse } from 'yaml';
+import { parse, stringify } from 'yaml';
 const USAGE = "usage: house <tool> ['<arguments as JSON>']";
 const PUSH_USAGE = 'usage: house push [commit] [--owner]';
 const PUSH = "push [commit]: sends the Local copy's committed changes to House";
@@ -21,6 +21,33 @@ const REVOKED = 'this conversation no longer has House access; nothing to do fro
 const UNCONNECTED = "this computer's own agent has no House connection; run kit login";
 const DISCONNECTED = "House no longer accepts this computer's own agent; run kit login";
 const socketPath = process.env.HOUSE_BRIDGE;
+const MEDIA_TYPES = new Map([
+    ['avif', 'image/avif'],
+    ['csv', 'text/csv'],
+    ['docx', 'application/vnd.openxmlformats-officedocument.wordprocessingml.document'],
+    ['gif', 'image/gif'],
+    ['heic', 'image/heic'],
+    ['html', 'text/html'],
+    ['jpeg', 'image/jpeg'],
+    ['jpg', 'image/jpeg'],
+    ['json', 'application/json'],
+    ['m4a', 'audio/mp4'],
+    ['md', 'text/markdown'],
+    ['mov', 'video/quicktime'],
+    ['mp3', 'audio/mpeg'],
+    ['mp4', 'video/mp4'],
+    ['ogg', 'audio/ogg'],
+    ['pdf', 'application/pdf'],
+    ['png', 'image/png'],
+    ['pptx', 'application/vnd.openxmlformats-officedocument.presentationml.presentation'],
+    ['svg', 'image/svg+xml'],
+    ['txt', 'text/plain'],
+    ['wav', 'audio/wav'],
+    ['webm', 'video/webm'],
+    ['webp', 'image/webp'],
+    ['xlsx', 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet'],
+    ['zip', 'application/zip'],
+]);
 function refused(path, status, text) {
     const refusal = refusalOf(text);
     if (refusal !== null)
@@ -56,6 +83,7 @@ async function direct(message) {
     const ownAgent = await readOwnAgent();
     if (ownAgent === null)
         throw new Error(UNCONNECTED);
+    await readEnrolment();
     setGlobalProxyFromEnv();
     const answer = await callHouse(ownAgent.house, ownAgent.credential, message).catch(() => {
         throw new Error(UNREACHABLE);
@@ -97,28 +125,43 @@ async function sent(url, bytes, operation) {
         return text;
     throw new Error(refused(url, answer.status, text));
 }
-async function upload(path, roomRef, missing) {
-    if (typeof path !== 'string' || path === '')
-        throw new Error(missing);
-    const bytes = await localFile(path);
-    const declared = parse(await called('upload', {
-        ...(roomRef === undefined ? {} : { room_ref: roomRef }),
-        name: basename(path),
+async function upload({ file, ...destination }) {
+    if (typeof file !== 'string' || file === '')
+        throw new Error('upload needs "file", a local file');
+    const bytes = await localFile(file);
+    const mediaType = MEDIA_TYPES.get(extname(file).slice(1).toLowerCase());
+    const answer = await called('upload', {
+        ...destination,
         bytes: bytes.length,
         sha256: createHash('sha256').update(bytes).digest('hex'),
-    }));
+        ...(mediaType === undefined ? {} : { media_type: mediaType }),
+    });
+    const declared = parse(answer);
     if (declared.upload === undefined)
-        return declared.attachment;
-    const saved = JSON.parse(await sent(declared.upload.url, bytes, declared.upload.operation));
-    if (saved.upload_failure !== undefined)
-        throw new Error(`${path} was not saved: ${saved.upload_failure}; call again later`);
-    return saved.attachment;
+        return answer;
+    const written = JSON.parse(await sent(declared.upload.url, bytes, declared.upload.operation));
+    return stringify(written, { lineWidth: 0 }).trimEnd();
+}
+function unexpected(argument, usage) {
+    return new Error(`unexpected argument ${argument}; ${usage}`);
+}
+function accepted(args, flags, positionals, usage) {
+    const given = { flags: new Set(), positionals: [] };
+    for (const arg of args) {
+        if (flags.includes(arg))
+            given.flags.add(arg);
+        else if (!arg.startsWith('-') && given.positionals.length < positionals)
+            given.positionals.push(arg);
+        else
+            throw unexpected(arg, usage);
+    }
+    return given;
 }
 async function push(args) {
-    if (args.includes('--help'))
+    const { flags, positionals: [commit = 'HEAD'] } = accepted(args, ['--help', '--owner'], 1, PUSH_USAGE);
+    if (flags.has('--help'))
         return PUSH_USAGE;
-    const owner = args.includes('--owner');
-    const commit = args.find((arg) => arg !== '--owner') ?? 'HEAD';
+    const owner = flags.has('--owner');
     if (owner && socketPath !== undefined)
         throw new Error('--owner is not for Agent conversations; run house push without it');
     if (!owner && socketPath === undefined)
@@ -129,7 +172,7 @@ async function push(args) {
     return pushed.text;
 }
 async function fetched(args) {
-    if (args.includes('--help'))
+    if (accepted(args, ['--help'], 0, FETCH_USAGE).flags.has('--help'))
         return FETCH_USAGE;
     const answer = JSON.parse(await bridged('/git/fetch', {}, undefined, socketPath ?? join(kitHome(), 'owner.sock')));
     if (answer.refused)
@@ -150,28 +193,23 @@ function argumentsOf(argument) {
         throw new Error(ARGUMENTS);
     return parsed;
 }
-async function house([verb, argument]) {
-    if (verb === undefined || verb === '--help' || verb === 'help') {
+async function house(args) {
+    const { flags, positionals: [verb, argument] } = accepted(args, ['--help'], 2, USAGE);
+    if (verb === 'help' && argument !== undefined)
+        throw unexpected(argument, USAGE);
+    if (flags.has('--help') && argument !== undefined)
+        throw unexpected('--help', USAGE);
+    if (verb === undefined || verb === 'help') {
         return [USAGE, 'help', PUSH, FETCH, ...(await tools()).map((tool) => (tool.description === undefined ? tool.name : `${tool.name}: ${tool.description}`))].join('\n');
     }
-    if (argument === '--help') {
+    if (flags.has('--help')) {
         const tool = (await tools()).find((listed) => listed.name === verb);
         if (tool === undefined)
             throw new Error(`${verb} is no Tool; house find_command '{"query":"${verb}"}' finds Commands`);
         return [...(tool.description === undefined ? [] : [tool.description]), JSON.stringify(tool.inputSchema)].join('\n');
     }
-    const args = argumentsOf(argument);
-    if (verb === 'upload') {
-        return JSON.stringify({ attachment: await upload(args.path, args.room_ref, 'upload needs "path", a local file') });
-    }
-    if (verb === 'append_record' && Array.isArray(args.attachments)) {
-        const attachments = [];
-        for (const path of args.attachments) {
-            attachments.push(await upload(path, args.room_ref, 'each attachments entry is the path of a local file'));
-        }
-        args.attachments = attachments;
-    }
-    return called(verb, args);
+    const parsed = argumentsOf(argument);
+    return verb === 'upload' ? upload(parsed) : called(verb, parsed);
 }
 async function called(name, args) {
     const result = await mcp('tools/call', { name, arguments: args });
@@ -181,7 +219,9 @@ async function called(name, args) {
     return text;
 }
 const argv = process.argv.slice(2);
-(argv[0] === 'push' ? push(argv.slice(1)) : argv[0] === 'fetch' ? fetched(argv.slice(1)) : house(argv)).then((text) => {
+const named = argv.findIndex((arg) => !arg.startsWith('-'));
+const rest = argv.filter((_arg, index) => index !== named);
+(argv[named] === 'push' ? push(rest) : argv[named] === 'fetch' ? fetched(rest) : house(argv)).then((text) => {
     process.stdout.write(`${text}\n`);
     if (argv[0] === 'shell')
         process.exitCode = Number(/^exit: (\d+)(?:\n|$)/.exec(text)?.[1] ?? 0);

package/dist/instructions.js

@@ -1,8 +1,9 @@
 import { HOUSE_REF } from './git.js';
 import { HOW_WE_WORK } from './skills.js';
-const HOUSE_LINE = 'Work with House through the `house` CLI: run `house --help`.';
-const FILE_LINE = 'To give the User a file or a page, upload it with `house upload` and link it; never start a server.';
-const READ_LINE = 'Before working in a Room, read `/rooms/private/rooms/<handle>/AGENTS.md`.';
+const SOURCE_LINE = "From House:";
+const HOUSE_LINE = "Work with House through the `house` CLI: run `house --help`, and `house find_command` for House's guides and formats.";
+const FILE_LINE = 'To give the User a file, upload it with `house upload` and link it; for an App, a Site or a website, follow `house find_command \'{"query":"app"}\'`. Never start a server.';
+const READ_LINE = "Optional per-Room instructions: `/rooms/private/rooms/<handle>/AGENTS.md`.";
 const COPIES_LINE = `House Local copies; before work run \`house fetch\` and rebase onto \`${HOUSE_REF}\`; after it commit, then \`house push\`:`;
 const UNREADABLE = /^(?:\S+: )?(?:path_not_found|room_not_found|operation_denied)\b/;
 const FAILED = /^exit: [1-9]\d*$/;
@@ -30,6 +31,6 @@ async function howWeWork(bridge) {
     return document.replace(/\n$/, '');
 }
 export async function instructions(bridge, base, copies) {
-    const lines = [HOUSE_LINE, FILE_LINE, READ_LINE, ...(copies.length === 0 ? [] : [COPIES_LINE, ...copies])];
+    const lines = [SOURCE_LINE, HOUSE_LINE, FILE_LINE, READ_LINE, ...(copies.length === 0 ? [] : [COPIES_LINE, ...copies])];
     return [lines.join('\n'), base, await howWeWork(bridge)].filter((part) => part !== '').join('\n\n');
 }

package/dist/kit-main.js

@@ -1,22 +1,67 @@
 #!/usr/bin/env node
 import { setGlobalProxyFromEnv } from 'node:http';
+import { parseArgs } from 'node:util';
 import { answerGitCredential } from './app-git.js';
+import { codex } from './codex.js';
 import { login } from './login.js';
 import { logout } from './logout.js';
 import { resident } from './resident.js';
+const USAGE = 'usage: kit <login|logout|resident|codex>\n';
+const COMMANDS = new Map([
+    [
+        'logout',
+        {
+            usage: 'usage: kit logout',
+            about: "disconnects this computer, stops House Kit and ends your own agent's connection",
+            operands: 0,
+            run: logout,
+        },
+    ],
+    [
+        'resident',
+        {
+            usage: 'usage: kit resident',
+            about: "keeps this Environment connected; House Kit's service runs it",
+            operands: 0,
+            run: resident,
+        },
+    ],
+    [
+        'git-credential',
+        {
+            usage: 'usage: kit git-credential <get|store|erase>',
+            about: "answers git with your own agent's House credential; git runs it",
+            operands: 1,
+            run: ([operation]) => answerGitCredential(operation),
+        },
+    ],
+]);
 const [command, ...argv] = process.argv.slice(2);
 setGlobalProxyFromEnv();
 async function run() {
     if (command === 'login')
         return login(argv);
-    if (command === 'logout')
-        return logout();
-    if (command === 'resident')
-        return resident();
-    if (command === 'git-credential')
-        return answerGitCredential(argv[0]);
-    process.stderr.write('usage: kit <login|logout|resident>\n');
-    process.exitCode = 2;
+    if (command === 'codex')
+        return codex(argv);
+    if (command === '--help') {
+        parseArgs({ args: argv });
+        process.stdout.write(USAGE);
+        return;
+    }
+    const chosen = COMMANDS.get(command ?? '');
+    if (chosen === undefined) {
+        process.stderr.write(USAGE);
+        process.exitCode = 2;
+        return;
+    }
+    const { values, positionals } = parseArgs({ args: argv, options: { help: { type: 'boolean', default: false } }, allowPositionals: true });
+    if (positionals.length > chosen.operands)
+        throw new Error(`unexpected argument ${positionals[chosen.operands]}; ${chosen.usage}`);
+    if (values.help) {
+        process.stdout.write(`${chosen.usage}\n  ${chosen.about}\n`);
+        return;
+    }
+    return chosen.run(positionals);
 }
 run().catch((error) => {
     process.stderr.write(`kit: ${error instanceof Error ? error.message : String(error)}\n`);

package/dist/login.js

@@ -4,9 +4,13 @@ import { hostname } from 'node:os';
 import { parseArgs } from 'node:util';
 import { post, retrying } from './api.js';
 import { placeAppGit } from './app-git.js';
+import { writeCodexRule } from './clis.js';
 import { forgetOwnAgent, readDisconnected, readEnrolment, readOwnAgent, writeEnrolment, writeOwnAgent } from './home.js';
 import { callHouse, rpc } from './mcp.js';
-const DEFAULT_HOUSE = 'https://agents.house';
+import { selectRelay } from './relay.js';
+import { startService } from './service.js';
+import { placeSkillSet } from './skills.js';
+export const DEFAULT_HOUSE = 'https://agents.house';
 const OPENER = process.platform === 'darwin' ? 'open' : 'xdg-open';
 // Polling every two seconds brings the User's confirmation to the waiting Kit moments after they give it.
 const POLL_INTERVAL_MS = 2000;
@@ -15,7 +19,7 @@ function open(link) {
         .on('error', () => undefined)
         .unref();
 }
-async function accepted(house, credential) {
+export async function accepted(house, credential) {
     const checked = await callHouse(house, credential, rpc('tools/list', {}));
     if (checked.status === 200)
         return true;
@@ -23,39 +27,101 @@ async function accepted(house, credential) {
         return false;
     throw new Error(`House answered ${checked.status} when Kit checked this computer's own agent's connection: ${checked.text}`);
 }
+const USAGE = `usage: kit login [--house <origin>] [--environment <id>] [--rooms <ref>[,<ref>...] | --no-private]
+       kit login [--house <origin>] --code <code>
+  --house <origin>          the House to connect to, ${DEFAULT_HOUSE} unless one is stored
+  --environment <id>        reconnect this Environment
+  --rooms <ref>[,<ref>...]  give this Environment only these Rooms
+  --no-private              give this Environment every Room but your Private Room
+  --code <code>             connect this machine with a login code
+`;
+function chosenRooms(rooms, noPrivate) {
+    if (rooms !== undefined && noPrivate)
+        throw new Error('--rooms and --no-private are two choices of Rooms; pass one');
+    if (rooms !== undefined)
+        return { rooms: { reach: 'selected', refs: rooms.split(',') } };
+    return noPrivate ? { rooms: { reach: 'all_but_private' } } : {};
+}
 export async function login(argv) {
     const { values } = parseArgs({
         args: argv,
         options: {
             house: { type: 'string' },
             environment: { type: 'string' },
+            rooms: { type: 'string' },
+            'no-private': { type: 'boolean', default: false },
+            code: { type: 'string' },
+            help: { type: 'boolean', default: false },
         },
     });
+    if (values.help) {
+        process.stdout.write(USAGE);
+        return;
+    }
+    if (values.code !== undefined && values.rooms !== undefined)
+        throw new Error('--code cannot be used with --rooms');
+    if (values.code !== undefined && values['no-private'])
+        throw new Error('--code cannot be used with --no-private');
+    if (values.code !== undefined && values.environment !== undefined)
+        throw new Error('--code cannot be used with --environment');
+    const rooms = chosenRooms(values.rooms, values['no-private']);
     const enrolled = (await readEnrolment()) ?? (await readDisconnected());
+    if (values.code !== undefined && enrolled !== null) {
+        throw new Error(`--code connects a new machine; this Kit home records Environment ${enrolled.environment}, so run kit login to reconnect it`);
+    }
+    const relay = process.env.HOUSE_KIT_RELAY || undefined;
+    selectRelay(relay);
     const house = values.house ?? enrolled?.house ?? DEFAULT_HOUSE;
     const replaces = process.env.HOUSE_KIT_REPLACES;
     const environment = replaces === undefined ? (values.environment ?? (enrolled?.house === house ? enrolled.environment : undefined)) : undefined;
     const ownAgent = await readOwnAgent();
-    const held = ownAgent !== null && ownAgent.house === house && (await accepted(house, ownAgent.credential));
-    const verifier = randomBytes(32).toString('base64url');
-    const started = await retrying(() => post(house, '/kit', {
-        ...(environment === undefined
-            ? { act: 'new_environment', label: hostname(), ...(replaces === undefined ? {} : { replaces }) }
-            : { act: 'existing_environment', environment_id: environment }),
-        code_challenge: createHash('sha256').update(verifier).digest('base64url'),
-        ...(held ? {} : { headless: true }),
-    }));
-    process.stdout.write(`Open this link and confirm: ${started.start_url}\n`);
-    open(started.start_url);
-    const exchanged = await retrying(() => post(house, '/kit/token', { login: started.login, code_verifier: verifier }), undefined, () => POLL_INTERVAL_MS);
-    await writeEnrolment({ house, environment: exchanged.environment, credential: exchanged.credential });
+    let held = false;
+    let exchanged;
+    if (values.code !== undefined) {
+        exchanged = await post(house, '/kit/token', { code: values.code, label: hostname() });
+    }
+    else {
+        held = ownAgent !== null && ownAgent.house === house && (await accepted(house, ownAgent.credential));
+        const verifier = randomBytes(32).toString('base64url');
+        const started = await retrying(() => post(house, '/kit', {
+            label: hostname(),
+            ...(environment === undefined
+                ? { act: 'new_environment', ...(replaces === undefined ? {} : { replaces }) }
+                : { act: 'existing_environment', environment_id: environment }),
+            ...rooms,
+            code_challenge: createHash('sha256').update(verifier).digest('base64url'),
+            ...(held ? {} : { headless: true }),
+        }));
+        process.stdout.write(`Open this link and confirm: ${started.start_url}\n`);
+        open(started.start_url);
+        exchanged = await retrying(() => post(house, '/kit/token', { login: started.login, code_verifier: verifier }), undefined, () => POLL_INTERVAL_MS);
+    }
+    try {
+        await placeSkillSet();
+    }
+    catch (error) {
+        process.stderr.write(`kit: the skills could not be placed: ${error.message}\n`);
+    }
+    await writeCodexRule().catch((error) => process.stderr.write(`kit: ${error.message}\n`));
+    await writeEnrolment({
+        house,
+        ...(relay === undefined ? {} : { relay }),
+        environment: exchanged.environment,
+        credential: exchanged.credential,
+    });
     process.stdout.write(`Environment ${exchanged.environment} is connected to ${house}.\n`);
     if (exchanged.headless_credential !== undefined) {
         await writeOwnAgent({ house, user: exchanged.user, credential: exchanged.headless_credential });
     }
-    else if (held && ownAgent.user !== exchanged.user) {
+    else if (held && ownAgent !== null && ownAgent.user !== exchanged.user) {
         await forgetOwnAgent();
         process.stdout.write("This computer's own agent was another User's; run kit login again to connect it to you.\n");
     }
     await placeAppGit(ownAgent, await readOwnAgent());
+    try {
+        startService();
+    }
+    catch (error) {
+        process.stderr.write(`kit: ${error.message}\n`);
+    }
 }

package/dist/parts.js

@@ -2,7 +2,10 @@ export class Parts {
     parts = [];
     context = null;
     emit;
+    made = [];
+    events = 0;
     writing = null;
+    counting = null;
     planned = null;
     constructor(emit) {
         this.emit = emit;
@@ -10,32 +13,34 @@ export class Parts {
     write(type, id, text) {
         if (text === '')
             return;
-        const last = this.parts.length - 1;
-        const part = this.parts[last];
-        if (this.writing?.type === type && this.writing.id === id && part?.type === type) {
-            part.text += text;
-            this.emit({ op: 'append', index: last, text });
+        if (this.writing?.type === type && this.writing.id === id) {
+            this.parts[this.writing.index].text += text;
+            this.emit({ op: 'append', index: this.writing.index, text });
             return;
         }
-        this.start({ type, text });
-        this.writing = { type, id };
+        this.writing = { type, id, index: this.start({ type, text }) };
     }
     command() {
-        const last = this.parts.length - 1;
-        const part = this.parts[last];
-        if (part?.type !== 'commands') {
-            this.start({ type: 'commands', count: 1 });
+        if (this.counting === null) {
+            this.counting = this.start({ type: 'commands', count: 1 });
             return;
         }
+        const part = this.parts[this.counting];
         part.count++;
-        this.emit({ op: 'count', index: last, count: part.count });
+        this.emit({ op: 'count', index: this.counting, count: part.count });
     }
     start(part) {
         this.writing = null;
-        this.parts.push(part);
-        const index = this.parts.length - 1;
-        this.emit({ op: 'start', index, part });
-        return index;
+        this.counting = null;
+        return this.add(part, ++this.events);
+    }
+    reserve() {
+        this.writing = null;
+        this.counting = null;
+        return ++this.events;
+    }
+    arrive(part, reserved) {
+        this.add(part, reserved);
     }
     done(index, result) {
         const part = this.parts[index];
@@ -55,10 +60,23 @@ export class Parts {
         this.context = context;
         this.emit({ op: 'context', ...context });
     }
+    saved() {
+        return this.parts
+            .map((part, index) => ({ part, made: this.made[index] }))
+            .sort((a, b) => a.made - b.made)
+            .map(({ part }) => part);
+    }
     operations() {
         return [
             ...this.parts.map((part, index) => ({ op: 'start', index, part })),
             ...(this.context === null ? [] : [{ op: 'context', ...this.context }]),
         ];
     }
+    add(part, made) {
+        this.parts.push(part);
+        this.made.push(made);
+        const index = this.parts.length - 1;
+        this.emit({ op: 'start', index, part });
+        return index;
+    }
 }

package/dist/placement.js

@@ -0,0 +1,48 @@
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { run } from './clis.js';
+import { kitHome } from './home.js';
+import { relayOrigin } from './relay.js';
+export function service() {
+    if (process.platform !== 'linux' || !process.env.INVOCATION_ID)
+        return null;
+    return process.env.MANAGERPID ? 'user' : 'system';
+}
+export function throughSudo() {
+    return service() === 'system' && process.getuid() !== 0;
+}
+export async function updatesItself() {
+    if (service() === null)
+        return false;
+    if (!throughSudo())
+        return true;
+    // sudo answers at once, so ten seconds only bounds a stuck sudo.
+    return (await run('sudo', ['-n', 'true'], 10_000)).status === 0;
+}
+function installed() {
+    try {
+        return readFileSync(join(kitHome(), 'placement'), 'utf8').trim();
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return null;
+        throw error;
+    }
+}
+function entries(house) {
+    const host = new URL(house).host;
+    const relay = relayOrigin();
+    if (relay === undefined)
+        return [`curl -fsSL ${host}/kit | sh`, `irm ${host}/kit.ps1 | iex`];
+    const entry = `${relay}/${host}/kit`;
+    return [`curl -fsSL ${entry} | HOUSE_KIT_RELAY=${relay} sh`, `$env:HOUSE_KIT_RELAY='${relay}'; irm ${entry}.ps1 | iex`];
+}
+export function installCommand(house) {
+    const [shell, windows] = entries(house);
+    const placement = installed();
+    if (placement === 'native')
+        return shell;
+    if (placement === 'server')
+        return `${shell} -s -- --linux`;
+    return `${shell} -s -- --container, or ${windows} on Windows`;
+}

package/dist/relay.js

@@ -1,7 +1,17 @@
+let selected;
+export function selectRelay(relay) {
+    selected = relay === undefined || relay === '' ? null : relay;
+}
+export function relayOrigin() {
+    if (selected !== undefined)
+        return selected ?? undefined;
+    const ambient = process.env.HOUSE_KIT_RELAY;
+    return ambient === undefined || ambient === '' ? undefined : ambient;
+}
 export function relayed(target) {
     const url = new URL(target);
-    const relay = process.env.HOUSE_KIT_RELAY;
-    if (relay === undefined || relay === '')
+    const relay = relayOrigin();
+    if (relay === undefined)
         return url;
     const through = new URL(`${url.host}${url.pathname}${url.search}`, `${relay}/`);
     if (url.protocol === 'wss:' || url.protocol === 'ws:')

package/dist/resident.js

@@ -7,9 +7,10 @@ import { fileURLToPath } from 'node:url';
 import { Agents } from './agents.js';
 import { house } from './api.js';
 import { received } from './bridge.js';
-import { Conversations } from './conversations.js';
+import { CONVERSATION_INPUTS, Conversations } from './conversations.js';
 import { LocalCopies } from './copies.js';
-import { agentBase, enrolled, kitHome } from './home.js';
+import { restart } from './end.js';
+import { agentBase, enrolled, forgetRestart, kitHome, restartAsked } from './home.js';
 import { killDescendants } from './scope.js';
 import { quoted } from './shell.js';
 import { SignIns } from './sign-in.js';
@@ -73,6 +74,7 @@ function connected() {
 }
 export async function resident() {
     await connected();
+    await forgetRestart();
     watch(kitHome(), () => {
         if (enrolled())
             return;
@@ -95,6 +97,9 @@ export async function resident() {
         if (!idle()) {
             reported = false;
         }
+        else if (restartAsked() && conversations.quiet()) {
+            restart('restarting for an updated CLI');
+        }
         else if (!reported) {
             reported = true;
             logged(house.deliver('/kit/idle', {}, idle));
@@ -135,8 +140,12 @@ export async function resident() {
                     signIns.start(arrived);
                 else if (arrived.kind === 'update')
                     updates.start(arrived);
-                else
+                else if (CONVERSATION_INPUTS.has(arrived.kind))
                     conversations.input(arrived);
+                else {
+                    const refused = { refused: `This Kit does not know ${arrived.kind}; update the Kit` };
+                    logged(house.deliver(`/kit/inputs/${arrived.input_id}/ack`, refused).finally(changed));
+                }
             }
         },
     });

package/dist/service-main.js

@@ -0,0 +1,9 @@
+import { startService } from './service.js';
+try {
+    if (startService())
+        process.stdout.write('started\n');
+}
+catch (error) {
+    process.stderr.write(`kit: ${error.message}\n`);
+    process.exitCode = 1;
+}

package/dist/service.js

@@ -0,0 +1,33 @@
+import { spawnSync } from 'node:child_process';
+const UNIT = 'house-kit.service';
+// launchctl and systemctl answer at once, so ten seconds only bounds a stuck service manager.
+const MANAGER_MS = 10_000;
+function manage(command, args) {
+    return spawnSync(command, args, { encoding: 'utf8', timeout: MANAGER_MS });
+}
+function start(command, args) {
+    const started = manage(command, args);
+    if (started.status === 0)
+        return;
+    const cause = started.error?.message ?? (started.stderr.trim() || `${command} exited with ${started.status ?? 'a signal'}`);
+    throw new Error(`the House Kit service could not be started: ${cause}`);
+}
+export function startService() {
+    if (process.platform === 'darwin') {
+        const service = `gui/${process.getuid()}/house-kit`;
+        const printed = manage('launchctl', ['print', service]);
+        if (printed.status !== 0 || /^\tstate = running$/m.test(printed.stdout))
+            return false;
+        start('launchctl', ['kickstart', service]);
+        return true;
+    }
+    for (const scope of [['--user'], []]) {
+        if (manage('systemctl', [...scope, 'is-enabled', '--quiet', UNIT]).status !== 0)
+            continue;
+        if (manage('systemctl', [...scope, 'is-active', '--quiet', UNIT]).status === 0)
+            return false;
+        start('systemctl', [...scope, 'start', UNIT]);
+        return true;
+    }
+    return false;
+}

package/dist/stream.js

@@ -1,10 +1,11 @@
 import { subscribe } from 'node:diagnostics_channel';
 import { finalRefusal, HouseRefusal, retryDelay } from './api.js';
-import { end, REPLACED, SIGN_IN_AGAIN } from './end.js';
+import { end, REPLACED, signInAgain, updateRequired } from './end.js';
 import { readEnrolment } from './home.js';
 import { relayed } from './relay.js';
+import { KIT_WIRE, tooOld } from './wire.js';
 const PATH = '/kit/stream';
-const SUBPROTOCOL = 'house.kit.stream.1';
+const SUBPROTOCOL = `house.kit.stream.${KIT_WIRE}`;
 const REFUSAL_HEADER = 'x-house-refusal';
 function streamUrl(house) {
     const url = new URL(PATH, house);
@@ -52,8 +53,12 @@ export function holdStream(handlers) {
             process.stderr.write(`kit: control stream closed ${event.code} ${event.reason}\n`);
             if (event.reason === 'replaced')
                 end(REPLACED);
-            if (event.reason === 'credential_rejected' || refused?.status === 401)
-                end(SIGN_IN_AGAIN);
+            if (event.reason === 'credential_rejected' || refused?.status === 401) {
+                void signInAgain(credential);
+                return;
+            }
+            if (refused !== null && tooOld(refused.text))
+                updateRequired(house);
             if (finalRefusal(refused))
                 end(refused.message);
             // A closed socket reopens in one to three seconds, spread so Kits one restart closed return apart; an opening House refused as retryable or left unanswered backs off on the jittered curve.

package/dist/update.js

@@ -4,8 +4,8 @@ import { mkdir, readFile, rm, writeFile } from 'node:fs/promises';
 import { homedir } from 'node:os';
 import { join } from 'node:path';
 import { run } from './clis.js';
-import { kitHome } from './home.js';
-const RECORD = 'outcome=$1; shift; bash "$0" --linux "$@"; printf %s "$?" > "$outcome"; systemctl start house-kit.service';
+import { kitHome, workspaceRoot } from './home.js';
+import { service, throughSudo } from './placement.js';
 function logged(error) {
     process.stderr.write(`kit: ${error instanceof Error ? error.message : String(error)}\n`);
 }
@@ -21,6 +21,21 @@ function outcome() {
 function unit(inputId) {
     return `house-kit-update-${inputId}`;
 }
+function manager() {
+    return service() === 'user' ? ['--user'] : [];
+}
+function elevated() {
+    return throughSudo() ? ['sudo', '-n'] : [];
+}
+function account() {
+    return throughSudo() ? [`--uid=${process.getuid()}`, `--gid=${process.getgid()}`] : [];
+}
+function placement() {
+    return service() === 'user' ? ['--workspace', workspaceRoot()] : ['--linux'];
+}
+function record() {
+    return `outcome=$1; shift; bash "$0" "$@"; printf %s "$?" > "$outcome"; ${[...elevated(), 'systemctl', ...manager(), 'start', 'house-kit.service'].join(' ')}`;
+}
 async function pendingInput() {
     try {
         return JSON.parse(await readFile(pending(), 'utf8')).input_id;
@@ -41,7 +56,7 @@ async function finished(inputId) {
         if (ack !== null)
             return ack;
         // systemctl answers at once, so ten seconds only bounds a stuck service manager.
-        if ((await run('systemctl', ['is-active', '--quiet', unit(inputId)], 10_000)).status !== 0) {
+        if ((await run('systemctl', [...manager(), 'is-active', '--quiet', unit(inputId)], 10_000)).status !== 0) {
             return (await recorded()) ?? { refused: 'the Kit bootstrap did not finish' };
         }
         // The bootstrap runs for minutes, so checking each second sees its outcome within a second at little cost.
@@ -50,7 +65,11 @@ async function finished(inputId) {
 }
 function rerun(script, inputId, flags) {
     return new Promise((resolve) => {
-        const child = spawn('systemd-run', [
+        const [command, ...args] = [
+            ...elevated(),
+            'systemd-run',
+            ...manager(),
+            ...account(),
             '--wait',
             '--collect',
             '--quiet',
@@ -58,11 +77,13 @@ function rerun(script, inputId, flags) {
             `--setenv=HOME=${homedir()}`,
             '/bin/sh',
             '-c',
-            RECORD,
+            record(),
             script,
             outcome(),
+            ...placement(),
             ...flags,
-        ], { stdio: ['ignore', 'ignore', 'inherit'] });
+        ];
+        const child = spawn(command, args, { stdio: ['ignore', 'ignore', 'inherit'] });
         child.on('error', () => resolve({ refused: 'no service manager runs this Kit' }));
         child.on('close', () => resolve(null));
     });

package/dist/wire.js

@@ -0,0 +1,6 @@
+import { refusalOf } from './refusals.js';
+export const KIT_WIRE = 1;
+export const KIT_WIRE_HEADER = 'x-house-kit-wire';
+export function tooOld(text) {
+    return refusalOf(text)?.code === 'kit_update_required';
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agentshouse/kit",
-  "version": "0.2.1-c53a84236c3d9",
+  "version": "0.2.1-c62e8a5e845ed",
   "description": "House Kit connects an Environment to agents.house.",
   "license": "MIT",
   "repository": {
@@ -27,7 +27,7 @@
   },
   "dependencies": {
     "@agentclientprotocol/sdk": "1.7.0",
-    "@agentshouse/mdmodel": "0.1.0-alpha.19",
+    "@agentshouse/mdmodel": "0.1.0-c68e2039f1ca8",
     "yaml": "2.9.1"
   },
   "peerDependencies": {