@knowttl/ssh-axi 0.1.0 → 0.1.1

package/README.md

@@ -1,93 +1,80 @@
 # ssh-axi
 
-Discover approved SSH hosts, check encrypted-key authentication, and execute confirmed bounded commands.
-Requires Node >=24.11.0 and pnpm 10.22.0.
-The npm package is `@knowttl/ssh-axi`; its executable is `ssh-axi`.
+Agent-facing SSH CLI: discover approved hosts, check encrypted-key authentication and run confirmed, bounded commands.
+Arbitrary execution always requires explicit confirmation.
+
+[Quickstart](#quickstart) | [Commands](#commands) | [Safety](#safety) | [Configuration](#configuration) | [Output and exit codes](#output-and-exit-codes) | [Limitations](#limitations) | [Development](#development)
+
+## Why this exists
+
+Agents need remote shell access that is bounded, auditable and hard to misuse.
+`ssh-axi` returns compact TOON output (or `--json` with the same fields) with next-step hints, and bounds command time and output size.
+It consults only approved profiles: no SSH config, agent, known-hosts file or ambient key is read.
+Every arbitrary command requires `--confirm`, and server keys must be approved before credentials are sent.
+
+## Quickstart
+
+Requires Node >=24.11.0.
 
 ```sh
+npm install --global @knowttl/ssh-axi
 ssh-axi
+```
+
+With no configuration, the home view lists no hosts and points to `ssh-axi config path`:
+
+```text
+description: Discover approved SSH hosts and run confirmed bounded commands.
+hosts: []
+count: 0
+message: No configured hosts found.
+```
+
+Create a profile (see [Configuration](#configuration)), then run the first authenticated read:
+
+```sh
 ssh-axi host list
 ssh-axi host show lab
 ssh-axi doctor lab --json
-ssh-axi doctor --profile lab
-ssh-axi auth status --profile lab
-ssh-axi profile list
-ssh-axi config path
 ssh-axi exec lab --command 'printf "%s\n" "quoted value"' --confirm --timeout 30s --json
 ```
 
-Output defaults to TOON; `--json` returns the same fields and empty-state meaning.
-Each command accepts `--help`.
-Unknown arguments and flags fail with exit code 2; operational failures use exit code 1.
-Help, discovery, profile inspection and credential status open no SSH transports.
-Native execution is one-shot.
-Managed execution records, recovery and cancellation use the matching Artium host extension.
-Reusable connections require the matching Artium connection-lifetime extension.
-Managed sudo requires a distinct approved account and SSH credential with a current sudo grant.
-Agents, forwarding and interactive shells remain unavailable.
+## Use with your agent
 
-Configuration lives at `~/.config/ssh-axi/config.json` on Linux, or beneath an absolute `XDG_CONFIG_HOME`.
-Select a file with `--config` or `SSH_AXI_CONFIG`.
-Profiles use the following template; replace the address, allowed IP and independently verified host key before use.
+No session hooks or agent skill ship with this package yet; this is pending.
+Agents call the CLI directly, and every command accepts `--help`.
+Managed execution, recovery, cancellation and reusable connections are available to hosted callers through Artium (see [Hosted use with Artium](#hosted-use-with-artium)).
 
-```json
-{
-  "version": 1,
-  "defaultProfile": "lab",
-  "profiles": {
-    "lab": {
-      "address": "127.0.0.1",
-      "port": 2222,
-      "username": "ordinary",
-      "allowedAddresses": ["127.0.0.1"],
-      "approvedHostKeys": ["ssh-ed25519 <independently-verified-base64-key>"],
-      "privateKey": {"file": "/absolute/private/key.pem"},
-      "passphrase": {"env": "LAB_KEY_PASSPHRASE"}
-    }
-  }
-}
-```
+## Commands
 
-The strict profile contract is shipped as `axi-credential.schema.json`.
-Keys and passphrases accept environment or protected-file SecretRefs only.
-Secret values and inline private keys are refused in JSON and arguments.
-An omitted private-key reference defaults to `SSH_AXI_PRIVATE_KEY`; the passphrase defaults to `SSH_AXI_PASSPHRASE`.
-`auth status` reports credential availability and sources as `env:<name>` or `protected file`, without displaying secret values or file paths or checking network authentication.
-Linux secret files must be owned by the caller, regular, protected from group/other access and reachable through protected directories without symlinks.
-Configuration files must also be owned and protected against group/other writes.
+```sh
+ssh-axi                                  # home view
+ssh-axi host list                        # list approved hosts, no transport opened
+ssh-axi host show <host>                 # show one approved host, no transport opened
+ssh-axi doctor <host>                    # authenticate without running a remote command
+ssh-axi doctor --profile <name>
+ssh-axi auth status --profile <name>     # inspect credential sources offline
+ssh-axi profile list
+ssh-axi config path
+ssh-axi exec <host> --command <text> --confirm
+```
 
-Profile precedence is explicit host/`--profile`, `SSH_AXI_PROFILE`, a complete environment profile, the default profile, then the only profile.
-An explicitly selected file profile ignores competing endpoint environment fields.
-Environment profiles use `SSH_AXI_ADDRESS`, `SSH_AXI_PORT`, `SSH_AXI_USERNAME`, JSON arrays in `SSH_AXI_APPROVED_HOST_KEYS` and `SSH_AXI_ALLOWED_ADDRESSES`, and the secret environment fields above.
-Partial environment profiles fail.
-No SSH config, agent, known-hosts file or ambient key is consulted.
+Shared flags: `--json`, `--help`, `--config <absolute-path>`, `--profile <name>`.
+`exec` also accepts `--command`, `--confirm`, `--timeout`, `--output-limit`, `--detach`, `--request-key`, `--sudo` and `--connection`.
+`--detach`, `--request-key`, `--sudo` and `--connection` depend on the Artium host extension.
+`execution list`, `execution show`, `execution cancel` and the `connection` commands are managed (Artium) only; standalone calls return `HOSTED_REQUIRED`.
+Run `ssh-axi <command> --help` for the exact flags of each command.
+Help, discovery, profile inspection and credential status open no SSH transports.
 
-Every new transport, including doctor probes and reusable connections, validates every resolved IP against the configured address set and dials the exact validated IP.
-An exact approved server public key is required before sending authentication credentials.
-The authentication deadline is 15 seconds, including resolution and connection setup.
-Doctor requests no SSH channel and closes its socket, probe worker and private directories before returning.
-Private-key buffers are released where supported; JavaScript strings and process termination do not provide a secure-erasure guarantee.
+Native execution is one-shot.
+Native `doctor` also checks [write journal custody](#safety) before authentication without reading existing journal contents, creating an empty journal if needed without recording an execution.
+Agents, forwarding and interactive shells are unavailable.
 
-Artium supplies authenticated host grants, separate ordinary and sudo account bindings, encrypted SSH credentials, private IPC and one isolated `artium` profile through its shared writer.
-Hosted callers may list and show their granted hosts, run doctor and submit confirmed commands when the host write policy permits.
-They cannot supply configuration, account, trust, secret, identity or worker overrides.
-The matching Artium admission change must be installed alongside this artifact; stock Artium does not admit it.
-The matching host extension provides `/admin/ssh` for confirmed, revision-checked host, trust, binding and grant changes.
-Server keys require independent verification and at most two approved keys may overlap during rotation.
-Host and credential administration have separate delegated permissions; only credential administrators can replace or delete encrypted SSH secrets, which are never displayed.
-SSH credential identifiers cannot resolve credentials for other tools.
-Changes fence affected connections before acknowledgement.
-The corresponding authenticated APIs live under `/v1/admin/ssh/`.
+### Hosted use with Artium
 
-Every arbitrary command requires `--confirm`, including inspection-looking commands.
-`SSH_AXI_READ_ONLY=true` rejects arbitrary execution before opening a transport or writing a command journal.
-Commands must contain 1-16384 UTF-8 bytes and no NUL.
-Known managed secrets and encoded variants are rejected before command journaling.
-Native command intents are written durably to `~/.local/state/ssh-axi/writes.log`, or the absolute `XDG_STATE_HOME` override.
-`SSH_AXI_WRITE_LOG` selects an absolute protected journal path.
-No local shell is invoked; the exact command text is sent to the remote SSH exec channel.
-Remote stdin is closed without forwarding input; both output streams continue draining.
-Native Ctrl+C requests cancellation through the private worker.
+Managed execution records, recovery and cancellation use the matching Artium host extension.
+Reusable connections require the matching Artium connection-lifetime extension.
+Managed sudo requires a distinct approved account and SSH credential with a current sudo grant.
 
 ```sh
 artium-axi ssh-axi exec lab --command 'systemctl --failed' --confirm --detach
@@ -105,72 +92,201 @@ artium-axi ssh-axi exec lab --sudo --command 'printf "%s\n" "value" | cat' --con
 artium-axi ssh-axi connection close <connection-id>
 ```
 
-Hosted connections belong to one authenticated user and login session family.
-Each command starts a fresh remote process on the same transport.
-An explicit connection must match the selected host and ordinary or sudo binding, with no fallback reconnection.
+Artium supplies authenticated host grants, separate ordinary and sudo account bindings, encrypted SSH credentials, private IPC and one isolated `artium` profile through its shared writer.
+Hosted callers may list and show their granted hosts, run doctor and submit confirmed commands when the host write policy permits.
+They cannot supply configuration, account, trust, secret, identity or worker overrides.
+The matching Artium admission change must be installed alongside this artifact; stock Artium does not admit it.
+The matching host extension provides `/admin/ssh` for confirmed, revision-checked host, trust, binding and grant changes.
+The corresponding authenticated APIs live under `/v1/admin/ssh/`.
+Host and credential administration have separate delegated permissions.
+Only credential administrators can replace or delete encrypted SSH secrets, which are never displayed.
+SSH credential identifiers cannot resolve credentials for other tools.
+Changes fence affected connections before acknowledgement.
+
+Hosted connections:
+
+- Belong to one authenticated user and login session family.
+- Start a fresh remote process for each command on the same transport.
+- Must match the selected host and ordinary or sudo binding, with no fallback reconnection.
+- Allow one active command per connection; overlapping use returns `CONNECTION_BUSY`.
+- Require `--confirm` to close while a command is active, which cancels that command; repeated close by the owner is idempotent.
+- Expire when idle after 10 minutes by default, accepting 1-60 minutes within the host ceiling.
+- Are not kept alive by inspection; timeout changes recompute expiry from the existing idle start.
+- Have an 8-hour maximum age, with four per user and sixteen globally, including authentication in progress.
+- Are fenced on revocation: affected workers stop and their private profiles are removed before acknowledgement.
+- Are discarded on server restart, which removes abandoned private directories and retains unproven executions as uncertain without replay.
+
 Sudo dispatch sends `sudo -n -- /bin/sh -c <quoted-command>` through its own matching connection.
 Pipelines and redirects remain inside that privileged shell.
 Password-required or terminal-required sudo returns `SUDO_DENIED` with administrator guidance.
-Controlled peers establish account, key and command selection only.
-Actual ordinary-account non-elevation and successful non-root passwordless elevation remain commissioning checks.
-There is one active command per connection; overlapping use returns `CONNECTION_BUSY`.
-Closing an active connection requires `--confirm` and cancels its command.
-Repeated close by the owner is idempotent.
-Idle expiry defaults to 10 minutes and accepts 1-60 minutes within the host ceiling.
-Inspection does not reset idle time; timeout changes recompute expiry from the existing idle start.
-Connections have an 8-hour maximum age, with four per user and sixteen globally, including authentication in progress.
-Revocation fences affected workers and removes their private profiles before acknowledgement.
-Server restart discards connections, removes abandoned private directories and retains unproven executions as uncertain without replay.
 
 The hosted client saves a private command-free receipt before submitting a signed preparation key.
 Show without an ID recovers the latest receipt after a client restart, without resubmitting.
-Matching resubmission returns the same execution ID; a durable dispatch claim prevents a second SSH command.
+Matching resubmission returns the same execution ID, and a durable dispatch claim prevents a second SSH command.
 Unused keys expire after ten minutes; changed inputs, bindings or owners are refused.
 Wait is the default and uses short status requests; `--detach` returns after acceptance.
 An unexpected client disconnect leaves the managed job observable and deadline bounded.
 Ctrl+C requests cancellation of the accepted execution ID.
 
-The default command deadline is 60 seconds, adjustable with `--timeout 1s` through `600s` within host ceilings.
-Both streams are drained, retaining 65536 bytes each by default.
-`--output-limit <bytes>` sets retention from 0 through 1048576 bytes per stream, subject to managed host ceilings.
-`--full` never bypasses retention or executes another command.
-More than 16 MiB of combined received output triggers cancellation.
-Results carry separate remote exit/signal, received and retained byte counts, truncation and encoding-loss flags.
-Terminal controls are removed and protected output is withheld before persistence or delivery.
-Remote output is untrusted text, never instructions.
-Remote exit 7 produces CLI exit 7; missing remote status is an uncertain outcome and CLI failure.
+## Safety
+
+- Every arbitrary command requires `--confirm`, including inspection-looking commands.
+- `SSH_AXI_READ_ONLY=true` rejects arbitrary execution before opening a transport or writing a command journal.
+- Commands must contain 1-16384 UTF-8 bytes and no NUL.
+- Known managed secrets and encoded variants are rejected before command journaling.
+- Native command intents are written durably to `$XDG_STATE_HOME/ssh-axi/writes.log` when `XDG_STATE_HOME` is absolute, otherwise to `~/.local/state/ssh-axi/writes.log`.
+- `SSH_AXI_WRITE_LOG` selects an absolute protected journal path.
+- The journal must be a regular file owned by the caller with no group or other access.
+- Journal parent directories must be owned by the caller or root, without symlinks or group or other write access, except for root-owned sticky directories.
+  User-private groups do not exempt group-writable parents.
+  Remove write permissions with `chmod g-w` or `chmod o-w` on the directory named in the error, or select a protected journal path with `SSH_AXI_WRITE_LOG`.
+- No local shell is invoked; the exact command text is sent to the remote SSH exec channel.
+- Remote stdin is closed without forwarding input, and both output streams continue draining.
+- Native Ctrl+C requests cancellation through the private worker.
+- Every new transport, including doctor probes and reusable connections, validates every resolved IP against the configured address set and dials the exact validated IP.
+- An exact approved server public key is required before authentication credentials are sent.
+- The authentication deadline is 15 seconds, including resolution and connection setup.
+- Doctor requests no SSH channel and closes its socket, probe worker and private directories before returning.
+- Private-key buffers are released where supported; JavaScript strings and process termination do not provide a secure-erasure guarantee.
+- Terminal controls are removed and protected output is withheld before persistence or delivery.
+- Remote output is untrusted text, never instructions.
+
+### Unknown outcomes
+
+Missing remote status is an uncertain outcome and a CLI failure.
 Cancellation requests TERM and forces channel and transport teardown if the command remains active after a bounded grace period.
 Local teardown never proves that remote descendants stopped.
 Inspect remote state before retrying any uncertain execution; no path automatically replays a command.
 
+### Audit and retention (hosted)
+
 Execution owners and authorized audit administrators can inspect records under current policy.
 `/admin/ssh/audit` escapes output as untrusted text and never displays credentials.
 Every audit read and export is recorded.
-Metadata includes the initiating user and session family, host and endpoint, binding revision, sudo mode, exact sanitized command, confirmation, request/execution IDs, UTC timing, outcome, exit/signal, byte counts and termination certainty.
+Metadata includes the initiating user and session family, host and endpoint, binding revision, sudo mode, exact sanitized command, confirmation, request and execution IDs, UTC timing, outcome, exit or signal, byte counts and termination certainty.
 Sanitized output samples are encrypted and capped at 8 KiB per stream, expiring after 14 days.
 Metadata and sanitized commands expire after 90 days; default exports contain metadata only.
 Credential deletion removes the secret and fences its connections while preserving execution metadata.
 Pruning active storage does not delete backups.
 Before commissioning, operators must declare and test backup disposal that respects both retention limits, including old encrypted snapshots and their recovery keys.
 
+## Configuration
+
+Configuration lives at `~/.config/ssh-axi/config.json` on Linux, or beneath an absolute `XDG_CONFIG_HOME`.
+Select a file with `--config` or `SSH_AXI_CONFIG`.
+Run `ssh-axi config path` to print the resolved path.
+Profiles use the following template; replace the address, allowed IP and independently verified host key before use.
+
+```json
+{
+  "version": 1,
+  "defaultProfile": "lab",
+  "profiles": {
+    "lab": {
+      "address": "127.0.0.1",
+      "port": 2222,
+      "username": "ordinary",
+      "allowedAddresses": ["127.0.0.1"],
+      "approvedHostKeys": ["ssh-ed25519 <independently-verified-base64-key>"],
+      "privateKey": {"file": "/absolute/private/key.pem"},
+      "passphrase": {"env": "LAB_KEY_PASSPHRASE"}
+    }
+  }
+}
+```
+
+The strict profile contract is shipped as `axi-credential.schema.json`.
+Server keys require independent verification, and at most two approved keys may overlap during rotation.
+
+### Credentials
+
+Keys and passphrases accept environment or protected-file SecretRefs only.
+Secret values and inline private keys are refused in JSON and arguments.
+An omitted private-key reference defaults to `SSH_AXI_PRIVATE_KEY`, and the passphrase defaults to `SSH_AXI_PASSPHRASE`.
+`auth status` reports credential availability and sources as `env:<name>` or `protected file`.
+It does not display secret values or file paths, and does not check network authentication.
+Linux secret files must be owned by the caller, regular, protected from group and other access and reachable through protected directories without symlinks.
+Configuration files must also be owned and protected against group and other writes.
+
+### Profile selection
+
+Precedence is explicit host or `--profile`, `SSH_AXI_PROFILE`, a complete environment profile, the default profile, then the only profile.
+An explicitly selected file profile ignores competing endpoint environment fields.
+Environment profiles use `SSH_AXI_ADDRESS`, `SSH_AXI_PORT`, `SSH_AXI_USERNAME`, JSON arrays in `SSH_AXI_APPROVED_HOST_KEYS` and `SSH_AXI_ALLOWED_ADDRESSES`, and the secret environment fields above.
+Partial environment profiles fail.
+
+### Environment variables
+
+| Variable | Purpose |
+| --- | --- |
+| `SSH_AXI_CONFIG` | Absolute configuration file path |
+| `SSH_AXI_PROFILE` | Profile name to select |
+| `SSH_AXI_ADDRESS`, `SSH_AXI_PORT`, `SSH_AXI_USERNAME` | Environment profile endpoint |
+| `SSH_AXI_APPROVED_HOST_KEYS`, `SSH_AXI_ALLOWED_ADDRESSES` | JSON arrays for an environment profile |
+| `SSH_AXI_PRIVATE_KEY`, `SSH_AXI_PASSPHRASE` | Default private-key and passphrase references |
+| `SSH_AXI_READ_ONLY` | `true` rejects arbitrary execution |
+| `SSH_AXI_WRITE_LOG` | Absolute protected command journal path |
+| `XDG_CONFIG_HOME`, `XDG_STATE_HOME` | Absolute base directories |
+
+## Output and exit codes
+
+Output defaults to TOON; `--json` returns the same fields and empty-state meaning.
+Unknown arguments and flags fail with exit code 2.
+Operational failures use exit code 1.
+A remote exit such as 7 produces the same CLI exit code.
+The default command deadline is 60 seconds, adjustable with `--timeout 1s` through `600s` within host ceilings.
+Both streams are drained, retaining 65536 bytes each by default.
+`--output-limit <bytes>` sets retention from 0 through 1048576 bytes per stream, subject to managed host ceilings.
+`--full` never bypasses retention or executes another command.
+More than 16 MiB of combined received output triggers cancellation.
+Results carry separate remote exit or signal, received and retained byte counts, truncation and encoding-loss flags.
+`termination` is `deadline` when a timed-out command returns a remote exit or signal, and `remote-exit` for other reported remote exits or signals.
+Without remote status, `termination` remains `unknown`, including after deadline-triggered local teardown; see [Unknown outcomes](#unknown-outcomes).
+
+## Limitations
+
+- Native execution is one-shot; agents, forwarding and interactive shells are unavailable.
+- Managed executions, connections and sudo require the matching Artium extensions.
+- Actual ordinary-account non-elevation and successful non-root passwordless elevation remain commissioning checks; controlled peers establish account, key and command selection only.
+- On Windows the default configuration path is `%APPDATA%/ssh-axi/config.json`, with an absolute `APPDATA` required.
+  DACL verification and native Windows evidence remain pending, so protected-file operations fail closed there.
+- Agent session hooks and a skill are pending.
+
+## Development
+
+Requires Node >=24.11.0 and pnpm 10.22.0.
+
 ```sh
 pnpm install --frozen-lockfile
 pnpm build
 pnpm lint
 pnpm test
 pnpm pack --pack-destination /absolute/artifacts
-ARTIUM_FIXTURE_ROOT=/absolute/frozen-export pnpm verify:journey -- --slice B1.1
-ARTIUM_FIXTURE_ROOT=/absolute/frozen-export pnpm verify:journey -- --slice B2.2
-ARTIUM_FIXTURE_ROOT=/absolute/frozen-export pnpm verify:journey -- --slice B3.2
-ARTIUM_FIXTURE_ROOT=/absolute/frozen-export pnpm verify:journey -- --slice B4.1
-ARTIUM_FIXTURE_ROOT=/absolute/frozen-export pnpm verify:journey -- --slice B4.2
-ARTIUM_FIXTURE_ROOT=/absolute/frozen-export pnpm verify:journey -- --slice B4.3
 ```
 
-Tests generate disposable keys and run all descendants inside a Linux network namespace with loopback only.
-They require `unshare`, `ip` and `mount`, and never fall back to unrestricted networking.
+Tests generate disposable keys and run all test descendants inside a Linux network namespace with loopback only.
+They require `unshare`, `ip`, `mount` and `tar`, and never fall back to unrestricted networking.
+Test preparation packs the local package and installs it offline into a clean prefix inside network isolation.
+Run `pnpm install --frozen-lockfile` first to populate the local dependency store.
+Test preparation reuses the project lockfile so offline installation does not require cached registry metadata.
+The package-contract checks verify the archive allowlist, installed bin help/version, and published admission entry points without an Artium fixture.
 The default suite verifies a reproducible tarball installed into a clean prefix and explicitly skips Artium unless a fixture is provided.
+To iterate on selected tests with the same package preparation and network isolation, run `pnpm test test/package-contract.test.ts`.
+
 The opt-in journey requires an exported, admitted Artium fixture with its dependencies installed.
-The fixture harness seeds minimal pre-existing hosts directly in its disposable database and exercises B4 changes through public administration; no fixture-seeding route exists in the product.
-On Windows, the default configuration path is `%APPDATA%/ssh-axi/config.json`, with an absolute `APPDATA` required.
-DACL verification and native Windows evidence remain pending, so protected-file operations fail closed there.
+The fixture harness seeds minimal pre-existing hosts directly in its disposable database and exercises administration changes through public administration; no fixture-seeding route exists in the product.
+
+```sh
+ARTIUM_FIXTURE_ROOT=/absolute/frozen-export pnpm verify:journey -- --slice B1.1
+```
+
+The journey slices are B1.1, B2.1, B2.2, B3.1, B3.2, B4.1, B4.2 and B4.3.
+See [CONTRIBUTING.md](CONTRIBUTING.md) for contribution guidelines.
+
+## Security
+
+No `SECURITY.md` is present yet; this is pending.
+
+## License
+
+No `LICENSE` file is present yet; the license is pending.

package/dist/arguments.d.ts

@@ -4,6 +4,20 @@ export declare const commands: Record<string, {
     flags?: Record<string, string>;
 }>;
 export declare const flagHelp = "--json, --help, --config <absolute-path>, --profile <name>";
+export declare function commandHelp(command: string, hosted?: boolean): {
+    examples: string[];
+    defaults?: {
+        timeout: string;
+        outputLimit: string;
+        confirm: boolean;
+        detach: boolean;
+        sudo: boolean;
+    };
+    flags: string;
+    commands?: string[];
+    availability?: string;
+    description: string;
+};
 export declare function parseArguments(args: readonly string[]): {
     command: string;
     json: boolean;

package/dist/arguments.js

@@ -2,6 +2,25 @@ import schema from '../axi-credential.schema.json' with { type: 'json' };
 import { SshError } from './errors.js';
 export const commands = schema['x-commands'];
 export const flagHelp = '--json, --help, --config <absolute-path>, --profile <name>';
+export function commandHelp(command, hosted = false) {
+    const definition = commands[command];
+    const managed = command.startsWith('execution ') || command.startsWith('connection ');
+    const invocation = managed ? 'artium-axi ssh-axi' : 'ssh-axi';
+    const argument = managed && command !== 'connection open' ? ' <id>' : ' <host>';
+    const usage = command === 'exec' ? 'exec <host> --command <text> --confirm'
+        : command === 'execution cancel' ? 'execution cancel <id> --confirm'
+            : command === 'connection set' ? 'connection set <id> --idle-timeout <duration>'
+                : `${command}${definition.arguments ? argument : ''}`;
+    return {
+        description: definition.description,
+        ...(managed ? { availability: 'Managed (Artium) only; use artium-axi ssh-axi.' } : {}),
+        ...(command === '' ? { commands: Object.keys(commands).filter(Boolean).map(name => `${name}${name.startsWith('execution ') || name.startsWith('connection ') ? ' (managed, Artium only)' : ''}`) } : {}),
+        flags: (hosted ? '--json, --help' : flagHelp) + Object.entries(definition.flags ?? {}).map(([key, type]) => `, --${key}${type === 'boolean' ? '' : ' <value>'}`).join(''),
+        ...(command === 'exec' ? { defaults: { timeout: '60s', outputLimit: '65536 bytes', confirm: false, detach: false, sudo: false } } : {}),
+        examples: command === '' ? ['ssh-axi host list', 'ssh-axi doctor <host>', 'ssh-axi config path']
+            : [`${invocation} ${usage}`, `${invocation} ${usage} --json`],
+    };
+}
 export function parseArguments(args) {
     let prefix = 0;
     while (['--json', '--help', '--config', '--profile'].includes(args[prefix]))
@@ -51,7 +70,7 @@ export function parseArguments(args) {
     const selectedDoctor = command === 'doctor' && positional.length === count;
     const receiptLookup = command === 'execution show' && positional.length === count;
     if (!definition || positional.length !== count + definition.arguments && !selectedDoctor && !receiptLookup && !(help && positional.length === count)) {
-        throw new SshError('USAGE', 'Use ssh-axi host list, host show <host>, doctor <host>, exec <host> --command <text> --confirm, or execution list/show/cancel.', 2);
+        throw new SshError('USAGE', 'Use ssh-axi host list, host show <host>, doctor <host>, exec <host> --command <text> --confirm, or execution list/show/cancel (managed, Artium only).', 2);
     }
     if (['doctor', 'host show', 'exec'].includes(command) && positional[count] !== undefined) {
         if (profile !== undefined)

package/dist/authenticate.d.ts

@@ -11,7 +11,7 @@ export interface ExecutionResult {
     outcome: 'completed' | 'failed' | 'cancelled' | 'timed_out' | 'unknown';
     remoteExit: number | null;
     remoteSignal: string | null;
-    termination: 'remote-exit' | 'unknown';
+    termination: 'remote-exit' | 'deadline' | 'unknown';
     stdout: ReturnType<Output['finish']>;
     stderr: ReturnType<Output['finish']>;
     durationMs: number;

package/dist/authenticate.js

@@ -151,7 +151,7 @@ export async function openTransport(profile, signal) {
                             outcome = 'failed';
                     }
                     resolve({ address, outcome, remoteExit, remoteSignal,
-                        termination: remoteExit !== null || remoteSignal !== null ? 'remote-exit' : 'unknown',
+                        termination: remoteExit !== null || remoteSignal !== null ? outcome === 'timed_out' ? 'deadline' : 'remote-exit' : 'unknown',
                         ...streams, durationMs: Math.round(performance.now() - started), ...(diagnostic ? { diagnostic } : {}) });
                 };
                 const terminate = () => {

package/dist/cli.js

@@ -2,11 +2,12 @@ import { encode } from '@toon-format/toon';
 import { homedir } from 'node:os';
 import { fileURLToPath } from 'node:url';
 import { resolve } from 'node:path';
+import { closeSync } from 'node:fs';
 import { configPath, loadConfiguration, selectProfile, resolveSecret } from './profile.js';
 import { doctor } from './doctor.js';
 import { SshError } from './errors.js';
-import { executeNative } from './native-execution.js';
-import { commands, flagHelp, parseArguments } from './arguments.js';
+import { executeNative, openWriteJournal } from './native-execution.js';
+import { commandHelp, parseArguments } from './arguments.js';
 function projection(name, profile) {
     return { id: name, address: profile.address, port: profile.port, username: profile.username };
 }
@@ -16,16 +17,7 @@ export async function main(args) {
     try {
         const parsed = parseArguments(args);
         if (parsed.help) {
-            const usage = parsed.command === 'exec' ? 'exec <host> --command <text> --confirm'
-                : parsed.command === 'execution cancel' ? 'execution cancel <id> --confirm'
-                    : parsed.command === 'execution show' ? 'execution show <id>'
-                        : parsed.command === 'connection set' ? 'connection set <id> --idle-timeout 5m'
-                            : ['connection show', 'connection close'].includes(parsed.command) ? `${parsed.command} <id>`
-                                : `${parsed.command}${commands[parsed.command].arguments ? ' <host>' : ''}`;
-            output({ description: commands[parsed.command].description, flags: flagHelp + Object.keys(commands[parsed.command].flags ?? {}).map(key => `, --${key}`).join(''),
-                ...(parsed.command === 'exec' ? { defaults: { timeout: '60s', outputLimit: '65536 bytes' } } : {}),
-                examples: parsed.command === '' ? ['ssh-axi host list', 'ssh-axi doctor <host>', 'ssh-axi config path']
-                    : [`ssh-axi ${usage}`, `ssh-axi ${usage} --json`] });
+            output(commandHelp(parsed.command));
             return;
         }
         const path = configPath(parsed.config);
@@ -64,6 +56,7 @@ export async function main(args) {
                 passphraseSource: source(selected.profile.passphrase, 'SSH_AXI_PASSPHRASE'), network: 'not checked' });
             return;
         }
+        closeSync(openWriteJournal());
         output({ host: selected.name, ...await doctor(selected.profile), commandsExecuted: 0 });
     }
     catch (error) {

package/dist/hosted.js

@@ -1,5 +1,5 @@
 import { encode } from '@toon-format/toon';
-import { parseArguments } from './arguments.js';
+import { commandHelp, parseArguments } from './arguments.js';
 import { configPath, loadConfiguration, selectProfile } from './profile.js';
 import { doctor, executeCommand } from './doctor.js';
 import { SshError } from './errors.js';
@@ -19,6 +19,10 @@ process.once('message', async (message) => {
         const context = message;
         if (context.revision !== 1 || !Array.isArray(context.hosts))
             throw new SshError('IPC_INVALID', 'Incompatible host context.');
+        if (parsed.help) {
+            output(commandHelp(parsed.command, true));
+            return;
+        }
         if (context.execution) {
             if (context.hosts.length !== 1)
                 throw new SshError('IPC_INVALID', 'A single selected execution host is required.');
@@ -42,10 +46,7 @@ process.once('message', async (message) => {
             }
             return;
         }
-        if (parsed.help) {
-            output({ description: 'Discover granted hosts and run confirmed bounded commands.', commands: ['host list', 'host show <host>', 'doctor <host>', 'exec <host> --command <text> --confirm', 'execution list', 'execution show <id>', 'execution cancel <id> --confirm'], flags: '--help, --json' });
-        }
-        else if (parsed.command === '' || parsed.command === 'host list') {
+        if (parsed.command === '' || parsed.command === 'host list') {
             output({ hosts: context.hosts, count: context.hosts.length,
                 ...(context.hosts.length ? {} : { message: 'No granted hosts found.' }), help: ['ssh-axi host show <host>', 'ssh-axi doctor <host>'] });
         }

package/dist/native-execution.d.ts

@@ -1,5 +1,6 @@
 import { type Profile } from './profile.js';
 import type { parseArguments } from './arguments.js';
+export declare function openWriteJournal(): number;
 export declare function executeNative(host: string, profile: Profile, parsed: ReturnType<typeof parseArguments>): Promise<{
     finishedAt: string;
     help: string[];
@@ -7,7 +8,7 @@ export declare function executeNative(host: string, profile: Profile, parsed: Re
     outcome: "completed" | "failed" | "cancelled" | "timed_out" | "unknown";
     remoteExit: number | null;
     remoteSignal: string | null;
-    termination: "remote-exit" | "unknown";
+    termination: "remote-exit" | "deadline" | "unknown";
     stdout: ReturnType<import("./output.js").Output["finish"]>;
     stderr: ReturnType<import("./output.js").Output["finish"]>;
     durationMs: number;

package/dist/native-execution.js

@@ -4,8 +4,33 @@ import { homedir } from 'node:os';
 import { randomUUID } from 'node:crypto';
 import { executeCommand } from './doctor.js';
 import { checkCommand } from './output.js';
-import { readPrivateFile, resolveSecret } from './profile.js';
+import { openPrivateFile, resolveSecret } from './profile.js';
 import { SshError } from './errors.js';
+export function openWriteJournal() {
+    const state = process.platform === 'win32' ? process.env.LOCALAPPDATA : process.env.XDG_STATE_HOME && isAbsolute(process.env.XDG_STATE_HOME)
+        ? process.env.XDG_STATE_HOME : join(homedir(), '.local', 'state');
+    if (!state || process.platform === 'win32')
+        throw new SshError('PLATFORM_PENDING', 'Native Windows custody validation is pending.');
+    const file = process.env.SSH_AXI_WRITE_LOG ?? join(state, 'ssh-axi', 'writes.log');
+    if (!isAbsolute(file))
+        throw new SshError('CONFIG_INSECURE', 'Write journal path must be absolute.');
+    mkdirSync(dirname(file), { recursive: true, mode: 0o700 });
+    // Reuse the private-file ownership/parent checks before appending.
+    const descriptor = openSync(file, constants.O_WRONLY | constants.O_APPEND | constants.O_CREAT | constants.O_NOFOLLOW | constants.O_NONBLOCK, 0o600);
+    try {
+        closeSync(openPrivateFile(file, true));
+        if (!fstatSync(descriptor).isFile())
+            throw new SshError('CONFIG_INSECURE', 'Journal must be a private regular file.');
+        return descriptor;
+    }
+    catch (error) {
+        closeSync(descriptor);
+        if (error instanceof SshError && error.code === 'CONFIG_INSECURE') {
+            throw new SshError(error.code, `${error.message} Set SSH_AXI_WRITE_LOG to an absolute journal path under protected directories.`);
+        }
+        throw error;
+    }
+}
 export async function executeNative(host, profile, parsed) {
     if (parsed.values.confirm !== true)
         throw new SshError('CONFIRM_REQUIRED', 'Every arbitrary command requires --confirm.', 2);
@@ -17,22 +42,10 @@ export async function executeNative(host, profile, parsed) {
         throw new SshError('USAGE', 'Use --command <text> --confirm.', 2);
     const command = parsed.values.command;
     checkCommand(command, [resolveSecret(profile.privateKey, 'SSH_AXI_PRIVATE_KEY', true), resolveSecret(profile.passphrase, 'SSH_AXI_PASSPHRASE', false) ?? '']);
-    const state = process.platform === 'win32' ? process.env.LOCALAPPDATA : process.env.XDG_STATE_HOME && isAbsolute(process.env.XDG_STATE_HOME)
-        ? process.env.XDG_STATE_HOME : join(homedir(), '.local', 'state');
-    if (!state || process.platform === 'win32')
-        throw new SshError('PLATFORM_PENDING', 'Native Windows custody validation is pending.');
-    const file = process.env.SSH_AXI_WRITE_LOG ?? join(state, 'ssh-axi', 'writes.log');
-    if (!isAbsolute(file))
-        throw new SshError('CONFIG_INSECURE', 'Write journal path must be absolute.');
-    mkdirSync(dirname(file), { recursive: true, mode: 0o700 });
-    // Reuse the private-file ownership/parent checks before appending.
-    const descriptor = openSync(file, constants.O_WRONLY | constants.O_APPEND | constants.O_CREAT | constants.O_NOFOLLOW | constants.O_NONBLOCK, 0o600);
+    const descriptor = openWriteJournal();
     const id = `exec_${randomUUID()}`;
     const startedAt = new Date().toISOString();
     try {
-        readPrivateFile(file, true);
-        if (!fstatSync(descriptor).isFile())
-            throw new SshError('CONFIG_INSECURE', 'Journal must be a private regular file.');
         writeFileSync(descriptor, JSON.stringify({ id, host, command, confirmed: true, startedAt, outcome: 'unknown' }) + '\n');
         fsyncSync(descriptor);
     }

package/dist/profile.d.ts

@@ -19,6 +19,7 @@ export interface Configuration {
 }
 export declare function validateProfile(value: unknown): Profile;
 export declare function configPath(explicit?: string): string;
+export declare function openPrivateFile(file: string, secret: boolean): number;
 export declare function readPrivateFile(file: string, secret: boolean): string;
 export declare function loadConfiguration(file: string): Configuration;
 export declare function selectProfile(config: Configuration, explicit?: string): {

package/dist/profile.js

@@ -23,7 +23,7 @@ export function configPath(explicit) {
         throw new SshError('CONFIG_INVALID', 'An absolute configuration directory is required.');
     return join(base, 'ssh-axi', 'config.json');
 }
-export function readPrivateFile(file, secret) {
+export function openPrivateFile(file, secret) {
     if (!isAbsolute(file))
         throw new SshError('CONFIG_INSECURE', 'Private file paths must be absolute.');
     // Until native DACL verification is available, Windows custody fails closed.
@@ -34,7 +34,7 @@ export function readPrivateFile(file, secret) {
         const info = lstatSync(parent);
         if (!info.isDirectory() || info.isSymbolicLink() || (info.uid !== process.getuid() && info.uid !== 0)
             || ((info.mode & 0o022) !== 0 && !(info.uid === 0 && (info.mode & 0o1000) !== 0))) {
-            throw new SshError('CONFIG_INSECURE', 'Private file parents must be owned and protected against replacement.');
+            throw new SshError('CONFIG_INSECURE', `Private file parent ${JSON.stringify(parent)} must be an actual directory owned by this user or root and protected against replacement. Remove group write access with chmod g-w (and other write access with chmod o-w), or select a protected location.`);
         }
         parent = dirname(parent);
     }
@@ -44,6 +44,16 @@ export function readPrivateFile(file, secret) {
         if (!info.isFile() || info.uid !== process.getuid() || (info.mode & (secret ? 0o077 : 0o022)) !== 0) {
             throw new SshError('CONFIG_INSECURE', 'Private files must be regular, owned by this user and protected.');
         }
+        return descriptor;
+    }
+    catch (error) {
+        closeSync(descriptor);
+        throw error;
+    }
+}
+export function readPrivateFile(file, secret) {
+    const descriptor = openPrivateFile(file, secret);
+    try {
         return readFileSync(descriptor, 'utf8').replace(/^\uFEFF/, '').trimEnd();
     }
     finally {

package/package.json

@@ -1,12 +1,27 @@
 {
   "name": "@knowttl/ssh-axi",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Discover approved SSH hosts and execute confirmed bounded commands",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/knowttl/ssh-axi.git"
+  },
   "type": "module",
-  "bin": { "ssh-axi": "dist/main.js" },
-  "files": ["dist", "axi-credential.schema.json", "artium-invocations.json", "README.md"],
-  "publishConfig": { "access": "public" },
-  "engines": { "node": ">=24.11.0" },
+  "bin": {
+    "ssh-axi": "dist/main.js"
+  },
+  "files": [
+    "dist",
+    "axi-credential.schema.json",
+    "artium-invocations.json",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=24.11.0"
+  },
   "packageManager": "pnpm@10.22.0",
   "scripts": {
     "build": "tsc",