Crate start_command 

start-command library

Provides command execution with isolation, substitution, and failure handling.

Re-exports

pub use args_parser::generate_session_name;

pub use args_parser::generate_uuid;

pub use args_parser::get_effective_mode;

pub use args_parser::has_isolation;

pub use args_parser::is_valid_uuid;

pub use args_parser::parse_args;

pub use args_parser::validate_options;

pub use args_parser::ParsedArgs;

pub use args_parser::WrapperOptions;

pub use args_parser::VALID_BACKENDS;

pub use args_parser::VALID_OUTPUT_FORMATS;

pub use args_parser::VALID_SHELLS;

pub use detached_finalize::build_detached_finalize_snippet;

pub use detached_finalize::finalize_detached_execution;

pub use detached_finalize::reconcile_finalized_record;

pub use detached_finalize::run_internal_finalize;

pub use detached_finalize::DetachedFinalizeFacts;

pub use detached_finalize::FinalizeOutcome;

pub use detached_finalize::END_TIME_SOURCE_DOCKER_FINISHED_AT;

pub use detached_finalize::END_TIME_SOURCE_LOG_FOOTER;

pub use detached_finalize::END_TIME_SOURCE_OBSERVED_AT;

pub use detached_finalize::INTERNAL_FINALIZE_FLAG;

pub use detached_finalize::WATCHER_LOST_CONTAINER;

pub use docker_post_mortem::build_docker_post_mortem_snippet;

pub use docker_post_mortem::build_docker_removal_note_snippet;

pub use docker_post_mortem::build_docker_running_condition;

pub use docker_post_mortem::build_docker_state_snippet;

pub use docker_post_mortem::build_docker_still_running_note_snippet;

pub use docker_post_mortem::build_docker_wait_for_exit_snippet;

pub use docker_post_mortem::format_container_post_mortem;

pub use docker_post_mortem::format_container_removal_note;

pub use docker_post_mortem::format_lifetime;

pub use docker_post_mortem::normalize_docker_timestamp;

pub use docker_post_mortem::ContainerPostMortem;

pub use docker_post_mortem::DOCKER_RUNNING_INSPECT_FORMAT;

pub use docker_post_mortem::DOCKER_STATE_INSPECT_FORMAT;

pub use docker_post_mortem::DOCKER_ZERO_TIME;

pub use docker_post_mortem::LOG_CAPTURE_STOPPED_NOTE;

pub use docker_post_mortem::POST_MORTEM_HEADER;

pub use docker_post_mortem::STILL_RUNNING_NOTE;

pub use execution_attach::attach_execution;

pub use execution_attach::attach_execution_with_runners;

pub use execution_attach::build_attach_plan;

pub use execution_attach::format_attach_result_as_links_notation;

pub use execution_attach::AttachPlan;

pub use execution_attach::AttachResultFields;

pub use execution_attach::ExecutionAttachResult;

pub use execution_attach::InteractiveRunner;

pub use execution_attach::SystemInteractiveRunner;

pub use execution_control::collect_descendant_pids;

pub use execution_control::collect_descendant_pids_with_runner;

pub use execution_control::collect_process_ids;

pub use execution_control::collect_process_ids_with_runner;

pub use execution_control::control_execution;

pub use execution_control::control_execution_with_runner;

pub use execution_control::format_control_result_as_links_notation;

pub use execution_control::get_control_command;

pub use execution_control::parse_screen_pid;

pub use execution_control::CommandRunOutput;

pub use execution_control::CommandRunner;

pub use execution_control::ControlAction;

pub use execution_control::ControlCommand;

pub use execution_control::ExecutionControlResult;

pub use execution_control::SystemCommandRunner;

pub use execution_resume::build_resume_plan;

pub use execution_resume::build_resumed_session_name;

pub use execution_resume::build_snapshot_image_name;

pub use execution_resume::resume_execution;

pub use execution_resume::resume_execution_with;

pub use execution_resume::ExecutionResumeResult;

pub use execution_resume::ResumeHooks;

pub use execution_resume::ResumeMode;

pub use execution_resume::ResumePlan;

pub use execution_resume::ResumeResultFields;

pub use execution_resume::SystemResumeHooks;

pub use execution_resume_all::format_resume_all;

pub use execution_resume_all::resume_all_executions;

pub use execution_resume_all::resume_all_executions_with;

pub use execution_resume_all::ExecutionResumeAllResult;

pub use execution_resume_all::ResumeAllAction;

pub use execution_resume_all::ResumeAllEntry;

pub use execution_store::clink_reference;

pub use execution_store::is_clink_installed;

pub use execution_store::CleanupOptions;

pub use execution_store::CleanupResult;

pub use execution_store::ExecutionRecord;

pub use execution_store::ExecutionRecordOptions;

pub use execution_store::ExecutionStats;

pub use execution_store::ExecutionStatus;

pub use execution_store::ExecutionStore;

pub use execution_store::ExecutionStoreOptions;

pub use exit_reason::describe_exit_code;

pub use exit_reason::describe_exit_code_str;

pub use exit_reason::detect_exit_reason;

pub use exit_reason::resolve_exit_reason;

pub use exit_reason::signal_name_for_exit_code;

pub use exit_reason::ExitCodeDescription;

pub use failure_handler::handle_failure;

pub use failure_handler::Config as FailureConfig;

pub use isolation::append_log_file;

pub use isolation::build_command_string;

pub use isolation::build_command_string_with;

pub use isolation::build_display_command;

pub use isolation::build_shell_with_args_cmd_args;

pub use isolation::command_name;

pub use isolation::create_log_footer;

pub use isolation::create_log_header;

pub use isolation::create_log_path;

pub use isolation::create_log_path_for_execution;

pub use isolation::docker_image_exists;

pub use isolation::docker_pull_image;

pub use isolation::get_default_docker_image;

pub use isolation::get_timestamp;

pub use isolation::is_command_available;

pub use isolation::is_interactive_shell_command;

pub use isolation::is_shell_invocation_with_args;

pub use isolation::quote_shell_arg;

pub use isolation::quote_shell_arg_with;

pub use isolation::run_as_isolated_user;

pub use isolation::run_isolated;

pub use isolation::split_shell_words;

pub use isolation::split_shell_words_with;

pub use isolation::to_shell_words;

pub use isolation::write_log_file;

pub use isolation::IsolationOptions;

pub use isolation::IsolationResult;

pub use isolation::LogHeaderParams;

pub use isolation::ShellQuotingStyle;

pub use isolation_metadata::build_isolation_options_map;

pub use isolation_metadata::docker_runtime_metadata;

pub use isolation_metadata::docker_runtime_status_lines;

pub use isolation_metadata::docker_runtime_status_lines_for_options;

pub use log_uploader::upload_execution_log;

pub use output_blocks::create_command_line;

pub use output_blocks::create_empty_spine_line;Deprecated

pub use output_blocks::create_empty_timeline_line;

pub use output_blocks::create_finish_block;

pub use output_blocks::create_spine_line;Deprecated

pub use output_blocks::create_start_block;

pub use output_blocks::create_timeline_line;

pub use output_blocks::create_timeline_separator;

pub use output_blocks::create_virtual_command_block;

pub use output_blocks::create_virtual_command_result;

pub use output_blocks::escape_for_links_notation;

pub use output_blocks::format_duration;

pub use output_blocks::format_value_for_links_notation;

pub use output_blocks::generate_isolation_lines;

pub use output_blocks::get_result_marker;

pub use output_blocks::parse_isolation_metadata;

pub use output_blocks::FinishBlockOptions;

pub use output_blocks::IsolationMetadata;

pub use output_blocks::StartBlockOptions;

pub use output_blocks::FAILURE_MARKER;

pub use output_blocks::SPINE;Deprecated

pub use output_blocks::SUCCESS_MARKER;

pub use output_blocks::TIMELINE_MARKER;

pub use query_commands::dispatch_query_command;

pub use query_commands::handle_cleanup;

pub use query_commands::report_result;

pub use query_commands::QueryOutcome;

pub use session_probe::probe_session;

pub use session_probe::SessionProbe;

pub use session_probe::SessionState;

pub use signal_handler::clear_current_execution;

pub use signal_handler::get_signal_exit_code;

pub use signal_handler::set_current_execution;

pub use signal_handler::setup_signal_handlers;

pub use signal_handler::was_signal_received;

pub use status_footer::parse_footer_from_tail;

pub use status_footer::parse_footer_timestamp;

pub use status_footer::read_footer_from_log;

pub use status_footer::LogFooter;

pub use status_formatter::attach_current_time;

pub use status_formatter::enrich_detached_status;

pub use status_formatter::format_record;

pub use status_formatter::format_record_as_links_notation;

pub use status_formatter::format_record_as_links_notation_with_current_time;

pub use status_formatter::format_record_as_text;

pub use status_formatter::format_record_as_text_with_current_time;

pub use status_formatter::format_record_list;

pub use status_formatter::format_record_list_as_links_notation;

pub use status_formatter::format_record_list_as_text;

pub use status_formatter::format_record_with_current_time;

pub use status_formatter::list_executions;

pub use status_formatter::list_executions_filtered;

pub use status_formatter::query_status;

pub use status_formatter::read_exit_code_from_log;

pub use status_formatter::StatusQueryResult;

pub use status_probe::is_detached_session_alive;

pub use substitution::process_command;

pub use substitution::ProcessOptions;

pub use substitution::SubstitutionResult;

pub use usage::print_usage;

pub use user_manager::create_isolated_user;

pub use user_manager::delete_user;

pub use user_manager::get_current_user;

pub use user_manager::get_current_user_groups;

pub use user_manager::has_sudo_access;

pub use user_manager::CreateIsolatedUserOptions;

pub use user_manager::DeleteUserOptions;

pub use user_manager::UserOperationResult;

Modules

args_parser

Argument Parser for start-command wrapper options

args_parser_queries

Query/control option parsing for the start-command wrapper.

attached_diagnostics

Attached runs use the same sampler and penalty monitor as detached watchers.

cgroup_memory

cgroup v2 memory counters of a detached docker container (issue #182).

container_removal

Removed-container bookkeeping for --status (issue #225).

cpu_penalty

Opt-in timestamp-weighted CPU hysteresis. Missing coverage cannot trigger.

cpu_penalty_monitor

Watcher-owned CPU monitor; state lives beside the execution log.

detached_finalize

Detached completion finalizer (issue #170).

detached_output

Stream Docker output without buffering entire lines; timestamp command output only.

docker_command_handoff

Copy-free command handoff for newly launched detached Docker containers.

docker_init_option

Parse and validate the opt-in init process for docker isolation (issue #244):

docker_inspect_batch

One docker inspect for every container a status query probes (issue #243).

docker_post_mortem

Container post-mortem facts (issues #170, #171).

docker_recovery_options

Parse and validate the launch-time recovery options (issue #176):

docker_resource_limits

Docker resource limits that must survive a resume (issue #176).

docker_resource_options

Resolve launch/resume resource specs using Docker daemon capacity, never local RAM.

docker_snapshot_resume

Steps around the docker commit of a snapshot resume (issue #224):

docker_snapshot_safety

Serialize snapshots separately from the execution store and bound disk usage.

execution_attach

Attach to a tracked detached execution (issue #162).

execution_attempt

Attempt boundaries and evidence for executions sharing one UUID/log.

execution_chain

Continuation chains (issue #231): a launch with --continues <id> stores the UUID it continues, so a supervisor that relaunches fresh instead of --resume-ing in place can still treat every execution of one task as a whole. --status prints the chain and --upload-log uploads one file with every execution of it, oldest first.

execution_cleanup

$ --cleanup <uuid-or-session-name> (issue #224): remove the Docker containers of one execution and the snapshot images they were derived from.

execution_control

Detached execution control helpers.

execution_env

START_* variables that tell a launched command which execution it belongs to (issue #230). Every backend exports the same three variables, next to the kill-recovery START_COMMAND_RECOVERY_ATTEMPT:

execution_identity

Names an execution answers to (issue #231).

execution_recovery

Launch-time recovery for killed detached docker sessions (issue #176).

execution_resume

Resume tracked detached executions (issue #162).

execution_resume_all

--resume-all: re-attach or reconcile every execution still marked running.

execution_store

Execution Store - Dual storage (.lino text + .links binary) for command execution records

exit_evidence

Exit-time evidence; cumulative cgroup counters and OOMKilled are historical.

exit_reason

Exit reason hints for finished executions.

failure_handler

Failure handler for start-command

formal_ai

The task loop of the experimental --use-formal-ai mode (issue #255). Mirrors js/src/lib/formal-ai.js.

formal_ai_cli

CLI side of the experimental --use-formal-ai mode (issue #255): resolves the bounds and the runtime, tracks the execution like a direct run (start and finish blocks, log, execution record, START_* environment) and writes the evidence of the run into its log. Mirrors js/src/lib/formal-ai-cli.js.

formal_ai_client

Minimal client of the OpenAI-compatible agent-mode endpoint of Formal AI (POST /api/openai/v1/chat/completions), used by --use-formal-ai (issue #255). Mirrors js/src/lib/formal-ai-client.js. Only the bash function tool is offered: Formal AI picks the command, start decides whether and how it runs.

formal_ai_policy

Bounds and effect policy of the experimental --use-formal-ai mode (issue #255). Mirrors js/src/lib/formal-ai-policy.js.

formal_ai_runtime

Resolution and identity of the Formal AI runtime used by --use-formal-ai (issue #255). Mirrors js/src/lib/formal-ai-runtime.js.

formal_ai_tool

Runs one Formal AI tool call for --use-formal-ai (issue #255). Mirrors js/src/lib/formal-ai-tool.js.

isolation

Isolation Runners for start-command

isolation_metadata

Metadata helpers for isolated executions.

launch_identity

What a new launch may do with its execution id (issue #229).

launch_identity_options

Launch options about the identity of a new execution:

launch_owner

Reservations survive a launcher crash without permanently blocking resume.

log_sanitizer

Prepares logs and issue text for publication with @link-foundation/sensitive-data-sanitizer, the sanitizer shared by start-command, gh-upload-log and hive-mind (issue #250).

log_uploader

Helpers for uploading tracked execution logs.

output_blocks

Output formatting utilities for nicely rendered command blocks

query_commands

Query and control command handlers.

recovery_delay

Random delay before each launch-time kill recovery (issue #181):

resume_resources

sequence_parser

Sequence Parser for Isolation Stacking

session_probe

Session liveness probing for tracked executions.

signal_handler

Signal handling for graceful cleanup on process interruption

snapshot_resume_options

Options for the guarded Docker snapshot resume (issue #224):

status_footer

The anchored terminal footer start writes at the end of every log.

status_formatter

Status formatter module for execution records

status_probe

Live probing of a detached execution’s backend.

store_decode_cache

Decoded execution store, shared within one process and between processes (issue #243).

store_lock

Cross-language file lock. Publish fully written data with an atomic hard link.

substitution

Substitution Engine for start-command

usage

user_manager

User Manager for start-command

version_info

start --version: the version of start and of the isolation tools it can use. Moved out of the binary to keep it under the file-size limit.

Macros

eprint

eprintln

print

println

Structs

DockerWatcherOptions

Extra behaviour of a detached completion watcher (issue #176).

Enums

DockerContainerCleanupPolicy

Functions

build_detached_docker_completion_script

Build the shell the detached completion watcher runs after the container is gone.

build_detached_docker_completion_script_with

build_detached_docker_completion_script with DockerWatcherOptions.

docker_command