Struct JobDir 

pub struct JobDir {
    pub path: PathBuf,
    pub job_id: String,
}

Handle to a specific job’s directory.

Fields

path: PathBuf

job_id: String

Implementations

impl JobDir

pub fn open(root: &Path, job_id: &str) -> Result<Self>

Open an existing job directory by ID or unambiguous prefix.

Resolution order:

1. Exact match: if root/<job_id> exists, return it immediately (no scan).
2. Prefix scan: scan root/ for directories whose name starts with job_id.
   • 0 matches → Err(JobNotFound)
   • 1 match → resolve to that job
   • 2+ matches → Err(AmbiguousJobId)

pub fn create(root: &Path, job_id: &str, meta: &JobMeta) -> Result<Self>

Create a new job directory and write meta.json atomically.

pub fn meta_path(&self) -> PathBuf

pub fn state_path(&self) -> PathBuf

pub fn stdout_path(&self) -> PathBuf

pub fn stderr_path(&self) -> PathBuf

pub fn full_log_path(&self) -> PathBuf

pub fn completion_event_path(&self) -> PathBuf

pub fn notification_events_path(&self) -> PathBuf

pub fn write_completion_event_atomic( &self, record: &CompletionEventRecord, ) -> Result<()>

Write completion_event.json atomically.

pub fn read_meta(&self) -> Result<JobMeta>

pub fn read_state(&self) -> Result<JobState>

pub fn write_meta_atomic(&self, meta: &JobMeta) -> Result<()>

Write meta.json atomically: write to a temp file then rename.

pub fn write_state(&self, state: &JobState) -> Result<()>

Write state.json atomically: write to a temp file then rename.

pub fn tail_log( &self, filename: &str, tail_lines: u64, max_bytes: u64, ) -> String

Read the last max_bytes of a log file, returning lossy UTF-8.

pub fn tail_log_with_truncated( &self, filename: &str, tail_lines: u64, max_bytes: u64, ) -> (String, bool)

Read the last max_bytes of a log file, returning (content, truncated). truncated is true when the content was cut by bytes or lines constraints.

pub fn read_tail_metrics( &self, filename: &str, tail_lines: u64, max_bytes: u64, ) -> TailMetrics

Read tail content and byte metrics for a single log file.

Returns a TailMetrics that bundles the tail text, truncation flag, observed file size, and included byte count. Both run’s snapshot generation and tail’s JSON generation use this helper so that the metric calculation is defined in exactly one place.

encoding is always "utf-8-lossy" (as required by the contract).

pub fn init_state_created(&self) -> Result<JobState>

Write the initial JobState for a created (not-yet-started) job.

The state is created, no process has been spawned, and started_at is absent.

pub fn init_state(&self, pid: u32, started_at: &str) -> Result<JobState>

Write the initial JobState (running, supervisor PID) to disk.

This is called by the run command immediately after the supervisor process is spawned, so pid is the supervisor’s PID. The child process PID and, on Windows, the Job Object name are not yet known at this point.

On Windows, the Job Object name is derived deterministically from the job_id as "AgentExec-{job_id}". This name is written immediately to state.json so that callers reading state after run returns can always find the Job Object identifier, without waiting for the supervisor to perform its first write_state call. The supervisor will confirm the same name (or update to failed) after it successfully assigns the child process to the named Job Object.

Trait Implementations

impl Debug for JobDir

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.