# Process

## Key Ideas

- **Supervisor Ownership**: the system should know which processes it owns and why they exist.
- **Observable Execution**: long-running work should produce inspectable status, logs, and controls.
- **Recoverability**: process state should survive daemon restarts well enough to explain current reality.
- **Bounded Power**: Refine should run useful commands while keeping command ownership and authorization explicit.
- **Surface Independence**: process control should be available to CLI, browser, API, and agents through shared capability.

## Purpose

Process management exists because agentic software work is not just data mutation. Refine has to run target apps, agents, quality checks, import extraction, maintenance tasks, terminal sessions, and background operations.

Those processes need to be visible. A user or agent should be able to answer: what is running, who started it, what is it doing, where are its logs, can it be stopped, and did it succeed?

## Expected Role

The process capability should be the local operating substrate under workflow and tools. It should make process execution durable enough for real work without turning Refine into a general-purpose operating system.

Current implementation details that matter to intent:

- managed processes have owners such as daemon, runner, target app, agent, quality, import, maintenance, and user helper.
- process records include pid, state, label, details, output paths, limits, start time, and exit code.
- process metadata can attach workflow, Goal, session, mode, and runner context.
- managed agent launches carry prompt transport evidence rather than prompt
  content: transport kind, UTF-8 byte count, SHA-256, owner, and lifecycle.
  Authorization strings, routine process details, and persisted stdin redact the
  authoritative prompt. Process and session ownership retain any secure prompt
  file until the provider reaches a terminal handoff; recovery retains files
  for verified live owners and reaps only verified orphans.
- Process owns one effective launch environment assembled in actual precedence
  order from inheritance, configured agent values, per-process overrides, and
  direct API-key removals. Managed processes and PTYs apply that owned value
  after clearing their builders, so every final agent argv is preflighted
  against the exact environment passed to spawn, with per-string and aggregate
  budgets. Native stdin remains available where it preserves provider
  semantics; environment pressure can reselect an operation-owned prompt file
  and bounded bootstrap. Spawn errors preserve their original OS cause and
  never trigger blind E2BIG retries.
- workflow Goal Agents run as PTY-backed managed processes with shared transcript,
  input, resize, attention, and lifecycle state, so CLI and browser attachments
  observe the same process.
- the daemon remains a responsive control plane while supervised runners own workflow and Git synchronization waits.
- one shared host daemon-lifecycle capability selects port-scoped systemd or
  launchd control versus supervised direct-process fallback from the selected
  runtime and installation context. CLI, HTTP/API, Desktop, update, and
  maintenance callers submit lifecycle intent without owning parallel
  reachability, confirmation, evidence, recovery, or legacy-migration state
  machines. Work initiated inside the managed daemon that must stop or restart
  it first persists its operation receipt and moves execution into a separate
  systemd transient service, launchd submitted job, or detached direct-process
  session. The handoff then records the same observed lifecycle status,
  evidence, failure, and recovery guidance as synchronous host callers. Source
  promotion durably backs up and replaces an activated service registration
  with the built candidate before shutdown. If candidate verification fails,
  rollback retains the backup until the prior registration is restored and
  verified, forcibly replaces the live candidate through the shared
  service-manager restart path, and fresh-probes reachability and live
  executable identity. It records success only when the registered and live
  executables both resolve to the prior binary; command failures, a surviving
  candidate, and indeterminate identity remain explicit partial evidence with
  actionable recovery. Promotion success likewise requires the live daemon to
  identify the candidate executable.
  Direct fallback shutdown retains signal errors and uses a fresh tri-state
  reachability probe; only observed non-reachability is persisted as stopped.
- todo is a state-only queue. Promotion and claiming do not create a repository
  copy; only a capacity-admitted running claim may durably transition its Goal
  to in-progress and then materialize that Goal round's implementation worktree.
  A large todo queue therefore consumes workflow state, not one worktree per Goal.
- pause state can stop background processes or pause agents.
- stopping any managed, interactive, chat, or synthetic agent uses one shared
  capability, including Workflow claim settlement, rather than splitting
  process and Workflow semantics. A user Stop retains ownership evidence,
  confirms exact process exit, and records that outcome before registry or
  identity cleanup. It then releases the exact claim and capacity, returns the
  Goal to todo under the Node owner pinned before exit, and settles the operation
  and receipts. Stop never removes workflow worktrees or branches, regardless of
  whether they are pristine, tracked-dirty, untracked, ignored, or changing
  concurrently. Every recorded worktree and branch remains available with
  explicit durable retention and recovery evidence. Worktree cleanup is a
  separate shared maintenance operation outside Stop; ordinary retention is a
  successful result, not a partial failure. The operation is dry-run by default
  when invoked directly and a separately supervised cleanup worker applies the
  configured inactive-worktree retention delay even while the workflow worker
  is occupied. The default makes inactive worktrees eligible immediately and
  the cleanup worker scans every registered target app at least once per
  minute. Goal status controls workflow semantics, not physical checkout
  retention: any clean managed Goal worktree without a live Workflow claim,
  operation, or process may be hibernated. Recognized or explicitly configured
  generated cache paths may be removed first, but any other ignored content
  protects the worktree. Dirty, ambiguously owned, standalone, and state
  worktrees are retained. Recoverable candidate branches remain available for
  lazy recreation. A Refine-owned branch may be deleted locally and upstream
  only when durable integration evidence names its exact candidate, that exact
  SHA is still the branch tip, and the candidate is an ancestor of the local
  and remote target tips. Both deletions use exact-SHA compare-and-delete
  fences, so an advanced branch is retained. Termination intent is an
  explicit authoritative input to the shared capability: interactive user Stop
  requeues, while explicit Goal or workflow cancellation remains terminal
  cancelled. Process discovery and claim presence are settlement evidence, never
  a source for guessing that intent. Explicit cancellation has monotonic
  precedence: when durable Goal state is already cancelled, or becomes cancelled
  after Stop preflight, Stop may finish process, operation, claim, and capacity
  settlement but cannot return the Goal to todo. Journals, process receipts,
  replay, partial evidence, and surface results record the requested intent
  separately from the authoritative intent so recovery preserves that precedence.
  Workflow spawn-to-registration and cancellation share one execution fence:
  an empty target-bound process lookup is never treated as exit evidence, and a
  delayed worker cannot launch after its exact claim has settled.
  Settlement atomically validates and cancels the exact claim, applies the
  requested linked-Goal outcome, releases claim capacity, and preserves the
  execution, round, pinned Node owner, Goal revision/status, competing-owner,
  and retained-worktree fences. Claim, capacity, Goal, and retention evidence
  are journaled with their exact before/after states as one semantic settlement.
  Schema-compatible replay accepts prior cancellation and cleanup journals but
  never resumes their destructive worktree-removal stages; all still-present
  targets become retained recovery evidence. A semantic write failure restores
  the exact semantic pre-settlement state while advancing
  monotonic workflow, claim-decision, and Goal revisions to record the attempted
  settlement and rollback. An interruption is replayed before terminal-state
  shortcuts after restart. Settlement journals synchronize their temporary file
  before atomic replacement and synchronize the containing directory after the
  rename. Rollback evidence records each Goal, claim, and capacity restore
  outcome plus the exact restored Goal value, so replay can accept the
  restoration's monotonic revision without weakening its ownership fence or
  overwriting newer work. Workflow coordination is acquired before workflow
  and Goal mutation locks, including concurrent Ready Merge work, so settlement
  cannot deadlock or bypass those fences. Both normal persistence and replay
  preserve the complete existing workflow policy and target-app context, and
  confirmed process exit remains explicit. A stop uses the Goal owner pinned by
  the validated process/claim fence instead of rediscovering whichever Node the
  serving daemon currently calls active. Missing registration-time PID
  identity, mismatched or stale workflow ownership, failed or resisted stops,
  and process cleanup failures keep the Goal active, while every post-exit failure
  retains a truthful receipt with exit, registry/identity cleanup, claim/Goal,
  retained-worktree, cause, and supported recovery evidence.
  Single and bulk Goal cancellation both delegate to this capability. Bulk
  cancellation settles each selected Goal independently and returns explicit
  per-Goal failures, so one partial outcome is never reported as batch success.
  Public cancellation results report `cancelled: true` only after reading back a
  durably cancelled Goal; partial process, claim, capacity, or replay outcomes
  retain structured evidence without claiming terminal Goal success.
- the browser System and Processes surfaces read shared process state rather than inventing their own status.
- live observers enumerate and capture output through the shared Process
  capability. A listed process record or output artifact removed by ordinary
  reaping before capture is a terminal, skipped observation; permission,
  persistent I/O, serialization, and process-identity failures remain
  actionable.
- the browser Goal terminal resolves its session to the managed Goal Agent and
  delegates Stop to this same capability; only non-Goal local terminals retain
  process-only terminal shutdown behavior.

Process management should favor visibility and recovery over hiding execution behind polished UI messages. If something is running, failing, or waiting, Refine should be able to show it.

## Future Direction

As agent fleets grow, process management should evolve toward orchestration: resource limits, queues, priorities, remote nodes, cancellation, isolation, provenance, and health checks.

The future process layer should support many agents and target apps without losing local debuggability. Superintelligent systems may automate most decisions, but they will still need an observable substrate that explains what was launched, what happened, and what changed.