@fourier-labs/harbour 0.1.33 → 0.1.34

package/README.md

@@ -10,7 +10,7 @@ You describe the app in plain English inside Claude Code or Codex; the agent ins
 npx -y @fourier-labs/harbour agent-setup
 ```
 
-Paste that line into Claude Code or Codex (or a terminal). It teaches both agents the kit: it writes the `isomorph` skill for Claude Code (`~/.claude/skills/isomorph/SKILL.md`) and a fenced block in your global Codex instructions (`~/.codex/AGENTS.md`), and never touches your other skills or instructions.
+Paste that line into Claude Code or Codex (or a terminal). It teaches both agents the kit by installing the `isomorph` skill for each (`~/.claude/skills/isomorph/SKILL.md`, `~/.codex/skills/isomorph/SKILL.md`) and never touches your other skills or instructions. A skill is read only when the task matches it — a folder with `.harbour/`, an app you ask for on Isomorph — so the agent works exactly as before on everything else. (Releases up to 0.1.33 put the guide in your global Codex instructions, `~/.codex/AGENTS.md`, where every Codex session read it; running the line again takes that block out and leaves the rest of the file as it was.)
 
 That `npx` line runs the current release, but `harbour init`, `dev` and `check` afterwards run whatever `harbour` is installed on this machine. So `agent-setup` also compares the two and says, in its output and in `result.cli` of `--json` (`state`, `upgradeRequired`, `remediation`), when the installed CLI is missing or behind — a stale one carries an old kit bundle and builds an app the deployment pipeline refuses. The fix is always `npm i -g @fourier-labs/harbour`.
 
@@ -27,7 +27,7 @@ The only step you do yourself is the company sign-in: when the agent runs `harbo
 ## Commands
 
 ```
-harbour agent-setup                                        install the agent guide (Claude Code skill + Codex AGENTS.md block); idempotent; reports a missing or stale installed CLI
+harbour agent-setup                                        install the `isomorph` skill for Claude Code and Codex; idempotent; reports a missing or stale installed CLI
 harbour init --app-root <path> [--upgrade]                 starter app in an empty folder, or kit files in a Vite + React app (also runs agent-setup)
 harbour dev --app-root <path> [--reset]                    run the app locally on one loopback origin
 harbour stop --app-root <path>                             stop local services, keep data

package/dist/packages/harbour-cli/src/agent-setup.js

@@ -1,5 +1,5 @@
 import { execFile } from "node:child_process";
-import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { mkdir, readFile, rm, writeFile } from "node:fs/promises";
 import { homedir } from "node:os";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
@@ -15,26 +15,39 @@ export const MANAGED_END = "<!-- harbour:kit:end -->";
  * the kit names the package the same way a person typing it from memory would (LLD §15.5).
  */
 export const CLI_INSTALL_COMMAND = "npm i -g @fourier-labs/harbour";
-/** Where the two agents read their user-level instructions from; both honour the tools' own override variables. */
+/**
+ * Where the two agents read the user-level guide from; both honour the tools' own
+ * override variables. Both are skills — a file each tool lists by name and description
+ * and reads in full only when the task matches — so the guide costs nothing in every
+ * other session. `legacyCodexAgents` is Codex's global AGENTS.md, which releases up to
+ * 0.1.33 wrote the guide into; Codex reads that file in every session, in every
+ * folder, so the kit's rules for a non-developer's Isomorph app ("never paste logs",
+ * "end every report with three lines") were applied to all of a person's other work.
+ */
 export function agentPaths(env = process.env) {
     const home = env.HARBOUR_AGENT_HOME?.trim() || homedir();
+    const codexHome = env.CODEX_HOME?.trim() || join(home, ".codex");
     return {
         claudeSkill: join(env.CLAUDE_CONFIG_DIR?.trim() || join(home, ".claude"), "skills", "isomorph", "SKILL.md"),
-        codexAgents: join(env.CODEX_HOME?.trim() || join(home, ".codex"), "AGENTS.md")
+        codexSkill: join(codexHome, "skills", "isomorph", "SKILL.md"),
+        legacyCodexAgents: join(codexHome, "AGENTS.md")
     };
 }
 /**
- * Installs the user-level Isomorph guide for Claude Code (a skill file, wholly owned
- * by the kit) and Codex (a marker-fenced block in ~/.codex/AGENTS.md, everything else
- * in that file is kept). Idempotent: unchanged files are reported as kept. Also
- * reports which `harbour` the agent's next command will run (`result.cli`), because
- * this command is routinely reached through `npx` while everything after it is not.
+ * Installs the user-level Isomorph skill for Claude Code and Codex (one file each,
+ * wholly owned by the kit) and takes the guide back out of Codex's global AGENTS.md
+ * where an older release put it, keeping everything else in that file. Idempotent:
+ * unchanged files are reported as kept. Also reports which `harbour` the agent's next
+ * command will run (`result.cli`), because this command is routinely reached through
+ * `npx` while everything after it is not.
  */
 export async function agentSetup(env = process.env, lookups = {}) {
     const paths = agentPaths(env);
-    const result = { created: [], updated: [], kept: [], cli: await checkCliVersion(lookups) };
-    result[await upsertManagedBlock(paths.claudeSkill, `${SKILL_FRONTMATTER}\n${AGENT_GUIDE}`, {})].push(paths.claudeSkill);
-    result[await upsertManagedBlock(paths.codexAgents, [MANAGED_START, AGENT_GUIDE, MANAGED_END].join("\n"), { start: MANAGED_START, end: MANAGED_END, separator: "\n\n" })].push(paths.codexAgents);
+    const result = { created: [], updated: [], kept: [], removed: [], cli: await checkCliVersion(lookups) };
+    for (const skill of [paths.claudeSkill, paths.codexSkill])
+        result[await upsertManagedBlock(skill, `${SKILL_FRONTMATTER}\n${AGENT_GUIDE}`, {})].push(skill);
+    if (await removeManagedBlock(paths.legacyCodexAgents, { start: MANAGED_START, end: MANAGED_END }))
+        result.removed.push(paths.legacyCodexAgents);
     return result;
 }
 /** Compares the globally resolvable `harbour` with the package this process runs from. */
@@ -137,14 +150,38 @@ export async function upsertManagedBlock(file, block, options) {
     await writeFile(file, next);
     return "updated";
 }
+/**
+ * Takes the marker-fenced block out of `file`, keeping everything before and after it;
+ * a file that held nothing else is deleted. Returns whether there was a block to remove.
+ */
+export async function removeManagedBlock(file, options) {
+    const current = await readFile(file, "utf8").catch(() => undefined);
+    if (current === undefined || !current.includes(options.start) || !current.includes(options.end))
+        return false;
+    const remainder = current.replace(new RegExp(`\\n*${escape(options.start)}[\\s\\S]*?${escape(options.end)}\\n*`), "\n\n").replace(/^\n+/, "").replace(/\n*$/, "\n");
+    if (remainder.trim())
+        await writeFile(file, remainder);
+    else
+        await rm(file);
+    return true;
+}
 const escape = (value) => value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+/**
+ * Both agents show a skill to the model as this name and description and read the body
+ * only for a task that matches, so the description is the whole gate: it names the
+ * three signs of Isomorph work and rules everything else out, because "run it" or
+ * "ship it" is said about every kind of project.
+ */
+export const SKILL_DESCRIPTION = `Build, run, check and ship a company app on Isomorph (Harbour) from plain English. Use only when the folder has a .harbour/ directory, when the person names Isomorph or Harbour, or when they ask for a new app for their team in an empty folder; there, "run it", "check it", "I need Slack/Gmail/company data", "ship it" and "make it live" mean this skill. Do not use for any other project, script, question or coding task — nothing in it applies outside an Isomorph app.`;
 const SKILL_FRONTMATTER = `---
 name: isomorph
-description: Build, run, check and ship a company app on Isomorph (Harbour) from plain English. Use whenever someone wants an app for their team, says "run it", "check it", "I need Slack/Gmail/company data", "ship it" or "make it live", or when a folder has a .harbour/ directory.
+description: ${SKILL_DESCRIPTION}
 ---`;
-/** One guide, shared by the Claude Code skill and the Codex AGENTS.md block. Written for an agent working with a non-developer. */
+/** One guide, shared by the Claude Code and Codex skills. Written for an agent working with a non-developer, and only for that. */
 export const AGENT_GUIDE = `# Isomorph app kit
 
+This guide is for one job: an app that runs on Isomorph (Harbour). It applies when the folder has a \`.harbour/\` directory, when the person names Isomorph or Harbour, or when they ask for a new app for their team and the folder holds no other project. Anything else — another project, a script, a question, ordinary coding — is not this job: ignore every rule below and work as you always do. Never turn an existing project into an Isomorph app unless the person asks for that by name.
+
 The person you are working with may not be a developer. They say what they want in plain English; you build it with the Harbour kit and run every command yourself. Never ask them to type a terminal command (the one exception is sign-in, below). Turn every failure into one sentence about what happened and one about what happens next. Prefer \`--json\` output and read it yourself; never paste JSON, logs, stack traces or file contents at them.
 
 ## Getting ready (do this yourself, once per machine and folder)
@@ -157,14 +194,14 @@ The person you are working with may not be a developer. They say what they want
 
 - "run it", "show me", "let me try it" → start \`harbour dev --app-root .\` in the background (it keeps running; the first start pulls images and takes a minute or two). Wait for the line \`Harbour dev is running: http://127.0.0.1:<port>\` and give them that link. Do this unasked as soon as the first check is green — they should always have the link. Locally they are a fixture user; no company sign-in is needed.
 - "check it", "is it ok?", "is it ready?" → with dev running, \`harbour check --app-root . --json\`, then read \`.harbour/local/check-report.json\`. Failures in the app's code are yours to fix — fix, then check again until it is clean. Run the checks yourself after every change and before every ship, without being asked and without offering them as a choice.
-- "does it work?", and before you report anything as working → open the dev link in your own browser when you have one, press the control you built or changed, and read what the app shows. A green \`harbour check\` is not that proof: it answers governed AI and company systems from fixtures, so the refusals that matter (a field the company's AI route does not accept, a consent the operation does not need, a channel that is not approved) appear only when the control is really pressed. In development a Send posts for real to the approved channel — press it once to verify and tell them you did. If you have no browser, say that the button itself is untested.
+- "does it work?", and before you report anything as working → open the dev link in your own browser when you have one, press the control you built or changed, and read what the app shows. A green \`harbour check\` is not that proof: it answers governed AI and company systems from fixtures, so the refusals that matter (a field the company's AI route does not accept, a consent the operation does not need, a channel that is not approved) appear only when the control is really pressed. Test rendering, navigation, fixtures and approved reads automatically. In development a Send sends a real email or Slack message: reuse explicit authorization for that bounded test, or ask once if none exists; IT access approval alone is not permission to send. Never ask again for the same authorized test. Before a real integration test, run \`harbour integrations status --app-root . --json\`; explain pending IT approval or missing personal consent before pressing Send, and test the ready parts independently. If you have no browser, say that the button itself is untested.
 - "I need Slack / Gmail / the warehouse / company data" → a fresh \`harbour init\` declares no connection at all, which is why a new app ships with nothing waiting on IT. Never guess a connection, channel, view or mailbox name — a guessed one is refused before IT's queue ever sees it, so nothing appears for IT to approve; use the exact names the person or IT gave you, and if you have none, that is the one question to ask before declaring anything. Before asking, run \`harbour integrations catalog --app-root . --json\` — it lists the company's connections by the exact identifier \`.harbour/integrations.json\` uses, the operations IT allows on each and the approved channels, views and mailboxes per environment — and declare only identifiers and approved names it lists. Declare the connection and only the operations the app really calls in \`.harbour/integrations.json\` (the closed set is in the per-app block), then \`harbour integrations request <connection> --reason "<what the app does with it>" --app-root . --json\`. Request the preview grant in the same turn (\`--environment preview\`) so shipping does not wait on a second IT decision. READY means use it now. PENDING means IT has to approve it: say "IT has to approve this; the app works without it until then", and check later with \`harbour integrations status --app-root . --json\`. A refusal with \`RESOURCE_NOT_APPROVED\` means the channel, view or mailbox is not on the connection yet: IT adds it in the Harbour console under Controls & integrations → API integrations → the provider tile → Configure → Channels (a warehouse view: Controls & integrations → Databases → the source → Views for the environment), and then you run the same request command again. Say "IT has to add <name> to the Slack connection first; the app works without it until then" and nothing more. Never declare a connection the app does not call — every declared one blocks shipping until IT approves it.
 - "summarise", "draft", "explain", "AI" → one \`harbour.ai.chat\` call (through \`ai()\` in \`src/harbour.client.ts\`) behind a control the person presses; never an OpenAI/Anthropic key, SDK or URL. \`harbour check\` writes its journey. Send \`messages\` and \`maxTokens\` and nothing else: a refusal with \`unsupported_request_capability\` names a field the company's AI route does not accept — remove that field. A refusal with \`AI_NOT_ENABLED\` means IT has to enable an AI provider: say so in one line and keep the app working without it.
-- "ship it", "put it online", "let my team try it" → run \`harbour check --app-root . --json\` first and fix everything it finds, every time, unasked: the same gates run again in the cloud, where each failed attempt costs minutes instead of the seconds it costs here. Then each declared connection needs a preview grant (\`harbour integrations request <connection> --environment preview --reason "…" --app-root . --json\`); when the app calls governed AI, \`productionise\` also asks whether the company's AI setup is ready and refuses with \`AI_NOT_READY\` and the one IT step — say that line and nothing more; the app works without AI until then. \`harbour productionise --app-root . --wait --json\` gives them \`result.deployment.protectedUrl\`: a private preview that they, and the people they name, open after company sign-in. If your tool cuts the command off before it finishes, \`${continueCommand("<ref>")}\` continues the same deployment — never start another one to find out what happened. Keep \`operationRef\`; \`harbour setup --operation <ref> --json\` lists what is still missing (name, audience, secrets) and \`harbour profile\` / \`harbour audience\` / \`harbour secrets set\` fill it in.
+- "ship it", "put it online", "let my team try it" → run \`harbour check --app-root . --json\` first and fix everything it finds, every time, unasked: the same gates run again in the cloud, where each failed attempt costs minutes instead of the seconds it costs here. Then each declared connection needs a preview grant (\`harbour integrations request <connection> --environment preview --reason "…" --app-root . --json\`); when the app calls governed AI, \`productionise\` also asks whether the company's AI setup is ready and refuses with \`AI_NOT_READY\` and the one IT step — say that line and nothing more; the app works without AI until then. \`harbour productionise --app-root . --wait --json\` gives them \`result.deployment.protectedUrl\`: a private preview that they, and the people they name, open after company sign-in. If your tool cuts the command off before it finishes, \`${continueCommand("<ref>")}\` continues the same deployment — never start another one to find out what happened. For kit apps, describe \`TRANSFORMING\` as building and checking the app; it does not mean a transformation AI is running. The CLI saves \`operationRef\` in \`.harbour/local/productionise.json\`; repeating \`productionise\` continues that operation. Keep \`operationRef\`; \`harbour setup --operation <ref> --json\` lists what is still missing (name, audience, secrets) and \`harbour profile\` / \`harbour audience\` / \`harbour secrets set\` fill it in.
 - "make it live for everyone", "go to production" → only after they have tried the preview: \`harbour promote --operation <ref> --json\` with the operation reference from productionise. Report the production link, or that an operator approval is pending.
 - "stop it" → \`harbour stop --app-root .\` (local data kept). \`harbour dev --reset --app-root .\` deletes local data — only when they explicitly ask to start over.
 
-When a command refuses, the refusal names its own reason and its own fix: change that one thing, then run it again. Sending the same app again unchanged gets the same answer every time, so a repeat attempt is never the next step — and never start a second deploy of an app while one is running, because concurrent deploys of one app cancel each other.
+When a command refuses, the refusal names its own reason and its own fix: change that one thing, then run it again. A failed app needs its reported fix; a wait timeout means work is still running, so continue the saved operation — and never start a second deploy of an app while one is running, because concurrent deploys of one app cancel each other.
 
 ## Building the app
 
@@ -172,7 +209,7 @@ When a command refuses, the refusal names its own reason and its own fix: change
 - Authentication is Harbour SSO: no login forms, no roles or ids trusted from the browser; row ownership is decided in SQL through \`current_setting('harbour.user_id', true)\`. Every route needs a signed-in person; no public routes.
 - Schema changes are SQL files in \`migrations/\` with row-level security and GRANTs to \`harbour_app_gateway\`; \`harbour dev\` and \`harbour check\` apply them.
 - Know the operation's input bounds before writing a call: \`slack.channel.history\` \`input.limit\` 1..15, \`gmail.thread.list\` \`input.limit\` 1..15, \`warehouse.view.read\` \`input.limit\` 1..1000 (the connector's \`VIEW_READ_MAX_LIMIT\`); anything larger is refused with \`INPUT_INVALID\`, so page instead of asking for more.
-- A Slack message or an email (\`slack.message.post\`, \`gmail.message.send\`) is sent only when the person presses an explicit Send control, with a fresh UUID \`idempotencyKey\` per press (reused only to retry that press). Never send from an effect, a timer, a queue or during checks. Consent (\`harbour.integrations.connect\`) exists only for user-identity operations (\`slack.channel.history\`, \`gmail.thread.list\`, \`gmail.message.read\`, \`gmail.message.send\`, and \`slack.message.post\` declared \`"identity": "user"\`); app-identity operations (\`slack.message.post\` declared \`"identity": "app"\`, \`warehouse.view.read\`) never call it — a connect for them is refused as unapproved user access and puts nothing in IT's queue. Missing consent never falls back to another account.
+- A Slack message or an email (\`slack.message.post\`, \`gmail.message.send\`) is sent only from an explicit Send control (pressed by the person, or by you for an explicitly authorized test), with a fresh UUID \`idempotencyKey\` per press (reused only to retry that press). Never send from an effect, a timer, a queue or during checks. Consent (\`harbour.integrations.connect\`) exists only for user-identity operations (\`slack.channel.history\`, \`gmail.thread.list\`, \`gmail.message.read\`, \`gmail.message.send\`, and \`slack.message.post\` declared \`"identity": "user"\`); app-identity operations (\`slack.message.post\` declared \`"identity": "app"\`, \`warehouse.view.read\`) never call it — a connect for them is refused as unapproved user access and puts nothing in IT's queue. Missing consent never falls back to another account.
 - A Slack message is posted either as the app (\`"identity": "app"\` — the company's one Slack bot, Isomorph AI, under the name IT approved: declare \`"presentation": { "displayName": "<app name>", "iconEmoji": ":sandwich:" }\` on the connection and IT sees "posts as" before approving; leave it out to post as Isomorph AI itself) or as the person (\`"identity": "user"\` — their own Slack account, after their consent; an older consent answers \`USER_RECONNECT_REQUIRED\` "reconnect Slack to allow posting as you", so offer Connect again) — never pretend one is the other. The declaration in \`.harbour/integrations.json\` is the mode the app requests access for; a post names the approved mode it runs under with \`mode: "app"\` or \`mode: "user"\` on the execute call — optional while the app is approved for one mode, required once IT approved both (\`MODE_REQUIRED\`), and a mode IT has not approved is refused with \`MODE_NOT_GRANTED\`, never swapped for the other. An app-mode post always ends with "Posted by <app> on Isomorph". A post is refused with \`RESOURCE_NOT_APPROVED\` until the bot is in the channel: say "IT (or anyone in the channel) has to run \`/invite @Isomorph AI\` in #<channel> first".
 - No secrets, tokens, \`.env\` values or fetched company content in source. \`.harbour/local/\` is never committed; \`.harbour/integrations.json\` and \`.harbour/kit.lock.json\` are.
 
@@ -180,5 +217,5 @@ When a command refuses, the refusal names its own reason and its own fix: change
 
 - Plain words, short: "Your app is running at <link>.", "All 6 checks passed.", "One check failed: votes were not being saved — fixed, checking again.", "IT has to approve Slack; the app works without it until then."
 - Say what happens next and roughly how long it takes. Report only what you observed; if something is unknown, say so.
-- End every report with three short lines: what works now; what does not yet, and who unblocks it; what you decided for them (a fixed list instead of AI, a schedule the platform cannot run, a feature you left out). A decision of yours never passes as theirs, or as done.
+- Keep app reports natural and brief: say what you actually verified, any remaining blocker and who can resolve it, and any material scope decision you made. Do not force headings or repeat unchanged status. A platform check is not proof that the main task worked in the browser.
 - End a turn with at most one question, and only when a decision is genuinely theirs to make and you cannot go on without it. Never offer to do something this guide already tells you to do unasked — do it and report what happened.`;

package/dist/packages/harbour-cli/src/check.js

@@ -33,7 +33,7 @@ export async function runChecks(root, options) {
     const sdk = await ensureSdk(root, bundle, options.env ?? process.env, run, output).catch(error => { output(error instanceof Error ? error.message : String(error)); return "missing"; });
     if (sdk === "missing")
         output("The kit SDK is not installed: set HARBOUR_KIT_SDK_TARBALL to the bundle's @harbour/app-sdk tarball (or use a bundle with sdk.url).");
-    const gate = await runKitGate(root, { run, bundle, output, ...(options.fetch ? { fetch: options.fetch } : {}) });
+    const gate = await runKitGate(root, { run, bundle, output, ...(options.fetch ? { fetch: options.fetch } : {}), ...(options.runtime ? { runtime: options.runtime } : {}) });
     for (const check of gate.checks)
         record(check);
     let integrations = "not tested";
@@ -91,9 +91,8 @@ function renderCheck(check) {
 }
 /**
  * Runs the pipeline's kit gate in this app's local session: the pinned
- * gateway image's `gate` subcommand as a one-shot service of the Compose
- * project (the app mounted read-only, a scratch database on the session
- * PostgreSQL, the session bucket). The gate's control API drives two things
+ * native gateway's `gate` subcommand as a one-shot process using the local
+ * session's scratch database and files. The gate's control API drives two things
  * from here: the `checks` phase, where the gate hands over the app's tables
  * as its replayed database holds them and `.harbour/checks/` is regenerated
  * from them (retained-checks.ts) and handed back as the set to run; and the
@@ -104,7 +103,7 @@ function renderCheck(check) {
 export async function runKitGate(root, options) {
     const { run, bundle, output } = options;
     const fetchImpl = options.fetch ?? fetch;
-    const runtime = new LocalRuntime(root, run);
+    const runtime = options.runtime ?? new LocalRuntime(root, run);
     const started = await ensureSession(root, runtime, bundle, output);
     const port = await freePort();
     const base = `http://127.0.0.1:${port}`;
@@ -118,7 +117,7 @@ export async function runKitGate(root, options) {
     } };
     const post = (path, body) => request(path, { method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify(body) });
     // Everything after the session is up runs under one `finally`: a gate
-    // container that fails to start is exactly the case that used to leave a
+    // gate process that fails to start is exactly the case that could leave a
     // session this run had started still running.
     let container;
     try {
@@ -217,19 +216,19 @@ async function ensureSession(root, runtime, bundle, output) {
  * `productionise` pre-flight for a kit app: the same gate the pipeline runs,
  * here, before any operation exists. A failed check is refused with the
  * pipeline's own wording (kit.check-failed: <check>); a local runtime that
- * cannot start (no Docker) is reported and skipped — the pipeline's gate
+ * cannot start is reported and skipped — the pipeline's gate
  * still runs.
  */
-export async function preflightKitGate(root, bundle, output, run = runCommand, fetchImpl) {
+export async function preflightKitGate(root, bundle, output, run = runCommand, fetchImpl, runtime) {
     const lock = await readKitLock(root).catch(() => undefined);
     if (!lock)
         return "skipped";
     let report;
     try {
-        report = await runKitGate(root, { run, bundle, output, ...(fetchImpl ? { fetch: fetchImpl } : {}) });
+        report = await runKitGate(root, { run, bundle, output, ...(fetchImpl ? { fetch: fetchImpl } : {}), ...(runtime ? { runtime } : {}) });
     }
     catch (error) {
-        if (error instanceof CliError && ["LOCAL_RUNTIME_FAILED", "KIT_IMAGES_UNAVAILABLE"].includes(error.code)) {
+        if (error instanceof CliError && ["LOCAL_RUNTIME_FAILED", "KIT_IMAGES_UNAVAILABLE", "KIT_RUNTIME_UNAVAILABLE"].includes(error.code)) {
             output(`The kit gate was not run locally (${error.message}); the pipeline's gate will run in CodeBuild.`);
             return "skipped";
         }

package/dist/packages/harbour-cli/src/cli.js

@@ -12,9 +12,9 @@ import { initKit } from "./starter.js";
 import { agentPaths, agentSetup, cliVersionLines } from "./agent-setup.js";
 import { startDev } from "./dev.js";
 import { ensureSdk, LocalRuntime, readDevLock, releaseDevLock, runCommand } from "./local-runtime.js";
-import { stopAllHarbourProjects } from "./docker-networks.js";
 import { runChecks } from "./check.js";
 import { assertAiReady, GovernanceClient, integrationsCatalog, integrationsStatus, renderIntegrationsCatalog, requestIntegrations } from "./integrations.js";
+import { runJob } from "./jobs.js";
 const args = process.argv.slice(2);
 const command = args[0];
 const connectUrl = args[1];
@@ -31,14 +31,13 @@ const valueStdin = args.includes("--value-stdin");
 const subcommand = args[1] && !args[1].startsWith("--") ? args[1] : undefined;
 const wait = args.includes("--wait");
 const reset = args.includes("--reset");
-const stopAll = args.includes("--all");
-const force = args.includes("--force");
 const upgrade = args.includes("--upgrade");
 const testIntegrations = args.includes("--integrations");
 const reason = optionValue("--reason");
 const environment = optionValue("--environment");
 const operations = optionValue("--operations");
 const expiresAt = optionValue("--expires-at");
+const scheduledAt = optionValue("--scheduled-at");
 /** Seconds `productionise`, `status --wait`, `retry` and `promote` follow the operation before reporting it as still running (default: 30 minutes). */
 const maxWaitSeconds = args.includes("--max-wait") ? Number(optionValue("--max-wait")) : undefined;
 const waitOptions = maxWaitSeconds ? { maxWaitMs: maxWaitSeconds * 1000 } : {};
@@ -72,12 +71,12 @@ const usage = [
     "  harbour secrets list --operation <reference> [--json]",
     "  harbour secrets set --operation <reference> --name <NAME> [--personal] [--value-stdin]",
     "  harbour secrets dismiss --operation <reference> --name <NAME>",
-    "  harbour agent-setup [--json]                               install the plain-English Isomorph guide for Claude Code (~/.claude/skills/isomorph) and Codex (~/.codex/AGENTS.md)",
+    "  harbour agent-setup [--json]                               install the plain-English Isomorph skill for Claude Code (~/.claude/skills/isomorph) and Codex (~/.codex/skills/isomorph)",
     "  harbour init --app-root <path> [--upgrade]                 create the starter or add the kit files; --upgrade re-pins the kit bundle (also runs agent-setup)",
     "  harbour dev --app-root <path> [--reset]                    run the app locally on one loopback origin (--reset deletes this app's local data)",
-    "  harbour stop --app-root <path>                             stop this app's local services (containers and network removed), keeping data",
-    "  harbour stop --all [--force]                               bring down every stopped Harbour app's local services on this machine (frees Docker's network pool); --force includes running ones",
+    "  harbour stop --app-root <path>                             stop this app's local services, keeping its database and files",
     "  harbour check --app-root <path> [--integrations] [--json]  types, build, then the pipeline's kit gate in the local session: declaration, migrations + database gate, write probe with cross-user denial, journeys, operation coverage (+ authorised real reads)",
+    "  harbour jobs run <name> --app-root <path> [--scheduled-at <UTC>] [--json]  run one scheduled job now against the local services",
     "  harbour integrations request <connection> --reason <text> --app-root <path> [--environment <env>] [--operations a,b] [--expires-at <UTC>] [--json]",
     "  harbour integrations status --app-root <path> [--json]",
     "  harbour integrations catalog --app-root <path> [--json]   the company's connections as .harbour/integrations.json names them: identifiers, allowed operations, approved channels/views/mailboxes per environment (no app needed)",
@@ -89,7 +88,7 @@ const usage = [
     ""
 ].join("\n");
 const OPERATION_COMMANDS = ["status", "retry", "promote", "setup", "profile", "audience", "secrets"];
-const LOCAL_COMMANDS = ["init", "dev", "stop", "check"];
+const LOCAL_COMMANDS = ["init", "dev", "stop", "check", "jobs"];
 const progress = (message) => { process.stderr.write(`${message}\n`); };
 /** Envelope for commands that start no Harbour operation (local kit commands, integrations). */
 const summaryEnvelope = (result) => ({ schema: "harbour.cli-result/1.0", cliVersion: CLI_VERSION, status: "SUCCEEDED", operationStarted: false, result });
@@ -102,10 +101,12 @@ else if (!command || command === "help" || command === "--help" || args.includes
 }
 else if (command === "agent-setup") {
     const result = await agentSetup(process.env);
-    for (const state of ["created", "updated", "kept"])
+    for (const state of ["created", "updated", "kept", "removed"])
         for (const path of result[state])
             progress(`${state.padEnd(7)} ${path}`);
-    progress("Claude Code: the `isomorph` skill is available in every folder. Codex: the block is in your global AGENTS.md. Say what you want to build; the agent installs and runs the kit itself.");
+    if (result.removed.length)
+        progress("The guide is no longer in your global Codex instructions, where every session read it; Codex now has it as a skill, like Claude Code.");
+    progress("Claude Code and Codex: the `isomorph` skill is installed. Each agent uses it only for an Isomorph app (a folder with .harbour/, or an app you ask it to build) and works as usual everywhere else. Say what you want to build; the agent installs and runs the kit itself.");
     // Which `harbour` the next command will run. This command is usually reached through
     // `npx …@stable`, which tells you nothing about the CLI that does the actual work.
     if (result.cli)
@@ -117,14 +118,15 @@ else if (!["connect", "login", "logout", "productionise", "integrations", ...LOC
     || (command === "connect" && (!connectUrl || connectUrl.startsWith("--")))
     || (["productionise", "status", "retry", "promote"].includes(command) && optionError)
     || (command === "productionise" && !root)
-    || (LOCAL_COMMANDS.includes(command) && !root && !(command === "stop" && stopAll))
+    || (LOCAL_COMMANDS.includes(command) && !root)
+    || (command === "jobs" && (subcommand !== "run" || !args[2] || args[2].startsWith("--")))
     || (command === "integrations" && (!root || !subcommand || !["request", "status", "catalog"].includes(subcommand) || (subcommand === "request" && (!args[2] || args[2].startsWith("--") || !reason))))
     || (OPERATION_COMMANDS.includes(command) && !operationRef)
     || (command === "secrets" && (!subcommand || !["list", "set", "dismiss"].includes(subcommand) || (subcommand !== "list" && !secretName)))) {
     if (optionError)
         process.stderr.write(`${optionError}\n`);
     process.stderr.write(usage);
-    process.exitCode = 2;
+    process.exit(2);
 }
 else {
     try {
@@ -133,15 +135,6 @@ else {
             process.stdout.write(`Harbour is connected for ${saved.tenantId}.\n`);
             process.exitCode = 0;
         }
-        else if (command === "stop" && stopAll) {
-            // Every Harbour project on this machine, no app root needed: the complete remedy for a full Docker address pool.
-            const result = await stopAllHarbourProjects(runCommand, { force });
-            for (const project of result.stopped)
-                progress(`Brought down ${project.root ?? project.project} (data kept).`);
-            for (const project of result.running)
-                progress(`Left ${project.root ?? project.project} running; \`harbour stop --app-root ${project.root ?? "<path>"}\` or \`--force\` stops it.`);
-            emit(summaryEnvelope({ stopped: result.stopped.map(project => project.root ?? project.project), running: result.running.map(project => project.root ?? project.project), volumesRetained: true }));
-        }
         else if (LOCAL_COMMANDS.includes(command)) {
             // Local commands run before the company config/login requirement: the base app needs neither.
             const bundle = EMBEDDED_KIT_BUNDLE;
@@ -200,6 +193,11 @@ else {
                 else
                     emit(summaryEnvelope(report));
             }
+            else if (command === "jobs") {
+                const result = await runJob(target, args[2], scheduledAt, runCommand);
+                progress(`Job ${result.name} completed for ${result.scheduledAt}.`);
+                emit(summaryEnvelope(result));
+            }
             else {
                 const started = await startDev(target, { bundle, output: progress, reset, company: config ? { apiUrl: config.apiUrl, tenantId: config.tenantId, accessToken: companyToken, account: async () => { const token = await companyToken(); return token ? connectedAccount(config.mcpUrl, config.tenantId, token) : undefined; } } : undefined });
                 let stopping = false;
@@ -290,7 +288,7 @@ else {
         if (json || command === "productionise")
             process.stdout.write(`${JSON.stringify(envelope)}\n`);
         // Exit 2, like a usage error: nothing started and the fix is a command the maker runs.
-        process.exitCode = envelope.error?.code === "INTEGRATIONS_NOT_READY" || envelope.error?.code === "AI_NOT_READY" ? 2 : 1;
+        process.exit(envelope.error?.code === "INTEGRATIONS_NOT_READY" || envelope.error?.code === "AI_NOT_READY" ? 2 : 1);
     }
 }
 function renderIntegrationsStatus(status) {

package/dist/packages/harbour-cli/src/dev.js

@@ -5,9 +5,8 @@ import { GovernanceClient, ensureLinkedApp } from "./integrations.js";
 import { acquireDevLock, allocatePorts, ensureSdk, LocalRuntime, releaseDevLock, runCommand } from "./local-runtime.js";
 import { CliError } from "./output.js";
 /**
- * Starts the project's Compose services, applies migrations, starts Vite and the
- * loopback origin. Resolves when the runtime is up; the returned `stop` runs
- * `docker compose down` without `-v` (volumes retained, network freed) and is what Ctrl-C calls.
+ * Starts the kit-managed Postgres and App Gateway, applies migrations, then
+ * starts Vite and the loopback origin. Stopping retains the app's local data.
  */
 export async function startDev(root, options) {
     const run = options.run ?? runCommand;

package/dist/packages/harbour-cli/src/jobs.js

@@ -0,0 +1,49 @@
+import { readdir, readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { pathToFileURL } from "node:url";
+import { CliError } from "./output.js";
+import { parseSessionEnv, readDevLock, runCommand } from "./local-runtime.js";
+import { kitPaths } from "./kit.js";
+const jobName = /^[a-z0-9][a-z0-9_-]{0,63}$/;
+const scheduleDeclaration = /^export\s+const\s+schedule\s*=\s*["']([^"']+)["']\s*;?\s*$/m;
+export async function discoverJobs(root) {
+    const directory = join(root, "jobs");
+    const entries = await readdir(directory, { withFileTypes: true }).catch(() => []);
+    const jobs = [];
+    for (const entry of entries) {
+        if (!entry.isFile() || !entry.name.endsWith(".ts"))
+            continue;
+        const name = entry.name.slice(0, -3);
+        if (!jobName.test(name))
+            throw new CliError("JOB_INVALID", `jobs/${entry.name}: the file name must be a lowercase logical name.`);
+        const path = join(directory, entry.name);
+        const source = await readFile(path, "utf8");
+        const schedule = source.match(scheduleDeclaration)?.[1];
+        if (!schedule)
+            throw new CliError("JOB_INVALID", `jobs/${entry.name}: export one literal schedule, for example export const schedule = \"0 9 * * 1-5\".`);
+        if (!/^export\s+default\s+/m.test(source))
+            throw new CliError("JOB_INVALID", `jobs/${entry.name}: export one default job handler.`);
+        jobs.push({ name, schedule, path });
+    }
+    return jobs.sort((a, b) => a.name.localeCompare(b.name));
+}
+export async function runJob(root, name, scheduledAt, run = runCommand) {
+    if (!jobName.test(name))
+        throw new CliError("JOB_INVALID", "A valid job name is required.");
+    const job = (await discoverJobs(root)).find(candidate => candidate.name === name);
+    if (!job)
+        throw new CliError("JOB_NOT_FOUND", `No job named ${name} exists under jobs/.`);
+    const timestamp = scheduledAt ?? new Date().toISOString();
+    if (Number.isNaN(Date.parse(timestamp)))
+        throw new CliError("JOB_INVALID", "--scheduled-at must be an ISO 8601 timestamp.");
+    const session = await readFile(join(kitPaths(root).state, "session.env"), "utf8").catch(() => "");
+    const lock = await readDevLock(root);
+    if (!session || !lock)
+        throw new CliError("DEV_NOT_RUNNING", "Start `harbour dev` before running a job so it uses the same local data and identity boundary.");
+    const env = parseSessionEnv(session);
+    const runner = `const module = await import(${JSON.stringify(pathToFileURL(job.path).href)}); if (typeof module.default !== "function") throw new Error("job has no default handler"); await module.default({scheduledAt: process.env.HARBOUR_SCHEDULED_AT});`;
+    const result = await run(process.execPath, ["--experimental-strip-types", "--input-type=module", "--eval", runner], { cwd: root, env: { ...env, HARBOUR_GATEWAY_URL: `http://127.0.0.1:${lock.ports.gateway}`, HARBOUR_SCHEDULED_AT: timestamp } });
+    if (result.code !== 0)
+        throw new CliError("JOB_FAILED", `Job ${name} failed: ${result.stderr.trim().split("\n").at(-1) ?? "process exited non-zero"}`);
+    return { name, schedule: job.schedule, scheduledAt: timestamp };
+}

package/dist/packages/harbour-cli/src/kit-bundle.manifest.js

@@ -1,18 +1,18 @@
 export const PUBLISHED_KIT_BUNDLE = {
     "schema": "harbour.kit-bundle/1.0",
-    "kitVersion": "0.1.33",
+    "kitVersion": "0.1.34",
     "sdk": {
         "package": "@harbour/app-sdk",
-        "version": "1.1.0",
-        "tarballSha256": "3f7ee9d3f7161e8fdb1f7eb89e045c6288a919a72902dbc5bf68ec73e6e578ce",
-        "url": "https://public.ecr.aws/v2/y6t4p3i8/harbour-kit-bundle/blobs/sha256:3f7ee9d3f7161e8fdb1f7eb89e045c6288a919a72902dbc5bf68ec73e6e578ce"
+        "version": "1.1.1",
+        "tarballSha256": "49bb5c10f0b1825c2051add7b0975c06a64a0468b50e5feec091281952c2db57",
+        "url": "https://public.ecr.aws/v2/y6t4p3i8/harbour-kit-bundle/blobs/sha256:49bb5c10f0b1825c2051add7b0975c06a64a0468b50e5feec091281952c2db57"
     },
     "images": {
-        "appGateway": "public.ecr.aws/y6t4p3i8/harbour-app-gateway@sha256:7f96a6d1c4f78164d4c4b22fe49e784e87674600bbdae31d8098b2ea6833de11",
-        "sessionFixture": "public.ecr.aws/y6t4p3i8/harbour-session-fixture@sha256:573fb296161d57303bddf5e8134de0384ab4e9ae768d81ff09e84d6ef31c58a6"
+        "appGateway": "public.ecr.aws/y6t4p3i8/harbour-app-gateway@sha256:2d134fb8d4a10d4c25d22cb0df4da31ae91c9168d97cd99856d4677b41885077",
+        "sessionFixture": "public.ecr.aws/y6t4p3i8/harbour-session-fixture@sha256:b7f896aff3c88ecdd883a4f22b83741d2ad9c13fed6b21adabdff126ffff1f35"
     },
     "brief": {
-        "fingerprint": "4b3c61acdce47995c15e5ce8c38d5e636a624cd79ef7bebb9401b6228d129d11"
+        "fingerprint": "77cc3e0d6bc83c09b5c3ccbfebde644cc4143d77517a224d27f3e8a1aa541814"
     },
     "declarationSchema": "harbour.app-integrations/2.0"
 };

package/dist/packages/harbour-cli/src/kit.js

@@ -108,9 +108,9 @@ export function appRoot(rootArg) {
 export function kitPaths(root) {
     const harbour = join(root, ".harbour");
     const local = join(harbour, "local");
-    return { harbour, local, declaration: join(harbour, "integrations.json"), lock: join(harbour, "kit.lock.json"), checks: join(harbour, "checks"), compose: join(local, "compose.yml"), gatewayConfig: join(local, "app-gateway.json"), devLock: join(local, "dev.lock"), state: join(local, "state"), report: join(local, "check-report.json") };
+    return { harbour, local, declaration: join(harbour, "integrations.json"), lock: join(harbour, "kit.lock.json"), checks: join(harbour, "checks"), gatewayConfig: join(local, "app-gateway.json"), devLock: join(local, "dev.lock"), state: join(local, "state"), report: join(local, "check-report.json") };
 }
-/** Stable per-project identity for Compose projects and volumes: `harbour-<12 hex of sha256(abs root)>`. */
+/** Stable per-project identity for the kit-managed local state. */
 export function projectName(root, suffix = "") {
     return `harbour-${createHash("sha256").update(resolve(root)).digest("hex").slice(0, 12)}${suffix}`;
 }