feat: izba.yml manifest + diff/promote/export workflow

[Lupus]

What

Adds a Kubernetes-style project manifest (izba.yml) plus an izba diff / izba promote / izba export reconciliation workflow, so a project's sandbox configuration (image/build, resources, volumes, ports, egress policy) can live in the repo and be version-controlled — while keeping the in-guest agent unable to silently change its own jail.

Design: docs/superpowers/specs/2026-06-28-izba-manifest-diff-promote-design.md · Plan: docs/superpowers/plans/2026-06-28-izba-manifest-diff-promote.md

Trust model (the spine)

izba.yml lives in the workspace, which is mounted into the guest at /workspace — so the in-guest agent can edit it. It is therefore an untrusted proposal. The managed truth (config.json + policy.yaml under ~/.local/share/izba/sandboxes/<name>/, host-only, outside the guest overlay) is authority. izba promote is the human-gated bridge:

• izba diff records a host-only review token (manifest.review) over the exact manifest and referenced Dockerfile bytes.
• izba promote requires that token to match: no token → fail (run diff first); stale token → fail (TOCTOU guard — manifest changed after review); --force overrides both, loudly.
• manifest.review / manifest.base.yaml are host-only and never enter the overlay, so the guest cannot read or forge a reviewed state.

Surface

• Schema (izba_core::manifest): apiVersion: izba.dev/v1alpha1 / kind: Sandbox / metadata / spec (image xor build recipe, resources, rootDisk, volumes, ports, egress), k8s quantity strings (4Gi), kind-extensible to a future Project. The egress block reuses the existing policy type verbatim.
• izba diff — structural 3-way drift (base/repo/managed), per-field blast-radius class (live / restart / image), ⚠ weakens egress flag, records the review token.
• izba promote — gated apply: live fields (policy/ports/volumes) apply immediately; cpus/mem/image are restart-class (--restart); image changes reset the rw scratch overlay (--reset-scratch, default yes) with a loud expert-only warning when kept; image changes require --restart; confinement posture is replayed from state.json on restart; live RPCs are skipped on a stopped sandbox.
• izba export — write the managed truth back to izba.yml (declarative only — no secrets), for the app-edits-then-commit flow.
• izba create / izba run honor an izba.yml when present (flags still win) and seed the manifest base.
• Tauri app — backend manifest_diff / manifest_export commands + DiffView (drift badge / preview / save-to-repo).

No DAEMON_PROTO_VERSION bump — diff/promote/export are host-side over existing daemon RPCs + host-callable image resolution/build.

Deferred (follow-up)

• In-app Promote button and create-from-manifest wizard + manifest frontend UI (the security-critical promote path ships fully in the CLI).
• Persisting rootDisk size in SandboxConfig (diff currently ignores rw size, documented).
• Build options beyond build-in-VM's current set (build-arg/secret/no-cache/target).

Testing

Built TDD, subagent-driven, with per-task spec+quality review and a final whole-branch review (all findings fixed, incl. duplicate-host egress-weakening detection and the non-restart image-promote scratch-reset safety gap). All six workspace gates + the App gate verified green locally:
cargo test --workspace, clippy --workspace -D warnings, fmt --check, izba-init musl build, x86_64-pc-windows-gnu check + clippy, and app (npm build + src-tauri fmt/clippy/test).

🤖 Generated with Claude Code

Greptile Summary

This PR introduces the izba.yml manifest system — a Kubernetes-style YAML config (apiVersion: izba.dev/v1alpha1, kind: Sandbox) enabling version-controlled sandbox configuration with a TOCTOU-safe diff/promote/export workflow.

• Adds izba diff, izba promote, and izba export CLI subcommands backed by new manifest/ modules (schema, normalize, diff, ops, apply, store, quantity) in izba-core
• Implements a SHA-256 review token written by diff and verified by promote to prevent TOCTOU races; path/name traversal guards (ensure_within, validate_name) protect agent-controlled fields
• Extends SandboxConfig with build: Option<BuildSpec> and rw_size_gb: u64 (both serde(default)) for backward-compatible persistence, and makes reset_rw_scratch atomic via a tmp-file + fs::rename pattern

Confidence Score: 5/5

Safe to merge; no blocking issues found beyond minor P2 observations

All previously-raised issues are addressed. The three new observations are P2 quality/robustness notes (double manifest read, non-total sort order, noisy egress emit) with no correctness impact on the happy path. Security guards (ensure_within, validate_name, review token) are correctly implemented.

crates/izba-core/src/manifest/diff.rs and crates/izba-cli/src/commands/diff.rs for the double load_repo_manifest call

Important Files Changed

Filename	Overview
crates/izba-core/src/manifest/ops.rs	Core diff/export/apply helpers; ensure_within and validate_name guards correctly placed; managed_normalized rw_size_gb fallback chain is sound
crates/izba-core/src/manifest/apply.rs	plan/write_managed/write_policy logic is correct; ImageSource::Build branch now persists cfg.build, eliminating false drift
crates/izba-core/src/manifest/diff.rs	egress_weakens uses per-(host,port) BTreeMap correctly; classify 3-way logic is sound; minor TOCTOU window from double manifest read in diff command
crates/izba-core/src/manifest/normalize.rs	from_manifest/from_managed correctly reconstruct Normalized; sort_canonical sort key for same-host multi-entry allow lists is not a stable total order; to_manifest always emits egress even when empty
crates/izba-core/src/manifest/store.rs	review_token SHA-256 with 0x1f separator is correct; clear_review is idempotent; non-NotFound I/O errors propagated
crates/izba-core/src/manifest/quantity.rs	parse_bytes/parse_mib/parse_gib accept only binary-SI suffixes; format(0) returns bare 0 but managed_normalized guards against it
crates/izba-core/src/manifest/schema.rs	deny_unknown_fields on all structs; image XOR build validated in load_str; apiVersion/kind checked
crates/izba-cli/src/commands/diff.rs	Writes review token after compute_diff; double load_repo_manifest call introduces minor TOCTOU window on name resolution
crates/izba-cli/src/commands/promote.rs	gate() enforces review token; is_running guard prevents spurious Stop; build_opts_from uses ensure_within; recovery hint on Start failure is helpful
crates/izba-cli/src/commands/export.rs	exists() guard before load_repo_manifest correctly propagates parse errors
crates/izba-cli/src/commands/mod.rs	merge_manifest_into_opts uses load_manifest_yaml (not load_repo_manifest); sub-GiB volume MiB format fix is correct
crates/izba-core/src/sandbox.rs	reset_rw_scratch atomic via tmp+rename with cleanup on error; create() initialises build:None and rw_size_gb
crates/izba-core/src/state.rs	SandboxConfig gains build and rw_size_gb with serde(default) for backward compatibility

Sequence Diagram

%%{init: {'theme': 'neutral'}}%%
sequenceDiagram
    participant Agent
    participant CLI as izba CLI
    participant Store
    participant Core as izba-core
    participant Daemon

    Agent->>CLI: izba diff [--name]
    CLI->>Core: load_repo_manifest(dir)
    Core-->>CLI: (manifest, name)
    CLI->>Core: compute_diff(paths, dir, name)
    Core->>Core: load_repo_manifest (2nd read)
    Core->>Core: managed_normalized
    Core->>Core: diff / classify
    Core-->>CLI: (DriftState, deltas, token)
    CLI->>Store: write_review(sandbox_dir, token)
    CLI-->>Agent: drift report

    Agent->>CLI: izba promote [--force]
    CLI->>Store: read_review(sandbox_dir)
    CLI->>Core: compute_diff (recompute token)
    Core-->>CLI: current_token
    CLI->>CLI: gate(stored, current, force)
    alt token matches
        CLI->>Core: plan(current, target)
        CLI->>Daemon: live RPCs (CPU/mem/ports/egress)
        CLI->>Core: write_managed
        CLI->>Core: write_policy
        CLI->>Daemon: ReloadPolicy
        opt image or restart required
            CLI->>Daemon: Stop
            CLI->>Core: reset_rw_scratch (atomic)
            CLI->>Daemon: Start
        end
        CLI->>Store: clear_review
    else token mismatch
        CLI-->>Agent: error: manifest changed since diff
    end

    Agent->>CLI: izba export [dir]
    CLI->>Core: export(paths, name, dir)
    Core->>Core: managed_normalized → to_manifest
    Core-->>CLI: Manifest YAML
    CLI-->>Agent: writes izba.yml

Loading

%%{init: {'theme': 'base', 'themeVariables': {"darkMode": true, "background": "#0d1117", "primaryColor": "#21262d", "primaryTextColor": "#e6edf3", "primaryBorderColor": "#8b949e", "lineColor": "#8b949e", "textColor": "#e6edf3", "edgeLabelBackground": "#161b22", "actorBkg": "#21262d", "actorBorder": "#8b949e", "actorTextColor": "#e6edf3", "actorLineColor": "#8b949e", "signalColor": "#8b949e", "signalTextColor": "#e6edf3", "noteBkgColor": "#373320", "noteBorderColor": "#d4a72c", "noteTextColor": "#f0e6c0", "labelBoxBkgColor": "#21262d", "labelBoxBorderColor": "#8b949e", "labelTextColor": "#e6edf3", "loopTextColor": "#e6edf3", "activationBkgColor": "#30363d", "activationBorderColor": "#8b949e"}}}%%
sequenceDiagram
    participant Agent
    participant CLI as izba CLI
    participant Store
    participant Core as izba-core
    participant Daemon

    Agent->>CLI: izba diff [--name]
    CLI->>Core: load_repo_manifest(dir)
    Core-->>CLI: (manifest, name)
    CLI->>Core: compute_diff(paths, dir, name)
    Core->>Core: load_repo_manifest (2nd read)
    Core->>Core: managed_normalized
    Core->>Core: diff / classify
    Core-->>CLI: (DriftState, deltas, token)
    CLI->>Store: write_review(sandbox_dir, token)
    CLI-->>Agent: drift report

    Agent->>CLI: izba promote [--force]
    CLI->>Store: read_review(sandbox_dir)
    CLI->>Core: compute_diff (recompute token)
    Core-->>CLI: current_token
    CLI->>CLI: gate(stored, current, force)
    alt token matches
        CLI->>Core: plan(current, target)
        CLI->>Daemon: live RPCs (CPU/mem/ports/egress)
        CLI->>Core: write_managed
        CLI->>Core: write_policy
        CLI->>Daemon: ReloadPolicy
        opt image or restart required
            CLI->>Daemon: Stop
            CLI->>Core: reset_rw_scratch (atomic)
            CLI->>Daemon: Start
        end
        CLI->>Store: clear_review
    else token mismatch
        CLI-->>Agent: error: manifest changed since diff
    end

    Agent->>CLI: izba export [dir]
    CLI->>Core: export(paths, name, dir)
    Core->>Core: managed_normalized → to_manifest
    Core-->>CLI: Manifest YAML
    CLI-->>Agent: writes izba.yml

Loading

_{Reviews (20): Last reviewed commit: "ci(mutants): shard the linux incremental..." | Re-trigger Greptile}

Context used:

• Context used - CLAUDE.md (source)

[Lupus]

@greptile review

[Lupus]

@greptile review

[Lupus]

@greptile review

[Lupus]

@greptile review

[Lupus]

@greptile review

[sonarqubecloud]

Quality Gate passed

Issues
3 New issues
0 Accepted issues

Measures
0 Security Hotspots
88.8% Coverage on New Code
0.6% Duplication on New Code

See analysis details on SonarQube Cloud