feat: add project-local cmux Artifacts

AU
1mo ago
+29758-1145

Summary

Implements the project-local cmux Artifacts and Notes filesystem described in #8587:

  • stores ordinary user-organizable files under session roots at <project>/.cmux/<agent-session>/{artifacts,notes}
  • keeps _session.json and _workspace.json markers beside the two content folders so renamed/moved session folders are rediscovered without a path index
  • keeps hidden provenance and import staging under .cmux/.metadata/
  • reuses the shared chat artifact pipeline for selective automatic capture, content dedupe, bounded scanning/search, provenance, Git privacy checks, and manual “Save to cmux Artifacts” actions
  • adds socketless cmux artifact list|path|open|add|search and cmux note list|path|read|write|append|search|open|rm
  • adds a beta-gated Artifacts & Notes right-sidebar tab backed by a live filesystem watcher, fuzzy/content search, previews, drag-out, Finder reveal, copy path, and .cmux/... copy-reference actions
  • adds the cmux-project-files repo skill so agents use the CLI to read/write the filesystem without guessing session folder names

Architecture

<project>/.cmux/
  <agent-session>/
    _session.json
    _workspace.json
    artifacts/
    notes/
  .metadata/
    provenance/
    imports/

The live filesystem is authoritative. LocalArtifactRepository owns storage and scanning; capture policy/provenance remains separate; CLI and app entrypoints share the repository; the sidebar projects immutable row snapshots below its lazy-list boundary. Content and session folders can be reorganized as ordinary files, while marker lookup reconnects later writes to a moved session.

Git’s per-checkout exclude receives targeted patterns for session artifacts/, notes/, marker files, and .metadata/; project configuration such as .cmux/artifacts.json remains independently trackable.

Testing

  • arch -arm64 swift test --quiet — CmuxArtifacts: 105 tests
  • arch -arm64 swift test --quiet — CmuxAgentChat: 375 tests
  • arch -arm64 swift test --quiet — CmuxAgentChatUI: 108 tests
  • arch -arm64 swift test --quiet — CmuxSettingsUI: 115 tests
  • project normalization, workspace package grouping, Package.resolved policy, targeted app-test wiring, Swift parse, JSON/catalog validation, skill validation, and git diff --check
  • localization audit: every changed CLI/sidebar/settings key has English and Japanese values
  • all newly added Swift files are below 500 lines; no budget TSV was changed

Per task constraints, no app build, xcodebuild, XCUITest, reload, launch, or local UI recording was run.

Demo Video

Not recorded because this task explicitly disallows building or launching the app locally.

Review Trigger

Ready for automated and maintainer review at 940bed384e.

Checklist

  • Session-rooted .cmux filesystem with sibling Artifacts and Notes
  • Automatic and manual artifact capture with bounded policy and provenance
  • Artifact and Note CLI behavior coverage
  • Live beta-gated sidebar tree, search, preview, drag, reveal, and references
  • English and Japanese localization audit
  • Agent skill scaffolded and validated
  • Current origin/main merged with zero local conflicts

Refs #8587

[!NOTE]
Medium Risk
Touches local filesystem writes, artifact read authorization, and transcript provenance; changes are largely additive with fail-closed checks but affect security-sensitive path handling.

Overview
Adds socketless CLI access to project-local Artifacts and Notes under <project>/.cmux via new cmux artifact and cmux note commands (list/path/read/write/search/open/add/rm), wired through shared LocalArtifactRepository helpers for project discovery, agent-session identity from environment, and JSON or human output.

Exposes an artifacts right-sidebar mode in CLI parsing/help alongside existing sidebar controls, and documents the workflow in a new cmux-project-files skill entry.

Hardens the chat artifact filesystem layer: ArtifactByteReader moves to low-level Darwin opens with canonical-path and device/inode pinning, bounded directory listing (including isIncomplete), and safer thumbnails; panel/terminal authorization stores retain identities for reads. Transcript parsing now tracks capture authorization separately (successful apply_patch/Bash redirection mutations only), with bounded tool-path extraction and new shell mutation detection.

CI: Depot unit tests install Node 20 and forward TEST_RUNNER_PATH so XCTest hosts can run JavaScript helpers.

Reviewed by Cursor Bugbot for commit 6c4bbbce07ebaf48ae10b8caa1f1bb318ad04b88. Bugbot is set up for automated code reviews on this repo. Configure here.