@junoflow/cli 0.11.0 → 0.13.0

package/README.md

@@ -178,6 +178,15 @@ The group's working-copy commands (`integration init`, `gen-types`,
 | `juno webhook write`          | `write_webhook`          | `id`       | change |
 | `juno webhook fire`           | `fire_webhook`           | `id`       | act    |
 
+**`job`** (external jobs)
+
+| Command                              | Tool           | Positional | Effect |
+| ------------------------------------ | -------------- | ---------- | ------ |
+| `juno job list`                      | `list_jobs`    | —          | read   |
+| `juno job get-runs`                  | `get_job_runs` | `id`       | read   |
+| `juno job write`                     | `write_job`    | `id`       | change |
+| `juno job run [<url>] -- <command>…` | none           | ping URL   | act    |
+
 **`credential`**
 
 | Command                    | Tool               | Positional    | Effect |
@@ -185,6 +194,14 @@ The group's working-copy commands (`integration init`, `gen-types`,
 | `juno credential list`     | `list_credentials` | —             | read   |
 | `juno credential set <id>` | none               | credential id | act    |
 
+**`person`**
+
+| Command             | Tool           | Positional | Effect |
+| ------------------- | -------------- | ---------- | ------ |
+| `juno person list`  | `list_people`  | —          | read   |
+| `juno person get`   | `get_person`   | `id`       | read   |
+| `juno person write` | `write_person` | `id`       | change |
+
 **`ha`** (Home Assistant)
 
 | Command                      | Tool                 | Positional  | Effect |
@@ -319,6 +336,32 @@ exits 1 without sending anything otherwise. Any other message sent to a session
 waiting for an approval denies it, and the assistant sees the message as the
 reason.
 
+### `juno job run`
+
+Wraps a scheduled command so its runs are reported to an external job's ping URL
+(`juno job write` answers it as `url`):
+
+```bash
+juno job run https://juno.example/ping/<token> -- ./backup.sh --full
+juno job run --url-file .secrets/juno-jobs/backup -- ./backup.sh --full
+JUNO_JOB_URL=https://juno.example/ping/<token> juno job run -- python3 check.py
+```
+
+The command runs exactly as it would unwrapped: same stdin, the same stdout and
+stderr bytes as they arrive, the same exit status (`128 + N` when killed by
+signal `N`; 127, or 126 for a file that is not executable, when it cannot be
+started). Everything after `--` is the command's, flags included. Juno gets a
+`start`, then the exit status with the last 64 KiB of stdout and stderr, paired
+by a run id. The URL comes from the argument, else `--url-file` (keeps the token
+out of `ps`), else `$JUNO_JOB_URL`; nothing else is read — no instance config,
+no API key. A report that fails is retried once and then dropped silently
+(`--verbose` prints one line): Juno turns a run it never heard about into an
+overdue finding by itself. `SIGINT`, `SIGTERM` and `SIGHUP` are passed on to the
+command.
+
+See [External jobs](https://boivie.github.io/juno/external-jobs/) for creating
+the job, the ping protocol, and systemd and crontab examples.
+
 ### `juno credential set`
 
 ```bash
@@ -518,6 +561,29 @@ keeps them in `package.json` alone, so there `pull` leaves `dependencies` as it
 is. It refuses to overwrite uncommitted changes in a git working tree unless you
 pass `--force`.
 
+### The source, and the warning
+
+Every kind's `check` and `deploy` send where the working copy sits in git: the
+`origin` remote (the first remote without one; any user, password, query or
+fragment stripped), the `HEAD` sha, and `dirty` when `git status` reports a
+change or an untracked file under the working copy's directory. Outside git, or
+before the first commit, they send nothing and deploy as usual. Juno records it
+on the version, which is from then on **remote**: its source of truth is this
+working copy, not Juno.
+
+When a deploy moves the artifact's source, or replaces a version written in Juno
+since your last pull, the instance answers one sentence and the CLI prints it on
+stderr:
+
+```text
+warning: flow "porch-light" was local; v8 is remote from now on — change it in the working copy and deploy.
+```
+
+It is never a failure: the deploy has happened, and the exit code is what it
+would have been. `check` prints the warning the deploy would. With `--json` the
+sentence is the body's `source_warning`. See
+[Where the Source Lives](https://boivie.github.io/juno/assistant/source/).
+
 ## Flows as files
 
 ```bash

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@junoflow/cli",
-  "version": "0.11.0",
+  "version": "0.13.0",
   "description": "Develop Juno flows, integrations and apps, and operate a Juno instance from the command line",
   "license": "MIT",
   "repository": {
@@ -40,7 +40,7 @@
     "node": ">=20"
   },
   "dependencies": {
-    "@junoflow/eslint-plugin": "0.11.0",
+    "@junoflow/eslint-plugin": "0.13.0",
     "@typescript-eslint/parser": "^8.0.0"
   },
   "devDependencies": {

package/src/api.js

@@ -87,9 +87,10 @@ export class JunoClient {
    *
    * It does not go through #workingCopyJSON, whose 422-without-diagnostics
    * wording differs from what this route has always printed; only the 409 is
-   * shared.
+   * shared. `origin` (gitOrigin) is sent when given, dry runs included: they
+   * stamp nothing, but their source_warning says what a deploy would.
    */
-  async ingest(project, { dryRun = false, id, baseVersion } = {}) {
+  async ingest(project, { dryRun = false, id, baseVersion, origin } = {}) {
     const path = `/api/integrations/ingest${dryRun ? '?dry_run=true' : ''}`;
     const res = await this.#request('POST', path, {
       manifest: project.manifest,
@@ -98,6 +99,7 @@ export class JunoClient {
       lockfile: project.lockfile ?? undefined,
       id: id ?? undefined,
       base_version: baseVersion ?? undefined,
+      origin: origin ?? undefined,
     });
     if (res.status === 409) throw new ConflictError(problemDetail(res));
     return this.#answer('POST', path, res);
@@ -187,16 +189,20 @@ export class JunoClient {
    * POST /api/flows/ingest — verify a flow working copy and, unless dryRun,
    * commit and activate it. `files` is the working copy's src/ tree, path →
    * content. `baseVersion` undefined sends none (a new flow,
-   * or --force). A 409 is a ConflictError; a 422 with diagnostics is a
-   * DiagnosticsError.
+   * or --force). `origin` (gitOrigin) is sent when given. A 409 is a
+   * ConflictError; a 422 with diagnostics is a DiagnosticsError.
    */
-  async ingestFlow({ flowId, manifest, files, baseVersion }, { dryRun } = {}) {
+  async ingestFlow(
+    { flowId, manifest, files, baseVersion },
+    { dryRun, origin } = {}
+  ) {
     const query = dryRun ? '?dry_run=true' : '';
     return this.#workingCopyJSON(`/api/flows/ingest${query}`, {
       flow_id: flowId,
       manifest,
       files,
       base_version: baseVersion ?? undefined,
+      origin: origin ?? undefined,
     });
   }
 
@@ -227,11 +233,12 @@ export class JunoClient {
    * `baseVersion` undefined sends none (a copy that records no base, or
    * --force). When activating, a 409 is a ConflictError: the app's active
    * version is not the copy's base. A draft is never refused; the answer's
-   * `stale_base` carries the sentence instead.
+   * `stale_base` carries the sentence instead. `origin` (gitOrigin) is sent
+   * when given.
    */
   async ingestApp(
     { manifest, files, lockfile },
-    { activate = true, baseVersion } = {}
+    { activate = true, baseVersion, origin } = {}
   ) {
     return this.#workingCopyJSON('/api/apps/ingest', {
       manifest,
@@ -239,6 +246,7 @@ export class JunoClient {
       lockfile: lockfile ?? undefined,
       activate,
       base_version: baseVersion ?? undefined,
+      origin: origin ?? undefined,
     });
   }
 

package/src/commands/app-check.js

@@ -1,10 +1,15 @@
 import { connect } from '../api.js';
 import { readAppProject } from '../app-project.js';
-import { printDiagnosticsJSON, printJSON } from '../diagnostics.js';
+import {
+  printDiagnosticsJSON,
+  printJSON,
+  printSourceWarning,
+} from '../diagnostics.js';
 import { DiagnosticsError } from '../errors.js';
 import { EXIT_CONFLICT } from '../exit.js';
 import { runLocalChecks } from './check.js';
 import { warnOnDependencyDrift } from './flow-check.js';
+import { gitOrigin } from '../working-copy.js';
 
 export const APP_CHECK_USAGE = 'juno app check [--skip-local] [--json]';
 
@@ -35,6 +40,7 @@ export async function appCheck(argv, io) {
     result = await client.ingestApp(project, {
       activate: false,
       baseVersion: project.baseVersion,
+      origin: await gitOrigin(io.cwd, io.env),
     });
   } catch (err) {
     if (argv.json && err instanceof DiagnosticsError) {
@@ -47,6 +53,7 @@ export async function appCheck(argv, io) {
     printJSON(result, io);
   } else {
     for (const w of result.warnings ?? []) io.warn(`warning: ${w}`);
+    printSourceWarning(result, io);
     io.log(
       `${result.id}: verified and stored as draft v${result.version} on ${target}`
     );

package/src/commands/app-deploy.js

@@ -8,10 +8,15 @@ import {
   SRC_DIR,
   updateAppPackage,
 } from '../app-project.js';
-import { printDiagnosticsJSON, printJSON } from '../diagnostics.js';
+import {
+  printDiagnosticsJSON,
+  printJSON,
+  printSourceWarning,
+} from '../diagnostics.js';
 import { DiagnosticsError } from '../errors.js';
 import { deployOnChange } from '../watch.js';
 import {
+  gitOrigin,
   MANIFEST,
   manifestText,
   typeFiles,
@@ -79,6 +84,7 @@ export async function appDeploy(argv, io) {
 async function deployProject(client, project, argv, io, target) {
   const result = await client.ingestApp(project, {
     baseVersion: argv.force ? undefined : project.baseVersion,
+    origin: await gitOrigin(io.cwd, io.env),
   });
 
   const manifestRaw = manifestText(result.manifest);
@@ -97,6 +103,7 @@ async function deployProject(client, project, argv, io, target) {
     printJSON(result, io);
   } else {
     for (const w of result.warnings ?? []) io.warn(`warning: ${w}`);
+    printSourceWarning(result, io);
     const files = written.length ? ` (${written.sort().join(', ')})` : '';
     io.log(`deployed ${result.id} v${result.version} to ${target}${files}`);
     if (result.url) io.log(`open: ${result.url}`);

package/src/commands/check.js

@@ -2,11 +2,16 @@ import { spawn } from 'node:child_process';
 import { join } from 'node:path';
 
 import { connect } from '../api.js';
-import { printDiagnosticsJSON, printJSON } from '../diagnostics.js';
+import {
+  printDiagnosticsJSON,
+  printJSON,
+  printSourceWarning,
+} from '../diagnostics.js';
 import { DiagnosticsError, UserError } from '../errors.js';
 import { readProject } from '../project.js';
 import { baseFor } from './deploy.js';
 import { verifyTypes } from './verify-types.js';
+import { gitOrigin } from '../working-copy.js';
 
 export const CHECK_USAGE =
   'juno integration check [--skip-local] [--id <id>] [--json]';
@@ -48,6 +53,7 @@ export async function check(argv, io) {
       dryRun: true,
       id: argv.id,
       baseVersion: baseFor(project, argv, io),
+      origin: await gitOrigin(io.cwd, io.env),
     });
   } catch (err) {
     if (argv.json && err instanceof DiagnosticsError) {
@@ -60,6 +66,7 @@ export async function check(argv, io) {
     printJSON(result, io);
   } else {
     for (const w of result.warnings ?? []) io.warn(`warning: ${w}`);
+    printSourceWarning(result, io);
     io.log(`${result.id}: manifest and sources verified against ${target}`);
   }
 

package/src/commands/deploy.js

@@ -1,7 +1,11 @@
 import { join } from 'node:path';
 
 import { connect } from '../api.js';
-import { printDiagnosticsJSON, printJSON } from '../diagnostics.js';
+import {
+  printDiagnosticsJSON,
+  printJSON,
+  printSourceWarning,
+} from '../diagnostics.js';
 import { DiagnosticsError } from '../errors.js';
 import {
   readManifestRaw,
@@ -12,6 +16,7 @@ import {
 import { stampTypeFiles } from '../stamp.js';
 import { pickTypeFiles } from './gen-types.js';
 import { deployOnChange } from '../watch.js';
+import { gitOrigin } from '../working-copy.js';
 
 export const DEPLOY_USAGE =
   'juno integration deploy [--watch] [--force] [--id <id>] [--json]';
@@ -57,6 +62,7 @@ async function deployOnce(client, argv, io, target) {
   const result = await client.ingest(project, {
     id: argv.id,
     baseVersion: argv.force ? undefined : baseFor(project, argv, io),
+    origin: await gitOrigin(io.cwd, io.env),
   });
   // Stamped against the manifest this deploy was built from, so the watch loop
   // leaves a tree that `juno integration verify-types` accepts.
@@ -82,6 +88,7 @@ async function deployOnce(client, argv, io, target) {
     return result;
   }
   for (const warning of result.warnings ?? []) io.warn(`warning: ${warning}`);
+  printSourceWarning(result, io);
   io.log(
     `deployed ${result.id} v${result.version} to ${target} (${written.sort().join(', ')})`
   );

package/src/commands/flow-check.js

@@ -2,7 +2,12 @@ import { connect } from '../api.js';
 import { DiagnosticsError } from '../errors.js';
 import { readFlowProject } from '../flow-project.js';
 import { runLocalChecks } from './check.js';
-import { printDiagnosticsJSON, printJSON } from '../diagnostics.js';
+import {
+  printDiagnosticsJSON,
+  printJSON,
+  printSourceWarning,
+} from '../diagnostics.js';
+import { gitOrigin } from '../working-copy.js';
 import { printWarnings } from './flow-deploy.js';
 
 export const FLOW_CHECK_USAGE = 'juno flow check [--skip-local] [--json]';
@@ -28,7 +33,7 @@ export async function flowCheck(argv, io) {
         files: project.files,
         baseVersion: project.baseVersion,
       },
-      { dryRun: true }
+      { dryRun: true, origin: await gitOrigin(io.cwd, io.env) }
     );
   } catch (err) {
     if (argv.json && err instanceof DiagnosticsError) {
@@ -41,6 +46,7 @@ export async function flowCheck(argv, io) {
     printJSON(result, io);
   } else {
     printWarnings(result.warnings, io);
+    printSourceWarning(result, io);
     io.log(`${result.flow_id}: manifest and src/ verified against ${target}`);
   }
   return failed ? 1 : 0;

package/src/commands/flow-deploy.js

@@ -6,6 +6,7 @@ import {
   formatDiagnostic,
   printDiagnosticsJSON,
   printJSON,
+  printSourceWarning,
 } from '../diagnostics.js';
 import {
   MANIFEST,
@@ -17,6 +18,7 @@ import {
   writeFlowFiles,
 } from '../flow-project.js';
 import { deployOnChange } from '../watch.js';
+import { gitOrigin } from '../working-copy.js';
 
 export const FLOW_DEPLOY_USAGE =
   'juno flow deploy [--watch] [--force] [--json]';
@@ -73,12 +75,15 @@ async function deployOnce(client, argv, io, target) {
 }
 
 async function deployProject(client, project, argv, io, target) {
-  const result = await client.ingestFlow({
-    flowId: project.flowId,
-    manifest: project.manifest,
-    files: project.files,
-    baseVersion: argv.force ? undefined : project.baseVersion,
-  });
+  const result = await client.ingestFlow(
+    {
+      flowId: project.flowId,
+      manifest: project.manifest,
+      files: project.files,
+      baseVersion: argv.force ? undefined : project.baseVersion,
+    },
+    { origin: await gitOrigin(io.cwd, io.env) }
+  );
 
   const manifestRaw = manifestText(result.manifest);
   const written = await writeFlowFiles(io.cwd, {
@@ -96,6 +101,7 @@ async function deployProject(client, project, argv, io, target) {
     printJSON(result, io);
   } else {
     printWarnings(result.warnings, io);
+    printSourceWarning(result, io);
     const files = written.length ? ` (${written.sort().join(', ')})` : '';
     io.log(
       `deployed ${result.flow_id} v${result.version} to ${target}${files}`

package/src/commands/job-run.js

@@ -0,0 +1,276 @@
+import { spawn as nodeSpawn } from 'node:child_process';
+import { randomUUID } from 'node:crypto';
+import { readFile as nodeReadFile } from 'node:fs/promises';
+import { constants } from 'node:os';
+import { resolve } from 'node:path';
+import { parseArgs } from 'node:util';
+
+import { UsageError } from '../errors.js';
+
+export const JOB_RUN_USAGE =
+  'juno job run [<url>] [--url-file <path>] [--verbose] -- <command> [args…]';
+
+/** The tail of each stream a run reports; Juno keeps the same. */
+export const TAIL_BYTES = 64 << 10;
+
+/** The signals the wrapper passes on to the command instead of obeying. */
+const FORWARDED = ['SIGINT', 'SIGTERM', 'SIGHUP'];
+
+const DEFAULT_TIMEOUTS = {
+  start: 5000,
+  finish: 10000,
+  retryDelay: 1000,
+};
+
+/**
+ * `juno job run` runs a command and reports it to an external job's ping URL
+ * (plan-external-jobs-2-wrapper-and-tools.md, Decisions 3–5). Its first rule
+ * is transparency: the command gets the same stdin, and the wrapper's stdout,
+ * stderr and exit status are the command's, byte for byte — a scheduler such
+ * as OpenClaw delivers a task's stdout as its message. Juno gets a `start`,
+ * then the exit status with the last 64 KiB of each stream. A report that
+ * fails is dropped: a run Juno never hears about becomes an overdue finding
+ * on its own, so the wrapper never queues and never fails the command.
+ *
+ * It reads no Juno config and no API key; the URL is all it needs. argv is
+ * everything after `job run`, `--` included. The exit code is returned, not
+ * passed to process.exit, so stdout is flushed before the process ends.
+ * deps is injectable for the tests; the default binds the real ones.
+ */
+export async function jobRun(argv, io, deps = {}) {
+  const {
+    spawn = nodeSpawn,
+    fetch = globalThis.fetch,
+    env = process.env,
+    readFile = nodeReadFile,
+    stdout = process.stdout,
+    stderr = process.stderr,
+    signals = process,
+    timeouts = DEFAULT_TIMEOUTS,
+  } = deps;
+
+  const dash = argv.indexOf('--');
+  const command = dash === -1 ? [] : argv.slice(dash + 1);
+  const own = dash === -1 ? argv : argv.slice(0, dash);
+  let parsed;
+  try {
+    parsed = parseArgs({
+      args: own,
+      allowPositionals: true,
+      options: {
+        'url-file': { type: 'string' },
+        verbose: { type: 'boolean', default: false },
+      },
+    });
+  } catch (err) {
+    throw new UsageError(
+      `juno job run: ${err.message}\nusage: ${JOB_RUN_USAGE}`
+    );
+  }
+  if (command.length === 0) {
+    throw new UsageError(
+      `juno job run: missing -- <command>\nusage: ${JOB_RUN_USAGE}`
+    );
+  }
+  if (parsed.positionals.length > 1) {
+    throw new UsageError(
+      `juno job run: one URL before --, got ${parsed.positionals.length} arguments\nusage: ${JOB_RUN_USAGE}`
+    );
+  }
+  const url = await pingURL(parsed, env, readFile, io.cwd);
+  const verbose = parsed.values.verbose;
+
+  const rid = randomUUID();
+  await report(fetch, endpoint(url, 'start', rid), {
+    method: 'GET',
+    timeout: timeouts.start,
+  });
+
+  const out = new Tail();
+  const err = new Tail();
+  const outcome = await runCommand(command, {
+    spawn,
+    signals,
+    onStdout: (chunk) => out.push(chunk),
+    onStderr: (chunk) => err.push(chunk),
+    stdout,
+    stderr,
+  });
+
+  let suffix;
+  let exitCode;
+  if (outcome.startError) {
+    const line = `juno job run: ${command[0]}: ${outcome.startError.message}`;
+    io.error(line);
+    err.push(Buffer.from(`${line}\n`));
+    suffix = 'fail';
+    exitCode = outcome.startError.code === 'EACCES' ? 126 : 127;
+  } else if (outcome.signal) {
+    suffix = 'fail';
+    exitCode = 128 + (constants.signals[outcome.signal] ?? 0);
+  } else {
+    suffix = String(outcome.code);
+    exitCode = outcome.code;
+  }
+
+  const finish = () => {
+    const body = new FormData();
+    body.append('stdout', new Blob([out.bytes()]), 'stdout');
+    body.append('stderr', new Blob([err.bytes()]), 'stderr');
+    return report(fetch, endpoint(url, suffix, rid), {
+      method: 'POST',
+      body,
+      timeout: timeouts.finish,
+    });
+  };
+  let failure = await finish();
+  if (failure) {
+    await new Promise((resolve) => setTimeout(resolve, timeouts.retryDelay));
+    failure = await finish();
+  }
+  if (failure && verbose) {
+    io.error(`juno job run: could not report to Juno: ${failure}`);
+  }
+  return exitCode;
+}
+
+/**
+ * pingURL is the URL from the first source that yields one: the positional,
+ * then --url-file (its contents, trimmed), then $JUNO_JOB_URL. The two
+ * indirect sources keep the token off the command line, where `ps` and the
+ * scheduler's job definition would show it.
+ */
+async function pingURL(parsed, env, readFile, cwd = '.') {
+  const [positional] = parsed.positionals;
+  if (positional?.trim()) return positional.trim();
+  const file = parsed.values['url-file'];
+  if (file !== undefined) {
+    let text;
+    try {
+      text = await readFile(resolve(cwd, file), 'utf8');
+    } catch (err) {
+      throw new UsageError(`juno job run: --url-file ${file}: ${err.message}`);
+    }
+    if (text.trim()) return text.trim();
+  }
+  if (env.JUNO_JOB_URL?.trim()) return env.JUNO_JOB_URL.trim();
+  throw new UsageError(
+    `juno job run: no ping URL — pass it, --url-file or JUNO_JOB_URL\nusage: ${JOB_RUN_USAGE}`
+  );
+}
+
+/**
+ * endpoint is `<url>/<suffix>?rid=<rid>`, used as given otherwise: no /ping/
+ * check, so a Healthchecks URL works too. A query the URL already carries is
+ * kept.
+ */
+export function endpoint(url, suffix, rid) {
+  const q = url.indexOf('?');
+  const path = (q === -1 ? url : url.slice(0, q)).replace(/\/+$/, '');
+  const query = q === -1 ? '' : `${url.slice(q + 1)}&`;
+  return `${path}/${suffix}?${query}rid=${encodeURIComponent(rid)}`;
+}
+
+/**
+ * report sends one ping and answers why it failed, or undefined when it did
+ * not. It never throws: a ping that fails changes nothing about the command.
+ */
+async function report(fetch, url, { method, body, timeout }) {
+  try {
+    const res = await fetch(url, {
+      method,
+      body,
+      signal: AbortSignal.timeout(timeout),
+    });
+    await res.arrayBuffer().catch(() => {});
+    return res.ok ? undefined : `HTTP ${res.status}`;
+  } catch (err) {
+    return err?.cause?.message ?? err?.message ?? String(err);
+  }
+}
+
+/**
+ * runCommand spawns argv with stdin inherited and stdout and stderr piped,
+ * with no shell, and copies each chunk to the wrapper's own stream as it
+ * arrives. It resolves with `{code}`, `{signal}` or, when the command could
+ * not be started, `{startError}`. While it runs, SIGINT, SIGTERM and SIGHUP
+ * are passed on to the command, and do not end the wrapper.
+ */
+function runCommand(
+  argv,
+  { spawn, signals, onStdout, onStderr, stdout, stderr }
+) {
+  return new Promise((resolve) => {
+    let child;
+    try {
+      child = spawn(argv[0], argv.slice(1), {
+        stdio: ['inherit', 'pipe', 'pipe'],
+      });
+    } catch (err) {
+      resolve({ startError: err });
+      return;
+    }
+
+    const forward = Object.fromEntries(
+      FORWARDED.map((sig) => [
+        sig,
+        () => {
+          try {
+            child.kill(sig);
+          } catch {
+            // Already gone: its exit is on its way.
+          }
+        },
+      ])
+    );
+    for (const [sig, fn] of Object.entries(forward)) signals.on(sig, fn);
+    let settled = false;
+    const settle = (result) => {
+      if (settled) return;
+      settled = true;
+      for (const [sig, fn] of Object.entries(forward)) signals.off(sig, fn);
+      resolve(result);
+    };
+
+    child.stdout.on('data', onStdout);
+    child.stderr.on('data', onStderr);
+    child.stdout.pipe(stdout, { end: false });
+    child.stderr.pipe(stderr, { end: false });
+
+    child.on('error', (err) => {
+      // A spawn failure leaves no process behind; any later error is about
+      // one that did start, whose close still comes.
+      if (child.pid === undefined) settle({ startError: err });
+    });
+    child.on('close', (code, signal) => {
+      settle(signal ? { signal } : { code });
+    });
+  });
+}
+
+/**
+ * Tail keeps the last TAIL_BYTES of a stream as the chunks that arrived,
+ * dropping whole chunks from the front once over the limit and cutting the
+ * first one kept, so a long run costs at most a little over 64 KiB.
+ */
+export class Tail {
+  #chunks = [];
+  #size = 0;
+
+  push(chunk) {
+    this.#chunks.push(chunk);
+    this.#size += chunk.length;
+    while (this.#size - this.#chunks[0].length >= TAIL_BYTES) {
+      this.#size -= this.#chunks.shift().length;
+    }
+    if (this.#size > TAIL_BYTES) {
+      const cut = this.#size - TAIL_BYTES;
+      this.#chunks[0] = this.#chunks[0].subarray(cut);
+      this.#size -= cut;
+    }
+  }
+
+  bytes() {
+    return Buffer.concat(this.#chunks, this.#size);
+  }
+}

package/src/diagnostics.js

@@ -28,3 +28,13 @@ export function printDiagnosticsJSON(err, io) {
   printJSON({ detail: err.message, diagnostics: err.diagnostics }, io);
   return 1;
 }
+
+/**
+ * A route's `source_warning` — the server's sentence for a deploy that moves
+ * an artifact between sources (local, installed, remote) or supersedes a
+ * version written in Juno — on stderr as `warning: …`. Never a failure: the
+ * write already happened, or a check says what a deploy would do.
+ */
+export function printSourceWarning(result, io) {
+  if (result?.source_warning) io.warn(`warning: ${result.source_warning}`);
+}

package/src/exit.js

@@ -12,6 +12,9 @@
  *      409 because the active version is not the copy's base_version
  *   5  `juno ask` / `session approve`: the turn is still running (pending)
  *   6  `juno ask` / `session approve`: the assistant is awaiting input
+ *
+ * `juno job run` is the exception once its own arguments are accepted: it
+ * exits with the wrapped command's status, as a shell would report it.
  */
 export const EXIT_OK = 0;
 export const EXIT_FAILURE = 1;

package/src/index.js

@@ -29,6 +29,7 @@ import { FLOW_INIT_USAGE, flowInit } from './commands/flow-init.js';
 import { FLOW_PULL_USAGE, flowPull } from './commands/flow-pull.js';
 import { GEN_TYPES_USAGE, genTypes } from './commands/gen-types.js';
 import { INIT_USAGE, init } from './commands/init.js';
+import { JOB_RUN_USAGE, jobRun } from './commands/job-run.js';
 import { PULL_USAGE, pull } from './commands/pull.js';
 import { SKILL_USAGE, skill } from './commands/skill.js';
 import {
@@ -102,6 +103,18 @@ const NON_TOOL = {
     },
     usage: CREDENTIAL_SET_USAGE,
   },
+  // raw: everything after `--` is the wrapped command's, verbatim, so the
+  // argv goes to the handler unparsed (see runRow). No --url or --token: the
+  // wrapper reads no Juno config, only the ping URL.
+  'job run': {
+    run: (argv, io) => jobRun(argv, io, { env: io.env }),
+    options: {
+      'url-file': { type: 'string' },
+      verbose: { type: 'boolean', default: false },
+    },
+    usage: JOB_RUN_USAGE,
+    raw: true,
+  },
   'config set': { run: configSet, options: {}, usage: CONFIG_SET_USAGE },
   'agent-skill install': {
     run: agentSkillInstall,
@@ -405,6 +418,17 @@ async function showGroupHelp(group, args, io, code) {
 function runRow(row, argv, leading, io) {
   if (!row.tool) {
     const handler = handlerFor(row);
+    if (handler.raw) {
+      // Only the words before `--` are the command's own; a --help after it
+      // belongs to the wrapped program.
+      const dash = argv.indexOf('--');
+      const own = dash === -1 ? argv : argv.slice(0, dash);
+      if (own.includes('--help') || own.includes('-h')) {
+        io.log(nonToolHelp(row, handler));
+        return EXIT_OK;
+      }
+      return handler.run(argv, io);
+    }
     const run =
       row.working_copy && !handler.positional
         ? (args, io) => {

package/src/working-copy.js

@@ -249,6 +249,66 @@ export async function dirtyPaths(cwd) {
   }
 }
 
+/**
+ * gitOrigin is where this working copy sits in git, as the `origin` every
+ * ingest route accepts: `{git: {remote, sha, dirty}}` — the origin remote's
+ * URL (the first remote when there is no `origin`, none when there is no
+ * remote), HEAD's sha, and whether `git status --porcelain` reports anything
+ * under this directory, untracked files included. Scoped to the working copy,
+ * so changes elsewhere in a monorepo do not make it dirty.
+ *
+ * Best effort and never fatal: not a repository, no commit yet, no git on
+ * PATH or any other failure answers undefined, and the deploy goes ahead
+ * without it. The remote loses any credentials here; the server strips them
+ * again rather than trusting this.
+ */
+export async function gitOrigin(cwd, env) {
+  const git = async (...args) =>
+    (await execFileAsync('git', args, { cwd, env })).stdout;
+  try {
+    const sha = (await git('rev-parse', 'HEAD')).trim();
+    const dirty = (await git('status', '--porcelain', '--', '.')).trim() !== '';
+    let remote = '';
+    try {
+      remote = (await git('remote', 'get-url', 'origin')).trim();
+    } catch {
+      const first = (await git('remote')).split('\n')[0].trim();
+      if (first) remote = (await git('remote', 'get-url', first)).trim();
+    }
+    remote = stripCredentials(remote);
+    return {
+      git: {
+        ...(remote ? { remote } : {}),
+        sha,
+        ...(dirty ? { dirty } : {}),
+      },
+    };
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * stripCredentials drops what can carry a secret from a URL remote — its
+ * userinfo, query and fragment (`https://user:token@host/o/r` →
+ * `https://host/o/r`). An scp-like remote (`git@host:o/r.git`) names a user
+ * and no secret, and is kept. A URL that does not parse is dropped rather
+ * than guessed at.
+ */
+export function stripCredentials(remote) {
+  if (!remote.includes('://')) return remote;
+  try {
+    const u = new URL(remote);
+    u.username = '';
+    u.password = '';
+    u.search = '';
+    u.hash = '';
+    return u.toString();
+  } catch {
+    return '';
+  }
+}
+
 export async function readText(cwd, name) {
   try {
     return await readFile(join(cwd, name), 'utf8');

package/tsconfig.base.json

@@ -2,6 +2,7 @@
   "//": "The compiler options Juno type-checks with server-side. internal/verify's tsconfig_preset_test.go asserts this file and verify.CompilerOptions() are identical, so `tsc --noEmit` passing here means the deploy will not 422 on a type error. Extend it; do not fork it.",
   "compilerOptions": {
     "target": "ES2022",
+    "lib": ["ES2022", "DOM", "DOM.Iterable", "ESNext.Disposable"],
     "module": "CommonJS",
     "moduleResolution": "node",
     "strict": true,

package/verbs.json

@@ -221,7 +221,24 @@
     },
     { "command": "webhook write", "tool": "write_webhook", "id_field": "id" },
     { "command": "webhook fire", "tool": "fire_webhook", "id_field": "id" },
+    { "command": "job list", "tool": "list_jobs" },
+    { "command": "job get-runs", "tool": "get_job_runs", "id_field": "id" },
+    { "command": "job write", "tool": "write_job", "id_field": "id" },
     { "command": "credential list", "tool": "list_credentials" },
+    { "command": "person list", "tool": "list_people" },
+    { "command": "person get", "tool": "get_person", "id_field": "id" },
+    { "command": "person write", "tool": "write_person", "id_field": "id" },
+    {
+      "command": "question list",
+      "tool": "list_questions",
+      "flags": { "closed": { "field": "closed", "type": "string" } }
+    },
+    {
+      "command": "question get",
+      "tool": "get_question",
+      "id_field": "run_id",
+      "flags": { "handle": { "field": "handle_id", "type": "string" } }
+    },
     {
       "command": "ha get-entity",
       "tool": "get_entity",
@@ -257,6 +274,11 @@
       "effect": "act",
       "summary": "Approve the tool call an assistant session is waiting on"
     },
+    {
+      "command": "job run",
+      "effect": "act",
+      "summary": "Run a command and report it to an external job's ping URL"
+    },
     {
       "command": "credential set",
       "effect": "act",