[ydflow]

Summary

On Windows, path.join('~/.teamai/team-repo', 'manifest', 'roles.yaml') produces a path starting with ~\. expandHome only recognized ~/ and bare ~, so loadRolesManifest reported an existing manifest as missing. Absolute paths worked. A native ~\.teamai\team-repo in repo.localPath also made teamai roles list fail to find teamai.yaml.

Recognize ~\ on Windows in the shared helper. Keep backslashes literal on POSIX, and retain the existing handling of ~/, bare ~, absolute paths and ~username. Add Windows/POSIX regression coverage and document the supported repository path forms in both guide languages.

This is scoped to home-relative path handling: the current CLI already expands forward-slash ~/ config paths before reading manifests, so those roles list calls were already working.

Type of Change

• Bug fix (non-breaking change that fixes an issue)

Test Plan

Windows x64, Node v24.19.0; upstream baseline fe3b906.

• npm run build
• npm run typecheck
• npm run lint
• Added 4 Windows/POSIX helper regression cases; all pass. The Windows variants failed before the fix, and the existing roles.test.ts home-relative manifest case now passes.
• Focused run: npx vitest run src/__tests__/home-normalize.test.ts src/__tests__/home.test.ts src/__tests__/user-home-resolution.test.ts src/__tests__/roles.test.ts src/__tests__/projects.test.ts src/__tests__/roles-cmd.test.ts --maxWorkers=2 — 114 passed, 4 failed, 2 skipped. The same run on unmodified fe3b906 had 109 passed, 5 failed, 2 skipped. The four remaining failures match upstream: two symlink EPERM cases, a hard-coded / error-path assertion, and a chmod(0o000) unreadability assumption on Windows. They are not weakened or changed by this PR.
• A broader Windows unit run was stopped after more than 20 minutes without a complete result. It is not reported as passing; the completed focused baseline comparison above is the local unit evidence.

Real CLI after building both versions, with an isolated HOME and a local fixture containing frontend in manifest/roles.yaml:

repo.localPath	Upstream teamai roles list	Patched teamai roles list
~/.teamai/team-repo	Lists frontend, exit 0	Lists frontend, exit 0
~\.teamai\team-repo	Team config (teamai.yaml) not found, exit 1	Lists frontend, exit 0
Absolute fixture path	Lists frontend, exit 0	Lists frontend, exit 0

All six CLI runs left the config bytes unchanged. No model or remote provider calls were needed. Other providers/agents and the Linux/macOS runtime matrix are left to CI.

CI result (0a3b2fc)

All six Ubuntu/macOS × Node 20/22/24 lint/typecheck/unit-with-coverage jobs passed, as did Prepare build, Build and Code erosion metrics. The credentialed remote-provider job was skipped for this fork PR.

The fork-safe E2E job failed while setting up workspace-children-913.test.ts, before that suite's CLI assertions: git clone -q --bare <seed-other> <other.git> reported fatal: failed to copy file .../other.git/objects/...: No such file or directory. The run recorded 1256 passed / 54 skipped tests, with one failed suite and 152 passed files. The fixture file is unchanged by this PR, and the new runtime branch is Windows-only whereas this job runs on Linux. The setup failure's root cause is still unconfirmed; this is not an all-green CI result.

A failed-job rerun was requested once, but GitHub refused it with Must have admin rights to Repository. A maintainer is needed to rerun that job. The original failure is retained; no timeout or assertion was changed.

Related Issues

Reproduced directly against upstream main; no matching open fix was found.

[github-actions]

No findings in the specified diff.

The Windows-only ~\ expansion preserves POSIX backslashes and existing path handling; regression tests cover both platforms.

The PR description satisfies the required testing record with representative built, real-CLI baseline/patched runs. It explicitly reports the failed Linux E2E fixture setup and deferred coverage rather than claiming all-green CI.