@mriekki/project-forge 4.24.1 → 4.25.0

package/assets/components.json

@@ -1,7 +1,7 @@
 {
   "schemaVersion": 2,
   "package": "@mriekki/project-forge",
-  "version": "4.24.1",
+  "version": "4.25.0",
   "defaultProfile": "greenfield-project",
   "profiles": {
     "greenfield-project": {
@@ -13,15 +13,15 @@
   },
   "components": {
     "core": {
-      "revision": "59f5657bbb6f1edc45d1e8619ab1d0875b7907e0",
-      "version": "4.2.1",
+      "revision": "5d7c1285793f502d58ad4b6f8f2e51c77453073b",
+      "version": "4.3.0",
       "distribution": "greenfield-workspace",
       "descriptor": "assets/core/distribution.json",
       "sourceRoot": "assets/generated/core",
       "canonicalDescriptor": "distributions/greenfield-workspace.json"
     },
     "deployment": {
-      "revision": "3b31a8690720aa1eb8f5af27ddac5e0e6d3779ba",
+      "revision": "97dfcd7152619a434672da5045c0528f41984ced",
       "distribution": "greenfield-project",
       "descriptor": "assets/deployment/distribution.json",
       "sourceRoot": "assets/generated/deployment",

package/assets/deployment/distribution.json

@@ -7,6 +7,7 @@
     {"source": "src/project_forge_deployment/__init__.py", "destination": "tools/project-forge-deployment/project_forge_deployment/__init__.py"},
     {"source": "src/project_forge_deployment/__main__.py", "destination": "tools/project-forge-deployment/project_forge_deployment/__main__.py"},
     {"source": "src/project_forge_deployment/access_cli.py", "destination": "tools/project-forge-deployment/project_forge_deployment/access_cli.py"},
+    {"source": "src/project_forge_deployment/agent_session.py", "destination": "tools/project-forge-deployment/project_forge_deployment/agent_session.py"},
     {"source": "src/project_forge_deployment/access_diagnosis.py", "destination": "tools/project-forge-deployment/project_forge_deployment/access_diagnosis.py"},
     {"source": "src/project_forge_deployment/app_cli.py", "destination": "tools/project-forge-deployment/project_forge_deployment/app_cli.py"},
     {"source": "src/project_forge_deployment/app_deployment.py", "destination": "tools/project-forge-deployment/project_forge_deployment/app_deployment.py"},

package/assets/generated/ASSEMBLY.json

@@ -1,11 +1,11 @@
 {
   "schemaVersion": 2,
   "package": "@mriekki/project-forge",
-  "version": "4.24.1",
+  "version": "4.25.0",
   "components": {
     "core": {
-      "revision": "59f5657bbb6f1edc45d1e8619ab1d0875b7907e0",
-      "version": "4.2.1",
+      "revision": "5d7c1285793f502d58ad4b6f8f2e51c77453073b",
+      "version": "4.3.0",
       "distribution": "greenfield-workspace",
       "files": [
         {
@@ -56,7 +56,7 @@
         {
           "source": "core/skills/setup/SKILL.md",
           "destination": ".github/skills/setup/SKILL.md",
-          "sha256": "8f92aed1684a3dfd2ecffeb584b5da4daa9c7d7d7ab7ca7f01c8c6a4c82eaa1d"
+          "sha256": "fb1f752655c79d7ac68f3424adba2663492a8e9dd0b8d268cabb6dd28880b6fc"
         },
         {
           "source": "core/skills/build/SKILL.md",
@@ -91,7 +91,7 @@
         {
           "source": "core/skills/deliver/SKILL.md",
           "destination": ".github/skills/deliver/SKILL.md",
-          "sha256": "6a3886493e9b59725ff53652972c1830478176a8c8da648448401d9051820db4"
+          "sha256": "f7d4c611358bec5b348df994515d1253b59c72707b3a8f28e846174468c590c2"
         },
         {
           "source": "core/skills/work-item-status/SKILL.md",
@@ -126,12 +126,12 @@
         {
           "source": "core/skills/deployment-readiness/SKILL.md",
           "destination": ".github/skills/deployment-readiness/SKILL.md",
-          "sha256": "30202702cc368c872e62ce731e8ffe84a796aae243b287e3e670c8c8e1cd6531"
+          "sha256": "170e90e1d21050fb1134230f539c41a1ca62193c3d695fda5edee4147d56e929"
         },
         {
           "source": "core/skills/deploy/SKILL.md",
           "destination": ".github/skills/deploy/SKILL.md",
-          "sha256": "f5d40e549ca958cb51606ced7ca482651d9a436327b6070a9a94171f22401700"
+          "sha256": "82c05ae910f65efd170ca6d055cce9e6e5035628eba45bcfc8552a2b1619cce2"
         },
         {
           "source": "core/skills/tear-down/SKILL.md",
@@ -196,7 +196,7 @@
         {
           "source": "core/process/INTERACTIVE_SESSION_GUIDE.md",
           "destination": "docs/process/INTERACTIVE_SESSION_GUIDE.md",
-          "sha256": "f7573b9926878da3db4353db7297b66c9d907844142ae6486c7fd7580f187e3b"
+          "sha256": "71e25cd0603eecac2be67a696386fddf718c6da26e10c0ade74429ff68a3ac30"
         },
         {
           "source": "core/process/COACHING_GUIDE.md",
@@ -386,7 +386,7 @@
       ]
     },
     "deployment": {
-      "revision": "3b31a8690720aa1eb8f5af27ddac5e0e6d3779ba",
+      "revision": "97dfcd7152619a434672da5045c0528f41984ced",
       "distribution": "greenfield-project",
       "files": [
         {
@@ -409,6 +409,11 @@
           "destination": "tools/project-forge-deployment/project_forge_deployment/access_cli.py",
           "sha256": "007d01ae0c4e28e64f75fb96f9e8e7b99db5c4c8129698a78923baeac2f51953"
         },
+        {
+          "source": "src/project_forge_deployment/agent_session.py",
+          "destination": "tools/project-forge-deployment/project_forge_deployment/agent_session.py",
+          "sha256": "c1bc83cc9a4daa50e86fdfe54cc5902ae5052fe1ad8c193082d0b1966cf8a1d0"
+        },
         {
           "source": "src/project_forge_deployment/access_diagnosis.py",
           "destination": "tools/project-forge-deployment/project_forge_deployment/access_diagnosis.py",
@@ -477,7 +482,7 @@
         {
           "source": "src/project_forge_deployment/cli.py",
           "destination": "tools/project-forge-deployment/project_forge_deployment/cli.py",
-          "sha256": "3c3e7d4fadeccc1b8a7691c1a213250790fb728400914894c0d4e70a1ec91cc7"
+          "sha256": "6b4bb3a23b3df8387f13f544ce02e1d2bee863777de4965044435769c24ab98b"
         },
         {
           "source": "src/project_forge_deployment/doctor.py",

package/assets/generated/core/core/process/INTERACTIVE_SESSION_GUIDE.md

@@ -104,7 +104,7 @@ When the host has no structured question UI, use a concise textual fallback. A n
 
 When an authorized action must run in the developer's own terminal because it requires an interactive prompt, secure local input, or another terminal-owned interaction, treat the command handoff as continuation of the workflow rather than as a generic blocker.
 
-- If the action has its own bounded authorization, collect that authorization first through the host-native structured question control when available. Once the exact action is authorized, do not ask for the same permission again merely because execution moves to the terminal.
+- If the action has its own bounded authorization, collect that authorization first through the host-native structured question control when available. Once the exact action is authorized, do not ask for the same permission again merely because execution moves to the terminal. When the installed deterministic CLI exposes a scoped `--yes` option, prefer it **only after** the matching exact plan/stage has been approved through the native Chat gate, avoiding duplicate typed confirmation phrases. Do not use `--yes` as a standing default, bypass a changed plan, or suppress independent destructive/trust/credential authorizations. SSH passphrase entry remains interactive and never belongs in Chat.
 - Immediately after authorization, provide the exact command in a **standalone fenced code block**. State the working directory when it is not already unambiguous. Do not bury the command inside explanatory prose.
 - Briefly describe the local prompt the developer should expect and which sensitive values must be entered **only in the terminal**. Never ask for a passphrase, password, token, private key, or other secret through chat, and never place such a secret in the command arguments merely to avoid an interactive prompt.
 - State what observable result or concise evidence the developer should report back so the workflow can verify the action and continue. Prefer deterministic verification after the local step instead of asking for secret-bearing terminal transcripts.

package/assets/generated/core/core/skills/deliver/SKILL.md

@@ -21,7 +21,7 @@ Existing repository conventions outrank Project Forge defaults. Preserve branch
 
 ## 1. Authorization model
 
-Because `/deliver` is manually invoked, invoking it is one bounded authorization for the routine delivery mechanics of the already-reviewed/accepted work item:
+Because `/deliver` is manually invoked, invoking it is one bounded authorization for the routine delivery mechanics of the already-reviewed/accepted work item. Keep a delivery started in VS Code Copilot Chat in that interface when host tools can run the deterministic repository commands; a separate Copilot CLI session is not required for automation:
 
 ```text
 establish/recover the short-lived work branch when needed

package/assets/generated/core/core/skills/deploy/SKILL.md

@@ -224,13 +224,15 @@ Resolve the exact phrase from the installed tool/version. For a staged rollout,
 
 Authorization applies only to the exact environment, resolved classification, placement/target/provider, artifact, reviewed plan/stage, current isolation evidence and route evidence, and evidence shown. Material changes require renewed review/authorization.
 
+**Avoid duplicate terminal approval:** when the Builder has explicitly approved this exact current stage in VS Code Copilot Chat, the assistant may pass the installed Deployment Kit's supported `--yes` flag for **that stage only** instead of making the Builder type the displayed phrase again in Bash/PowerShell. `--yes` is an execution flag, not approval evidence; never use it because the human previously approved a different plan, artifact, target, route, session, or stage. If the installed command lacks the flag, preserve its normal gate. Destructive resets/restores and SSH trust/credential changes are independent consequences and are not authorized by a deployment approval.
+
 A runtime authorization never authorizes the route stage. A route authorization never retroactively authorizes a changed runtime artifact. If the rollout contains both stages, preserve the separate gates even though the Builder reviewed one coherent outcome.
 
 ## 9. Preview and execute only the approved contract
 
 Before mutation, show concise non-secret evidence such as exact environment, purpose, placement, target/provider when applicable, proof freshness, immutable application artifact, persistence/migration, exposure/route, application isolation state/fingerprint when exposed, shared failure-domain note when relevant, planned stages, endpoint state at each stage, and the exact required authorization phrase for the next consequence only.
 
-After authorization, invoke only the repository-provided deterministic launcher. Never redirect to another environment/host/provider, weaken trust/exposure, force through lock contention, or invent recovery writes.
+After authorization, invoke only the repository-provided deterministic launcher. For remote SSH placement, prefer the installed Deployment Kit's `target agent-session <target> -- <normal Deployment Kit command>` wrapper when supported; it reuses local SSH authentication across WSL/Linux, macOS, and native Windows VS Code sessions without copying long socket paths. For a Project-owned, repository-reviewed deployment script, use `target agent-run <target> -- <explicit local executable and argv>` when installed; it does not execute a shell, add `--yes`, or replace the script's approvals. Do not switch the workflow from VS Code Copilot Chat to Copilot CLI merely for terminal automation. A key passphrase, when required, stays in the developer-owned terminal and never in Chat. The session wrapper does not provide remote authorization or replace current plan/host checks. Never redirect to another environment/host/provider, weaken trust/exposure, force through lock contention, or invent recovery writes.
 
 The deterministic launcher must revalidate current isolation immediately before real application mutation when the installed contract provides that capability. If current isolation changed or became blocked after review, stop and create/review a fresh plan rather than continuing under the old authorization.
 

package/assets/generated/core/core/skills/deployment-readiness/SKILL.md

@@ -198,7 +198,9 @@ The current address is connectivity information, not trusted identity. Preserve
 
 Before asking questions, inspect existing non-secret profile/target evidence. Classify the workstation's target setup as `CONFIGURED`, `PARTIAL`, or `NOT CONFIGURED` and ask only for the smallest missing fact.
 
-Only after explicit `[REMOTE READ ONLY]` authorization under the installed/repository contract may new remote checks occur. Never scan/select another host or weaken host-key verification merely to get a green result.
+Invoking `/deployment-readiness <environment>` or directly asking to check readiness authorizes bounded **read-only** diagnostics for the exact resolved environment/target. Do not ask for a second `[REMOTE READ ONLY]` typed phrase or chat approval for each check once that scope is established. The consequence label remains useful in the plan, but the workflow request is the read-only authorization. Never scan/select another host, expand to a different target, change target trust, or weaken host-key verification merely to get a green result.
+
+When the installed Deployment Kit supports `target agent-session`, run supported remote checks via `target agent-session <target> -- <normal Deployment Kit command>` rather than copying `SSH_AUTH_SOCK` paths into each command. For existing Project-owned Python readiness scripts that use the same verified target, use the installed `target agent-run <target> -- <exact reviewed local executable and argv>` to inherit this SSH context without shell evaluation; do not invent script arguments or bypass their gates. This prepares only local SSH authentication (WSL/Linux stable private agent; macOS existing SSH agent or private fallback; native Windows OpenSSH agent service). It must not start or configure a Windows system service, enroll trust, skip an SSH passphrase, or authorize any remote write. If the key needs interactive local input, hand the exact non-secret command to the developer-owned terminal once and resume validation afterward. For older installed kits, use their supported SSH workflow and report the update opportunity rather than fabricating a command.
 
 #### Real application isolation preflight
 

package/assets/generated/core/core/skills/setup/SKILL.md

@@ -397,6 +397,8 @@ remote account/source-policy rejection
 
 Keep credentials, private keys, raw secure-prompt content, and unbounded SSH transcripts out of conversational diagnostics and journals.
 
+For workstation SSH-agent readiness, prefer the installed Deployment Kit's `target agent-session <target> -- <normal Deployment Kit command>` when supported; for repository-owned Python operations requiring SSH use `target agent-run <target> -- <exact local executable and arguments>` when available. This is a **local** convenience that works with the WSL/Linux private reused socket, the macOS agent or private fallback, and the native Windows OpenSSH agent service; the remote target OS is independent. Do not require the Builder to copy `SSH_AUTH_SOCK` paths across VS Code Chat terminal calls, switch to Copilot CLI, or type `[SSH AGENT WRITE]` as a second authorization merely to load the already-configured key. Keep the OpenSSH passphrase in the interactive terminal; never change the Windows agent service, host trust, or saved credentials without separate authority. After the key is ready, continue normal exact-target verification and the original write gates.
+
 For fingerprint input, show the expected public form such as `SHA256:<fingerprint>` and validate that shape before progressing. Distinguish the **server host fingerprint**, the **client public-key fingerprint**, and passwords/passphrases. If input looks credential-like rather than fingerprint-shaped, do not repeat it into commands, reports, journals, or upstream issues.
 
 If a local key/agent operation requires a passphrase or another terminal-owned secret prompt, follow the interactive-terminal handoff contract: collect any distinct bounded authorization once, then immediately provide the exact standalone copyable command, correct machine/working directory, expected local prompt, and the non-secret completion evidence to report. Do not ask for the passphrase through chat or ask a second ceremonial question merely to repeat the same authorized command.

package/assets/generated/deployment/src/project_forge_deployment/agent_session.py

@@ -0,0 +1,154 @@
+"""Explicit, reusable workstation SSH-agent session for Deployment Kit commands.
+
+This owns *local* authentication only. It does not authorize any remote write,
+alter target host trust, start an SSH tunnel, or change an operating-system service.
+"""
+from __future__ import annotations
+
+from contextlib import contextmanager
+import hashlib
+import os
+from pathlib import Path
+import platform
+import shutil
+import stat
+import subprocess
+from typing import Iterator
+
+from .errors import DeploymentKitError
+from .keys import add_key_to_agent, agent_status
+from .security import check_identity_security
+
+
+def _private_agent_directory(profile: dict[str, str]) -> Path:
+    identity = Path(profile["identityFile"])
+    check_identity_security(identity)
+    ssh_dir = next((p for p in identity.parents if p.name.lower() == ".ssh"), None)
+    if ssh_dir is None:
+        raise DeploymentKitError("The configured identity is outside the user's .ssh directory.")
+    directory = ssh_dir / "project-forge-agents"
+    if not directory.exists() and not directory.is_symlink():
+        directory.mkdir(mode=0o700)
+    try:
+        metadata = directory.lstat()
+    except OSError as error:
+        raise DeploymentKitError("Cannot inspect the dedicated SSH-agent directory.") from error
+    if (
+        not stat.S_ISDIR(metadata.st_mode)
+        or metadata.st_uid != os.getuid()
+        or metadata.st_mode & 0o077
+    ):
+        raise DeploymentKitError(
+            "Dedicated SSH-agent directory must be a real, current-user-owned directory with mode 0700."
+        )
+    return directory
+
+
+def _agent_socket(profile: dict[str, str]) -> Path:
+    directory = _private_agent_directory(profile)
+    digest = hashlib.sha256(
+        str(Path(profile["identityFile"]).resolve()).encode("utf-8")
+    ).hexdigest()[:16]
+    socket = directory / f"pf-{digest}.sock"
+    # Some OSes limit Unix-domain socket paths to ~104 bytes.
+    if len(os.fsencode(socket)) > 100:
+        raise DeploymentKitError(
+            "The dedicated SSH-agent socket path is too long for portable Unix socket support."
+        )
+    return socket
+
+
+def _ensure_posix_agent_socket(profile: dict[str, str]) -> str:
+    socket = _agent_socket(profile)
+    if socket.is_symlink():
+        raise DeploymentKitError("Refusing to follow a symlink at the dedicated SSH-agent socket.")
+    if socket.exists():
+        metadata = socket.lstat()
+        if not stat.S_ISSOCK(metadata.st_mode) or metadata.st_uid != os.getuid():
+            raise DeploymentKitError("Dedicated SSH-agent socket is not a current-user-owned Unix socket.")
+    else:
+        agent = shutil.which("ssh-agent")
+        if not agent:
+            raise DeploymentKitError("OpenSSH ssh-agent is not installed on this workstation.")
+        result = subprocess.run(
+            [agent, "-a", str(socket), "-s"],
+            check=False, text=True, capture_output=True,
+        )
+        if result.returncode or not socket.is_socket():
+            raise DeploymentKitError(
+                "Cannot start the dedicated SSH agent. Inspect the private socket directory; "
+                "no existing agent process or socket will be removed automatically."
+            )
+
+    # Do not trust an old socket solely because it looks like a socket: it must
+    # respond to the usual identity check under the exact selected environment.
+    return str(socket)
+
+
+def _set_socket(value: str | None) -> None:
+    if value is None:
+        os.environ.pop("SSH_AUTH_SOCK", None)
+    else:
+        os.environ["SSH_AUTH_SOCK"] = value
+
+
+@contextmanager
+def target_agent_session(profile: dict[str, str]) -> Iterator[dict[str, str | bool]]:
+    """Temporarily bind the selected target's agent to commands in this process.
+
+    WSL/Linux: a stable per-identity local OpenSSH agent survives separate
+    VS Code terminal processes. macOS: prefer its existing launchd agent when
+    available, otherwise use the same private stable POSIX fallback.
+    Native Windows: use the existing Windows OpenSSH agent *service* only.
+    Its service setup/start requires a separately authorized workstation action.
+    """
+    system = platform.system()
+    previous = os.environ.get("SSH_AUTH_SOCK")
+    managed_socket = False
+    try:
+        if system == "Windows":
+            # A native Windows OpenSSH service does not use SSH_AUTH_SOCK.
+            # Never start or reconfigure the privileged service automatically.
+            _set_socket(None)
+        elif system in {"Linux", "Darwin"}:
+            if system == "Darwin" and previous:
+                status = agent_status(profile)
+                if status["state"] == "agent-unavailable":
+                    _set_socket(_ensure_posix_agent_socket(profile))
+                    managed_socket = True
+            else:
+                _set_socket(_ensure_posix_agent_socket(profile))
+                managed_socket = True
+        else:
+            raise DeploymentKitError(
+                f"Unsupported workstation OS for SSH-agent session: {system}."
+            )
+
+        status = agent_status(profile)
+        if status["state"] == "agent-unavailable":
+            if system == "Windows":
+                raise DeploymentKitError(
+                    "Windows OpenSSH ssh-agent service is unavailable. "
+                    "Have the workstation administrator enable/start the ssh-agent service; "
+                    "Project Forge will not change its configuration automatically."
+                )
+            raise DeploymentKitError(
+                "The selected SSH-agent socket is unresponsive. "
+                "Inspect the private socket and agent process; Project Forge will not delete it automatically."
+            )
+
+        # The explicit 'agent-session' command authorizes this bounded local
+        # key load. SSH passphrase input remains with OpenSSH in the terminal.
+        if not status["loaded"]:
+            result = add_key_to_agent(profile)
+            if not result["loaded"]:
+                raise DeploymentKitError("Dedicated SSH identity is not loaded.")
+        yield {
+            "targetName": profile["targetName"],
+            "loaded": True,
+            "agent": "windows-service" if system == "Windows"
+                     else "dedicated-socket" if managed_socket
+                     else "existing-macos-agent",
+        }
+    finally:
+        _set_socket(previous)

package/assets/generated/deployment/src/project_forge_deployment/cli.py

@@ -230,6 +230,26 @@ def build_parser() -> argparse.ArgumentParser:
     agent_add.add_argument("name")
     agent_add.add_argument("--yes", action="store_true")
 
+    agent_session = target_sub.add_parser(
+        "agent-session",
+        help="Reuse a workstation SSH agent/key and run one normal Deployment Kit command",
+    )
+    agent_session.add_argument("name", help="Exact configured SSH target identity to load")
+    agent_session.add_argument(
+        "session_args", nargs=argparse.REMAINDER,
+        help="After --, a normal Deployment Kit command (with its usual authorization gates)",
+    )
+
+    agent_run = target_sub.add_parser(
+        "agent-run",
+        help="Run one repository-defined local program with the target's SSH agent, no shell",
+    )
+    agent_run.add_argument("name", help="Exact configured SSH target identity to load")
+    agent_run.add_argument(
+        "run_args", nargs=argparse.REMAINDER,
+        help="After --, exact executable and arguments for a normal local program",
+    )
+
     trust_candidates = target_sub.add_parser(
         "trust-candidates",
         help="Read candidate host-key fingerprints; candidates are never trusted by discovery",
@@ -373,6 +393,47 @@ def main(argv: list[str] | None = None) -> int:
         if args.group == "target" and args.command == "agent-status":
             _print(agent_status(load_profile(args.name)), as_json=args.json)
             return 0
+        if args.group == "target" and args.command == "agent-run":
+            import subprocess
+
+            command = list(args.run_args)
+            if command and command[0] == "--":
+                command.pop(0)
+            if not command:
+                raise DeploymentKitError(
+                    "Supply an exact local executable and argv after '--'. "
+                    "The agent-run command does not authorize the program's writes."
+                )
+            from .agent_session import target_agent_session
+
+            with target_agent_session(load_profile(args.name)) as session:
+                print(
+                    f"SSH agent ready for {session['targetName']} ({session['agent']}); "
+                    "the launched program retains its own authorization gates.",
+                    file=sys.stderr,
+                )
+                # No shell, eval, redirection, or implicit --yes. The caller
+                # selects an already-reviewed repository-owned program.
+                return subprocess.run(command, check=False).returncode
+        if args.group == "target" and args.command == "agent-session":
+            command = list(args.session_args)
+            if command and command[0] == "--":
+                command.pop(0)
+            if not command or command[:2] == ["target", "agent-session"]:
+                raise DeploymentKitError(
+                    "Supply a non-nested Deployment Kit subcommand after '--'. "
+                    "The SSH-agent session does not authorize remote operations."
+                )
+            from .agent_session import target_agent_session
+            from .entrypoint import main as dispatch
+
+            with target_agent_session(load_profile(args.name)) as session:
+                print(
+                    f"SSH agent ready for {session['targetName']} ({session['agent']}); "
+                    "normal CLI checks and write gates still apply.",
+                    file=sys.stderr,
+                )
+                return dispatch(command)
         if args.group == "target" and args.command == "agent-add":
             profile = load_profile(args.name)
             status = agent_status(profile)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mriekki/project-forge",
-  "version": "4.24.1",
+  "version": "4.25.0",
   "description": "Public consumer distribution and updater for Project Forge engineering assets.",
   "type": "module",
   "bin": {