fix(tarball): rewrite absolute /root symlinks after non-root extract

[AhmedTMM]

Root cause

Tarballs are built on a CI VM running as root, so file layouts contain absolute symlinks like:

```
/root/.local/bin/claude -> /root/.claude/local/claude
```

When extracted on a non-root user (Sprite, scp-style installs without passwordless sudo), tar's `--transform "s|^root/|${HOME#/}/|"` rewrites file PATHS — so the file lands at `$HOME/.local/bin/claude` — but does not rewrite symlink TARGETS. The symlink still points to `/root/.claude/local/claude`, which doesn't exist.

User experience: `tryTarballInstall` returns `true` (the marker file extracts fine), the orchestrator logs "Agent installed from pre-built tarball" and proceeds to launch. Then:

```
/tmp/spawn_T6Gu8f.sh: line 4: claude: command not found
```

10 retries, exit 127, give up. Repro from a real session today on `spawn claude sprite` (no flags — fast_provision experiment had bucketed the user to test).

Fix

Post-extract, walk `$HOME` and rewrite any `/root/*` symlink targets to point under `$HOME`:

```bash
find "$HOME" -type l 2>/dev/null | while IFS= read -r _l; do
_t=$(readlink "$_l" 2>/dev/null) || continue
case "$_t" in
/root/*) ln -snf "$HOME${_t#/root}" "$_l" 2>/dev/null ;;
esac
done
```

Wired into the non-root branch of `extractCmd` in `shared/agent-tarball.ts`. Only runs when the transform extract succeeds; the sudo fallback (which extracts as root and doesn't need rewriting) is unchanged.

Why this is the right fix vs. alternatives

• GNU tar `--transform "flags=rsh;..."` would rewrite symlink targets too, but only handles `^root/` (relative form) and would need a second rule for absolute `/root/`. Also relies on a relatively obscure GNU tar feature; the find walk is more portable.
• Build tarballs as a non-root user would require duplicating the install pipeline. Out of scope.
• Switch to relative symlinks at capture time would require knowing the layout each agent's installer produces. Brittle per-agent.

Test plan

• `bunx @biomejs/biome check src/` — 0 errors
• `bunx tsc --noEmit -p .` — 0 production errors
• `bun test orchestrate.test.ts` — 41 pass
• Smoke test: simulate post-transform extract layout in a temp dir with a dangling `/root/.claude/local/claude` symlink, run the fix loop, verify symlink resolves to `$HOME/.claude/local/claude` and `test -e` passes
• End-to-end: `spawn claude sprite --beta tarball` + `which claude` returns a working path
• End-to-end: `spawn openclaw sprite --beta tarball` + `openclaw --version` (separately, openclaw also has a config-validation issue surfacing in `Unrecognized key: "main"` — that's a different bug, not this PR)

Bumps CLI to 1.0.24.

🤖 Generated with Claude Code

[la14-1]

Review

Diagnosis is exactly right: `tar --transform` rewrites file paths but not symlink targets, so every non-root extract on Sprite etc. has been silently dangling binary symlinks. Repro case in the description (`spawn claude sprite` → `command not found` → 10 retries → exit 127) is the classic signature.

Looks good

• Scoped correctly: runs only in the non-root transform branch. Root-user extract and the sudo fallback are untouched.
• Trailing `true` makes the subshell succeed even if individual `ln -snf` calls fail — without it, the outer `||` would fall through to `sudo tar` and double-extract on clouds that have sudo. Correct and defensive.
• Shell-glob pattern `/root/*` matches `/root/foo` and `/root/x/y` but correctly does not match `/rooty` or a bare `/root` — target rewriting is narrowly scoped.
• Uses `_l` / `_t` underscore-prefixed locals — won't clash with anything in the user's shell env.
• `${_t#/root}` parameter expansion strips just the prefix, preserving the rest of the target path. Matches `$HOME${_t#/root}`.

Minor

• Edge case: target is exactly `/root` (no trailing slash) — the `/root/` glob won't match. Unlikely in practice (agents always install under subdirs) but if it ever happens, the symlink stays dangling. Extending the case to `/root|/root/` would be a one-char fix.
• `find "$HOME" -type l` walks the whole home. On a freshly-provisioned VM this is bounded by the tarball contents. Real users may have accumulated files, but we're running this inside the agent-install phase right after extract, so it's fine in practice.
• No automated test. The PR mentions a manual smoke test in a temp dir — fair for a shell fragment, but this is the second tarball-extract bug this release (see also fix(packer): repair cursor tarball + hermes interactive install #3367). A unit test that asserts the generated `extractCmd` contains the fix loop + a shelled-out integration test with a crafted tarball would catch future regressions. Not blocking.

Alt-fix considered (and rejected correctly)

You considered `--transform "flags=rsh;..."` — that rewrites symlink targets but only matches the relative form `^root/` after tar's own stripping, not absolute `/root/`. A find-walk is more portable than relying on GNU-tar-specific flag syntax. Right call.

Nice-to-have (follow-up)

• feat(cli): --repo flag clones a template repo and applies spawn.md #3360 / feat(cli): posthog feature flags + fast_provision experiment #3366 both introduced tarball-adjacent codepaths recently. A `verify-extracted-symlinks` step that runs `test -x "$HOME/.local/bin/"` right after `tryTarballInstall` returns true would turn silent-dangling-link bugs into loud failures that trigger the clean-install fallback. Worth filing as a separate issue.

LGTM.

Reviewed by SPA

[la14-1]

Approved. See full review at #3368 (comment).

[AhmedTMM]

Root cause

Tarballs are built on a CI VM running as root, so file layouts contain absolute symlinks like:

```
/root/.local/bin/claude -> /root/.claude/local/claude
```

When extracted on a non-root user (Sprite, scp-style installs without passwordless sudo), tar's `--transform "s|^root/|${HOME#/}/|"` rewrites file PATHS — so the file lands at `$HOME/.local/bin/claude` — but does not rewrite symlink TARGETS. The symlink still points to `/root/.claude/local/claude`, which doesn't exist.

User experience: `tryTarballInstall` returns `true` (the marker file extracts fine), the orchestrator logs "Agent installed from pre-built tarball" and proceeds to launch. Then:

```
/tmp/spawn_T6Gu8f.sh: line 4: claude: command not found
```

10 retries, exit 127, give up. Repro from a real session today on `spawn claude sprite` (no flags — fast_provision experiment had bucketed the user to test).

Fix

Post-extract, walk `$HOME` and rewrite any `/root/*` symlink targets to point under `$HOME`:

```bash
find "$HOME" -type l 2>/dev/null | while IFS= read -r _l; do
_t=$(readlink "$_l" 2>/dev/null) || continue
case "$_t" in
/root/*) ln -snf "$HOME${_t#/root}" "$_l" 2>/dev/null ;;
esac
done
```

Wired into the non-root branch of `extractCmd` in `shared/agent-tarball.ts`. Only runs when the transform extract succeeds; the sudo fallback (which extracts as root and doesn't need rewriting) is unchanged.

Why this is the right fix vs. alternatives

• GNU tar `--transform "flags=rsh;..."` would rewrite symlink targets too, but only handles `^root/` (relative form) and would need a second rule for absolute `/root/`. Also relies on a relatively obscure GNU tar feature; the find walk is more portable.
• Build tarballs as a non-root user would require duplicating the install pipeline. Out of scope.
• Switch to relative symlinks at capture time would require knowing the layout each agent's installer produces. Brittle per-agent.

Test plan

• `bunx @biomejs/biome check src/` — 0 errors
• `bunx tsc --noEmit -p .` — 0 production errors
• `bun test orchestrate.test.ts` — 41 pass
• Smoke test: simulate post-transform extract layout in a temp dir with a dangling `/root/.claude/local/claude` symlink, run the fix loop, verify symlink resolves to `$HOME/.claude/local/claude` and `test -e` passes
• End-to-end: `spawn claude sprite --beta tarball` + `which claude` returns a working path
• End-to-end: `spawn openclaw sprite --beta tarball` + `openclaw --version` (separately, openclaw also has a config-validation issue surfacing in `Unrecognized key: "main"` — that's a different bug, not this PR)

Bumps CLI to 1.0.24.

🤖 Generated with Claude Code

[la14-1]

Review

Diagnosis is exactly right: `tar --transform` rewrites file paths but not symlink targets, so every non-root extract on Sprite etc. has been silently dangling binary symlinks. Repro case in the description (`spawn claude sprite` → `command not found` → 10 retries → exit 127) is the classic signature.

Looks good

• Scoped correctly: runs only in the non-root transform branch. Root-user extract and the sudo fallback are untouched.
• Trailing `true` makes the subshell succeed even if individual `ln -snf` calls fail — without it, the outer `||` would fall through to `sudo tar` and double-extract on clouds that have sudo. Correct and defensive.
• Shell-glob pattern `/root/*` matches `/root/foo` and `/root/x/y` but correctly does not match `/rooty` or a bare `/root` — target rewriting is narrowly scoped.
• Uses `_l` / `_t` underscore-prefixed locals — won't clash with anything in the user's shell env.
• `${_t#/root}` parameter expansion strips just the prefix, preserving the rest of the target path. Matches `$HOME${_t#/root}`.

Minor

• Edge case: target is exactly `/root` (no trailing slash) — the `/root/` glob won't match. Unlikely in practice (agents always install under subdirs) but if it ever happens, the symlink stays dangling. Extending the case to `/root|/root/` would be a one-char fix.
• `find "$HOME" -type l` walks the whole home. On a freshly-provisioned VM this is bounded by the tarball contents. Real users may have accumulated files, but we're running this inside the agent-install phase right after extract, so it's fine in practice.
• No automated test. The PR mentions a manual smoke test in a temp dir — fair for a shell fragment, but this is the second tarball-extract bug this release (see also fix(packer): repair cursor tarball + hermes interactive install #3367). A unit test that asserts the generated `extractCmd` contains the fix loop + a shelled-out integration test with a crafted tarball would catch future regressions. Not blocking.

Alt-fix considered (and rejected correctly)

You considered `--transform "flags=rsh;..."` — that rewrites symlink targets but only matches the relative form `^root/` after tar's own stripping, not absolute `/root/`. A find-walk is more portable than relying on GNU-tar-specific flag syntax. Right call.

Nice-to-have (follow-up)

• feat(cli): --repo flag clones a template repo and applies spawn.md #3360 / feat(cli): posthog feature flags + fast_provision experiment #3366 both introduced tarball-adjacent codepaths recently. A `verify-extracted-symlinks` step that runs `test -x "$HOME/.local/bin/"` right after `tryTarballInstall` returns true would turn silent-dangling-link bugs into loud failures that trigger the clean-install fallback. Worth filing as a separate issue.

LGTM.

Reviewed by SPA

[la14-1]

Approved. See full review at #3368 (comment).

[AhmedTMM]

Root cause

Tarballs are built on a CI VM running as root, so file layouts contain absolute symlinks like:

```
/root/.local/bin/claude -> /root/.claude/local/claude
```

When extracted on a non-root user (Sprite, scp-style installs without passwordless sudo), tar's `--transform "s|^root/|${HOME#/}/|"` rewrites file PATHS — so the file lands at `$HOME/.local/bin/claude` — but does not rewrite symlink TARGETS. The symlink still points to `/root/.claude/local/claude`, which doesn't exist.

User experience: `tryTarballInstall` returns `true` (the marker file extracts fine), the orchestrator logs "Agent installed from pre-built tarball" and proceeds to launch. Then:

```
/tmp/spawn_T6Gu8f.sh: line 4: claude: command not found
```

10 retries, exit 127, give up. Repro from a real session today on `spawn claude sprite` (no flags — fast_provision experiment had bucketed the user to test).

Fix

Post-extract, walk `$HOME` and rewrite any `/root/*` symlink targets to point under `$HOME`:

```bash
find "$HOME" -type l 2>/dev/null | while IFS= read -r _l; do
_t=$(readlink "$_l" 2>/dev/null) || continue
case "$_t" in
/root/*) ln -snf "$HOME${_t#/root}" "$_l" 2>/dev/null ;;
esac
done
```

Wired into the non-root branch of `extractCmd` in `shared/agent-tarball.ts`. Only runs when the transform extract succeeds; the sudo fallback (which extracts as root and doesn't need rewriting) is unchanged.

Why this is the right fix vs. alternatives

• GNU tar `--transform "flags=rsh;..."` would rewrite symlink targets too, but only handles `^root/` (relative form) and would need a second rule for absolute `/root/`. Also relies on a relatively obscure GNU tar feature; the find walk is more portable.
• Build tarballs as a non-root user would require duplicating the install pipeline. Out of scope.
• Switch to relative symlinks at capture time would require knowing the layout each agent's installer produces. Brittle per-agent.

Test plan

• `bunx @biomejs/biome check src/` — 0 errors
• `bunx tsc --noEmit -p .` — 0 production errors
• `bun test orchestrate.test.ts` — 41 pass
• Smoke test: simulate post-transform extract layout in a temp dir with a dangling `/root/.claude/local/claude` symlink, run the fix loop, verify symlink resolves to `$HOME/.claude/local/claude` and `test -e` passes
• End-to-end: `spawn claude sprite --beta tarball` + `which claude` returns a working path
• End-to-end: `spawn openclaw sprite --beta tarball` + `openclaw --version` (separately, openclaw also has a config-validation issue surfacing in `Unrecognized key: "main"` — that's a different bug, not this PR)

Bumps CLI to 1.0.24.

🤖 Generated with Claude Code

[la14-1]

Review

Diagnosis is exactly right: `tar --transform` rewrites file paths but not symlink targets, so every non-root extract on Sprite etc. has been silently dangling binary symlinks. Repro case in the description (`spawn claude sprite` → `command not found` → 10 retries → exit 127) is the classic signature.

Looks good

• Scoped correctly: runs only in the non-root transform branch. Root-user extract and the sudo fallback are untouched.
• Trailing `true` makes the subshell succeed even if individual `ln -snf` calls fail — without it, the outer `||` would fall through to `sudo tar` and double-extract on clouds that have sudo. Correct and defensive.
• Shell-glob pattern `/root/*` matches `/root/foo` and `/root/x/y` but correctly does not match `/rooty` or a bare `/root` — target rewriting is narrowly scoped.
• Uses `_l` / `_t` underscore-prefixed locals — won't clash with anything in the user's shell env.
• `${_t#/root}` parameter expansion strips just the prefix, preserving the rest of the target path. Matches `$HOME${_t#/root}`.

Minor

• Edge case: target is exactly `/root` (no trailing slash) — the `/root/` glob won't match. Unlikely in practice (agents always install under subdirs) but if it ever happens, the symlink stays dangling. Extending the case to `/root|/root/` would be a one-char fix.
• `find "$HOME" -type l` walks the whole home. On a freshly-provisioned VM this is bounded by the tarball contents. Real users may have accumulated files, but we're running this inside the agent-install phase right after extract, so it's fine in practice.
• No automated test. The PR mentions a manual smoke test in a temp dir — fair for a shell fragment, but this is the second tarball-extract bug this release (see also fix(packer): repair cursor tarball + hermes interactive install #3367). A unit test that asserts the generated `extractCmd` contains the fix loop + a shelled-out integration test with a crafted tarball would catch future regressions. Not blocking.

Alt-fix considered (and rejected correctly)

You considered `--transform "flags=rsh;..."` — that rewrites symlink targets but only matches the relative form `^root/` after tar's own stripping, not absolute `/root/`. A find-walk is more portable than relying on GNU-tar-specific flag syntax. Right call.

Nice-to-have (follow-up)

• feat(cli): --repo flag clones a template repo and applies spawn.md #3360 / feat(cli): posthog feature flags + fast_provision experiment #3366 both introduced tarball-adjacent codepaths recently. A `verify-extracted-symlinks` step that runs `test -x "$HOME/.local/bin/"` right after `tryTarballInstall` returns true would turn silent-dangling-link bugs into loud failures that trigger the clean-install fallback. Worth filing as a separate issue.

LGTM.

Reviewed by SPA

[la14-1]

Approved. See full review at #3368 (comment).

[AhmedTMM]

Root cause

Tarballs are built on a CI VM running as root, so file layouts contain absolute symlinks like:

```
/root/.local/bin/claude -> /root/.claude/local/claude
```

When extracted on a non-root user (Sprite, scp-style installs without passwordless sudo), tar's `--transform "s|^root/|${HOME#/}/|"` rewrites file PATHS — so the file lands at `$HOME/.local/bin/claude` — but does not rewrite symlink TARGETS. The symlink still points to `/root/.claude/local/claude`, which doesn't exist.

User experience: `tryTarballInstall` returns `true` (the marker file extracts fine), the orchestrator logs "Agent installed from pre-built tarball" and proceeds to launch. Then:

```
/tmp/spawn_T6Gu8f.sh: line 4: claude: command not found
```

10 retries, exit 127, give up. Repro from a real session today on `spawn claude sprite` (no flags — fast_provision experiment had bucketed the user to test).

Fix

Post-extract, walk `$HOME` and rewrite any `/root/*` symlink targets to point under `$HOME`:

```bash
find "$HOME" -type l 2>/dev/null | while IFS= read -r _l; do
_t=$(readlink "$_l" 2>/dev/null) || continue
case "$_t" in
/root/*) ln -snf "$HOME${_t#/root}" "$_l" 2>/dev/null ;;
esac
done
```

Wired into the non-root branch of `extractCmd` in `shared/agent-tarball.ts`. Only runs when the transform extract succeeds; the sudo fallback (which extracts as root and doesn't need rewriting) is unchanged.

Why this is the right fix vs. alternatives

• GNU tar `--transform "flags=rsh;..."` would rewrite symlink targets too, but only handles `^root/` (relative form) and would need a second rule for absolute `/root/`. Also relies on a relatively obscure GNU tar feature; the find walk is more portable.
• Build tarballs as a non-root user would require duplicating the install pipeline. Out of scope.
• Switch to relative symlinks at capture time would require knowing the layout each agent's installer produces. Brittle per-agent.

Test plan

• `bunx @biomejs/biome check src/` — 0 errors
• `bunx tsc --noEmit -p .` — 0 production errors
• `bun test orchestrate.test.ts` — 41 pass
• Smoke test: simulate post-transform extract layout in a temp dir with a dangling `/root/.claude/local/claude` symlink, run the fix loop, verify symlink resolves to `$HOME/.claude/local/claude` and `test -e` passes
• End-to-end: `spawn claude sprite --beta tarball` + `which claude` returns a working path
• End-to-end: `spawn openclaw sprite --beta tarball` + `openclaw --version` (separately, openclaw also has a config-validation issue surfacing in `Unrecognized key: "main"` — that's a different bug, not this PR)

Bumps CLI to 1.0.24.

🤖 Generated with Claude Code

[la14-1]

Review

Diagnosis is exactly right: `tar --transform` rewrites file paths but not symlink targets, so every non-root extract on Sprite etc. has been silently dangling binary symlinks. Repro case in the description (`spawn claude sprite` → `command not found` → 10 retries → exit 127) is the classic signature.

Looks good

• Scoped correctly: runs only in the non-root transform branch. Root-user extract and the sudo fallback are untouched.
• Trailing `true` makes the subshell succeed even if individual `ln -snf` calls fail — without it, the outer `||` would fall through to `sudo tar` and double-extract on clouds that have sudo. Correct and defensive.
• Shell-glob pattern `/root/*` matches `/root/foo` and `/root/x/y` but correctly does not match `/rooty` or a bare `/root` — target rewriting is narrowly scoped.
• Uses `_l` / `_t` underscore-prefixed locals — won't clash with anything in the user's shell env.
• `${_t#/root}` parameter expansion strips just the prefix, preserving the rest of the target path. Matches `$HOME${_t#/root}`.

Minor

• Edge case: target is exactly `/root` (no trailing slash) — the `/root/` glob won't match. Unlikely in practice (agents always install under subdirs) but if it ever happens, the symlink stays dangling. Extending the case to `/root|/root/` would be a one-char fix.
• `find "$HOME" -type l` walks the whole home. On a freshly-provisioned VM this is bounded by the tarball contents. Real users may have accumulated files, but we're running this inside the agent-install phase right after extract, so it's fine in practice.
• No automated test. The PR mentions a manual smoke test in a temp dir — fair for a shell fragment, but this is the second tarball-extract bug this release (see also fix(packer): repair cursor tarball + hermes interactive install #3367). A unit test that asserts the generated `extractCmd` contains the fix loop + a shelled-out integration test with a crafted tarball would catch future regressions. Not blocking.

Alt-fix considered (and rejected correctly)

You considered `--transform "flags=rsh;..."` — that rewrites symlink targets but only matches the relative form `^root/` after tar's own stripping, not absolute `/root/`. A find-walk is more portable than relying on GNU-tar-specific flag syntax. Right call.

Nice-to-have (follow-up)

• feat(cli): --repo flag clones a template repo and applies spawn.md #3360 / feat(cli): posthog feature flags + fast_provision experiment #3366 both introduced tarball-adjacent codepaths recently. A `verify-extracted-symlinks` step that runs `test -x "$HOME/.local/bin/"` right after `tryTarballInstall` returns true would turn silent-dangling-link bugs into loud failures that trigger the clean-install fallback. Worth filing as a separate issue.

LGTM.

Reviewed by SPA

[la14-1]

Approved. See full review at #3368 (comment).

[AhmedTMM]

Root cause

Tarballs are built on a CI VM running as root, so file layouts contain absolute symlinks like:

```
/root/.local/bin/claude -> /root/.claude/local/claude
```

When extracted on a non-root user (Sprite, scp-style installs without passwordless sudo), tar's `--transform "s|^root/|${HOME#/}/|"` rewrites file PATHS — so the file lands at `$HOME/.local/bin/claude` — but does not rewrite symlink TARGETS. The symlink still points to `/root/.claude/local/claude`, which doesn't exist.

User experience: `tryTarballInstall` returns `true` (the marker file extracts fine), the orchestrator logs "Agent installed from pre-built tarball" and proceeds to launch. Then:

```
/tmp/spawn_T6Gu8f.sh: line 4: claude: command not found
```

10 retries, exit 127, give up. Repro from a real session today on `spawn claude sprite` (no flags — fast_provision experiment had bucketed the user to test).

Fix

Post-extract, walk `$HOME` and rewrite any `/root/*` symlink targets to point under `$HOME`:

```bash
find "$HOME" -type l 2>/dev/null | while IFS= read -r _l; do
_t=$(readlink "$_l" 2>/dev/null) || continue
case "$_t" in
/root/*) ln -snf "$HOME${_t#/root}" "$_l" 2>/dev/null ;;
esac
done
```

Wired into the non-root branch of `extractCmd` in `shared/agent-tarball.ts`. Only runs when the transform extract succeeds; the sudo fallback (which extracts as root and doesn't need rewriting) is unchanged.

Why this is the right fix vs. alternatives

• GNU tar `--transform "flags=rsh;..."` would rewrite symlink targets too, but only handles `^root/` (relative form) and would need a second rule for absolute `/root/`. Also relies on a relatively obscure GNU tar feature; the find walk is more portable.
• Build tarballs as a non-root user would require duplicating the install pipeline. Out of scope.
• Switch to relative symlinks at capture time would require knowing the layout each agent's installer produces. Brittle per-agent.

Test plan

• `bunx @biomejs/biome check src/` — 0 errors
• `bunx tsc --noEmit -p .` — 0 production errors
• `bun test orchestrate.test.ts` — 41 pass
• Smoke test: simulate post-transform extract layout in a temp dir with a dangling `/root/.claude/local/claude` symlink, run the fix loop, verify symlink resolves to `$HOME/.claude/local/claude` and `test -e` passes
• End-to-end: `spawn claude sprite --beta tarball` + `which claude` returns a working path
• End-to-end: `spawn openclaw sprite --beta tarball` + `openclaw --version` (separately, openclaw also has a config-validation issue surfacing in `Unrecognized key: "main"` — that's a different bug, not this PR)

Bumps CLI to 1.0.24.

🤖 Generated with Claude Code

[la14-1]

Review

Diagnosis is exactly right: `tar --transform` rewrites file paths but not symlink targets, so every non-root extract on Sprite etc. has been silently dangling binary symlinks. Repro case in the description (`spawn claude sprite` → `command not found` → 10 retries → exit 127) is the classic signature.

Looks good

• Scoped correctly: runs only in the non-root transform branch. Root-user extract and the sudo fallback are untouched.
• Trailing `true` makes the subshell succeed even if individual `ln -snf` calls fail — without it, the outer `||` would fall through to `sudo tar` and double-extract on clouds that have sudo. Correct and defensive.
• Shell-glob pattern `/root/*` matches `/root/foo` and `/root/x/y` but correctly does not match `/rooty` or a bare `/root` — target rewriting is narrowly scoped.
• Uses `_l` / `_t` underscore-prefixed locals — won't clash with anything in the user's shell env.
• `${_t#/root}` parameter expansion strips just the prefix, preserving the rest of the target path. Matches `$HOME${_t#/root}`.

Minor

• Edge case: target is exactly `/root` (no trailing slash) — the `/root/` glob won't match. Unlikely in practice (agents always install under subdirs) but if it ever happens, the symlink stays dangling. Extending the case to `/root|/root/` would be a one-char fix.
• `find "$HOME" -type l` walks the whole home. On a freshly-provisioned VM this is bounded by the tarball contents. Real users may have accumulated files, but we're running this inside the agent-install phase right after extract, so it's fine in practice.
• No automated test. The PR mentions a manual smoke test in a temp dir — fair for a shell fragment, but this is the second tarball-extract bug this release (see also fix(packer): repair cursor tarball + hermes interactive install #3367). A unit test that asserts the generated `extractCmd` contains the fix loop + a shelled-out integration test with a crafted tarball would catch future regressions. Not blocking.

Alt-fix considered (and rejected correctly)

You considered `--transform "flags=rsh;..."` — that rewrites symlink targets but only matches the relative form `^root/` after tar's own stripping, not absolute `/root/`. A find-walk is more portable than relying on GNU-tar-specific flag syntax. Right call.

Nice-to-have (follow-up)

• feat(cli): --repo flag clones a template repo and applies spawn.md #3360 / feat(cli): posthog feature flags + fast_provision experiment #3366 both introduced tarball-adjacent codepaths recently. A `verify-extracted-symlinks` step that runs `test -x "$HOME/.local/bin/"` right after `tryTarballInstall` returns true would turn silent-dangling-link bugs into loud failures that trigger the clean-install fallback. Worth filing as a separate issue.

LGTM.

Reviewed by SPA

[la14-1]

Approved. See full review at #3368 (comment).

[AhmedTMM]

Root cause

Tarballs are built on a CI VM running as root, so file layouts contain absolute symlinks like:

```
/root/.local/bin/claude -> /root/.claude/local/claude
```

When extracted on a non-root user (Sprite, scp-style installs without passwordless sudo), tar's `--transform "s|^root/|${HOME#/}/|"` rewrites file PATHS — so the file lands at `$HOME/.local/bin/claude` — but does not rewrite symlink TARGETS. The symlink still points to `/root/.claude/local/claude`, which doesn't exist.

User experience: `tryTarballInstall` returns `true` (the marker file extracts fine), the orchestrator logs "Agent installed from pre-built tarball" and proceeds to launch. Then:

```
/tmp/spawn_T6Gu8f.sh: line 4: claude: command not found
```

10 retries, exit 127, give up. Repro from a real session today on `spawn claude sprite` (no flags — fast_provision experiment had bucketed the user to test).

Fix

Post-extract, walk `$HOME` and rewrite any `/root/*` symlink targets to point under `$HOME`:

```bash
find "$HOME" -type l 2>/dev/null | while IFS= read -r _l; do
_t=$(readlink "$_l" 2>/dev/null) || continue
case "$_t" in
/root/*) ln -snf "$HOME${_t#/root}" "$_l" 2>/dev/null ;;
esac
done
```

Wired into the non-root branch of `extractCmd` in `shared/agent-tarball.ts`. Only runs when the transform extract succeeds; the sudo fallback (which extracts as root and doesn't need rewriting) is unchanged.

Why this is the right fix vs. alternatives

• GNU tar `--transform "flags=rsh;..."` would rewrite symlink targets too, but only handles `^root/` (relative form) and would need a second rule for absolute `/root/`. Also relies on a relatively obscure GNU tar feature; the find walk is more portable.
• Build tarballs as a non-root user would require duplicating the install pipeline. Out of scope.
• Switch to relative symlinks at capture time would require knowing the layout each agent's installer produces. Brittle per-agent.

Test plan

• `bunx @biomejs/biome check src/` — 0 errors
• `bunx tsc --noEmit -p .` — 0 production errors
• `bun test orchestrate.test.ts` — 41 pass
• Smoke test: simulate post-transform extract layout in a temp dir with a dangling `/root/.claude/local/claude` symlink, run the fix loop, verify symlink resolves to `$HOME/.claude/local/claude` and `test -e` passes
• End-to-end: `spawn claude sprite --beta tarball` + `which claude` returns a working path
• End-to-end: `spawn openclaw sprite --beta tarball` + `openclaw --version` (separately, openclaw also has a config-validation issue surfacing in `Unrecognized key: "main"` — that's a different bug, not this PR)

Bumps CLI to 1.0.24.

🤖 Generated with Claude Code

[la14-1]

Review

Diagnosis is exactly right: `tar --transform` rewrites file paths but not symlink targets, so every non-root extract on Sprite etc. has been silently dangling binary symlinks. Repro case in the description (`spawn claude sprite` → `command not found` → 10 retries → exit 127) is the classic signature.

Looks good

• Scoped correctly: runs only in the non-root transform branch. Root-user extract and the sudo fallback are untouched.
• Trailing `true` makes the subshell succeed even if individual `ln -snf` calls fail — without it, the outer `||` would fall through to `sudo tar` and double-extract on clouds that have sudo. Correct and defensive.
• Shell-glob pattern `/root/*` matches `/root/foo` and `/root/x/y` but correctly does not match `/rooty` or a bare `/root` — target rewriting is narrowly scoped.
• Uses `_l` / `_t` underscore-prefixed locals — won't clash with anything in the user's shell env.
• `${_t#/root}` parameter expansion strips just the prefix, preserving the rest of the target path. Matches `$HOME${_t#/root}`.

Minor

• Edge case: target is exactly `/root` (no trailing slash) — the `/root/` glob won't match. Unlikely in practice (agents always install under subdirs) but if it ever happens, the symlink stays dangling. Extending the case to `/root|/root/` would be a one-char fix.
• `find "$HOME" -type l` walks the whole home. On a freshly-provisioned VM this is bounded by the tarball contents. Real users may have accumulated files, but we're running this inside the agent-install phase right after extract, so it's fine in practice.
• No automated test. The PR mentions a manual smoke test in a temp dir — fair for a shell fragment, but this is the second tarball-extract bug this release (see also fix(packer): repair cursor tarball + hermes interactive install #3367). A unit test that asserts the generated `extractCmd` contains the fix loop + a shelled-out integration test with a crafted tarball would catch future regressions. Not blocking.

Alt-fix considered (and rejected correctly)

You considered `--transform "flags=rsh;..."` — that rewrites symlink targets but only matches the relative form `^root/` after tar's own stripping, not absolute `/root/`. A find-walk is more portable than relying on GNU-tar-specific flag syntax. Right call.

Nice-to-have (follow-up)

• feat(cli): --repo flag clones a template repo and applies spawn.md #3360 / feat(cli): posthog feature flags + fast_provision experiment #3366 both introduced tarball-adjacent codepaths recently. A `verify-extracted-symlinks` step that runs `test -x "$HOME/.local/bin/"` right after `tryTarballInstall` returns true would turn silent-dangling-link bugs into loud failures that trigger the clean-install fallback. Worth filing as a separate issue.

LGTM.

Reviewed by SPA

[la14-1]

Approved. See full review at #3368 (comment).

[AhmedTMM]

Root cause

Tarballs are built on a CI VM running as root, so file layouts contain absolute symlinks like:

```
/root/.local/bin/claude -> /root/.claude/local/claude
```

When extracted on a non-root user (Sprite, scp-style installs without passwordless sudo), tar's `--transform "s|^root/|${HOME#/}/|"` rewrites file PATHS — so the file lands at `$HOME/.local/bin/claude` — but does not rewrite symlink TARGETS. The symlink still points to `/root/.claude/local/claude`, which doesn't exist.

User experience: `tryTarballInstall` returns `true` (the marker file extracts fine), the orchestrator logs "Agent installed from pre-built tarball" and proceeds to launch. Then:

```
/tmp/spawn_T6Gu8f.sh: line 4: claude: command not found
```

10 retries, exit 127, give up. Repro from a real session today on `spawn claude sprite` (no flags — fast_provision experiment had bucketed the user to test).

Fix

Post-extract, walk `$HOME` and rewrite any `/root/*` symlink targets to point under `$HOME`:

```bash
find "$HOME" -type l 2>/dev/null | while IFS= read -r _l; do
_t=$(readlink "$_l" 2>/dev/null) || continue
case "$_t" in
/root/*) ln -snf "$HOME${_t#/root}" "$_l" 2>/dev/null ;;
esac
done
```

Wired into the non-root branch of `extractCmd` in `shared/agent-tarball.ts`. Only runs when the transform extract succeeds; the sudo fallback (which extracts as root and doesn't need rewriting) is unchanged.

Why this is the right fix vs. alternatives

• GNU tar `--transform "flags=rsh;..."` would rewrite symlink targets too, but only handles `^root/` (relative form) and would need a second rule for absolute `/root/`. Also relies on a relatively obscure GNU tar feature; the find walk is more portable.
• Build tarballs as a non-root user would require duplicating the install pipeline. Out of scope.
• Switch to relative symlinks at capture time would require knowing the layout each agent's installer produces. Brittle per-agent.

Test plan

• `bunx @biomejs/biome check src/` — 0 errors
• `bunx tsc --noEmit -p .` — 0 production errors
• `bun test orchestrate.test.ts` — 41 pass
• Smoke test: simulate post-transform extract layout in a temp dir with a dangling `/root/.claude/local/claude` symlink, run the fix loop, verify symlink resolves to `$HOME/.claude/local/claude` and `test -e` passes
• End-to-end: `spawn claude sprite --beta tarball` + `which claude` returns a working path
• End-to-end: `spawn openclaw sprite --beta tarball` + `openclaw --version` (separately, openclaw also has a config-validation issue surfacing in `Unrecognized key: "main"` — that's a different bug, not this PR)

Bumps CLI to 1.0.24.

🤖 Generated with Claude Code

[la14-1]

Review

Diagnosis is exactly right: `tar --transform` rewrites file paths but not symlink targets, so every non-root extract on Sprite etc. has been silently dangling binary symlinks. Repro case in the description (`spawn claude sprite` → `command not found` → 10 retries → exit 127) is the classic signature.

Looks good

• Scoped correctly: runs only in the non-root transform branch. Root-user extract and the sudo fallback are untouched.
• Trailing `true` makes the subshell succeed even if individual `ln -snf` calls fail — without it, the outer `||` would fall through to `sudo tar` and double-extract on clouds that have sudo. Correct and defensive.
• Shell-glob pattern `/root/*` matches `/root/foo` and `/root/x/y` but correctly does not match `/rooty` or a bare `/root` — target rewriting is narrowly scoped.
• Uses `_l` / `_t` underscore-prefixed locals — won't clash with anything in the user's shell env.
• `${_t#/root}` parameter expansion strips just the prefix, preserving the rest of the target path. Matches `$HOME${_t#/root}`.

Minor

• Edge case: target is exactly `/root` (no trailing slash) — the `/root/` glob won't match. Unlikely in practice (agents always install under subdirs) but if it ever happens, the symlink stays dangling. Extending the case to `/root|/root/` would be a one-char fix.
• `find "$HOME" -type l` walks the whole home. On a freshly-provisioned VM this is bounded by the tarball contents. Real users may have accumulated files, but we're running this inside the agent-install phase right after extract, so it's fine in practice.
• No automated test. The PR mentions a manual smoke test in a temp dir — fair for a shell fragment, but this is the second tarball-extract bug this release (see also fix(packer): repair cursor tarball + hermes interactive install #3367). A unit test that asserts the generated `extractCmd` contains the fix loop + a shelled-out integration test with a crafted tarball would catch future regressions. Not blocking.

Alt-fix considered (and rejected correctly)

You considered `--transform "flags=rsh;..."` — that rewrites symlink targets but only matches the relative form `^root/` after tar's own stripping, not absolute `/root/`. A find-walk is more portable than relying on GNU-tar-specific flag syntax. Right call.

Nice-to-have (follow-up)

• feat(cli): --repo flag clones a template repo and applies spawn.md #3360 / feat(cli): posthog feature flags + fast_provision experiment #3366 both introduced tarball-adjacent codepaths recently. A `verify-extracted-symlinks` step that runs `test -x "$HOME/.local/bin/"` right after `tryTarballInstall` returns true would turn silent-dangling-link bugs into loud failures that trigger the clean-install fallback. Worth filing as a separate issue.

LGTM.

Reviewed by SPA

[la14-1]

Approved. See full review at #3368 (comment).

[AhmedTMM]

Root cause

Tarballs are built on a CI VM running as root, so file layouts contain absolute symlinks like:

```
/root/.local/bin/claude -> /root/.claude/local/claude
```

When extracted on a non-root user (Sprite, scp-style installs without passwordless sudo), tar's `--transform "s|^root/|${HOME#/}/|"` rewrites file PATHS — so the file lands at `$HOME/.local/bin/claude` — but does not rewrite symlink TARGETS. The symlink still points to `/root/.claude/local/claude`, which doesn't exist.

User experience: `tryTarballInstall` returns `true` (the marker file extracts fine), the orchestrator logs "Agent installed from pre-built tarball" and proceeds to launch. Then:

```
/tmp/spawn_T6Gu8f.sh: line 4: claude: command not found
```

10 retries, exit 127, give up. Repro from a real session today on `spawn claude sprite` (no flags — fast_provision experiment had bucketed the user to test).

Fix

Post-extract, walk `$HOME` and rewrite any `/root/*` symlink targets to point under `$HOME`:

```bash
find "$HOME" -type l 2>/dev/null | while IFS= read -r _l; do
_t=$(readlink "$_l" 2>/dev/null) || continue
case "$_t" in
/root/*) ln -snf "$HOME${_t#/root}" "$_l" 2>/dev/null ;;
esac
done
```

Wired into the non-root branch of `extractCmd` in `shared/agent-tarball.ts`. Only runs when the transform extract succeeds; the sudo fallback (which extracts as root and doesn't need rewriting) is unchanged.

Why this is the right fix vs. alternatives

• GNU tar `--transform "flags=rsh;..."` would rewrite symlink targets too, but only handles `^root/` (relative form) and would need a second rule for absolute `/root/`. Also relies on a relatively obscure GNU tar feature; the find walk is more portable.
• Build tarballs as a non-root user would require duplicating the install pipeline. Out of scope.
• Switch to relative symlinks at capture time would require knowing the layout each agent's installer produces. Brittle per-agent.

Test plan

• `bunx @biomejs/biome check src/` — 0 errors
• `bunx tsc --noEmit -p .` — 0 production errors
• `bun test orchestrate.test.ts` — 41 pass
• Smoke test: simulate post-transform extract layout in a temp dir with a dangling `/root/.claude/local/claude` symlink, run the fix loop, verify symlink resolves to `$HOME/.claude/local/claude` and `test -e` passes
• End-to-end: `spawn claude sprite --beta tarball` + `which claude` returns a working path
• End-to-end: `spawn openclaw sprite --beta tarball` + `openclaw --version` (separately, openclaw also has a config-validation issue surfacing in `Unrecognized key: "main"` — that's a different bug, not this PR)

Bumps CLI to 1.0.24.

🤖 Generated with Claude Code

[la14-1]

Review

Diagnosis is exactly right: `tar --transform` rewrites file paths but not symlink targets, so every non-root extract on Sprite etc. has been silently dangling binary symlinks. Repro case in the description (`spawn claude sprite` → `command not found` → 10 retries → exit 127) is the classic signature.

Looks good

• Scoped correctly: runs only in the non-root transform branch. Root-user extract and the sudo fallback are untouched.
• Trailing `true` makes the subshell succeed even if individual `ln -snf` calls fail — without it, the outer `||` would fall through to `sudo tar` and double-extract on clouds that have sudo. Correct and defensive.
• Shell-glob pattern `/root/*` matches `/root/foo` and `/root/x/y` but correctly does not match `/rooty` or a bare `/root` — target rewriting is narrowly scoped.
• Uses `_l` / `_t` underscore-prefixed locals — won't clash with anything in the user's shell env.
• `${_t#/root}` parameter expansion strips just the prefix, preserving the rest of the target path. Matches `$HOME${_t#/root}`.

Minor

• Edge case: target is exactly `/root` (no trailing slash) — the `/root/` glob won't match. Unlikely in practice (agents always install under subdirs) but if it ever happens, the symlink stays dangling. Extending the case to `/root|/root/` would be a one-char fix.
• `find "$HOME" -type l` walks the whole home. On a freshly-provisioned VM this is bounded by the tarball contents. Real users may have accumulated files, but we're running this inside the agent-install phase right after extract, so it's fine in practice.
• No automated test. The PR mentions a manual smoke test in a temp dir — fair for a shell fragment, but this is the second tarball-extract bug this release (see also fix(packer): repair cursor tarball + hermes interactive install #3367). A unit test that asserts the generated `extractCmd` contains the fix loop + a shelled-out integration test with a crafted tarball would catch future regressions. Not blocking.

Alt-fix considered (and rejected correctly)

You considered `--transform "flags=rsh;..."` — that rewrites symlink targets but only matches the relative form `^root/` after tar's own stripping, not absolute `/root/`. A find-walk is more portable than relying on GNU-tar-specific flag syntax. Right call.

Nice-to-have (follow-up)

• feat(cli): --repo flag clones a template repo and applies spawn.md #3360 / feat(cli): posthog feature flags + fast_provision experiment #3366 both introduced tarball-adjacent codepaths recently. A `verify-extracted-symlinks` step that runs `test -x "$HOME/.local/bin/"` right after `tryTarballInstall` returns true would turn silent-dangling-link bugs into loud failures that trigger the clean-install fallback. Worth filing as a separate issue.

LGTM.

Reviewed by SPA

[la14-1]

Approved. See full review at #3368 (comment).