Filesystem Layout

This page covers the per-section files the session_agent_harness job type writes under ~/.blobhub-worker/jobs/. For the generic top-level layout (identity.yaml, credentials.yaml, instance.yaml, config.yaml, logs/{instance_id}/worker.jsonl) see Filesystem Layout.

Tree

~/.blobhub-worker/jobs/
└── session_agent_harness-{session_id}/
    ├── section.yaml             # per-section runtime state (event-poll cursor, attachment)
    ├── logs/
    │   └── section.log
    └── threads/
        └── {thread_alias}/
            ├── thread.yaml      # per-thread state (agent state, agent_session_id, cursors)
            └── logs/
                └── thread.log   # full untruncated agent stdio + tool I/O

The agent runs with cwd = workspace.work_folder; the worker keeps no separate agent-session directory on disk. Session resume is SDK-managed and keyed by agent_session_id (recorded in thread.yaml). job_id is deterministic: session_agent_harness-{session_id}. This guarantees stable paths across restarts, reinstalls, and config edits — and namespaces this job type away from any future ones.

File-by-file

`section.yaml` — per-section runtime state

Persisted by the worker. Recovery on next start re-reads this.

name: my-project
job_type: session_agent_harness
session:
  org_id: org_01J...
  blob_id: blb_01J...
  revision_id: rev_01J...
  session_id: ses_01J...
attachment:
  status: attached                    # attached | refused
  attached_at: 2026-05-27T12:35:01Z
  error:
    code: null
    message: null
events:
  last_processed_at: 2026-05-27T12:40:00Z

`logs/section.log`

Section-scoped JSON-line log: poll cadence, event dispatch, thread discovery.

`threads/{alias}/thread.yaml` — per-thread state

The worker’s local, authoritative-for-recovery view of a thread, plus the inbound/outbound item cursors. This local layout differs from the wire envelope: it keeps workspace.agent_type and agent.state, and the agent_session_id resume pointer and error block are local-only — they never appear on the wire. The mapping is documented on Job Session Object.

alias: my-feature-x
session: { ... }
workspace:
  agent_type: claude_code         # local layout keeps agent_type here (wire uses agent.type)
  work_folder: /Users/me/projects/foo
agent:
  state: active                   # "" | pending | active | completed | failed
  agent_session_id: ag_sess_...   # local-only resume pointer (never on the wire)
  error:                          # local-only failure detail (surfaces via thread_failed)
    code: null
    message: null
items:
  last_consumed:
    item_id: itm_01J...
    created_at: 2026-05-27T12:50:00Z
  last_posted:
    item_id: itm_01J...
    created_at: 2026-05-27T12:50:05Z

`threads/{alias}/logs/thread.log`

Captures the full untruncated agent stdio + tool I/O. When the worker truncates a thread item to fit the 350 KB budget, the local log retains the full payload — see Thread Items.

Why both server-side metadata and `thread.yaml`?

The server-side envelope is authoritative for handoff. Anyone with API access (web UI, SDK, another tool) reads it to see the agent state machine.
thread.yaml is authoritative for local recovery. The worker writes it before any externally observable side-effect, so a crash-restart finds a truthful local record.

​Tree

​File-by-file

​section.yaml — per-section runtime state

​logs/section.log

​threads/{alias}/thread.yaml — per-thread state

​threads/{alias}/logs/thread.log

​Why both server-side metadata and thread.yaml?

​See also