Skip to content
Merged
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
4 changes: 2 additions & 2 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -43,15 +43,15 @@ Depending on setup, Codex reaches the ledger through a local MCP bridge or a com

## Choose a setup

- **Local Windows:** one person, no VM. Download the [Windows installer](https://github.com/gonzoinc/Conductor/releases/tag/v0.4.0), choose Codex desktop, VS Code, or both, and keep task data in a separate folder. Setup downloads a private Python runtime and runs the ledger only when Codex uses it.
- **Local Windows:** one person, no VM. Download the [Windows installer](https://github.com/gonzoinc/Conductor/releases/tag/v0.4.1), choose Codex desktop, VS Code, or both, and keep task data in a separate folder. Setup downloads a private Python runtime and runs the ledger only when Codex uses it.
- **Local macOS:** one person, no VM. Needs Python 3.11+, internet for package installation, and a stable local checkout. The SQLite ledger runs through an MCP bridge only while Codex uses it.
- **Shared Linux VM + Windows client:** a team or multiple computers. The Windows client uses an authorized SSH login and installs one command and the skill. It needs no local Python, MCP package, copied service key, or background tunnel.

The [older hosted MCP path](docs/client-setup.md#single-script-windows-hosted-setup) and [guided command-line wizard](docs/guided-setup.md) remain documented for existing setups and migration.

### Local Windows

Download `ConductorSetup.exe` from the [latest release](https://github.com/gonzoinc/Conductor/releases/tag/v0.4.0) and run it as your normal Windows user. The app guides you through the install folder, task-data folder, and Codex clients. See the [Windows setup guide](docs/windows-gui-setup.md) for the full walkthrough.
Download `ConductorSetup.exe` from the [latest release](https://github.com/gonzoinc/Conductor/releases/tag/v0.4.1) and run it as your normal Windows user. The app guides you through the install folder, task-data folder, and Codex clients. See the [Windows setup guide](docs/windows-gui-setup.md) for the full walkthrough.

### Local macOS

Expand Down
19 changes: 19 additions & 0 deletions docs/releases/v0.4.1.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,19 @@
# Conductor 0.4.1

Fixes [issue #3](https://github.com/gonzoinc/Conductor/issues/3): Windows packaged Desktop and VS Code could resolve the same AppData ledger path differently, preventing VS Code from connecting to an existing local ledger.

## Windows setup and repair

- New local installations keep task data in `%USERPROFILE%\.conductor`, separate from the program installation. Setup rejects redirectable AppData task-data locations.
- Existing installations have an explicit offline repair command. It verifies a consistent SQLite backup and all records, preserves private permissions and ownership metadata, switches settings atomically, and retains the original ledger and rollback journal. Logical and physical aliases of one database are recognized as one source; conflicting databases are rejected.
- Bridge errors identify a missing configured ledger and the possible Windows package-redirection mismatch. Startup and installer retries refuse to initialize an empty replacement for a configured missing ledger.

**Existing users:** downloading or rerunning setup does not migrate your ledger automatically. Close both clients and follow the [repair instructions](https://github.com/gonzoinc/Conductor/blob/v0.4.1/docs/windows-gui-setup.md#repair-an-existing-redirected-local-ledger). Keep the original ledger until both clients pass the shared-read/write and restart checks.

Download `ConductorSetup.exe` below for new Windows installations. Run it as your normal Windows user. The accompanying SHA-256 file verifies the download. macOS and Linux state-directory defaults are unchanged.

## Validation

Installer, GUI, bridge, and migration tests passed locally, including interrupted two-profile migration and rollback. The corrected installer passed its packaged self-test. Actual Codex Desktop and VS Code health, writes in both directions to the same migrated ledger, and post-restart reads were verified on the repaired Windows installation. Actual macOS client testing was not performed for this patch.

The release workflow builds the installer from this tag, runs Windows setup tests and the packaged self-test, and publishes the installer and checksum.
26 changes: 25 additions & 1 deletion docs/windows-gui-setup.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@
`ConductorSetup.exe` installs the local, single-user ledger for Codex desktop and the Codex VS Code extension. It downloads a private Python runtime and Python packages during installation, so an internet connection is required. It does not ask for a Git-host token or a Codex API key. To install a shared service on a Linux VM, use [the VM installer](host-install.md) on that VM.

1. Run `ConductorSetup.exe` on Windows 10 or 11 as the same normal Windows user who runs Codex. Administrator rights are not needed. Running as another administrator account installs into that account's profile instead.
2. Pick an app folder and a separate local task-data folder. No VM, Docker, SSH, or service key is needed.
2. Pick an app folder and a separate local task-data folder (default: `%USERPROFILE%\.conductor`). Task data under AppData is rejected because Windows packaged apps can redirect it. No VM, Docker, SSH, or service key is needed.
3. Choose Codex desktop, VS Code, or both. **Separate test profiles** is checked by default and leaves normal Codex settings alone. Clear it only when you want Conductor added to your usual Codex configuration.
4. Select **Install Conductor**. Progress and errors appear in the app. Fix an error and select the same button again to resume. Cancel stops the current command and can be retried. A newer setup package can reuse an earlier Conductor-owned app folder; it stages updated source inside that folder and preserves the earlier source during setup.

Expand All @@ -18,3 +18,27 @@ The Windows GUI has no VM option. A Linux VM uses its own one-command installer
## Building the Windows app

From a Windows checkout, run `py -3 gui/build_windows.py .`. The script requires an installed Python 3.11+ and network access. It pins PyInstaller, downloads uv from its official release, verifies SHA256 for the archive and executable, and includes the maintained Conductor source tree. Build scratch and the resulting executable stay under the repository's primary `.codex/gui-build/` directory. The expected output is `.codex/gui-build/dist/ConductorSetup.exe`. Run setup and the client checks on the target machine after building.

## Repair an existing redirected local ledger

Changing the default does not move an existing ledger. Do not delete the old database or rerun setup into an empty folder to work around a missing-ledger error. The bridge and repeat installer refuse to recreate a configured missing database.

Close Codex Desktop, VS Code, and any other Conductor writers before repair. Use the new source with a Python environment containing Conductor's legacy MCP dependencies, as the same normal Windows user. The repair command is included in the GUI source payload. Supply the **physical existing** database path, a destination that does not yet exist, and every affected `client.json` (repeat `--settings` for separate profiles). Do not copy a live SQLite file with Explorer; it may have uncheckpointed WAL records.

```powershell
& '<Conductor Python>' '<updated source>\scripts\repair_local.py' --source '<physical existing tasks.sqlite3>' --destination "$HOME\.conductor" --settings "$HOME\.codex\conductor-coordination\client.json" --clients-stopped
```

For a redirected installation, the physical source is typically beneath `%LOCALAPPDATA%\Packages\<Desktop package>\LocalCache\Local\Conductor`. The tool checks the configured location and matching package-cache candidates. It refuses missing or ambiguous sources and existing destinations. It verifies source ownership and private permissions, holds a SQLite writer lock during backup, checks integrity and all schema/records at the destination, then switches settings using private atomic writes. The original ledger is retained. Interrupted repairs retain the destination and `.conductor-repair.json` journal for recovery; do not retry into that existing destination.

With clients still stopped, restore original settings using:

```powershell
& '<Conductor Python>' '<updated source>\scripts\repair_local.py' --rollback "$HOME\.conductor\.conductor-repair.json" --clients-stopped
```

Rollback preserves both databases and refuses to overwrite unrelated settings changes. If either ledger received writes after cutover, resolve those records before rollback or deleting either copy; rollback does not merge databases. A forced interruption between settings writes can leave profiles temporarily split: keep clients closed and use the journal to restore settings before restarting.

Installation or repair success means **actual-client verification is pending**. In actual Desktop and VS Code sessions, confirm `coordination_health` is discovered and succeeds. Create a bounded test workload in Desktop and read it in VS Code, write a change in VS Code and read it in Desktop, then restart both clients and repeat the read/health checks. Use the same workload ID throughout. Keep the old ledger and rollback journal until these checks pass. Backend checks alone do not establish shared physical storage.

macOS and Linux state-directory defaults are unchanged.
4 changes: 2 additions & 2 deletions gui/build_windows.py
Original file line number Diff line number Diff line change
Expand Up @@ -33,7 +33,7 @@ def build_source_zip(source: Path, output: Path) -> None:
with zipfile.ZipFile(output, "w", compression=zipfile.ZIP_DEFLATED) as archive:
candidates = [source / name for name in roots]
candidates.extend(source / "scripts" / name for name in
("bootstrap.py", "install_client.py", "legacy_install.py"))
("bootstrap.py", "install_client.py", "legacy_install.py", "repair_local.py"))
for name in prefixes:
folder = source / name
if folder.is_dir():
Expand Down Expand Up @@ -97,7 +97,7 @@ def main() -> None:
environment = dict(os.environ, PYINSTALLER_CONFIG_DIR=str(build / "pyinstaller-cache"),
TEMP=str(build / "tmp"), TMP=str(build / "tmp"), TMPDIR=str(build / "tmp"))
subprocess.run([str(python), "-m", "PyInstaller", "--noconfirm", "--clean", "--onefile", "--windowed",
"--name", "ConductorSetup", "--distpath", str(build / "dist"), "--workpath", str(build / "work"),
"--paths", str(source / "src"), "--name", "ConductorSetup", "--distpath", str(build / "dist"), "--workpath", str(build / "work"),
"--specpath", str(build), "--add-data", add("uv.exe"), "--add-data", add("conductor-source.zip"),
"--add-data", add("runtime-lock.json"), str(GUI / "setup_app.py")], check=True,
env=environment)
Expand Down
4 changes: 2 additions & 2 deletions gui/setup_app.py
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,7 @@
from tkinter import filedialog, ttk

from setup_controller import (SetupCancelled, SetupConfig, completed_setup, install,
installed_setup, launch_test_profile)
installed_setup, launch_test_profile, local_state_root)
from workflow_window import WorkflowWindow


Expand All @@ -27,7 +27,7 @@ def __init__(self) -> None:
self.configure(padx=28, pady=22)
local = Path(os.environ.get("LOCALAPPDATA", str(Path.home() / "AppData/Local")))
self.install_path = tk.StringVar(value=str(local / "Programs/Conductor"))
self.data_path = tk.StringVar(value=str(local / "Conductor"))
self.data_path = tk.StringVar(value=str(local_state_root()))
self.desktop = tk.BooleanVar(value=True)
self.vscode = tk.BooleanVar(value=False)
self.isolated = tk.BooleanVar(value=True)
Expand Down
7 changes: 6 additions & 1 deletion gui/setup_controller.py
Original file line number Diff line number Diff line change
Expand Up @@ -19,6 +19,10 @@
from client_launch import launch_isolated


sys.path.insert(0, str(Path(__file__).resolve().parents[1] / "src"))
from conductor_coordination.state_paths import local_state_root, validate_shared_windows_path


PYTHON_VERSION = "3.12.15"
OWNERSHIP = {"product": "conductor-codex", "purpose": "windows-gui-install", "version": 1}

Expand Down Expand Up @@ -139,6 +143,7 @@ def validate(config: SetupConfig) -> SetupConfig:
if config.state_dir is None:
raise ValueError("Choose where Conductor should keep its local task data.")
state = _local_path(config.state_dir)
validate_shared_windows_path(state)
install = _local_path(config.install_dir)
if state == install or state.is_relative_to(install) or install.is_relative_to(state):
raise ValueError("Choose separate folders for the app and task data.")
Expand Down Expand Up @@ -328,5 +333,5 @@ def install(config: SetupConfig, resources: Path, progress: Callable[[str], None
arguments += ["--local-state-root", str(_local_path(config.state_dir)), "--db-path", str(_local_path(config.state_dir) / "tasks.sqlite3")]
_run([str(python), str(source / "scripts/bootstrap.py"), str(source), *arguments],
env=env, cancel=cancel, progress=progress)
progress("Conductor setup is complete.")
progress("Conductor installation is complete. Desktop and VS Code verification is pending; restart both clients and run the cross-client acceptance checks.")
return install_dir
2 changes: 1 addition & 1 deletion pyproject.toml
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
[project]
name = "conductor-codex"
version = "0.4.0"
version = "0.4.1"
description = "Durable task coordination for native Codex subagents"
requires-python = ">=3.11"
dependencies = []
Expand Down
9 changes: 5 additions & 4 deletions scripts/bootstrap.py
Original file line number Diff line number Diff line change
Expand Up @@ -12,6 +12,10 @@
import tomllib


sys.path.insert(0, str(Path(__file__).resolve().parents[1] / "src"))
from conductor_coordination.state_paths import local_state_root


def run(command: list[str], *, root: Path, env: dict[str, str], stage: str, quiet: bool = False) -> None:
print(stage + '...', flush=True)
subprocess.run(command, cwd=root, env=env, check=True, **({"stdout": subprocess.PIPE} if quiet else {}))
Expand Down Expand Up @@ -154,10 +158,7 @@ def setup(root: Path, arguments: list[str], *, prepared_runtime: Path | None = N
else:
if args.token_file or args.url or args.ssh_target:
raise ValueError('Local mode does not use a service URL or token file')
if os.name == 'nt':
default_root = Path(os.environ.get('LOCALAPPDATA') or Path.home() / 'AppData/Local') / 'Conductor'
else:
default_root = Path(os.environ.get('XDG_STATE_HOME') or Path.home() / '.local/state') / 'conductor'
default_root = local_state_root()
state_root = (args.local_state_root or default_root).expanduser().absolute()
database = (args.db_path or state_root / 'tasks.sqlite3').expanduser().absolute()
# The installed client performs the full local-disk and private-path checks.
Expand Down
6 changes: 6 additions & 0 deletions scripts/install_client.py
Original file line number Diff line number Diff line change
Expand Up @@ -18,6 +18,7 @@
import tempfile
import tomllib

from conductor_coordination.state_paths import validate_shared_windows_path
from conductor_coordination.client_bridge import local_state_root, read_private, validate_local_database, validate_url

SERVER_NAME = "conductor_coordination"
Expand Down Expand Up @@ -81,6 +82,7 @@ def install(*, codex_home: Path, skills_dir: Path, url: str | None = None, token
if token is not None or url is not None or ssh_target is not None:
raise ValueError("Local setup uses no service URL or credential")
data_root = (data_root or local_state_root()).expanduser().absolute()
validate_shared_windows_path(data_root)
db_path = validate_local_database(db_path or data_root / "tasks.sqlite3", data_root)
else:
raise ValueError("Unknown Conductor client mode")
Expand All @@ -93,6 +95,10 @@ def install(*, codex_home: Path, skills_dir: Path, url: str | None = None, token
settings_dir = codex_home / "conductor-coordination"
token_path = settings_dir / "service-token"
settings_path = settings_dir / "client.json"
if mode == "local" and settings_path.exists():
saved = json.loads(read_private(settings_path))
if saved.get("mode") == "local" and not Path(saved["db_path"]).is_file():
raise ValueError(f"Configured ledger is missing: {saved['db_path']}. Use explicit repair; no empty replacement was created.")
data_marker = data_root / ".conductor-local-owner.json" if mode == "local" else None
marker_content = b'{"purpose":"conductor-local-state","version":1}\n'
skill_source = source_root / "skills" / SKILL_NAME
Expand Down
9 changes: 5 additions & 4 deletions scripts/install_support.py
Original file line number Diff line number Diff line change
Expand Up @@ -20,6 +20,10 @@
import urllib.request


sys.path.insert(0, str(Path(__file__).resolve().parents[1] / "src"))
from conductor_coordination.state_paths import local_state_root


def protect(path: Path) -> None:
if os.name == 'nt':
result = subprocess.run(['whoami', '/user', '/fo', 'csv', '/nh'], check=True, capture_output=True, text=True)
Expand Down Expand Up @@ -49,10 +53,7 @@ def private_write(path: Path, data: bytes, *, replace: bool = False) -> None:
def local_database_path(identifier: str) -> Path:
if not re.fullmatch(r'[a-f0-9]{8}', identifier):
raise ValueError('Invalid local setup identifier')
if os.name == 'nt':
base = Path(os.environ.get('LOCALAPPDATA') or Path.home() / 'AppData/Local') / 'Conductor'
else:
base = Path(os.environ.get('XDG_STATE_HOME') or Path.home() / '.local/state') / 'conductor'
base = local_state_root()
return (base / 'guided' / identifier / 'tasks.sqlite3').absolute()


Expand Down
Loading
Loading