Pre-release Harn is pre-1.0 — the language, standard library, and CLI may change between releases. See the release notes

Command stage output

harness.tools.run_command accepts capture: {final_stage: true} to retain output from the final literal command separately from preceding shell setup. The option defaults to false. Normal command output and execution policy remain available in the same result.

fn main(harness: Harness) {
  const result = harness.tools.run_command({
    mode: "shell",
    shell_id: "sh",
    command: "printf 'setup complete\\n' && python -m pytest tests",
    cwd: harness.fs.cwd(),
    capture: {final_stage: true},
  })
  const stage = result?.stage_output
  if stage?.status == "captured" {
    harness.stdio.println(stage.stdout)
  }
}

Result#

std/command exports the CommandStageOutput union. A completed foreground result, or the terminal wait_command result for a background command, includes stage_output when the option was requested. Running background results do not provide terminal capture evidence.

StatusFieldsMeaning
"captured"argv, stdout, stderr, truncation flags, artifact paths and line_countThe runner observed the selected stage and finished reading its output
"unmeasured"reasonThe runner cannot attribute a complete stage output

argv contains the selected literal argument list. stdout_truncated and stderr_truncated describe the inline strings. output_path, stdout_path and stderr_path identify the separately retained stage artifacts. Output and arguments pass through the existing command-output redaction policy.

The regular stdout, stderr and output artifacts still include preceding setup output. A consumer that needs stage attribution must require stage_output.status == "captured" and read that stage's fields. Missing or unmeasured stage output supplies no attribution evidence.

Supported invocations#

Direct argument-vector calls select the whole invocation. On Unix, supported POSIX shell calls select the final literal external command in a fixed && chain. Earlier commands retain their original shell scope and short-circuit behavior, including literal cd. Their executions close the private capture handles. The existing process guardian reserves shell-compatible descriptor slots and hands output to the existing command readers and terminal waiter.

The runner leaves the original invocation unchanged and reports unmeasured output for unsupported shell syntax, expansions, redirections, pipelines, compound control flow, startup state that can change command lookup, unavailable descriptor slots, file capture transport or an unsupported sandbox transport. This includes shell declarations such as export and shell startup files such as BASH_ENV. A stage that never starts, a cancelled command or a failed output read also supplies no complete stage capture.

Interpretation#

Captured output identifies a byte stream and a literal argument list. It does not attest that an executable is a test runner, that it ran tests, or that its claims are true. A verifier consumer must separately match the argument list to its declared verifier and apply its existing result parser. Report files found elsewhere in a workspace are not bound to this stage by this option.

See Command sequence plans for structural command comparison without execution.