feat(orchestrator): add --skip-binary-integrity for system-package installs

[yashranaway]

feat(orchestrator): add --skip-binary-integrity for system-package installs

Summary

• Adds --skip-binary-integrity (and OPENWORK_SKIP_BINARY_INTEGRITY=1 env equivalent) to openwork start, openwork serve, and openwork daemon start.
• When set, verifyBinary() short-circuits before hashing, so SHA-256 checks against the bundled-sidecar manifest are skipped.
• Default behavior unchanged: integrity checks still run for normal installs.

Why

System-package distributions like AUR build the orchestrator + companion binaries (opencode, openwork-server, opencode-router) locally. Those rebuilt binaries cannot match the upstream-bundled SHA-256 manifest, so verifyBinary throws Integrity check failed for ... and the orchestrator refuses to start. Today there is no documented escape hatch, so packagers either patch the source or strip versions.json from the bundle.

Issue

• Closes bug: openwork-orchestrator integrity checks fail with system-installed binaries #1230

Scope

• apps/orchestrator/src/cli.ts
  • New shouldSkipBinaryIntegrity() helper next to sha256File() / verifyBinary(). Reads OPENWORK_SKIP_BINARY_INTEGRITY and accepts 1 / true / yes (case-insensitive).
  • verifyBinary() returns early when the helper reports true, before the file read + hash compare. The expected-manifest short-circuit (if (!expected) return;) is preserved unchanged.
  • Flag is read at all three orchestrator entry points (spawnRouterDaemon, runRouterDaemon, runStart) using the existing readBool(...) pattern. When set, the entry point exports OPENWORK_SKIP_BINARY_INTEGRITY=1 to its own process.env, so every downstream verifyBinary call in the same process picks it up.
  • spawnRouterDaemon also forwards --skip-binary-integrity to the spawned child orchestrator via commandArgs.push(...), mirroring how --allow-external is forwarded.
  • Help text gains one line under --allow-external.
• apps/orchestrator/README.md
  • Short paragraph next to --allow-external explaining the flag, the env var, and that it is for trusted system-package installs.

Out of scope

• The reporter also mentioned "auto-detect non-bundled install" as one option. That path is harder to make predictable (which install layouts count as system-managed?) and conflicts with ARCHITECTURE.md's "Predictable > clever" rule. An explicit, documented opt-out is the lowest-risk option.
• No change to bundled / downloaded / external resolver branches. The only behavior change is that verifyBinary becomes a no-op when the env var is set.

Testing

Ran

• pnpm --filter openwork-orchestrator typecheck
• bun src/cli.ts --help (verify help text placement)
• bun src/cli.ts start --workspace /tmp --skip-binary-integrity --allow-external --opencode-bin /nonexistent
• OPENWORK_SKIP_BINARY_INTEGRITY=1 bun src/cli.ts daemon start --workspace /tmp --allow-external --opencode-bin /nonexistent
• Unit-equivalent helper test: assert shouldSkipBinaryIntegrity() returns false for empty / no, true for 1 / true.

Result

• pass: typecheck clean
• pass: --help lists --skip-binary-integrity directly under --allow-external
• pass: flag is accepted on start and reaches the downstream binary-resolver layer (the only error is the unrelated opencode-bin not found: /nonexistent)
• pass: env-var path on daemon start accepted equivalently
• pass: helper recognizes truthy variants and rejects empty / negative values

CI status

• pass: pending CI on the PR
• code-related failures: none expected
• external/env/auth blockers: n/a

Manual verification

1. On a system where bundled sidecar SHAs do not match the manifest (e.g. an AUR build that rebuilt opencode), confirm openwork start fails with Integrity check failed for ....
2. Re-run with openwork start --skip-binary-integrity and confirm the orchestrator proceeds past binary resolution and reaches the normal startup path.
3. Re-run without the flag and confirm the failure returns (no sticky state).
4. Confirm OPENWORK_SKIP_BINARY_INTEGRITY=1 openwork start produces the same passing result as the explicit flag.

Evidence

• N/A (CLI text-only change). Help-output and reproduction commands are listed above.

Risk

• Low. Default unchanged. The flag is opt-in, gated behind both an explicit CLI flag and an explicit env var. README explicitly notes the trust assumption.
• Security note: this disables a tampering check, which is why the README scopes it to "trusted system-package installs only". It does not weaken any auth, network, or filesystem boundary.

Rollback

• Revert this commit. No persisted state, no schema changes, no config migrations.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
openwork-landing	Ready	Preview, Comment, Open in v0	Apr 26, 2026 10:55am

[vercel]

@yashranaway is attempting to deploy a commit to the Different AI Team on Vercel.

A member of the Team first needs to authorize it.

[github-actions]

The following comment was made by an LLM, it may be inaccurate:

[src-opn]

this is complex and a dirty workaround. will keep this as is for now, and potentially merge this if theres a better fix