Add guarded Agent Machine and Office execution

Adds explicit --execute --policy-ok guarded local execution for Agent Machine directory materialization and Office text generation/conversion evidence flows.

Author: mdheller

README.md

@@ -19,7 +19,7 @@ It should contain:
 - guardrail/eval/evidence helpers;
 - agent sandbox/run helpers;
 - Agent Machine local mount and secure host-interface helpers;
-- Office Plane dry-run, inspection, and evidence helpers;
+- Office Plane dry-run, guarded execution, inspection, and evidence helpers;
 - fingerprint and proof bundle tools;
 - local-to-mesh registration helpers;
 - release/operator install scripts.
@@ -38,7 +38,7 @@ It should not contain:
 
 ## sourceosctl CLI
 
-`sourceosctl` is the read-only/dry-run CLI surface for SourceOS developer and AI operator workflows.
+`sourceosctl` is the guarded CLI surface for SourceOS developer and AI operator workflows. Commands are read-only or dry-run by default. Narrow local mutations require explicit `--execute --policy-ok` and emit evidence.
 
 ### Usage
 
@@ -62,12 +62,15 @@ sourceosctl [--version] <command> [<subcommand>] [options]
 | `sourceosctl agents sandbox plan --dry-run` | Print agent sandbox plan (dry-run only) |
 | `sourceosctl agent-machine mounts plan` | Render Agent Machine local mount plan for dev/docs/downloads roots (dry-run) |
 | `sourceosctl agent-machine mounts init --dry-run` | Render mount initialization plan; no directories or mounts are created |
+| `sourceosctl agent-machine mounts init --execute --policy-ok` | Create only scoped local output/download directories and emit AgentMachineMountEvidence |
 | `sourceosctl agent-machine mounts inspect [--include-downloads]` | Inspect default/local Agent Machine mount posture |
 | `sourceosctl agent-machine mounts evidence inspect <path>` | Inspect Agent Machine mount evidence JSON (read-only) |
 | `sourceosctl office doctor` | Inspect local Office Plane backend availability, including LibreOffice detection |
 | `sourceosctl office plan` | Render an OfficeArtifact-compatible workroom artifact plan |
 | `sourceosctl office generate --dry-run` | Render an Office generation plan without writing files |
+| `sourceosctl office generate --execute --policy-ok --format md|txt|json` | Write a guarded text/Markdown/JSON artifact and emit OfficeArtifactEvidence |
 | `sourceosctl office convert <path> --to <format> --dry-run` | Render a LibreOffice-style conversion plan without writing files |
+| `sourceosctl office convert <path> --to <format> --execute --policy-ok` | Run guarded local LibreOffice conversion and emit OfficeArtifactEvidence |
 | `sourceosctl office inspect <path>` | Inspect a local office artifact file and hash it |
 | `sourceosctl office evidence inspect <path>` | Inspect Office Plane evidence JSON (read-only) |
 
@@ -87,16 +90,19 @@ python3 bin/sourceosctl ai labs list
 python3 bin/sourceosctl agents sandbox plan --dry-run
 python3 bin/sourceosctl agent-machine mounts plan
 python3 bin/sourceosctl agent-machine mounts init --dry-run
+python3 bin/sourceosctl agent-machine mounts init --execute --policy-ok --evidence-out ./mount-evidence.json
 python3 bin/sourceosctl agent-machine mounts inspect --include-downloads
 python3 bin/sourceosctl office doctor
 python3 bin/sourceosctl office plan --artifact-type slide-deck --format pptx --title "Demo Deck"
 python3 bin/sourceosctl office generate --dry-run --artifact-type document --format docx --title "Demo Report"
+python3 bin/sourceosctl office generate --execute --policy-ok --artifact-type document --format md --title "Demo Report" --evidence-out ./office-evidence.json
 python3 bin/sourceosctl office convert ./example.docx --to pdf --dry-run
+python3 bin/sourceosctl office convert ./example.docx --to pdf --execute --policy-ok --evidence-out ./office-convert-evidence.json
 ```
 
 ### Agent Machine local mount defaults
 
-The first Agent Machine mount slice is contract-first and dry-run only. It aligns with the SourceOS contracts in `SourceOS-Linux/sourceos-spec`:
+The first Agent Machine mount slice aligns with the SourceOS contracts in `SourceOS-Linux/sourceos-spec`:
 
 - `AgentMachineLocalDataPlane`
 - `AgentMachineMountPolicy`
@@ -107,16 +113,18 @@ Default host roots:
 | Purpose | Host path | Agent path | Posture |
 | --- | --- | --- | --- |
 | Code / repositories | `~/dev` | `/workspace/dev` | read/write; explicit workspace root |
-| Generated documents / reports | `~/Documents/SourceOS/agent-output` | `/workspace/output` | read/write; created only by future explicit mutation |
+| Generated documents / reports | `~/Documents/SourceOS/agent-output` | `/workspace/output` | read/write; created only by explicit guarded materialization |
 | Browser downloads | `~/Downloads/SourceOS/agent-downloads` | `/workspace/downloads` | browser read/write; agent read-only |
 
 The CLI does **not** mount `$HOME` wholesale and does **not** expose `.ssh`, `.gnupg`, browser profiles, keychains, cloud credential directories, token stores, or password stores by default.
 
+Guarded materialization creates only the declared `createIfMissing` folders. It does not create Podman machines, Podman bind mounts, containers, or background services.
+
 TopoLVM is treated as a Linux cluster-local backend profile for the same logical mount contract. It is not used for macOS/APFS local mode and it is not represented as cross-node shared storage.
 
 ### Office Plane local defaults
 
-The first Office Plane slice is dry-run/read-only. It aligns with `SocioProphet/prophet-workspace`:
+The Office Plane aligns with `SocioProphet/prophet-workspace`:
 
 - `ProfessionalWorkroom`
 - `OfficeArtifact`
@@ -137,11 +145,17 @@ Backends are modeled as an abstraction:
 - Microsoft Graph / Office 365 and Google Workspace: compatibility adapters, not core authority.
 - SourceOS-native: future native document surfaces.
 
-The CLI does not create, convert, or modify files yet. It renders plans and inspects artifacts/evidence. Email sending and external publishing remain policy-gated side effects and are not enabled here.
+Guarded Office execution is intentionally narrow:
+
+- `office generate --execute --policy-ok` currently writes only `txt`, `md`, or `json` artifacts.
+- Office binary generation (`docx`, `xlsx`, `pptx`, `odt`, `ods`, `odp`) remains disabled until template/render backends are hardened.
+- `office convert --execute --policy-ok` uses local LibreOffice/`soffice` when available.
+- All guarded Office execution emits or writes `OfficeArtifactEvidence`.
+- Email sending, external publishing, and calendar modification remain policy-gated side effects and are not enabled here.
 
 ### Design constraints
 
-All commands in the current surface are **read-only or dry-run**. No mutating command is implemented. Commands that would mutate host state are explicitly rejected at runtime.
+All mutating commands require `--execute --policy-ok`. Commands that would mutate host state without both flags are rejected at runtime.
 
 ## First milestone
 

sourceosctl/cli.py

@@ -163,7 +163,9 @@ def add_mount_common(p):
     add_mount_common(mounts_plan_p)
     mounts_plan_p.set_defaults(func=agent_machine.mounts_plan)
 
-    mounts_init_p = mounts_sub.add_parser("init", help="Render mount initialization plan (dry-run only)")
+    mounts_init_p = mounts_sub.add_parser(
+        "init", help="Render or execute guarded local directory materialization"
+    )
     add_mount_common(mounts_init_p)
     mounts_init_p.add_argument(
         "--dry-run",
@@ -172,6 +174,23 @@ def add_mount_common(p):
         dest="dry_run",
         help="Print plan without creating directories or mounts (default: True)",
     )
+    mounts_init_p.add_argument(
+        "--execute",
+        action="store_true",
+        default=False,
+        help="Create only explicitly-scoped output/download directories; does not create Podman mounts",
+    )
+    mounts_init_p.add_argument(
+        "--policy-ok",
+        action="store_true",
+        default=False,
+        help="Confirm Policy Fabric/operator approval for guarded local materialization",
+    )
+    mounts_init_p.add_argument(
+        "--evidence-out",
+        default=None,
+        help="Optional path to write AgentMachineMountEvidence JSON",
+    )
     mounts_init_p.set_defaults(func=agent_machine.mounts_init)
 
     mounts_inspect_p = mounts_sub.add_parser("inspect", help="Inspect default/local mount posture")
@@ -236,7 +255,9 @@ def add_office_common(p):
     add_office_common(office_plan_p)
     office_plan_p.set_defaults(func=office.plan)
 
-    office_generate_p = office_sub.add_parser("generate", help="Render Office generation plan (dry-run only)")
+    office_generate_p = office_sub.add_parser(
+        "generate", help="Render or execute guarded Office text/Markdown/JSON generation"
+    )
     add_office_common(office_generate_p)
     office_generate_p.add_argument("--template", default=None, help="Optional template reference")
     office_generate_p.add_argument("--prompt-ref", default=None, help="Optional prompt/context reference")
@@ -248,9 +269,28 @@ def add_office_common(p):
         dest="dry_run",
         help="Print generation plan without writing files (default: True)",
     )
+    office_generate_p.add_argument(
+        "--execute",
+        action="store_true",
+        default=False,
+        help="Write txt/md/json artifacts only; Office binary generation remains disabled",
+    )
+    office_generate_p.add_argument(
+        "--policy-ok",
+        action="store_true",
+        default=False,
+        help="Confirm Policy Fabric/operator approval for guarded Office generation",
+    )
+    office_generate_p.add_argument(
+        "--evidence-out",
+        default=None,
+        help="Optional path to write OfficeArtifactEvidence JSON",
+    )
     office_generate_p.set_defaults(func=office.generate)
 
-    office_convert_p = office_sub.add_parser("convert", help="Render Office conversion plan (dry-run only)")
+    office_convert_p = office_sub.add_parser(
+        "convert", help="Render or execute guarded LibreOffice conversion"
+    )
     office_convert_p.add_argument("input", help="Input Office artifact path")
     office_convert_p.add_argument("--to", required=True, help="Target format, e.g. pdf, docx, pptx")
     add_office_common(office_convert_p)
@@ -261,6 +301,23 @@ def add_office_common(p):
         dest="dry_run",
         help="Print conversion plan without writing files (default: True)",
     )
+    office_convert_p.add_argument(
+        "--execute",
+        action="store_true",
+        default=False,
+        help="Run LibreOffice conversion under guarded local execution",
+    )
+    office_convert_p.add_argument(
+        "--policy-ok",
+        action="store_true",
+        default=False,
+        help="Confirm Policy Fabric/operator approval for guarded Office conversion",
+    )
+    office_convert_p.add_argument(
+        "--evidence-out",
+        default=None,
+        help="Optional path to write OfficeArtifactEvidence JSON",
+    )
     office_convert_p.set_defaults(func=office.convert)
 
     office_inspect_p = office_sub.add_parser("inspect", help="Inspect an Office artifact file")