Skip to content

Fix Mac workspace sync for guest symlinks #45

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
gitcommit90 merged 1 commit into from
Aug 1, 2026
Merged

Fix Mac workspace sync for guest symlinks #45

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
12 changes: 11 additions & 1 deletion CHANGELOG.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,15 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0

## [Unreleased]

## [0.0.32] - 2026-08-01

### Fixed

- Fixed macOS channel commands, stop, and archive after ordinary guest tools
create workspace symlinks such as Python virtual environments. Symlinks now
remain durable inside the isolated Linux computer and are omitted from the
symlink-free host mirror instead of failing the entire mirror transaction.

## [0.0.31] - 2026-08-01

### Fixed
Expand Down Expand Up @@ -911,7 +920,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
notarization, stapled tickets, Gatekeeper verification, persistent
Application Support, and isolated Apple container machines.

[Unreleased]: https://github.com/gitcommit90/1Helm/compare/v0.0.31...HEAD
[Unreleased]: https://github.com/gitcommit90/1Helm/compare/v0.0.32...HEAD
[0.0.32]: https://github.com/gitcommit90/1Helm/compare/v0.0.31...v0.0.32
[0.0.31]: https://github.com/gitcommit90/1Helm/compare/v0.0.30...v0.0.31
[0.0.30]: https://github.com/gitcommit90/1Helm/compare/v0.0.29...v0.0.30
[0.0.29]: https://github.com/gitcommit90/1Helm/compare/v0.0.28...v0.0.29
Expand Down
2 changes: 1 addition & 1 deletion README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -313,7 +313,7 @@ A fresh data directory opens first-run setup. The source runtime defaults to
| `PORT` | `8123` | HTTP/WebSocket control-plane port. |
| `CTRL_DATA_DIR` | `./data` | Databases, routing state, uploads, and non-OCI development/Apple workspace mirrors. |
| `HELM_CHANNEL_COMPUTER_BACKEND` | `apple` on macOS, `oci` on Linux and Windows | Host isolation backend; `native` and `mock` are explicit development/test overrides. |
| `HELM_CHANNEL_MACHINE_IMAGE` | `local/1helm-channel-machine:0.0.31` | Versioned channel-machine image contract. |
| `HELM_CHANNEL_MACHINE_IMAGE` | `local/1helm-channel-machine:0.0.32` | Versioned channel-machine image contract. |

### Agent-first JSON CLI

Expand Down
4 changes: 2 additions & 2 deletions package-lock.json
View file
Open in desktop

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

2 changes: 1 addition & 1 deletion package.json
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
{
"name": "1helm",
"productName": "1Helm",
"version": "0.0.31",
"version": "0.0.32",
"private": true,
"type": "module",
"license": "AGPL-3.0-only",
Expand Down
11 changes: 9 additions & 2 deletions src/server/channel-computers.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -68,7 +68,7 @@ const APPLE_RUNTIME_VERSION = "1.1.0";
export const APPLE_RUNTIME_PACKAGE = `container-${APPLE_RUNTIME_VERSION}-installer-signed.pkg`;
export const APPLE_RUNTIME_URL = `https://github.com/apple/container/releases/download/${APPLE_RUNTIME_VERSION}/${APPLE_RUNTIME_PACKAGE}`;
export const APPLE_RUNTIME_SHA256 = "0ca1c42a2269c2557efb1d82b1b38ac553e6a3a3da1b1179c439bcee1e7d6714";
export const DEFAULT_CHANNEL_IMAGE = process.env.HELM_CHANNEL_MACHINE_IMAGE || "local/1helm-channel-machine:0.0.31";
export const DEFAULT_CHANNEL_IMAGE = process.env.HELM_CHANNEL_MACHINE_IMAGE || "local/1helm-channel-machine:0.0.32";
const CONTAINER_CANDIDATES = [process.env.HELM_CONTAINER_CLI, "/usr/local/bin/container", "/opt/homebrew/bin/container", "container"].filter(Boolean) as string[];
const OCI_RUNTIME_VERSION = "1helm-oci-runtime-v1";
const OCI_HELPER_CANDIDATES = [
Expand Down Expand Up @@ -1033,7 +1033,14 @@ async function syncGuestToHostUnlocked(computer: ChannelComputer): Promise<void>
const staging = `${hostWorldRoot(computer.channel_id)}.guest-sync-${randomBytes(6).toString("hex")}`;
mkdirSync(staging, { recursive: true });
try {
const invocation = isolatedInvocation(["/bin/tar", "-C", "/", "-cf", "-", "workspace"], computer, "agent", "/workspace");
// Guest workspaces legitimately contain symlinks (Python venvs are the
// common case). The host mirror deliberately has no symlink semantics,
// so export only ordinary directories/files. Symlinks remain durable in
// the guest VM and can never be followed across the host boundary.
const invocation = isolatedInvocation([
"/bin/bash", "-lc",
"set -o pipefail; cd /; find -P workspace -xdev \\( -type d -o -type f \\) -print0 | tar --null --no-recursion -T - -cf -",
], computer, "agent", "/workspace");
Comment on lines +1036 to +1043

@coderabbitai coderabbitai Bot Aug 1, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🔒 Security & Privacy | 🟠 Major | 🏗️ Heavy lift

🧩 Analysis chain

🏁 Script executed:

#!/usr/bin/env bash
set -euo pipefail

tmp="$(mktemp -d)"
trap 'rm -rf "$tmp"' EXIT

mkdir -p "$tmp/workspace" "$tmp/outside"
printf '%s\n' outside-secret > "$tmp/outside/secret"
ln -s "$tmp/outside" "$tmp/workspace/ancestor"

printf '%s\0' 'workspace/ancestor/secret' |
  (cd "$tmp" && tar --null --no-recursion -T - -cf "$tmp/archive.tar") \
  2>"$tmp/tar.err" || true

if tar -xOf "$tmp/archive.tar" 'workspace/ancestor/secret' 2>/dev/null |
  grep -Fxq outside-secret; then
  echo "FAIL: tar follows a symlink ancestor" >&2
  exit 1
fi

echo "PASS: tar did not archive through the symlink ancestor"

Repository: gitcommit90/1Helm

Length of output: 192

🏁 Script executed:

#!/usr/bin/env bash
set -euo pipefail

printf '%s\n' '--- target code ---'
sed -n '1000,1075p' src/server/channel-computers.ts

printf '%s\n' '--- validation and export references ---'
rg -n -C 4 'validateMirrorTree|isolatedInvocation|--no-recursion|find -P|mirror' src/server/channel-computers.ts src test tests 2>/dev/null || true

printf '%s\n' '--- tar implementation ---'
tar --version | head -n 2

Repository: gitcommit90/1Helm

Length of output: 50373

🏁 Script executed:

#!/usr/bin/env bash
set -euo pipefail

tmp="$(mktemp -d)"
trap 'rm -rf "$tmp"' EXIT
mkdir -p "$tmp/workspace/ancestor" "$tmp/outside"
printf '%s\n' guest-secret >"$tmp/workspace/ancestor/secret"
printf '%s\n' outside-secret >"$tmp/outside/secret"

(
  cd "$tmp"
  find -P workspace -xdev \( -type d -o -type f \) -print0 >"$tmp/entries"
)

# Model the TOCTOU window between find's path emission and tar's path lookup.
mv "$tmp/workspace/ancestor" "$tmp/workspace/ancestor.real"
ln -s "$tmp/outside" "$tmp/workspace/ancestor"

(
  cd "$tmp"
  tar --null --no-recursion -T "$tmp/entries" -cf "$tmp/archive.tar"
)

if tar -xOf "$tmp/archive.tar" 'workspace/ancestor/secret' 2>/dev/null |
  grep -Fxq outside-secret; then
  echo "FAIL: the exact find/tar sequence archived data through a replaced ancestor"
  exit 1
fi

echo "PASS: the exact find/tar sequence did not archive outside data"

Repository: gitcommit90/1Helm

Length of output: 231

🏁 Script executed:

#!/usr/bin/env bash
set -euo pipefail

printf '%s\n' '--- synchronization and guest-write context ---'
sed -n '740,885p' src/server/channel-computers.ts
printf '%s\n' '--- terminal and command call sites ---'
sed -n '885,970p' src/server/channel-computers.ts

Repository: gitcommit90/1Helm

Length of output: 15962

Make symlink exclusion atomic with the archive.

find -P passes paths to a separate tar process while active guest commands and terminals can modify /workspace. If a guest process replaces an emitted directory with a symlink, tar --no-recursion -T can archive data outside /workspace. validateMirrorTree cannot detect the source inode that tar read.

Use a read-only snapshot or quiesce guest writes during export. Add a race regression test.

🤖 Prompt for AI Agents 
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@src/server/channel-computers.ts` around lines 1036 - 1043, Update the export
flow around isolatedInvocation and validateMirrorTree so symlink exclusion is
atomic with archiving: use a read-only snapshot of /workspace or quiesce guest
writes before generating and archiving the file list, ensuring tar cannot follow
a path replaced after find emits it. Preserve ordinary directory/file export
semantics, and add a regression test covering replacement of an emitted
directory with a symlink during export.

const child = spawn(invocation.command, invocation.args, { stdio: ["ignore", "pipe", "pipe"] });
const extract = spawn("tar", ["-C", staging, "-xf", "-", "--no-same-owner", "--no-same-permissions"], { stdio: ["pipe", "ignore", "pipe"] });
let archiveBytes = 0, oversized = false;
Expand Down
2 changes: 1 addition & 1 deletion src/server/db.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -939,7 +939,7 @@ export function migrate(): void {
const platformBackend = process.platform === "darwin" ? "apple" : "oci";
const configuredBackend = String(process.env.HELM_CHANNEL_COMPUTER_BACKEND || platformBackend);
const backend = ["apple", "oci", "native", "mock"].includes(configuredBackend) ? configuredBackend : platformBackend;
const image = String(process.env.HELM_CHANNEL_MACHINE_IMAGE || "local/1helm-channel-machine:0.0.31");
const image = String(process.env.HELM_CHANNEL_MACHINE_IMAGE || "local/1helm-channel-machine:0.0.32");

@coderabbitai coderabbitai Bot Aug 1, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🗄️ Data Integrity & Integration | 🟠 Major | 🏗️ Heavy lift

🧩 Analysis chain

🏁 Script executed:

#!/usr/bin/env bash
set -euo pipefail

rg -n -C 5 \
  'DEFAULT_CHANNEL_IMAGE|HELM_CHANNEL_MACHINE_IMAGE|INSERT OR IGNORE INTO channel_computers|UPDATE channel_computers.*image|reprovision|repair' \
  src test

Repository: gitcommit90/1Helm

Length of output: 38056

🏁 Script executed:

#!/usr/bin/env bash
set -euo pipefail

printf '%s\n' '--- db.ts outline and initialization region ---'
ast-grep outline src/server/db.ts --match 'function $_($$$) { $$$ }' --view summary | head -200
sed -n '700,780p' src/server/db.ts
sed -n '900,980p' src/server/db.ts

printf '%s\n' '--- channel-computers.ts outline ---'
ast-grep outline src/server/channel-computers.ts --match 'function $_($$$) { $$$ }' --view summary | head -260

printf '%s\n' '--- candidate lifecycle and migration code ---'
rg -n -C 8 \
  'channelComputer\(|ensureChannelComputer|reconcileChannelComputers|provision_status|computer\.image|image: computer|image\)|CREATE TABLE.*channel_computers|ALTER TABLE.*channel_computers|PRAGMA user_version|schema|migration' \
  src/server/channel-computers.ts src/server/db.ts src/server/*.ts

Repository: gitcommit90/1Helm

Length of output: 354

🏁 Script executed:

#!/usr/bin/env bash
set -u

printf '%s\n' '--- db.ts initialization region ---'
sed -n '700,780p' src/server/db.ts
sed -n '900,980p' src/server/db.ts

printf '%s\n' '--- channel-computers.ts declarations ---'
ast-grep outline src/server/channel-computers.ts --view signatures | head -260

printf '%s\n' '--- lifecycle and migration references ---'
rg -n -C 8 \
  'channelComputer\(|ensureChannelComputer|reconcileChannelComputers|provision_status|computer\.image|image: computer|CREATE TABLE.*channel_computers|ALTER TABLE.*channel_computers|PRAGMA user_version|migration|schema' \
  src/server/channel-computers.ts src/server/db.ts src/server/*.ts

Repository: gitcommit90/1Helm

Length of output: 50374

🏁 Script executed:

#!/usr/bin/env bash
set -euo pipefail

printf '%s\n' '--- record creation and provisioning ---'
sed -n '120,230p' src/server/channel-computers.ts
sed -n '583,805p' src/server/channel-computers.ts

printf '%s\n' '--- reconciliation and update paths ---'
sed -n '1310,1515p' src/server/channel-computers.ts

printf '%s\n' '--- all channel_computers image writes and image consumers ---'
rg -n -C 3 \
  'channel_computers.*image|SET[^"\n]*image|image[^"\n]*channel_computers|ensureAppleProvisioned|ensureOciProvisioned|provisionChannelComputer|reconcileOne' \
  src/server/db.ts src/server/channel-computers.ts

Repository: gitcommit90/1Helm

Length of output: 43491

🏁 Script executed:

#!/usr/bin/env bash
set -euo pipefail

python3 - <<'PY'
import sqlite3

db = sqlite3.connect(":memory:")
db.executescript("""
CREATE TABLE channel_computers (
  channel_id INTEGER PRIMARY KEY,
  image TEXT NOT NULL
);
INSERT INTO channel_computers VALUES (7, 'local/1helm-channel-machine:0.0.31');
""")
db.execute(
    """INSERT OR IGNORE INTO channel_computers(channel_id, image)
       VALUES (?, ?)""",
    (7, "local/1helm-channel-machine:0.0.32"),
)
row = db.execute(
    "SELECT channel_id, image FROM channel_computers WHERE channel_id=7"
).fetchone()
print({"after_insert_or_ignore": row})

db.execute(
    "UPDATE channel_computers SET image=? WHERE channel_id=?",
    ("local/1helm-channel-machine:0.0.32", 7),
)
row = db.execute(
    "SELECT channel_id, image FROM channel_computers WHERE channel_id=7"
).fetchone()
print({"after_explicit_update": row})
PY

printf '%s\n' '--- image versions and machine replacement controls ---'
rg -n -C 3 \
  '0\.0\.3[01-9]|image-contract|machine (create|delete|rm|stop|run)|container (create|rm|stop|start)|DELETE FROM channel_computers|UPDATE channel_computers SET[^;]*image' \
  src container scripts test

Repository: gitcommit90/1Helm

Length of output: 17475

Migrate existing channel computers to image 0.0.32.

INSERT OR IGNORE preserves existing channel_computers.image values. ensureAppleProvisioned uses the stored image only when it creates a missing machine. Update existing rows and explicitly replace or reprovision machines that still use 0.0.31; restarting them does not load the new image.

📍 Affects 2 files
  • src/server/db.ts#L942-L942 (this comment)
  • src/server/channel-computers.ts#L71-L71
🤖 Prompt for AI Agents 
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@src/server/db.ts` at line 942, Update the channel-computer provisioning flow
in src/server/db.ts at lines 942-942 and src/server/channel-computers.ts at
lines 71-71 so existing rows using image 0.0.31 are migrated to 0.0.32, and
explicitly replace or reprovision their machines rather than only restarting
them; preserve INSERT OR IGNORE behavior for unaffected records and ensure
ensureAppleProvisioned uses the updated image.

for (const channel of q(`SELECT c.id FROM channels c JOIN agent_channels ac ON ac.channel_id=c.id
WHERE c.kind='channel' AND c.status<>'deleted'`)) {
const channelId = Number(channel.id);
Expand Down
9 changes: 8 additions & 1 deletion test/channel-computers.mjs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -102,6 +102,13 @@ test("Apple channel-computer contract preserves isolation, files, wakes, archive
assert.equal(readFileSync(join(dataDir, "channels", String(alpha.channelId), "workspace", "name with spaces.txt"), "utf8"), "semi; quote ' and space", "guest command quoting survives Apple's login-shell handoff");
assert.equal(existsSync(join(dataDir, "channels", String(alpha.channelId), "files", "guest.txt")), false, "guest deletions do not resurrect stale Files entries");

result = await computers.runChannelCommand(alpha.channelId, "mkdir -p .venv/bin; ln -s /usr/bin/python3 .venv/bin/python3; ln -s python3 .venv/bin/python; printf venv-ok > .venv/marker");
assert.equal(result.exit_code, 0, "a normal Python-style venv does not make the command fail during mirror sync");
assert.equal(readFileSync(join(dataDir, "channels", String(alpha.channelId), "workspace", ".venv", "marker"), "utf8"), "venv-ok");
assert.equal(existsSync(join(dataDir, "channels", String(alpha.channelId), "workspace", ".venv", "bin", "python3")), false, "guest symlinks stay in the VM instead of crossing the host mirror boundary");

@coderabbitai coderabbitai Bot Aug 1, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win

🧩 Analysis chain

🏁 Script executed:

#!/usr/bin/env bash
set -euo pipefail

node <<'NODE'
const { existsSync, lstatSync, mkdtempSync, rmSync, symlinkSync } = require("node:fs");
const { join } = require("node:path");
const { tmpdir } = require("node:os");

const dir = mkdtempSync(join(tmpdir(), "symlink-test-"));
const link = join(dir, "python3");

try {
  symlinkSync("/definitely-missing-python3", link);
  if (existsSync(link)) throw new Error("existsSync unexpectedly returned true");
  if (!lstatSync(link).isSymbolicLink()) throw new Error("lstatSync did not detect the symlink");
} finally {
  rmSync(dir, { recursive: true, force: true });
}
NODE

Repository: gitcommit90/1Helm

Length of output: 155

🏁 Script executed:

sed -n '1,125p' test/channel-computers.mjs

Repository: gitcommit90/1Helm

Length of output: 10019

🏁 Script executed:

rg -n -C 5 'symlink|mirror|lstat|existsSync|workspace' src test/fake-container.mjs

Repository: gitcommit90/1Helm

Length of output: 50374

🏁 Script executed:

fd -i 'channel-computers|fake-container' src test

Repository: gitcommit90/1Helm

Length of output: 324

🏁 Script executed:

rg -n -C 8 'sync|mirror|symlink|workspace|files' src/server/channel-computers.ts test/fake-container.mjs

Repository: gitcommit90/1Helm

Length of output: 50374

🏁 Script executed:

sed -n '808,980p' src/server/channel-computers.ts

Repository: gitcommit90/1Helm

Length of output: 11571

🏁 Script executed:

rg -n -A 90 'function syncGuestToHostUnlocked|validateMirrorTree' src/server/channel-computers.ts

Repository: gitcommit90/1Helm

Length of output: 18663

Inspect the directory entry instead of following the symlink.

existsSync follows symlinks and returns false for a dangling symlink. Use lstatSync and assert that the entry itself is absent. Import lstatSync from node:fs.

🤖 Prompt for AI Agents 
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@test/channel-computers.mjs` at line 108, Update the test around the guest
workspace Python path to import and use lstatSync from node:fs instead of
existsSync, so the assertion inspects the directory entry itself without
following a potentially dangling symlink and verifies that the entry is absent.

result = await computers.runChannelCommand(alpha.channelId, "test -L .venv/bin/python3 && readlink .venv/bin/python3");
assert.match(result.output, /\/usr\/bin\/python3/, "the venv symlink remains durable and usable inside the guest");

computers.upsertObligation(alpha.channelId, "command", "held", "resident", "active work");
await computers.stopChannelComputer(alpha.channelId, "idle");
assert.equal(db.q1("SELECT observed_state FROM channel_computers WHERE channel_id=?", alpha.channelId).observed_state, "running", "resident work prevents idle sleep");
Expand Down Expand Up @@ -167,7 +174,7 @@ test("Apple channel-computer contract preserves isolation, files, wakes, archive
test("runtime digest and packaged image recipe stay pinned", async () => {
assert.equal(computers.APPLE_RUNTIME_SHA256, "0ca1c42a2269c2557efb1d82b1b38ac553e6a3a3da1b1179c439bcee1e7d6714");
assert.match(computers.APPLE_RUNTIME_URL, /\/1\.1\.0\/container-1\.1\.0-installer-signed\.pkg$/);
assert.equal(computers.DEFAULT_CHANNEL_IMAGE, "local/1helm-channel-machine:0.0.31");
assert.equal(computers.DEFAULT_CHANNEL_IMAGE, "local/1helm-channel-machine:0.0.32");
const packaging = await readFile(join(root, "scripts", "package-mac-dmg.cjs"), "utf8");
assert.match(packaging, /container\(\?:\$\|\\\/\)/, "release packaging includes container/ image assets");
const image = await readFile(join(root, "container", "Containerfile"), "utf8");
Expand Down
6 changes: 4 additions & 2 deletions test/fake-container.mjs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -119,10 +119,12 @@ if (script.includes("image-contract") && script.includes("/var/lib/1helm/owner")
writeFileSync(join(root, "var", "lib", "1helm", "owner"), `${ownerValue}\n`);
process.exit(0);
}
if (command[0] === "/bin/tar" && command.includes("-cf")) {
if ((command[0] === "/bin/tar" && command.includes("-cf")) || (script.includes("find -P workspace") && script.includes("--no-recursion"))) {
const delay = Math.max(0, Number(process.env.FAKE_CONTAINER_EXPORT_DELAY_MS || 0));
if (delay) Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, delay);
const tar = spawnSync("tar", ["-C", root, "-cf", "-", "workspace"], { maxBuffer: 256 * 1024 ** 2 });
const listed = spawnSync("find", ["-P", "workspace", "-xdev", "(", "-type", "d", "-o", "-type", "f", ")", "-print0"], { cwd: root });
if (listed.status !== 0) fail(String(listed.stderr || "fake workspace listing failed"));
const tar = spawnSync("tar", ["-C", root, "--null", "--no-recursion", "-T", "-", "-cf", "-"], { input: listed.stdout, maxBuffer: 256 * 1024 ** 2 });
if (tar.status !== 0) fail(String(tar.stderr || "fake export failed"));
process.stdout.write(tar.stdout);
process.exit(0);
Expand Down
Loading