@aion0/forge 0.10.71 → 0.10.74

package/RELEASE_NOTES.md

@@ -1,11 +1,8 @@
-# Forge v0.10.71
+# Forge v0.10.74
 
 Released: 2026-06-11
 
-## Changes since v0.10.70
+## Changes since v0.10.73
 
-### Other
-- fix(auth): persist AUTH_SECRET so sessions survive refresh/restart
 
-
-**Full Changelog**: https://github.com/aiwatching/forge/compare/v0.10.70...v0.10.71
+**Full Changelog**: https://github.com/aiwatching/forge/compare/v0.10.73...v0.10.74

package/components/EnterpriseBadge.tsx

@@ -217,7 +217,7 @@ export default function EnterpriseBadge({ onOpenSettings: _onOpenSettings }: { o
         ok: boolean;
         steps_completed?: number;
         error?: string;
-        post_login_terminal?: Array<{ name: string; ok: boolean; command?: string; error?: string }>;
+        post_login_terminal?: Array<{ name: string; ok: boolean; command?: string; error?: string; skipped?: boolean }>;
       }>) {
         if (entry.ok) {
           parts.push(`✓ ${entry.idp_host} (${entry.steps_completed || 0} steps)`);
@@ -229,6 +229,10 @@ export default function EnterpriseBadge({ onOpenSettings: _onOpenSettings }: { o
         }
         if (Array.isArray(entry.post_login_terminal)) {
           for (const r of entry.post_login_terminal) {
+            if (r.skipped) {
+              parts.push(`${r.name} ⊘ (n/a on this platform)`);
+              continue;
+            }
             parts.push(r.ok ? `${r.name} ✓` : `${r.name}: ${r.error || 'skipped'}`);
             if (!r.ok && r.command) {
               failedTerminals.push({ name: r.name, command: r.command, error: r.error });

package/docs/SSH-to-PAT-migration-analysis.md

@@ -0,0 +1,256 @@
+# SSH → PAT migration: scope, what changed where, what's still needed
+
+**Author**: Z + Claude  ·  **Date**: 2026-06-12  ·  **Audience**: Forge / forge-connectors maintainers
+
+## Why this doc exists
+
+While integrating Forge against the Fortinet corp GitLab inside a Docker
+sandbox, we ran into the warning
+
+```
+✓ fac.corp.fortinet.com  (3 steps, final=https://...)
+    · GitLab SSH 2FA: Keystroke mode is macOS-only.
+```
+
+and a related glab error path. We sorted out what's actually broken vs
+what just looks broken, and made a narrow fix in the sandbox repo
+(corp-workspace). **A separate fix is still required in the Forge ↔
+forge-connectors stack to benefit users who run Forge directly on
+their machines.**
+
+This doc lays out the full picture so the right person can decide
+whether and how to land the second fix.
+
+---
+
+## 1. The three different things people mean by "SSH"
+
+It's easy to conflate, but they are independent code paths:
+
+| # | Thing | Who uses it | What was/is the issue |
+|---|---|---|---|
+| A | `git push ssh://git@…` from a Forge-managed clone | Pipeline shell steps | **Never an issue.** Forge's `connectorEnv()` injects `GITLAB_TOKEN` and clones with `https://oauth2:<PAT>@…` in `.git/config`. Push was already HTTPS+PAT. |
+| B | `glab repo clone foo/bar` (convenience CLI) | Dev typing in workspace terminal; future workflow nodes | glab CLI's stock config has `git_protocol: ssh`. With no SSH key in the container that fails opaquely. Trivial to fix per workspace, but easy to forget. |
+| C | `ssh git@dops-git106.fortinet-us.com 2fa_verify` post-IdP-login step | Triggered by Fortinet's `_idp` wizard after a successful FAC SAML login. Implemented by `lib/auth/terminal-keystroke.ts`. | The implementation **only works on macOS** because it uses `osascript` to type into the user's frontmost Terminal.app (the only PID that FortiClient lets through the corp tunnel). On Linux/container/Windows it returns `Keystroke mode is macOS-only.` and the IdP login shows a yellow warning. |
+
+### Why each path exists
+
+- **A** exists because git push must work end-to-end for any agent that
+  edits + commits. Forge's framework already handles this transparently.
+
+- **B** exists because dev workflow is more natural with `glab repo clone`
+  than `git clone $(glab repo view --url)`. Default protocol matters.
+
+- **C** exists because FortiClient VPN gates each TCP session by the
+  process tree of the PID that opened it. Forge-spawned processes are
+  not in the user's whitelisted PID, so they can't reach the internal
+  GitLab over SSH. AppleScript-typing the command into the user's
+  frontmost Terminal.app makes it a direct child of the
+  user-whitelisted PID. Hence the macOS dependency.
+
+---
+
+## 2. What was changed in corp-workspace this round
+
+**Only B** has been fixed in the corp-workspace repo:
+
+```diff
+ # ─── Git provider CLIs (gh + glab) ──────────────────────────────────────
+ ...
+ gh --version; glab --version
++
++USER neko
++RUN mkdir -p /home/neko/.config/glab-cli \
++    && glab config set -g git_protocol https
++USER root
+```
+
+Net effect inside any container built from this image: `glab repo clone`
+defaults to HTTPS URLs and the in-env GITLAB_TOKEN authenticates them.
+No effect on Forge backend, no effect on A or C.
+
+The architecture-decisions doc in corp-workspace was updated with a §15
+section that documents the SSH-removal stance.
+
+---
+
+## 3. What's NOT fixed by anything in corp-workspace
+
+**C — the macOS-only post-login terminal step.** That warning still
+fires every time a non-Mac (or sandboxed-Mac) Forge instance walks the
+Fortinet IdP flow. It looks like a real failure to users seeing it for
+the first time.
+
+This needs fixing in TWO upstream places, one optional:
+
+### Required: `aiwatching/forge-connectors` — `enterprise-fortinet/wizards/fortinac.json`
+
+Either remove the `post_login_terminal` array, or annotate it as
+platform-specific. We recommend keeping it but tagging:
+
+```diff
+ {
+   "host": "fac.corp.fortinet.com",
+   "saml_sps": ["mantis","pmdb","tp","teams"],
+   "post_login_terminal": [
+     {
+       "name": "GitLab SSH 2FA",
+       "command": "ssh git@dops-git106.fortinet-us.com 2fa_verify",
+       "needs_otp": true,
++      "platforms": ["darwin"],
+       "valid_minutes": 55
+     }
+   ]
+ }
+```
+
+The semantics we want:
+- macOS user running Forge natively → step runs as today
+- macOS user running Forge in container → step skipped (no warning)
+- Linux/Windows user → step skipped (no warning)
+
+### Optional but needed to honor the tag: `@aion0/forge` (Forge backend)
+
+Only required if we go with the `platforms` annotation (option B in
+corp-workspace's analysis). Without backend support the new key is
+silently ignored — the step still runs, still fails on non-darwin,
+warning still shows. The patch is small:
+
+```diff
+ // lib/auth/idp-login.ts (the loop that iterates post_login_terminal)
+ const results: TerminalResult[] = [];
+ for (const t of (block.post_login_terminal || [])) {
++  // Wizard authors can scope an entry to specific platforms; on
++  // others, skip silently rather than emit a noisy "macOS-only"
++  // warning that confuses container/Linux users.
++  if (Array.isArray(t.platforms) && t.platforms.length > 0
++      && !t.platforms.includes(process.platform)) {
++    continue;
++  }
+   results.push(await runTerminalKeystroke(t, otp));
+ }
+```
+
+Plus extending the `TerminalSpec` interface to include
+`platforms?: NodeJS.Platform[]`.
+
+### Easier alternative: don't add a new field, just drop the step entirely
+
+Replace the wizard's `post_login_terminal` entry with `[]` or remove
+the key. Justification:
+
+- The step exists to refresh GitLab's per-IP 2FA window for SSH push.
+- Forge agent pushes via HTTPS+PAT (path A). Doesn't need 2FA refresh.
+- Devs pushing from their host machine over SSH already type
+  `ssh ... 2fa_verify` themselves; auto-running it during SSO login
+  is convenience, not correctness.
+
+Trade-off: macOS dev who got used to the auto-2fa convenience loses
+that. They now have to type the command themselves once per 55 min if
+they do SSH pushes.
+
+Our recommendation: **start with the annotation approach (preserves
+existing behavior for the small set of macOS-native users)**. Drop the
+step entirely only if telemetry / feedback shows nobody actually relies
+on it.
+
+---
+
+## 4. Decision matrix — impact of each option
+
+| Change | Lines touched | Mac native (Forge on host) | Mac docker (corp-workspace) | Linux server (Forge native or docker) |
+|---|---|---|---|---|
+| nothing (status quo) | 0 | ✓ auto 2fa_verify works | ⚠️ warning shown | ⚠️ warning shown |
+| corp-workspace Dockerfile only (done) | ~3 | (no change) | (no change for C; B fixed) | (no change for C; B fixed if they use the same image) |
+| **forge-connectors + Forge backend, annotated** | ~10 | ✓ unchanged | ✓ silently skipped | ✓ silently skipped |
+| **forge-connectors only, remove step** | ~5 | ✗ Mac native loses auto-2fa | ✓ silent | ✓ silent |
+
+---
+
+## 5. Open questions for the team
+
+1. **Is the auto-2fa convenience valuable enough to keep for macOS
+   natives?** If yes → go with annotation. If most macOS users actually
+   work in containers / Linux servers and rarely SSH-push directly, the
+   annotation adds a config knob nobody will ever change → drop the
+   step.
+
+2. **Are there other `post_login_terminal` use cases (or future ones)
+   that benefit from platform tagging?** If yes → annotation gives us
+   the lever. If no → just delete.
+
+3. **Should we also document a way to set up SSH inside the container?**
+   Some power user might want to mount their host SSH key into the
+   container for personal-signed git commits. We don't need to enable
+   it by default — just document it works if you bind-mount
+   `~/.ssh:/home/neko/.ssh:ro`.
+
+---
+
+## 6. Suggested action sequence
+
+If you decide to land the annotation approach:
+
+1. **`@aion0/forge`** (Forge backend repo)
+   - Patch `lib/auth/idp-login.ts` per §3 above.
+   - Extend `TerminalSpec` in `lib/auth/terminal-keystroke.ts` with
+     `platforms?: NodeJS.Platform[]`.
+   - Add changelog entry.
+   - Bump patch version (e.g. 0.10.69 → 0.10.70). Publish.
+
+2. **`aiwatching/forge-connectors`** (wizard JSON repo)
+   - Open `enterprise-fortinet/wizards/fortinac.json`.
+   - Add `"platforms": ["darwin"]` to the FAC entry's
+     `post_login_terminal[0]`.
+   - Commit + push to `main`.
+
+3. **Verification path**
+   - In corp-workspace: `make sync-registry U=zliu` to pull new wizard.
+     Then `make login U=zliu`. Result: no more `GitLab SSH 2FA:
+     Keystroke mode is macOS-only.` warning in the output.
+   - In a separate macOS-native Forge install: `make sync-registry`
+     equivalent. Then trigger IdP login. Result: warning gone for
+     non-darwin, but on macOS native the AppleScript path still runs.
+
+4. (Optional) Land a follow-up to corp-workspace updating §15 to
+   reference the new platform-aware behavior so future readers
+   understand both halves of the fix.
+
+If you instead decide to drop the step entirely, you only need step (2)
+and don't have to bump Forge backend.
+
+---
+
+## 7. Outcome (2026-06-12)
+
+All landed on branch `analysis/ssh-to-pat-migration` (Forge) + `main`
+(forge-enterprise-agent-fortinet). Corrections and final state:
+
+- **Location correction**: the wizard JSON lives in
+  `forge-enterprise-agent-fortinet/templates/wizards/fortinac.json`, not
+  `aiwatching/forge-connectors` as §3 said. The public forge-connectors
+  repo carries no wizard / `post_login_terminal` anywhere — verified, so
+  nothing to change there (zero blast radius for non-fortinet users).
+
+- **Both options were taken, in sequence**:
+  1. Annotation mechanism landed in Forge (`TerminalSpec.platforms`,
+     silent `skipped: true` + ⊘ in EnterpriseBadge) and the wizard was
+     tagged `"platforms": ["darwin"]`.
+  2. After end-to-end validation that pipeline `git push` works over
+     HTTPS+PAT, the wizard's `post_login_terminal` entry was **deleted
+     entirely**. The `platforms` mechanism stays in Forge for future
+     wizard steps.
+
+- **Beyond the doc's scope, the real root fix**: path A was *not* fully
+  "never an issue" — since v0.10.68/72 Forge prefers the user's local
+  checkout, whose origin may be SSH-style. Forge now injects
+  `GIT_CONFIG_COUNT/KEY/VALUE` insteadOf rules (git ≥ 2.31) via
+  `connectorEnv()` so `git@host:` / `ssh://git@host/` remotes rewrite to
+  `https://oauth2:<PAT>@host/` per task process. Empty token → no
+  injection → SSH behavior preserved as the backup path. Optional
+  `gitlab.config.ssh_aliases` covers SSH-host ≠ HTTPS-host setups.
+  `preflightGitAuth` inherits the same env so the probe matches push
+  behavior. `lib/init.ts` also defaults glab to `git_protocol https`.
+
+- corp-workspace `architecture-decisions.md` §15 updated to reflect the
+  step removal (the §6.4 follow-up).

package/lib/auth/terminal-keystroke.ts

@@ -24,6 +24,9 @@ export interface TerminalSpec {
   prompt_markers?: string[];
   /** Validity window (informational only, surfaced to UI). */
   valid_minutes?: number;
+  /** When set, only run on these platforms; on others, silently skip
+   *  instead of emitting the "macOS-only" warning. */
+  platforms?: NodeJS.Platform[];
   /** Regex (case-insensitive). If transcript matches, force verdict=fail
    *  even when exit code is 0. Needed when the command prints failure
    *  text to stdout without setting a non-zero exit code (e.g. GitLab
@@ -42,6 +45,9 @@ export interface TerminalResult {
   command: string;
   error?: string;
   transcript?: string;
+  /** Set when a `platforms` spec excluded the current OS — UI should
+   *  treat this as "not applicable", not as failure. */
+  skipped?: boolean;
 }
 
 const DEFAULT_PROMPT_MARKERS = ['OTP', 'Token', 'verification', 'code:'];
@@ -71,6 +77,13 @@ export async function runTerminalKeystroke(
   spec: TerminalSpec,
   otp?: string,
 ): Promise<TerminalResult> {
+  // Wizard authors can scope to specific platforms; on others, silently
+  // skip so non-darwin Forge instances don't see a noisy "macOS-only"
+  // warning for steps that simply aren't applicable to them.
+  if (Array.isArray(spec.platforms) && spec.platforms.length > 0
+      && !spec.platforms.includes(process.platform)) {
+    return { name: spec.name, command: spec.command, ok: true, skipped: true };
+  }
   if (process.platform !== 'darwin') {
     return { name: spec.name, command: spec.command, ok: false, error: 'Keystroke mode is macOS-only.' };
   }

package/lib/help-docs/05-pipelines.md

@@ -73,6 +73,12 @@ nodes: { ... }
   are ignored — only a genuine OTP marker blocks. Those still surface at push
   time as before.
 
+> **Note**: with a GitLab connector PAT configured, SSH-style origins are
+> transparently rewritten to HTTPS+PAT for both this preflight and the actual
+> push (see *GitLab connector — git push avoids SSH 2FA* in `17-connectors.md`),
+> so the OTP wall is normally never hit. The preflight remains as the safety
+> net for the no-PAT / SSH-fallback path.
+
 ## Auth-required alerts (git OTP + expired connector logins)
 
 When a `git_push` pipeline hits the OTP wall, **or** any pipeline fails on an

package/lib/help-docs/10-troubleshooting.md

@@ -23,6 +23,18 @@ Fix AUTH_SECRET so it persists:
 echo "AUTH_SECRET=$(openssl rand -hex 32)" >> ~/.forge/data/.env.local
 ```
 
+### Pipeline push asks for OTP / "2fa_verify" / "Keystroke mode is macOS-only"
+Pipeline `git push` should never hit an SSH 2FA wall when the GitLab
+connector has a PAT: Forge rewrites SSH-style remotes
+(`git@host:owner/repo.git`) to HTTPS+PAT per task process (needs git ≥ 2.31).
+If you still see a 2FA abort:
+- Check Settings → Connectors → GitLab has a valid token.
+- If your GitLab's SSH hostname differs from the HTTPS `base_url` host, add
+  it to the connector's `ssh_aliases`.
+- An old wizard may still carry a "GitLab SSH 2FA" post-login step — resync
+  the enterprise marketplace to pull the updated wizard; the warning row
+  disappears from the Enterprise badge.
+
 ### Orphan processes after Ctrl+C
 Use `forge server stop` or:
 ```bash

package/lib/help-docs/17-connectors.md

@@ -413,6 +413,22 @@ Each prompt may include `url` + `url_label`, surfaced in the modal as
 a "↗ Get token" link next to the field so the user can jump straight
 to the page that issues the value.
 
+## GitLab connector — git push avoids SSH 2FA
+
+When the GitLab connector has a PAT, Forge injects per-process git config
+into every task it spawns (`GIT_CONFIG_COUNT/KEY/VALUE`, git ≥ 2.31) so
+SSH-style remotes (`git@host:owner/repo.git`) are rewritten to
+`https://oauth2:<PAT>@host/owner/repo.git` at push time. Effect: pipeline
+`git push` nodes use the PAT and never trigger `ssh ... 2fa_verify`.
+
+- No write to `~/.gitconfig` or the repo's `.git/config` — the rewrite is
+  scoped to the task process and its children only.
+- Empty token → no rewrite injected → SSH behavior is preserved as a
+  backup path (useful if PAT use ever gets restricted).
+- If the SSH host differs from the HTTPS `base_url` host, add the SSH
+  hostname(s) to the gitlab config's optional `ssh_aliases` array — Forge
+  rewrites those too.
+
 ## Migration from pre-v0.9
 
 Pre-v0.9 Forge stored connectors as built-in plugins under

package/lib/init.ts

@@ -115,6 +115,19 @@ export function ensureInitialized() {
     catch (e) { console.warn('[init] startScratchCleanup failed:', (e as Error).message); }
   });
   time('autoDetectAgents', autoDetectAgents);
+  time('ensureGlabHttps', () => {
+    // Default glab CLI to HTTPS so `glab repo clone` uses the connector PAT
+    // instead of SSH (which would hit ssh 2fa_verify). Best-effort; absent
+    // glab or read-only config dir just skip.
+    try {
+      const { execSync } = require('node:child_process');
+      const cur = execSync('glab config get git_protocol 2>/dev/null', { encoding: 'utf-8', timeout: 3000, stdio: ['pipe', 'pipe', 'pipe'] }).trim();
+      if (cur && cur !== 'https') {
+        execSync('glab config set -g git_protocol https', { timeout: 3000, stdio: ['pipe', 'pipe', 'pipe'] });
+        console.log(`[init] glab git_protocol: ${cur} → https`);
+      }
+    } catch {}
+  });
   time('logToolStatus', () => {
     try { const { logToolStatus } = require('./health'); logToolStatus(); }
     catch (e) { console.warn('[tools] health check failed:', (e as Error).message); }

package/lib/pipeline.ts

@@ -842,11 +842,16 @@ function preflightGitAuth(pipeline: Pipeline): { message: string; action?: strin
   if (!existsSync(join(projectPath, '.git'))) return null;
 
   try {
+    // Inherit connectorEnv (GIT_CONFIG_* insteadOf rewrite) so a user-cloned
+    // SSH origin probes via HTTPS+PAT instead of hitting ssh 2fa_verify —
+    // same rewrite task-manager applies to pipeline shell nodes.
+    const { connectorEnv } = require('./task-manager') as typeof import('./task-manager');
     execSync('git ls-remote --heads origin', {
       cwd: projectPath,
       stdio: 'pipe',
       timeout: 15_000,
       encoding: 'utf8',
+      env: { ...process.env, ...connectorEnv() },
     });
     return null; // remote reachable, no OTP wall
   } catch (e) {

package/lib/projects.ts

@@ -386,15 +386,25 @@ export function resolveOrCloneProject(name: string | undefined): ResolveResult {
   //   2. `name` is empty / unknown — pull the gitlab connector's
   //      `default_project_path` (e.g. "fortinet/fortinac-dev") and use
   //      it as the fallback repo.
-  // Either way we clone into <dataDir>/cloned-projects/ and reuse on
-  // subsequent runs. The previous behaviour silently dropped to scratch
-  // and code-fix pipelines exploded with "fatal: not a git repository".
+  // Before cloning, scan local projectRoots for a checkout whose git
+  // origin already matches — saves a redundant clone and also covers the
+  // "server just booted, registry/settings cache not warm yet" window
+  // where the user's real local FortiNAC was missed by the name-based
+  // lookups above.
   const gl = readGitlabConnector();
   if (gl) {
     const targetPath = trimmed && trimmed.includes('/')
       ? trimmed
       : (gl.default_project_path || '').trim();
     if (targetPath) {
+      const projects = scanProjects();
+      const want = normalizeRepoPath(targetPath) || targetPath.toLowerCase().replace(/^\/+|\/+$/g, '');
+      const wantBase = want.split('/').pop()!;
+      const byRepo = projects.filter((p) => p.repo && p.repo === want);
+      if (byRepo.length === 1) return { project: byRepo[0], source: 'existing' };
+      const byRepoBase = projects.filter((p) => p.repo && p.repo.split('/').pop() === wantBase);
+      if (byRepoBase.length === 1) return { project: byRepoBase[0], source: 'existing' };
+
       const cloned = tryGitlabClone(targetPath);
       if (cloned) return { project: cloned, source: 'gitlab-cloned', clone_url: `${gl.base_url}/${targetPath.replace(/^\/+|\/+$/g, '')}.git` };
     }

package/lib/task-manager.ts

@@ -440,7 +440,7 @@ async function processNextTask() {
  * Only well-known connectors map to env vars. Token never leaves the
  * server — the bash child inherits the env directly.
  */
-function connectorEnv(): Record<string, string> {
+export function connectorEnv(): Record<string, string> {
   try {
     const out: Record<string, string> = {};
     const gitlab = getInstalledConnector('gitlab');
@@ -450,13 +450,40 @@ function connectorEnv(): Record<string, string> {
         // glab CLI honours GITLAB_TOKEN; HTTP libs honour CI_JOB_TOKEN-style names too,
         // but GITLAB_TOKEN covers glab + most curl-based scripts in our pipelines.
         out.GITLAB_TOKEN = tok;
+        let httpsBase = '';
+        let httpsHost = '';
         if (typeof gitlab.config?.base_url === 'string' && gitlab.config.base_url) {
-          // glab uses GITLAB_URI for the API host on self-hosted instances.
           try {
             const u = new URL(String(gitlab.config.base_url));
             out.GITLAB_URI = u.origin;
+            httpsBase = u.origin.replace(/\/+$/, '');
+            httpsHost = u.host;
           } catch {}
         }
+        // Transparent SSH→HTTPS rewrite for pipeline `git push`. Without this,
+        // a user-cloned `git@host:owner/repo.git` origin pushes over SSH and
+        // hits 2fa_verify even though we have a PAT. Per-process via git's
+        // GIT_CONFIG_COUNT/KEY/VALUE env triplet (git ≥ 2.31) — no write to
+        // ~/.gitconfig or the repo, no SSH leak when token is absent.
+        if (httpsBase && httpsHost) {
+          const aliases: string[] = Array.isArray(gitlab.config?.ssh_aliases)
+            ? gitlab.config.ssh_aliases.filter((s: unknown) => typeof s === 'string' && s.trim()).map((s: string) => s.trim())
+            : [];
+          const hosts = Array.from(new Set([httpsHost, ...aliases]));
+          const target = `${httpsBase}/`.replace(/^https?:\/\//, (m) => `${m}oauth2:${encodeURIComponent(tok)}@`);
+          const rules: Array<[string, string]> = [];
+          for (const h of hosts) {
+            rules.push([`url.${target}.insteadOf`, `git@${h}:`]);
+            rules.push([`url.${target}.insteadOf`, `ssh://git@${h}/`]);
+          }
+          if (rules.length > 0) {
+            out.GIT_CONFIG_COUNT = String(rules.length);
+            rules.forEach(([k, v], i) => {
+              out[`GIT_CONFIG_KEY_${i}`] = k;
+              out[`GIT_CONFIG_VALUE_${i}`] = v;
+            });
+          }
+        }
       }
     }
     const gh = getInstalledConnector('github-api');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aion0/forge",
-  "version": "0.10.71",
+  "version": "0.10.74",
   "description": "Unified AI workflow platform — multi-model task orchestration, persistent sessions, web terminal, remote access",
   "type": "module",
   "scripts": {