[klaidliadon]

ELI5

Setting up orcad as a supervised service meant hand-writing a systemd unit and
hoping. orcad --print-service writes one for you; orcad --doctor reads an
installed one back, probes the live host, and tells you which settings would
destroy your running terminals.

What Changed

Two flags on orcad, and the modules behind them:

• orcad --print-service generates a systemd unit (and a launchd plist) for a
  given data root, bind and port. Writes the file to stdout; placement and enable
  hints go to stderr, so redirecting stdout gives you the file and nothing else.
• orcad --doctor audits an installed definition, then probes the live host —
  the unit as written, the daemon socket, the data root — and reports what it
  measured, not what it expected.

Supporting modules under src/shared/supervisor-* (render, audit, probe,
evidence audit, file read) and src/main/orcad/supervisor-* (discovery, host
observations, generation warnings, daemon socket budget).

Why

Three things reviewers will want to look at directly:

1. KillMode=process, not mixed

Measured on systemd 219: under mixed, a systemctl restart destroyed the
daemon, its shell, the session and its scrollback; the identical unit under
process kept all four.

mixed SIGTERMs the main process and then SIGKILLs everything still in the
control group — and the detached daemon is in that control group, because
setsid() escapes the process group, not the cgroup.

So the generator emits process, and the doctor reports mixed as critical —
including in units orcad itself generated before this was settled, which is why
the finding names the generator as a possible source rather than assuming an
operator wrote it.

The cost of process is real and stated rather than hidden: systemd no longer
reaps what the runtime leaves behind. orcad owns that lifecycle through the daemon
pid-record it adopts on the next start, and a supervisor that "helpfully" cleans up
is exactly what breaks the guarantee.

2. systemd values are quoted, and the readers parse quotes

Both halves matter together. A data root containing a space would otherwise
round-trip into a unit that silently pins a different root — and an audit that
could not parse its own generator's output would call every quoted unit malformed.
supervisor-service-file-read.ts exists for the reading half.

3. Unreadable is not absent

A service definition that exists but cannot be read is reported as unreadable, not
missing. Those are different operator actions — one is a permissions fix, the other
an install — and collapsing them sent people to reinstall a unit that was already
sitting there.

The doctor also answers whether the data root leaves room for the daemon's socket,
reusing the budget from #17851. It is critical when a unit file pins the
root, and a warning naming whose root it measured when it falls back to the
invoking shell's — because those are different claims and conflating them would
have the doctor assert something it did not check.

ORCAD_ENTRY_FILENAME is named once in orcad-artifacts because a generated unit
execs it. OrcadArtifact.optional goes with it: nothing set it, the filter was a
no-op, and the one artifact that would want it cannot be an entry there at all
since its filename is derived per platform-arch.

Linked Issue

Refs #15956 — that issue asks for the PTY daemon to survive a supervised restart,
and lists documenting/shipping a correct unit as one acceptable shape. This gives
operators a generator and an audit that get KillMode right; it does not
restructure the daemon's lifetime, so Refs rather than Fixes.

Visual Proof

N/A — CLI output on a headless runtime, no UI surface. Sample generated unit and
doctor output can be pasted into review on request.

Testing

Unit-level coverage for the render, audit, file-read, generation-warning and socket
budget modules, including the quoting round-trip (generate → read back → same
values) and the unreadable-vs-absent distinction.

Field-tested on a Synology NAS (DSM, systemd 219) against a built artifact, and
on a root runner. Several commits' worth of defects found that way are folded in —
the KillMode measurement, the fallback-root warning, and the unreadable-service
case all came from running this against real units rather than fixtures.

• I manually tested these changes locally
• Automated tests added/updated, or explained why not below

Not run by me in this environment: pnpm lint, pnpm typecheck, pnpm test
and pnpm build. The host this was developed and field-tested on cannot install
the full toolchain. The gates were run separately and reported clean; I'd rather
say that plainly than tick a box I didn't personally execute. CI is the authority
here.

AI Disclosure

Claude Opus 5 wrote the commits and this description. I reviewed them and ran the
NAS field testing.

Review

• Cross-platform: generates systemd units on Linux and launchd plists on macOS;
  Windows is not a supervised-orcad target and the command says so rather than
  emitting something unusable. Path handling goes through node:path.
• SSH/remote/local: the doctor inspects THIS machine's service files. That is
  the intent — it is a host-setup tool — and the wording says so, so nobody reads
  its answer as being about a paired remote runtime.
• Agents/integrations: none. This is below the agent layer.
• Performance: the doctor's live probes run once, on demand, from a CLI
  invocation. Nothing runs at runtime or in a hot path.
• UI: none.
• Security: the generator writes to stdout, never to a system path — an
  operator places the file themselves, so nothing here needs elevated privileges.
  Generated units pin an explicit data root and default to a loopback bind,
  with widening left as an explicit operator choice. The doctor reads service files
  and reports parse results; it does not print credentials or tokens.
• Backwards compatibility: purely additive to orcad's flag surface. The only
  shared-file change is orcad-artifacts, whose removed optional field has no
  consumer in the tree.

Agent skill upstream boundary

• Not applicable, or this change follows docs/reference/agent-skill-sharing-upstream-boundary.md and copies or mechanically translates no upstream skill-installer source, tests, fixtures, registry entries, path tables, comments, or documentation.

Notes

Stacked on #17851 (fix/daemon-socket-path-budget) — that PR consolidates the daemon's
endpoint path builders, which is what lets the doctor ask about them without
pulling the daemon into the CLI's import graph. Please land that one first; this
diff is only readable on top of it.

feat/orca-supervisor-command stacks on this in turn and adds the orca supervisor print|doctor front door.

The companion docs correction is a separate PR so it can land immediately.

Checklist

• This PR is small and focused
• I explained what changed and why (including ELI5)
• Before/after screenshots or videos attached for UI changes, or N/A with reason
• Self-reviewed for correctness, security, and performance
• Cross-platform, SSH/remote, and path/shortcut impact considered (or N/A)
• pnpm lint, pnpm typecheck, pnpm test, and pnpm build pass (or CI will cover; local preferred)

[pullfrog]

the model provider had a temporary upstream failure.

The provider refused or dropped the request mid-run — nothing in your repo or your credentials is at fault. Re-trigger Pullfrog; if it keeps happening, check the provider's status page.

provider error: {"code":504,"message":"Upstream idle timeout exceeded","metadata":{"error_type":"timeout"}}

  ^{｜ Rerun failed job ➔ ｜ View workflow run ｜ via Pullfrog ｜ Using DeepSeek Pro (free via Pullfrog for OSS) ｜ 𝕏}

[greptile-apps]

Greptile Summary

The PR adds systemd and launchd service generation plus host auditing and live diagnostic probes to orcad, while consolidating daemon socket-path calculations.

• Adds --print-service and --doctor command routing and reporting.
• Adds supervisor rendering, discovery, parsing, auditing, and host probes.
• Adds daemon socket path budgeting and startup preflight.
• The launchd log-path correction remains inconsistent with an explicitly configured run-as account.

Confidence Score: 4/5

The PR is not yet safe to merge because generated launchd jobs can still receive a log path that their configured run-as account cannot write.

Service generation selects UserName from --user but selects the log path from the generating process and service scope, leaving valid cross-account and non-root LaunchDaemon configurations unable to open their configured logs.

Files Needing Attention: src/main/orcad/orcad-service-command.ts, src/shared/supervisor-service-render.ts

Important Files Changed

Filename	Overview
src/main/orcad/orcad-service-command.ts	Adds service generation and doctor orchestration, but launchd log paths are not derived from the configured run-as account.
src/shared/supervisor-service-render.ts	Renders systemd and launchd definitions with quoting, XML escaping, root-account refusal, and terminal-preserving supervisor settings.
src/shared/supervisor-service-file-read.ts	Reads generated and installed service definitions and now correctly decodes the XML entities emitted by the launchd renderer.
src/main/daemon/daemon-runtime-paths.ts	Centralizes daemon endpoint paths and exposes deterministic Unix socket-path budget checks.
src/main/orcad/orcad-entry.ts	Adds an early socket-path preflight and maps permanent path overflow to the supervisor configuration exit code.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart LR
  CLI[orcad service flags] --> P{Command}
  P -->|--print-service| G[Resolve service configuration]
  G --> R[Render systemd unit or launchd plist]
  P -->|--doctor| D[Discover and read installed definition]
  D --> A[Audit parsed configuration]
  D --> H[Probe executable, data root, socket, and endpoint]
  A --> O[Report findings]
  H --> O

Loading

_{Reviews (2): Last reviewed commit: "fix(orcad): decode plist entities, refus..." | Re-trigger Greptile}

[klaidliadon]

All three of Greptile's findings were real and are fixed in 9a05941. Each was the same shape of defect — the generator and the reader disagreeing about an encoding or an identity — so all three got the fix on both halves rather than only where the symptom showed.

1. Plist entities remained encoded (P1). Answered inline. The reader now decodes, one pass, and ProgramArguments decodes too since readExecTarget stats those paths.

2. --user 0 bypassed the non-root guard. Correct. assertNotRoot compared against the name only, but systemd's User= accepts a numeric uid, so --user 0 rendered exactly the unit the guard exists to refuse. The reader had the matching hole: auditRunAsUser read User=0 back and reported Runs as 0. as healthy — so an installed unit running as root passed a clean audit. Both now share isRootAccount, which also covers 00 and surrounding whitespace, and there is a negative-control test that orca0 is still an ordinary account.

3. LaunchAgent pointed at an unwritable log path. Correct, and the failure mode is nastier than it looks: /var/log is root-owned on macOS, the agent runs unprivileged, and launchd reports the open failure against the log path rather than against the job — so it reads as a broken install for a reason the plist never states.

The renderer is pure by contract and does no I/O, so it cannot resolve a home directory, and launchd expands no ~. It now emits StandardOutPath/StandardErrorPath only when the caller resolved a path; printService supplies ~/Library/Logs/orcad.log for an agent and /var/log/orcad.log for a daemon. Naming no log is the honest fallback — strictly better than naming one the job cannot open.

Verified the escape/decode round trip against a real plist parser rather than only against our own reader: rendering userDataPath: /Volumes/a&b/.orca and loading the output with Python plistlib returns /Volumes/a&b/.orca, matching what readPinnedUserData now returns. Both branches of the plist (with and without the log keys) parse clean.

Tests added: four in supervisor-service-file-read.test.ts (decode, ProgramArguments, endpoint, single-round decode), three in supervisor-service-render.test.ts (numeric root, negative control, log-key emission), three in supervisor-service-audit.test.ts (User=0, negative control, and an end-to-end assertion that the audit does not accuse its own plist of a data-root mismatch).

Note on the confidence score: none of the three touched KillMode, the mount ordering, or the probe/finding boundary — they were all in the plist and account-identity paths.

Pushed as a new commit, not a force-push, so #17853 (stacked on this branch) is undisturbed.

[klaidliadon]

Cross-posting from #17853 (the PR stacked on this one): Greptile reviewed the whole stack there and filed two P1s that are against files this PR adds, so they never appeared on this thread. Both verified against the tree.

1. The generated launchd plist is not well-formed XML

src/shared/supervisor-service-render.ts:205-207 opens an XML comment and then emits orcad --print-service --scope ${config.scope}; in user scope scopeNote adds --scope system instead. inside the same comment. XML forbids -- inside a comment body, so the plist is malformed in both scopes. Verified with a real parser, not by eye:

xml.parsers.expat.ExpatError: not well-formed (invalid token): line 3, column 15

Column 15 is the -- of --print-service. plutil -lint fails on the same token — and plutil -lint is the first thing an operator runs against a generated plist.

The systemd renderer at 123-124 carries the same sentence as # comments, where -- is harmless, which is why this is darwin-only.

supervisor-service-render.test.ts asserts AbandonProcessGroup, entity escaping and the logout warning, but never parses its own output — so nothing currently fails. A well-formedness assertion over both scopes would pin it.

2. --service-path extends conventional discovery instead of selecting

collectServiceFiles appends the explicit path to candidateServicePaths(platform) rather than replacing them (src/main/orcad/supervisor-service-discovery.ts:76-79).

Sharpest consequence: point --service-path at the definition conventional discovery already finds, and the same file is collected twice. files.length === 2, so auditDuplicates sees two paths sharing one data root and emits multiple_services_one_root at severity critical, exit 1 — while probing goes false and every live check is silently skipped. A false critical produced entirely by naming the file you wanted audited.

An explicit path selecting the definition, rather than extending the candidate list, avoids both.

---

A third finding on that thread — "sudo generation selects root" — I read as not a defect and declined it there, with reasoning: generation never runs under sudo in the documented flow (supervisorInstallHint puts sudo only on the launchctl/systemctl steps), and when it does, assertNotRoot's refusal naming --user is the intended outcome rather than a failure to handle one.

Full dispositions: #17853 (comment)

[greptile-apps]

Log path ignores run-as user

When --user differs from the account generating the launchd definition, UserName uses the requested account while the log path still uses the generator's home directory—or /var/log for system scope—causing the job to open a path its run-as account cannot write and preventing reliable startup or logging.

[klaidliadon]

Correct, and correct about system scope too — which is the part I had wrong. Fixed in 125bd54.

My previous commit swapped one guess for another. /var/log/orcad.log is root-owned while assertNotRoot guarantees the job runs unprivileged, so a LaunchDaemon cannot create it either; and the generating user's home is the run-as account's home only when --user did not name someone else, which this process cannot resolve.

So no path is defaulted at all now. The renderer emits StandardOutPath/StandardErrorPath only when the caller passes one explicitly, and printService no longer passes anything — it emits a warning instead, naming both reasons and telling the operator to create a file the run-as account owns, add the two keys, and pair it with a newsyslog.d entry since nothing rotates it. Guessing a path the job cannot open is worse than naming none, because launchd reports that failure against the log path rather than against the job, so it reads as a broken install for a reason the file never states.

systemd is unaffected: journald captures the unit's output with nothing configured, which is exactly why the asymmetry is now written down rather than papered over with a plausible default.

[klaidliadon]

Both cross-posted findings from #17853 verified and fixed in 125bd54, along with the log-path P1 filed here.

1. Malformed plist XML — confirmed, and worse than "a lint nit"

This one was real and I had already missed it once: my earlier verification of the plist used a hand-rolled replica that omitted the comment header, so it passed. Re-running against the actual template from supervisor-service-render.ts:

/tmp/hdr-system.plist -> FAILS: ExpatError not well-formed (invalid token): line 4, column 15
/tmp/hdr-user.plist   -> FAILS: ExpatError not well-formed (invalid token): line 4, column 15

XML forbids -- anywhere inside a comment body, so --print-service in the header made every generated plist unparseable, in both scopes. plutil -lint rejects it and launchctl will not load the job — the darwin path was dead on arrival, not degraded.

The flags are now named rather than written (run orcad with the print-service flag and scope user), and the file states the constraint so nobody restores the dashes. renderSystemd carries the same sentence safely because # comments have no such rule; that asymmetry is now a comment.

Re-verified all four variants (both scopes x with/without log keys) against the real template with Python plistlib — all parse. Lesson taken on the process point: nothing caught this because no test parsed the output it asserted against, so there is now a well-formedness assertion over both scopes, one that the regeneration guidance survives being de-dashed, and one proving a -- inside a generated path cannot reach a comment.

2. --service-path extended instead of selecting — confirmed

Exactly as described: naming the definition conventional discovery already finds collected the same file twice, auditDuplicates reported multiple_services_one_root as CRITICAL with exit 1, and files.length === 2 silently skipped every live probe. A false critical produced by asking about your own install.

An explicit path now selects. There is corroborating evidence this was always wrong — the existing test carried a comment apologising for it:

Scoped to the path under test rather than to the whole result: discovery also scans the conventional locations, so a host with a real orcad.service installed would otherwise fail these on its own installation.

That workaround is gone, and the new test asserts toEqual([path]) rather than toContain — the old behaviour also "contained" the path, and only an equality check sees the conventional candidates riding along.

3. "sudo generation selects root" — agreed, declining

Same disposition as on #17853, same reasoning: supervisorInstallHint puts sudo only on the systemctl/launchctl steps, so generation does not run under sudo in the documented flow, and where it does, assertNotRoot refusing while naming --user is the intended outcome rather than an unhandled case. It now also catches --user 0.

---

Still no force-push — three commits added on top, so #17853's base is undisturbed. Standing caveat: I cannot run pnpm lint/typecheck/test/build in this environment, so the verification above is real-parser and behavioural, not a green local gate.