Skip to content
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion .github/ISSUE_TEMPLATE/bug_report.yml
Original file line number Diff line number Diff line change
Expand Up @@ -23,7 +23,7 @@ body:
label: Steps to Reproduce
description: Step-by-step instructions to reproduce the behavior.
placeholder: |
1. Run `npm install -g @oxgeneral/orch`
1. Install the secured fork using the pinned command from the README
2. Run `orch init`
3. Run `orch task add "test" -p 1`
4. See error...
Expand Down
4 changes: 2 additions & 2 deletions .github/ISSUE_TEMPLATE/config.yml
Original file line number Diff line number Diff line change
@@ -1,8 +1,8 @@
blank_issues_enabled: false
contact_links:
- name: Questions & Discussions
url: https://github.com/oxgeneral/ORCH/discussions
url: https://github.com/Thibault1818/ORCH/discussions
about: Ask questions, share ideas, or show off what you've built with ORCH.
- name: Documentation
url: https://github.com/oxgeneral/ORCH#readme
url: https://github.com/Thibault1818/ORCH#readme
about: Check the README and docs before opening an issue.
7 changes: 7 additions & 0 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,9 @@ on:
pull_request:
branches: [main]

permissions:
contents: read

jobs:
test:
runs-on: ubuntu-latest
Expand All @@ -16,5 +19,9 @@ jobs:
node-version: 20
cache: npm
- run: npm ci
- run: npm test -- test/security/security-regression.test.ts
- run: npm run typecheck
- run: npm test
- run: npm run build
- name: Verify Git-installable package includes workflow distribution
run: npm pack --dry-run --ignore-scripts 2>&1 | grep -q 'dist/workflow-'
59 changes: 9 additions & 50 deletions .github/workflows/publish.yml
Original file line number Diff line number Diff line change
@@ -1,64 +1,23 @@
name: Publish to npm
name: Publication guard

on:
push:
tags: ['v*']
workflow_dispatch:

permissions:
contents: read

jobs:
publish:
verify-private-package:
runs-on: ubuntu-latest
permissions:
contents: write
steps:
- uses: actions/checkout@v4
with:
fetch-depth: 0
- uses: actions/setup-node@v4
with:
node-version: 24
node-version: 20
cache: npm
registry-url: https://registry.npmjs.org
- run: npm install -g npm@latest
- run: npm ci
- run: npm run typecheck
- run: npm test
- name: Check if version already published
id: check
run: |
LOCAL=$(node -p "require('./package.json').version")
REMOTE=$(npm view @oxgeneral/orch version 2>/dev/null || echo "0.0.0")
echo "version=$LOCAL" >> "$GITHUB_OUTPUT"
echo "tag=v$LOCAL" >> "$GITHUB_OUTPUT"
if [ "$LOCAL" = "$REMOTE" ]; then
echo "skip=true" >> "$GITHUB_OUTPUT"
echo "Version $LOCAL already published — skipping"
else
echo "skip=false" >> "$GITHUB_OUTPUT"
echo "Publishing $LOCAL (remote has $REMOTE)"
fi
- run: npm publish --access public
if: steps.check.outputs.skip != 'true'
env:
NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
- name: Extract changelog for this version
id: changelog
run: |
VERSION="${{ steps.check.outputs.version }}"
# Extract section between "## $VERSION" and next "## " or EOF
BODY=$(awk "/^## ${VERSION//./\\.}/{found=1; next} /^## [0-9]/{if(found) exit} found" CHANGELOG.md)
if [ -z "$BODY" ]; then
BODY="Release ${{ steps.check.outputs.tag }}"
fi
# Write to file to avoid quoting issues
echo "$BODY" > /tmp/release-notes.md
- name: Create or update GitHub Release
run: |
TAG="${{ steps.check.outputs.tag }}"
if gh release view "$TAG" >/dev/null 2>&1; then
gh release edit "$TAG" --notes-file /tmp/release-notes.md
else
gh release create "$TAG" --target "$GITHUB_SHA" --notes-file /tmp/release-notes.md
fi
env:
GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
- name: Verify npm publication is disabled
run: node -e "const p=require('./package.json'); if(p.private!==true) throw new Error('package must remain private')"
- run: npm test -- test/security/security-regression.test.ts
8 changes: 4 additions & 4 deletions .github/workflows/welcome.yml
Original file line number Diff line number Diff line change
Expand Up @@ -22,9 +22,9 @@ jobs:

We appreciate you taking the time to report this. Here are some helpful links:

- 📖 [Contributing Guide](https://github.com/oxgeneral/ORCH/blob/main/CONTRIBUTING.md) — how to set up, test, and submit changes
- 🏗️ [Architecture Overview](https://github.com/oxgeneral/ORCH/blob/main/CLAUDE.md) — understand the codebase structure
- 💬 [GitHub Discussions](https://github.com/oxgeneral/ORCH/discussions) — ask questions or share ideas
- 📖 [Contributing Guide](https://github.com/Thibault1818/ORCH/blob/main/CONTRIBUTING.md) — how to set up, test, and submit changes
- 🏗️ [Architecture Overview](https://github.com/Thibault1818/ORCH/blob/main/CLAUDE.md) — understand the codebase structure
- 💬 [GitHub Issues](https://github.com/Thibault1818/ORCH/issues) — ask questions or share ideas

If you'd like to fix this yourself, PRs are very welcome! We have **1493+ tests** and strict TypeScript — the CI will guide you.

Expand All @@ -37,6 +37,6 @@ jobs:
- ✅ Full test suite (1493+ tests via Vitest)
- ✅ ESM build verification

A maintainer will review your changes shortly. In the meantime, check the [Contributing Guide](https://github.com/oxgeneral/ORCH/blob/main/CONTRIBUTING.md) to make sure everything is in order.
A maintainer will review your changes shortly. In the meantime, check the [Contributing Guide](https://github.com/Thibault1818/ORCH/blob/main/CONTRIBUTING.md) to make sure everything is in order.

⭐ If you enjoy working with ORCH, a star on the repo goes a long way!
7 changes: 7 additions & 0 deletions .npmignore
Original file line number Diff line number Diff line change
@@ -0,0 +1,7 @@
*
!dist/**
!scripts/**
!skills/**
!LICENSE
!readme.md
!package.json
21 changes: 21 additions & 0 deletions IMPLEMENTATION_STATUS.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,21 @@
# Implementation Status

## Architecture

ORCH uses layered domain, application, infrastructure, and CLI/TUI modules. The dedicated workflow domain persists contracts, a compact passport, sessions, usage, canonical artifacts, and events under `.orchestry/workflows/`. `WorkflowEngine` coordinates injected Codex, Fable, Opus, and Git ports independently from the generic goal state machine.

## Security Baseline

Dangerous permission bypass and shell execution are disabled by default and require config plus `ORCHESTRY_ALLOW_DANGEROUS_EXECUTION=1`. Prompt transport, restricted child environments, redaction, no-persistence defaults, path/symlink checks, opt-in postinstall behavior, private package metadata, and absence of background npm installs are protected by `test/security/security-regression.test.ts`.

## Verification

The deterministic fake-adapter workflow covers planning, bounded replans, patch validation, session recovery, FIX and REPLAN behavior, review joining, stale commit and diff approvals, deterministic checks, and fail-closed merging. The final local run passed 2,075 tests across 128 files with 2 skips, typecheck, build, `git diff --check`, package dry-run, and `npm audit` with zero advisories.

## Upstream Reconciliation

The fork and upstream were fetched and compared before implementation. Changes restoring Cursor `--yolo`, shell convenience defaults, npm publishing, and other unsafe execution behavior were rejected. The later Pi terminal-failure fix was reviewed as safe but deferred because it is unrelated to this pipeline and changes a large adapter surface; no wholesale upstream merge was performed.

## Limitation

Neither `claude` nor `codex` is installed on the development host, so their local help output and native resume behavior could not be verified. `orch workflow doctor` reports this plainly. The controller uses the durable passport/worktree fallback instead of inventing unverified resume syntax. `start` runs autonomously in the foreground after printing the recoverable job ID.
64 changes: 17 additions & 47 deletions SECURITY.md
Original file line number Diff line number Diff line change
@@ -1,57 +1,27 @@
# Security Policy

Thanks for helping keep ORCH and its users safe.
## Supported Distribution

## Supported Versions
Only the secured fork at [Thibault1818/ORCH](https://github.com/Thibault1818/ORCH) is covered by this policy. It is a private/local package and is not published to npm. Install from the fork at an audited commit or tag; do not substitute the upstream npm package.

Security fixes land on the latest published minor version on npm (`@oxgeneral/orch`). Older versions are not patched — upgrade to the latest to stay protected.
```bash
npm install -g "git+https://github.com/Thibault1818/ORCH.git#6f8272cf8c4a6a3942d618be34dd5377da4d646c"
```

| Version | Supported |
|---------|-----------|
| latest | ✅ |
| older | ❌ |
## Security Defaults

## Reporting a Vulnerability
- Permission bypass and the shell adapter default to disabled.
- Dangerous execution requires both the corresponding config flag and `ORCHESTRY_ALLOW_DANGEROUS_EXECUTION=1`.
- Prompts are sent over stdin where supported, excluded from child environments, and not persisted by default.
- Child environments are allowlisted; persisted data and terminal output are redacted.
- Worktree isolation, path containment, identifier validation, and symlink checks protect local state.
- Postinstall exits without side effects unless `ORCH_POSTINSTALL_OPT_IN=1`.
- ORCH does not install npm packages automatically or in the background. `orch update` only displays the secured fork's explicit update procedure.

**Please do not open a public issue for security problems.**
These invariants are enforced by `test/security/security-regression.test.ts` and CI.

Report vulnerabilities privately through GitHub's built-in advisory form:
## Reporting

1. Go to the [Security tab](https://github.com/oxgeneral/ORCH/security) of this repository
2. Click **Report a vulnerability**
3. Fill out the advisory form
Do not open a public issue for a vulnerability. Use the fork's [private security advisory form](https://github.com/Thibault1818/ORCH/security/advisories/new) and include impact, reproduction steps, affected commit, OS, and Node.js version.

Please include:

- A clear description of the issue and its impact
- Steps to reproduce (minimal example preferred)
- Affected version(s) and environment (OS, Node version)
- Any suggested fix or mitigation

### What to expect

This is a small open-source project maintained in spare time — please be patient. A realistic expectation:

- **Acknowledgement**: within a week
- **Fix timeline**: based on severity, communicated after triage
- **Credit**: we're glad to credit you in the release notes (unless you prefer to remain anonymous)

## Scope

In scope:
- The `@oxgeneral/orch` npm package and its runtime
- The CLI (`orch`) and TUI
- Adapters that spawn external processes (claude, opencode, codex, cursor, shell)
- File storage under `.orchestry/` (YAML/JSON/JSONL)
- Template rendering (LiquidJS prompts)

Out of scope:
- Vulnerabilities in external AI tools (Claude CLI, OpenCode, etc.) — report those upstream
- Misconfiguration by end users (e.g., running untrusted skills, exposing API keys)
- Denial-of-service via self-inflicted resource exhaustion

## Disclosure

We prefer **coordinated disclosure**: give us a reasonable window to release a fix before publishing details. Low-impact issues can be disclosed sooner; critical issues may need longer — we'll agree a timeline together.

Thank you for reporting responsibly.
External agent CLI vulnerabilities remain the responsibility of their respective vendors.
Loading