@sema-agent/connectors 0.2.0 → 0.4.0

package/CHANGELOG.md

@@ -4,6 +4,103 @@ All notable changes to this package are documented here. Released sections are
 frozen: once a version is published its section is never edited again; new text
 goes into the next version's section.
 
+## 0.4.0 (2026-10-15)
+
+### Added
+
+- `INTEGRATION.md` ships with the package: how a command-line tool mounts a
+  connector of the default catalog through `mount`, `mountCommand` and `seed`,
+  what it reads back, and what the engine then sees.
+- The parked session (CN-046): in standalone mode the launcher never starts a
+  connector whose status would be `unauthorized` (no secret handle, the
+  status's own judgement); it answers the session itself, through the same
+  session and stages as a connector run. `initialize` is answered with the
+  requested protocol version, the tools and resources capabilities and
+  `serverInfo` `sema-connector` at this package's version; `tools/list` lists
+  no tools, `resources/list` the status entry alone, the status reads
+  `unauthorized` with no tools, and `ping` is answered. A tool call is refused
+  with `-32603`, another resource read with `-32602` and any other method with
+  `-32601`, each with `connector.auth_required` and the message
+  `connector <name> has no credentials; run its auth`; the refused call's
+  receipt is `refused` with `connector.auth_required`. The session ends with
+  exit 0 at the end of input or on a stop signal. So
+  `sema-connector-<name> status` before `auth` prints the `unauthorized`
+  status and exits 0, and an upstream program that would begin a login of its
+  own without a token never starts.
+
+### Changed
+
+- A standalone launcher starts a connector only when it has a secret handle
+  (CN-046). Before, it started every connector, and one that refuses to start
+  without its handles (as the Gitea and GitHub connectors do) ended the run
+  with exit 5 and `connector.internal`. A connector that needs no credential
+  at all is parked as well until a secret handle is stored for it. A connector
+  whose secret handle has expired, and every hosted connector, is started as
+  before.
+
+### Fixed
+
+- `sema-connector-<name> status` (CN-049) no longer discovers the status
+  resource's URI through `resources/list` and then insists on exactly one
+  entry there; it reads the status resource straight by its URI (the one
+  `statusUri` makes). Before, a started connector that lists resources of its
+  own made `resources/list` answer with more than the status entry the
+  launcher adds, so `status` always failed with "the launcher did not list
+  exactly one resource, its status" once authorized, even though the launcher
+  itself serves the status resource correctly. This affected the GitHub
+  connector once authorized (github-mcp-server lists 4 `ui://` resources of
+  its own); the Gitea connector, which lists none, was not affected.
+
+## 0.3.0 (2026-10-15)
+
+### Added
+
+- The default catalog seed (CN-009): `sema-connector seed --config-dir
+  <absolute path>`, the launcher's second command, and `seed({ configDir })`
+  mount every installed connector of the default catalog into
+  `config.d/mcp.json`. The catalog is `DEFAULT_CONNECTORS` (today `gitea` and
+  `github`, CN-044),
+  the one list of default connectors; `SEED_VERSION` is the newest version
+  that added a name. Each connector is resolved with the launcher's own rule
+  first (one that is not installed gets no entry) and mounted only through
+  `mount`, so another entry under its name is never overwritten.
+  `config.d/.sema-connector-seed.json` records what each name came to
+  (mounted, present, not installed): a name recorded as mounted or present is
+  never mounted again, so an entry a person removed stays removed; a conflict
+  or a refusal is not recorded and is tried again. Seeds on one directory
+  exclude each other with `config.d/.sema-connector-seed.json.lock` (a second
+  seed refuses as `locked`). One line per connector on stdout; exit 0 when
+  every connector is mounted, present or not installed, 1 otherwise. A marker
+  the seed cannot read refuses it before any mount; a marker write that fails
+  leaves the old marker as it was and the mounted entries in place.
+- `pinnedUpstream({ connector, upstream, lockFile, handles })` (CN-044): what
+  a connector that runs a third-party MCP server takes from the shared layer,
+  so that no connector package carries its own copy. `install(configDir)` is
+  the install subcommand: this platform's release archive from the source the
+  package's `binaries.lock.json` gives (`https`, redirects followed only to
+  `https`, or `file` for a local copy of the releases), its sha256 compared
+  with the lock before anything is written, then the archive and its
+  `upstream` entry kept in `<configuration directory>/connectors/<name>/bin/`
+  (directory 0700, program 0755), each file written whole before it replaces
+  the old one; nothing changes when the pinned build is there. `start(env)`
+  checks `CONNECTOR_DIR`, one `<NAME>_FILE` per handle naming a regular file
+  (not a symbolic link) inside it, and the pinned build in the bin directory
+  (the same check as install's), and refuses with a sentence naming what to
+  run; its `run(args, extra)` starts the program as the connector's child on
+  the same standard input, output and error, with the connector's environment
+  minus `CONNECTOR_DIR` and the handle paths plus `extra`, passes `SIGTERM`,
+  `SIGINT` and `SIGHUP` on, and ends as the program ends. The Gitea connector
+  is its first user (moved from its own package) and the GitHub connector its
+  second.
+
+### Changed
+
+- A launcher command line that starts with neither `run` nor `seed` is
+  refused with `expected the command "run" or "seed"` (exit 2, as before).
+- `readStdinJson` with one key names it as "the key" in its refusals
+  (`the object must have exactly the key token`); with two or more keys the
+  wording is as before.
+
 ## 0.2.0 (2026-10-15)
 
 ### Added

package/INTEGRATION.md

@@ -0,0 +1,68 @@
+# Integrating `@sema-agent/connectors` from a command-line tool
+
+How a tool outside this repository (the CLI's `connectors add`, for one) mounts a connector of the default
+catalog into the engine's local configuration and reads what happened, using this package only. The rules
+live in the repository's `docs/ARCHITECTURE.md` ("Mounting", "Seeding the default catalog", "Parked
+session"); this page states the surface a tool consumes and does not restate the rules.
+
+## The configuration directory
+
+One configuration directory per engine installation, the engine's local one: `CONFIG_LOCAL_DIR`, an
+absolute path. `resolveConfigDir(process.env)` turns the variable into `{ ok: true, dir }` or
+`{ ok: false, reason }` (not set, empty, or not absolute; the reason names the variable, never the value).
+It is the same root `sema-connector seed --config-dir <dir>` seeds and the same root every connector CLI
+(`sema-connector-<name> auth | mount | status`) reads from `CONFIG_LOCAL_DIR`. Entries land in
+`<dir>/config.d/mcp.json`; a connector's secrets live in `<dir>/connectors/<name>/`.
+
+## Mounting one connector
+
+```ts
+import { mount, mountCommand, resolveConfigDir, DEFAULT_CONNECTORS, SEED_VERSION, seed } from '@sema-agent/connectors'
+
+const result = mount({ name: 'gitea', configDir: dir })
+```
+
+- `mount(options: { name: string; configDir: string }): MountResult`. There is no `entry` argument: the entry
+  is fixed by the package and written as
+  `{"name": "<name>", "transport": {"kind": "stdio", "command": "sema-connector", "args": ["run", "<name>",
+  "--mode", "standalone", "--transport", "stdio", "--config-dir", "<configDir>"]}}`, never with environment
+  references or headers. A tool never composes an entry of its own.
+- `MountResult` is `{ ok: true, changed: boolean, file: string }` (`changed: false` when the same entry was
+  already there, byte for byte apart from key order; `file` is the catalog file written) or
+  `{ ok: false, reason: MountRefusal, message: string }` with `reason` one of the closed set
+  `config_dir | invalid_name | reserved_name | unreadable | unexpected_shape | conflict | locked |
+  changed_during_write | write_failed`. `mount` does not throw for a refusal.
+- Idempotence: a second `mount` of the same name changes nothing. Another entry under the same name (other
+  arguments, another `--config-dir`, `enabled: false`, environment references) is `conflict` and is never
+  overwritten; the tool reports it and leaves the person to remove the entry. `mount` keeps no marker of
+  its own.
+- `mountCommand(name, configDir): number` is the same call with the CLI's output: on success one line on
+  standard output (`mounted connector <name> in <file>; restart the engine to apply`, or
+  `connector <name> is already mounted in <file>`) and exit 0; on a refusal one line on standard error,
+  `mount refused (<reason>): <message>`, and exit 1. A thin wrapper returns its number as its exit code.
+- `mount` does not check that the connector package is installed: an entry for a connector that is not
+  installed makes the launcher exit 4 (`connector.not_installed`) when the engine starts it. A tool that
+  wants only installed connectors mounted uses the seed.
+
+## The default catalog and the seed
+
+- `DEFAULT_CONNECTORS: readonly { name: string; since: number }[]`: the one list of default connectors, in
+  order; `name` is the connector (the package is `@sema-agent/connector-<name>`), `since` the seed version
+  that added it. `SEED_VERSION` is the newest `since`.
+- `seed({ configDir }): SeedResult` mounts every installed connector of the default catalog through `mount`,
+  resolving each with the launcher's own rule first, and remembers the outcome per name in
+  `<dir>/config.d/.sema-connector-seed.json`, so an entry a person removed is never brought back. Readings per
+  name: `mounted | present | conflict | not_installed | refused`; the whole seed is refused as `config_dir |
+  locked | unreadable | unexpected_shape | write_failed`. `sema-connector seed --config-dir <dir>` is the same
+  call as a command (exit 0 when every connector is mounted, present or not installed, 1 otherwise, 2 for a bad
+  command line). A tool that offers "mount the defaults" runs the seed; a tool that offers "mount this one"
+  calls `mount`.
+
+## What the engine sees
+
+Entries are read by the engine from `config.d/mcp.json` through the server's local file configuration
+(the same path that reads every other stdio entry there); an entry `mount` wrote is read at the engine's next
+start, and the launcher it names reads the connector's secrets under the same directory. Before `auth` has
+stored the connector's credential the launcher parks the session: the connector lists no tools, its status
+reads `unauthorized`, and a tool call is refused with `connector.auth_required`; after `auth`, the next start
+runs the connector.

package/dist/cli-kit.d.ts

@@ -28,6 +28,7 @@ export type StdinJson = {
     readonly ok: false;
     readonly problem: string;
 };
+export declare const listed: (keys: readonly string[]) => string;
 export declare function readStdinJson(limit: number, keys: readonly string[]): Promise<StdinJson>;
 export declare function mountCommand(name: string, configDir: string): number;
 export declare function statusCommand(name: string, configDir: string): Promise<number>;

package/dist/cli-kit.js

@@ -1,11 +1,11 @@
 import { spawn } from 'node:child_process';
-import { readFileSync } from 'node:fs';
-import { dirname, join } from 'node:path';
-import { fileURLToPath } from 'node:url';
 import { resolveConfigDir } from './config-dir.js';
 import { CONNECTOR_NAME } from './connector-name.js';
 import { hasRepeatedKey } from './json-text.js';
 import { mount } from './mount.js';
+import { ownManifest } from './own-package.js';
+import { MCP_PROTOCOL_VERSION } from './session.js';
+import { statusUri } from './status.js';
 export function cliOutput(name) {
     if (typeof name !== 'string' || !CONNECTOR_NAME.test(name))
         throw new Error('a connector name is lowercase letters and digits in hyphen-separated words');
@@ -63,12 +63,13 @@ export async function readStdinLine(limit) {
         return { ok: false, problem: 'standard input must hold exactly one line' };
     return { ok: true, line };
 }
-const listed = (keys) => (keys.length < 2 ? keys.join('') : `${keys.slice(0, -1).join(', ')} and ${keys[keys.length - 1]}`);
+export const listed = (keys) => (keys.length < 2 ? keys.join('') : `${keys.slice(0, -1).join(', ')} and ${keys[keys.length - 1]}`);
 export async function readStdinJson(limit, keys) {
     const read = await readStdinLine(limit);
     if (!read.ok)
         return read;
-    const shape = `standard input must be one JSON object with exactly the keys ${listed(keys)}, each a string, on one line`;
+    const exactly = keys.length === 1 ? `exactly the key ${listed(keys)}` : `exactly the keys ${listed(keys)}`;
+    const shape = `standard input must be one JSON object with ${exactly}, ${keys.length === 1 ? 'a string' : 'each a string'}, on one line`;
     let value;
     try {
         value = JSON.parse(read.line);
@@ -83,7 +84,7 @@ export async function readStdinJson(limit, keys) {
     const object = value;
     const own = Object.keys(object);
     if (own.length !== keys.length || !keys.every((k) => own.includes(k)))
-        return { ok: false, problem: `the object must have exactly the keys ${listed(keys)}` };
+        return { ok: false, problem: `the object must have ${exactly}` };
     if (!keys.every((k) => typeof object[k] === 'string'))
         return { ok: false, problem: shape };
     return { ok: true, values: Object.fromEntries(keys.map((k) => [k, object[k]])) };
@@ -105,16 +106,10 @@ export function mountCommand(name, configDir) {
     say(r.changed ? `mounted connector ${name} in ${r.file}; restart the engine to apply` : `connector ${name} is already mounted in ${r.file}`);
     return 0;
 }
-const PROTOCOL_VERSION = '2025-11-25';
 const STATUS_TIMEOUT_MS = 10_000;
 const KILL_GRACE_MS = 2_000;
 const SHOWN_LINES = 5;
 const RECEIPT_PREFIX = 'sema-connector: receipt ';
-function ownManifest() {
-    const url = new URL('../package.json', import.meta.url);
-    const manifest = JSON.parse(readFileSync(url, 'utf8'));
-    return { version: manifest.version, launcher: join(dirname(fileURLToPath(url)), manifest.bin['sema-connector'] ?? '') };
-}
 function lineReader(stream) {
     const lines = [];
     const waiters = [];
@@ -183,24 +178,17 @@ export async function statusCommand(name, configDir) {
     let found = null;
     let problem = null;
     try {
-        const init = await reply(1, 'initialize', { protocolVersion: PROTOCOL_VERSION, capabilities: {}, clientInfo: { name: program, version: own.version } });
+        const init = await reply(1, 'initialize', { protocolVersion: MCP_PROTOCOL_VERSION, capabilities: {}, clientInfo: { name: program, version: own.version } });
         if (init?.result === undefined)
             problem = 'the launcher did not complete initialize';
         else {
             write({ method: 'notifications/initialized' });
-            const list = await reply(2, 'resources/list');
-            const entries = list?.result?.resources;
-            const uri = Array.isArray(entries) && entries.length === 1 ? entries[0]?.uri : undefined;
-            if (typeof uri !== 'string')
-                problem = 'the launcher did not list exactly one resource, its status';
-            else {
-                const read = await reply(3, 'resources/read', { uri });
-                const text = read?.result?.contents?.[0]?.text;
-                if (typeof text !== 'string')
-                    problem = `the status could not be read${typeof read?.error?.message === 'string' ? `: ${read.error.message}` : ''}`;
-                else
-                    found = JSON.parse(text);
-            }
+            const read = await reply(2, 'resources/read', { uri: statusUri(name) });
+            const text = read?.result?.contents?.[0]?.text;
+            if (typeof text !== 'string')
+                problem = `the status could not be read${typeof read?.error?.message === 'string' ? `: ${read.error.message}` : ''}`;
+            else
+                found = JSON.parse(text);
         }
     }
     catch {

package/dist/index.d.ts

@@ -6,7 +6,11 @@ export { ASSERTION_HEADER, hostedResolver, standaloneResolver, verifyAssertion }
 export type { AnonymousPrincipal, AssertionPrincipal, AssertionStep, Principal, PrincipalResolver, PrincipalResult, RequestContext, VerifyOptions, VerifyResult, } from './principal.js';
 export { mount } from './mount.js';
 export type { MountOptions, MountRefusal, MountResult } from './mount.js';
+export { DEFAULT_CONNECTORS, SEED_VERSION, seed } from './seed.js';
+export type { DefaultConnector, SeedOptions, SeedReading, SeedRefusal, SeedResult } from './seed.js';
 export { cliOutput, connectorCli, mountCommand, readStdinJson, readStdinLine, statusCommand } from './cli-kit.js';
 export type { CliOutput, ConnectorCommands, StdinJson, StdinLine } from './cli-kit.js';
 export { isLoopbackHttpOrHttps } from './jwks.js';
+export { pinnedUpstream } from './pinned-upstream.js';
+export type { PinnedUpstream, PinnedUpstreamOptions, UpstreamStart } from './pinned-upstream.js';
 export { writeAll } from './write-all.js';

package/dist/index.js

@@ -2,6 +2,8 @@ export { resolveConfigDir } from './config-dir.js';
 export { openFileSecrets } from './secrets.js';
 export { ASSERTION_HEADER, hostedResolver, standaloneResolver, verifyAssertion } from './principal.js';
 export { mount } from './mount.js';
+export { DEFAULT_CONNECTORS, SEED_VERSION, seed } from './seed.js';
 export { cliOutput, connectorCli, mountCommand, readStdinJson, readStdinLine, statusCommand } from './cli-kit.js';
 export { isLoopbackHttpOrHttps } from './jwks.js';
+export { pinnedUpstream } from './pinned-upstream.js';
 export { writeAll } from './write-all.js';

package/dist/launcher.js

@@ -1,20 +1,22 @@
 import { spawn } from 'node:child_process';
 import { randomUUID } from 'node:crypto';
-import { readFileSync } from 'node:fs';
-import { createRequire } from 'node:module';
 import { isIPv4, isIPv6 } from 'node:net';
 import { tmpdir } from 'node:os';
-import { dirname, join } from 'node:path';
+import { join } from 'node:path';
 import { absoluteDir, given } from './config-dir.js';
 import { CONNECTOR_NAME } from './connector-name.js';
 import { serveHttp } from './http.js';
 import { keySetSource, obtainKeySet } from './jwks.js';
+import { ownManifest } from './own-package.js';
 import { hostedResolver, standaloneResolver } from './principal.js';
 import { Scrubber, secretMatcher } from './redact.js';
+import { resolveConnector } from './resolve-connector.js';
 import { NO_HANDLES, copyForLaunch, handleDirectory } from './secrets.js';
-import { INSPECT_LIMIT_BYTES, Session } from './session.js';
-import { mintStatus } from './status.js';
-const EXIT = { ok: 0, guard: 2, notInstalled: 4, connectorFailed: 5 };
+import { seed } from './seed.js';
+import { INSPECT_LIMIT_BYTES, Session, parkedAnswer } from './session.js';
+import { mintState, mintStatus } from './status.js';
+import { writeFailure } from './write-all.js';
+const EXIT = { ok: 0, notSeeded: 1, guard: 2, notInstalled: 4, connectorFailed: 5 };
 const NOT_INSTALLED = 'connector.not_installed';
 const INTERNAL = 'connector.internal';
 const STOP_SIGNALS = ['SIGTERM', 'SIGINT', 'SIGHUP'];
@@ -22,21 +24,15 @@ const TEARDOWN_STEP_MS = 1000;
 const STALL_STEPS = 10;
 const STALL_MS = STALL_STEPS * TEARDOWN_STEP_MS;
 const PIECE_BYTES = 1024;
-const USAGE = 'usage: sema-connector run <name> --mode standalone|hosted --transport stdio|http [--listen <ip>:<port>] [--config-dir <absolute path>]';
+const USAGE = 'usage: sema-connector run <name> --mode standalone|hosted --transport stdio|http [--listen <ip>:<port>] [--config-dir <absolute path>]\n       sema-connector seed --config-dir <absolute path>';
 const FLAGS = ['--mode', '--transport', '--listen', '--config-dir'];
+const SEED_FLAGS = ['--config-dir'];
 const CHILD_ENV = ['HOME', 'LOGNAME', 'USER', 'PATH', 'SHELL', 'TERM', 'LANG', 'LC_ALL', 'TZ'];
 const CONNECTOR_DIR = 'CONNECTOR_DIR';
-function guard(argv, env) {
-    if (argv[0] !== 'run')
-        return 'expected the command "run"';
-    const name = argv[1];
-    if (name === undefined || name.startsWith('-'))
-        return 'missing the connector <name> after "run"';
-    if (!CONNECTOR_NAME.test(name))
-        return '<name> must be lowercase letters and digits in hyphen-separated words (it names the package @sema-agent/connector-<name>)';
+function flagValues(argv, from, allowed) {
     const values = new Map();
-    for (let i = 2; i < argv.length; i += 2) {
-        const flag = FLAGS.find((f) => f === argv[i]);
+    for (let i = from; i < argv.length; i += 2) {
+        const flag = allowed.find((f) => f === argv[i]);
         if (flag === undefined)
             return `unknown argument at position ${i + 1}`;
         if (values.has(flag))
@@ -46,6 +42,31 @@ function guard(argv, env) {
             return `${flag} needs a value`;
         values.set(flag, value);
     }
+    return values;
+}
+function guard(argv, env) {
+    if (argv[0] === 'seed') {
+        const values = flagValues(argv, 1, SEED_FLAGS);
+        if (typeof values === 'string')
+            return values;
+        const configDirArgument = values.get('--config-dir');
+        if (configDirArgument === undefined)
+            return 'seed requires --config-dir <absolute path>, the configuration directory it seeds (there is no default)';
+        const configDir = absoluteDir(configDirArgument);
+        if (configDir === null)
+            return '--config-dir must be an absolute path';
+        return { command: 'seed', configDir };
+    }
+    if (argv[0] !== 'run')
+        return 'expected the command "run" or "seed"';
+    const name = argv[1];
+    if (name === undefined || name.startsWith('-'))
+        return 'missing the connector <name> after "run"';
+    if (!CONNECTOR_NAME.test(name))
+        return '<name> must be lowercase letters and digits in hyphen-separated words (it names the package @sema-agent/connector-<name>)';
+    const values = flagValues(argv, 2, FLAGS);
+    if (typeof values === 'string')
+        return values;
     const mode = values.get('--mode');
     const transport = values.get('--transport');
     const listen = values.get('--listen');
@@ -68,7 +89,7 @@ function guard(argv, env) {
         const configDir = absoluteDir(configDirArgument);
         if (configDir === null)
             return '--config-dir must be an absolute path';
-        return { name, mode, configDir };
+        return { command: 'run', name, mode, configDir };
     }
     if (transport !== 'http')
         return 'hosted mode requires --transport http';
@@ -88,7 +109,7 @@ function guard(argv, env) {
     const keySet = keySetSource(env, issuer);
     if (typeof keySet === 'string')
         return keySet;
-    return { name, mode, listen: address, issuer, audience, keySet };
+    return { command: 'run', name, mode, listen: address, issuer, audience, keySet };
 }
 function listenAddress(value) {
     const m = /^(?:\[([^\]]+)\]|([^:[\]]+)):([1-9][0-9]{0,4})$/.exec(value);
@@ -99,31 +120,6 @@ function listenAddress(value) {
     const port = Number(m[3]);
     return hostOk && port <= 65535 ? { host, port } : null;
 }
-function resolveConnector(name) {
-    const packageName = `@sema-agent/connector-${name}`;
-    let manifestPath;
-    try {
-        manifestPath = createRequire(new URL('../package.json', import.meta.url)).resolve(`${packageName}/package.json`);
-    }
-    catch {
-        return { packageName, reason: 'is not installed where the launcher can resolve it' };
-    }
-    let bin;
-    try {
-        bin = JSON.parse(readFileSync(manifestPath, 'utf8')).bin;
-    }
-    catch {
-        return { packageName, reason: 'has a package.json that cannot be read' };
-    }
-    let rel;
-    if (typeof bin === 'string')
-        rel = bin;
-    else if (bin !== null && typeof bin === 'object' && !Array.isArray(bin) && Object.keys(bin).length === 1)
-        rel = Object.values(bin)[0];
-    if (typeof rel !== 'string' || rel === '')
-        return { packageName, reason: 'does not declare exactly one bin' };
-    return { packageName, binPath: join(dirname(manifestPath), rel) };
-}
 class Out {
     stream;
     held = [];
@@ -386,31 +382,20 @@ function childEnvironment(env, connectorDir, secrets) {
 const hostedConnectorDir = (name) => join(tmpdir(), `sema-connector-${randomUUID()}`, 'connectors', name);
 const describe = (o) => `connector process ${o.stalled ? `stopped reading its input (stalled input: none of it taken for ${STALL_MS / 1000} s) and ` : ''}${o.error ? `could not be started (${o.error.message})` : o.signal !== null ? `was terminated by signal ${o.signal}` : `exited with code ${String(o.code)}`}`;
 const abnormal = (o) => o.code !== 0 || o.stalled === true;
-function startConnector(binPath, childEnv, session, scrubber, toUpstream, upstreamOut, log, stderrAfterExitMs) {
-    const child = spawn(process.execPath, [binPath], { stdio: ['pipe', 'pipe', 'pipe'], detached: true, env: childEnv });
-    const toGroup = (signal) => {
-        if (child.pid === undefined)
-            return false;
-        try {
-            process.kill(-child.pid, signal);
-            return true;
-        }
-        catch {
-            return false;
-        }
-    };
-    const toChild = new Out(child.stdin);
-    const perform = (actions) => {
+function performer(log, toUpstream, toConnector) {
+    return (actions) => {
         for (const a of actions) {
             if (a.to === 'receipt')
                 log.line(`${RECEIPT_PREFIX}${asciiJson(a.receipt)}\n`);
             else if (a.to === 'upstream')
                 toUpstream(a.data);
             else
-                toChild.write(a.data);
+                toConnector(a.data);
         }
     };
-    const judged = (judge, unreadable) => {
+}
+function judging(perform) {
+    return (judge, unreadable) => {
         let actions;
         try {
             actions = judge();
@@ -420,6 +405,23 @@ function startConnector(binPath, childEnv, session, scrubber, toUpstream, upstre
         }
         perform(actions);
     };
+}
+function startConnector(binPath, childEnv, session, scrubber, toUpstream, upstreamOut, log, stderrAfterExitMs) {
+    const child = spawn(process.execPath, [binPath], { stdio: ['pipe', 'pipe', 'pipe'], detached: true, env: childEnv });
+    const toGroup = (signal) => {
+        if (child.pid === undefined)
+            return false;
+        try {
+            process.kill(-child.pid, signal);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    };
+    const toChild = new Out(child.stdin);
+    const perform = performer(log, toUpstream, (data) => toChild.write(data));
+    const judged = judging(perform);
     let rung = 0;
     let stopped = false;
     const climb = (to, signal = 'SIGTERM') => {
@@ -463,7 +465,7 @@ function startConnector(binPath, childEnv, session, scrubber, toUpstream, upstre
         return ended;
     })();
     return {
-        toChild,
+        input: toChild,
         perform,
         fromUpstream: (line, principal) => judged(() => session.fromUpstream(line, principal), () => session.upstreamOversized()),
         endInput: () => climb(1),
@@ -477,13 +479,37 @@ function startConnector(binPath, childEnv, session, scrubber, toUpstream, upstre
         outcome,
     };
 }
-async function runStdio(packageName, binPath, childEnv, session, scrubber, stdout, log) {
+function parkedRun(session, connector, stdout, log) {
+    const serverInfo = { name: 'sema-connector', version: ownManifest().version };
+    let end = () => undefined;
+    const ended = new Promise((resolve) => (end = () => resolve({ code: 0, signal: null })));
+    const perform = performer(log, (data) => stdout.write(data), (data) => {
+        const answer = parkedAnswer(data, connector, serverInfo);
+        if (answer !== null)
+            judged(() => session.fromConnector(Buffer.from(JSON.stringify(answer), 'utf8')), () => session.connectorOversized());
+    });
+    const judged = judging(perform);
+    return {
+        input: stdout,
+        perform,
+        fromUpstream: (line, principal) => judged(() => session.fromUpstream(line, principal), () => session.upstreamOversized()),
+        endInput: end,
+        stop: () => {
+            end();
+            setTimeout(abandon, TEARDOWN_STEP_MS).unref();
+        },
+        outcome: ended.then((outcome) => {
+            perform(session.connectorGone('the launcher ended the parked session', false));
+            return outcome;
+        }),
+    };
+}
+async function runStdio(packageName, run, session, stdout, log) {
     const resolution = standaloneResolver().resolve({ headers: {} });
     if (!resolution.ok)
         throw new Error('the standalone principal cannot be refused');
     const anonymous = resolution.principal;
-    const run = startConnector(binPath, childEnv, session, scrubber, (data) => stdout.write(data), stdout, log);
-    const upstream = pump(process.stdin, run.toChild, { line: (line) => run.fromUpstream(line, anonymous), oversized: () => run.perform(session.upstreamOversized()) }, [stdout]);
+    const upstream = pump(process.stdin, run.input, { line: (line) => run.fromUpstream(line, anonymous), oversized: () => run.perform(session.upstreamOversized()) }, [stdout]);
     void upstream.then(() => run.endInput());
     for (const s of STOP_SIGNALS)
         process.on(s, (signal) => run.stop(signal));
@@ -505,7 +531,7 @@ async function runHosted(plan, keys, packageName, binPath, env, log) {
         const run = startConnector(binPath, childEnvironment(env, hostedConnectorDir(plan.name), NO_HANDLES), session, new Scrubber(NO_HANDLES.values), (data) => deliver(String(data)), null, log, TEARDOWN_STEP_MS);
         return {
             send: (raw, principal) => run.fromUpstream(raw, principal),
-            busy: () => run.toChild.behind(),
+            busy: () => run.input.behind(),
             readStatus: (id, principal) => run.perform(session.statusFor(id, principal)),
             end: (signal) => (signal === undefined ? run.endInput() : run.stop(signal)),
             gone: run.outcome.then((o) => {
@@ -527,6 +553,24 @@ async function runHosted(plan, keys, packageName, binPath, env, log) {
     setTimeout(abandon, TEARDOWN_STEP_MS);
     return EXIT.ok;
 }
+const readingLine = (r) => `seed: ${r.name} ${r.outcome}${r.outcome === 'not_installed' ? ` (${r.message})` : r.outcome === 'refused' ? ` (${r.reason}: ${r.message})` : ''}\n`;
+function runSeed(configDir, stdout, log) {
+    let result;
+    try {
+        result = seed({ configDir });
+    }
+    catch (e) {
+        log.line(`sema-connector: seed: failed (${writeFailure(e)}); the marker was not written\n`);
+        return EXIT.notSeeded;
+    }
+    for (const r of result.readings)
+        stdout.write(readingLine(r));
+    if (!result.ok) {
+        log.line(`sema-connector: seed: ${result.reason}: ${result.message}\n`);
+        return EXIT.notSeeded;
+    }
+    return result.readings.every((r) => r.outcome === 'mounted' || r.outcome === 'present' || r.outcome === 'not_installed') ? EXIT.ok : EXIT.notSeeded;
+}
 export async function main(argv, env) {
     const stdout = new Out(process.stdout);
     const log = new Log(new Out(process.stderr));
@@ -539,6 +583,8 @@ export async function main(argv, env) {
         log.line(`sema-connector: ${plan}\n${USAGE}\n`);
         return finish(EXIT.guard);
     }
+    if (plan.command === 'seed')
+        return finish(runSeed(plan.configDir, stdout, log));
     if (plan.mode === 'hosted') {
         const keys = await obtainKeySet(plan.keySet);
         if (!keys.ok) {
@@ -570,14 +616,19 @@ export async function main(argv, env) {
         log.line(`sema-connector: ${NOT_INSTALLED}: package ${resolved.packageName} ${resolved.reason}\n`);
         return finish(EXIT.notInstalled);
     }
+    const parked = mintState({ handles: secrets.handles, nowMs: Date.now() }) === 'unauthorized';
     const session = new Session({
         connector: plan.name,
         status: (tools) => mintStatus({ handles: secrets.handles, nowMs: Date.now(), tools }),
         ownIdPrefix: `sema-connector/${randomUUID()}`,
         withheld: secretMatcher(secrets.values),
+        ...(parked ? { parked: true } : {}),
     });
     try {
-        return finish(await runStdio(resolved.packageName, resolved.binPath, childEnvironment(env, handleDirectory(plan.configDir, plan.name), secrets), session, new Scrubber(secrets.values), stdout, log));
+        const run = parked
+            ? parkedRun(session, plan.name, stdout, log)
+            : startConnector(resolved.binPath, childEnvironment(env, handleDirectory(plan.configDir, plan.name), secrets), session, new Scrubber(secrets.values), (data) => stdout.write(data), stdout, log);
+        return finish(await runStdio(resolved.packageName, run, session, stdout, log));
     }
     finally {
         secrets.remove();

package/dist/mount.d.ts

@@ -12,6 +12,10 @@ export type MountResult = {
     readonly reason: MountRefusal;
     readonly message: string;
 };
+export declare function nameRefusal(name: unknown): {
+    readonly reason: 'invalid_name' | 'reserved_name';
+    readonly message: string;
+} | null;
 export declare function standaloneEntry(name: string, configDir: string): {
     name: string;
     transport: {