@monster-orange/den 0.2.7 → 0.2.8

package/CHANGELOG.md

@@ -4,6 +4,114 @@ All notable changes to Den are documented here. Each release lists the
 config and manifest changes a distribution must make to move to it under
 **Migrations**.
 
+## [0.2.8] - 2026-11-05
+
+### Added
+
+- **A scoped MCP server for cooperating agents** (0.2.8-dev.0, AG-2a-core).
+  `<cli> mcp --workspace <ws> --actor agent:<id>` pins one workspace: a tool
+  that takes a workspace gets `<ws>`, and a call naming another is refused
+  before it reaches the web server and recorded in the activity trail.
+  Lists are filtered to `<ws>`: `workspaces` shows it alone, the log tools
+  and `manifest_validate` take only its services and repos, `workspace_sync`
+  syncs it, and the test tools need it to be the focused workspace. Every
+  web API call is stamped with the actor (`x-den-mcp-agent`,
+  `x-den-mcp-workspace`), so each exec, run and sync in the activity trail
+  and the server log names `agent:<id>` and its workspace. Both flags or
+  neither; a bad value is a usage error (exit 2). `--list` and `--call` take
+  them too. Without them the server is unchanged. **Limit:** it binds
+  cooperating agents only. The scope lives in the MCP process, and the web
+  server's HTTP API does not check it yet (WS-3a, 0.4); `mcp connect` still
+  registers the unscoped server.
+- **`<cli> setup --plan -w <ws>` and `--all-active`** (0.2.8-dev.0). `-w` is
+  repeatable and plans those workspaces, active or not; `--all-active` plans
+  every active one; on a fresh machine `-w` narrows the blueprint's plan. A
+  closing hint names the repos only workspaces outside the plan hold. `-w`
+  and `--all-active` go with `--plan` only.
+- **Orgs are Den's own; sources are bindings** (0.2.8-dev.1, ORG-1d). An
+  org is any key of `orgs:`. `orgs.<id>.sources: [{host, owner|group}]`
+  claims git-host owners for it (an org can span two GitHub owners), and
+  `orgs.<id>.repos: [...]` lists repos outright (one owner can be split
+  across orgs). Catalog entries take `remote: <git url>` for any host;
+  `gh: owner/repo` stays the GitHub shorthand. A repo's org is the org
+  listing it, else the one whose source claims its owner, else its GitHub
+  owner; inference, `/api/orgs` and `org list` use it, and a claimed owner
+  is not listed as its own org. A repo clones from its source (GitHub with
+  `gh` as credential helper), or with no source from its `remote:` through
+  plain git and the user's own credential helper (SEC-0); `setup --plan`
+  shows that URL. Discovery (`register`) and the Release page skip an org
+  with no GitHub source. A bad value names its key; a repo or owner claimed
+  by two orgs is an error naming both. See docs/distributions.md, Orgs.
+- **`<cli> register <path> -w <ws>`** (0.2.8-dev.0) writes that workspace,
+  active or not, and leaves focus alone. It used to fail with "-w/--workspace
+  is not valid with register".
+
+### Changed
+
+- **`setup --plan` and `up --plan` show a dev-managed repo's real branch**
+  (0.2.8-dev.0): the one its checkout has out (read from `.git/HEAD`, no git
+  process), or `(branch unknown)`, where they printed `main` for every
+  checkout.
+- **`up --plan` exits 1 when nothing resolves** (0.2.8-dev.0): a name no
+  workspace has, or a workspace with nothing to start. It exited 0.
+- **`register` with no terminal exits 2** (0.2.8-dev.0) with one usage line
+  that names `-w`: `register needs a terminal (stdin is not a TTY); without
+  one: <cli> register <path> [--name <repo>] [--gh <owner/repo>] [-w
+  <workspace>]`. It went on to prompt with nothing to answer.
+
+### Fixed
+
+- **A config that fails validation stops every command** (0.2.8-dev.2).
+  A repo or owner claimed by two orgs (or any other bad ORG-1d value) is
+  checked before any command that touches orgs, the catalog, clones or
+  releases runs, and it exits 1 naming both keys. `sync` over existing
+  clones exited 0 and pulled, because it reads only workspaces.yml and the
+  catalog; `register <path> -w <ws>` wrote workspaces.yml and the catalog,
+  `workspace create` wrote workspaces.yml, and `workspace use` /
+  `add-service` exited 0. Now each stops before any git call or write. `web`, `mcp`, `validate`, `create`,
+  `config`, `local-dev` and `view-results` still run.
+- **The web API answers a config that fails validation as JSON**
+  (0.2.8-dev.2). Every API route that reads the config answers 422
+  `{ ok: false, error: "<the message naming the keys>", code:
+  "config_invalid" }`, where `/api/orgs`, `/api/services` and others
+  answered a text/plain 500 "internal server error" and some routes turned
+  it into a 400 or an empty list. The error names config keys, never
+  values. `/api/server-info`, `/api/server-log`, `/api/changelog` and
+  `/api/web/restart` still answer, and pages still load.
+- **A scoped MCP `manifest_validate` refused on another workspace's path
+  shows in that repo's activity** (0.2.8-dev.2). The refusal is recorded
+  under the catalog repo whose checkout holds the path (in any workspace),
+  as `logs_tail` refusals are since 0.2.8-dev.1. The entry is addressed by
+  the repo, not the path; its detail is the refusal message, which quotes
+  the path.
+- **A scoped MCP refusal of a non-lifecycle tool shows on its service**
+  (0.2.8-dev.1). A refused `logs_tail`, `logs_search` or other non-lifecycle tool
+  was stored with an empty detail and no service, so the service panel's
+  activity (`GET /api/activity?address=<repo>/<svc>`) never showed it. The
+  entry's detail is now the refusal, and it carries `addresses`: the repo
+  or `repo/service` the call named, or every target of a `logs_search`
+  (one entry, listed under each).
+- **`up --plan -w <ws>` with nothing to start is a usage error**
+  (0.2.8-dev.1): one line, exit 2, naming `up -a -w <ws>` (the whole
+  workspace) and `up <repo> -w <ws>`. It printed "No services specified and
+  no invocation target resolvable".
+- **Test workers inherit no credentials** (0.2.8-dev.0). `tests/setup.ts`
+  strips credential-shaped variables (by name, family or token shape) from
+  the environment before any suite runs, so a failing assertion on a
+  spawn env can no longer print a developer's tokens.
+
+### Migrations
+
+- None. A script that ran `up --plan` and ignored its exit code may now see
+  1 when the plan is empty (2 for `up --plan -w <ws>` with no repo or
+  `-a`).
+- ORG-1d (`orgs.<id>.sources`, `orgs.<id>.repos`, catalog `remote:`) is
+  optional: no change is needed, and a config without those keys behaves
+  exactly as on 0.2.7. A den.yml that uses them needs Den 0.2.8 or later.
+- A client of the web API that reads a config error should check for
+  status 422 and `code: "config_invalid"` (0.2.8-dev.2); it was a
+  text/plain 500.
+
 ## [0.2.7] - 2026-11-05
 
 ### Added

package/docs/distributions.md

@@ -473,8 +473,14 @@ To see what a setup would clone before it clones anything, run
 `acme setup --plan`: each repo with its org and clone URL, and whether it
 is cloned yet. On a fresh machine it plans the blueprint (every workspace
 `acme workspace seed` would create); once seeded, the focused workspace.
-`acme up --plan` lists the same lines for the repos it would start. Both
-are read-only: nothing is cloned, seeded or written.
+`-w <workspace>` (repeatable) plans those workspaces instead, active or not,
+and `--all-active` every active one; on a fresh machine `-w` narrows the
+blueprint's plan. Repos that only workspaces outside the plan hold are named
+in a closing hint. A dev-managed repo shows the branch its checkout has out
+(read from its `.git/HEAD`), not a configured one. `acme up --plan` lists
+the same lines for the repos it would start, and exits 1 when nothing
+resolves (a name no workspace has, an empty workspace). Both are read-only:
+nothing is cloned, seeded or written.
 
 ## Orgs
 
@@ -523,6 +529,73 @@ its workspace's org is a warning in both lists, never an error.
 `org:` in the blueprint needs Den 0.2.7 or later: an older Den rejects the
 unknown key. Pin 0.2.7 before you commit it.
 
+### Sources and repos (0.2.8)
+
+An org is Den's own: its id is any key of `orgs:`, and it needs no git
+host. Two optional keys bind it to where its repos live:
+
+```yaml
+github_org: acme
+orgs:
+  acme-group: # one org, two GitHub owners
+    label: Acme Group
+    sources:
+      - { host: github, owner: acme }
+      - { host: github, owner: acme-labs }
+  globex-billing: # one owner split across two orgs
+    repos: [globex-invoices]
+  globex:
+    sources: [{ host: github, owner: globex }]
+  initech: # no git host at all
+    sources: []
+    repos: [widget]
+```
+
+- `orgs.<id>.sources` is a list of `{host, owner}` (or `{host, group}`). A
+  source claims that owner's repos for the org. `host: github` is built
+  in; any other host id (`gitlab`, …) claims repos whose `remote:` is on
+  `<host>.com` or a `<host>.` hostname, and clones them from that remote.
+- `orgs.<id>.repos` lists repos that belong to the org whatever their
+  owner.
+- An entry with neither key is what it was before 0.2.8: the GitHub owner
+  of its own name.
+
+The catalog (`config/local/service-catalog.yml`) takes a `remote:` for any
+host, beside `gh: owner/repo`, which stays as the GitHub shorthand:
+
+```yaml
+widget: { remote: git@git.initech.example:tools/widget.git }
+```
+
+A repo's org is the org whose `repos` lists it, else the org with a source
+that claims its owner, else its GitHub owner as before. That org is what
+`/api/orgs?repos=1` maps the repo to and what infers a workspace's org (step
+3 above). A claimed owner is not listed as an org of its own, and a
+`github_org` that names one makes the claiming org the default. Service rows
+(`/api/services`, `/api/health`) keep `org` as the repo's GitHub owner.
+
+A repo clones from its source: a GitHub source gives
+`https://github.com/<owner>/<repo>.git` with your `gh` as credential helper.
+A repo with no source that claims it clones and pulls from its `remote:`
+through plain git, with your own git credential helper; Den never hands it
+`gh` or any credential of its own. A remote must be `https://`, `ssh://`,
+`git://`, `file://`, `user@host:path` or an absolute path. `setup --plan`
+shows it as the clone URL, with any user info masked.
+
+An org with no GitHub source has no repo discovery (`register` lists
+nothing for it) and its repos are left off the Release page.
+
+These keys are checked when den.yml is read, and a bad value is an error
+that names its key (`orgs.initech.sources[0].owner must be …`). A repo
+listed by two orgs, or an owner claimed by two orgs' sources (or by a
+source and an org with no `sources` of that name), is an error naming both
+keys. Such an error stops every command that touches orgs, the catalog,
+clones or releases (exit 1, before any git call or write), and every web
+API route that reads the config answers it as 422 `{ "ok": false, "error":
+"<message>", "code": "config_invalid" }`. Without the new keys nothing
+changes: `/api/orgs` is byte for byte what 0.2.7 answered. They need Den
+0.2.8 or later.
+
 ## Releases
 
 The Release page dispatches each repo's CD workflow on GitHub. A repo's
@@ -736,6 +809,46 @@ everyone's checkout is in the same place.
 `--port <n>` (on `mcp` or `mcp connect`) points it at a web server on another
 port.
 
+### Scoped to one workspace
+
+```sh
+./bin/acme mcp --workspace smb --actor agent:planner
+```
+
+`--workspace <ws>` and `--actor agent:<id>` (both or neither) scope the server
+to one workspace for one agent:
+
+- **Pinned.** A tool that takes a `workspace` gets `<ws>` when none is given.
+  A call naming another workspace is refused (`Refused: <tool>: this MCP
+server is scoped to workspace "<ws>" (agent:<id>); "<other>" is another
+workspace`) before anything reaches the web server. A refused call is
+  recorded in the activity trail, read tools included.
+- **Filtered.** `workspaces` lists `<ws>` only. `logs_search` and `logs_tail`
+  take only `<ws>`'s services, `manifest_validate` takes only an absolute path
+  inside one of its repos (or the content), and `workspace_sync` syncs `<ws>`.
+  Tests run against the focused workspace, so `tests_available` and
+  `run_tests` are refused unless `<ws>` is the focused one.
+- **Not workspace data**, served as unscoped: `environments`,
+  `security_latest`, `release_status` and `edge_status` (the org's and the
+  distribution's, not a workspace's).
+- **Stamped.** Every web API call carries `x-den-mcp-agent: agent:<id>` and
+  `x-den-mcp-workspace: <ws>` beside the usual audit headers. The activity
+  entry gains `agent` and `workspace`, and the log line reads `· by
+agent:<id> <client> <version> (workspace <ws>, mcp pid <pid>, session
+<id>)` for every exec, run and sync.
+- `<ws>` must exist in this distribution; until it does, every tool says so.
+  The id is letters, digits, dots, dashes and underscores (at most 64). A bad
+  or half-given scope is a usage error, exit 2. `--list` and `--call` take
+  the scope too.
+
+**It binds cooperating agents only.** The scope lives in the MCP server's
+process. The web server's HTTP API does not check it yet, so an agent that
+calls the API itself (curl, a browser) is not held to its workspace. Enforcing
+the scope in the HTTP server is WS-3a, planned for 0.4. `mcp connect` still
+registers the unscoped server; to hand one agent a scoped server, add it to
+that agent's config yourself, for example in a project's `.mcp.json`:
+`"args": ["mcp", "--workspace", "smb", "--actor", "agent:planner"]`.
+
 ### One call from a shell
 
 ```sh

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@monster-orange/den",
-  "version": "0.2.7",
+  "version": "0.2.8",
   "description": "Den: a local multi-repo dev orchestrator, HTTPS edge and E2E harness",
   "type": "module",
   "bin": {

package/src/shared/agent-actor.ts

@@ -12,8 +12,20 @@ export const AUDIT_HEADERS = {
   clientVersion: "x-den-mcp-client-version",
   pid: "x-den-mcp-pid",
   session: "x-den-mcp-session",
+  /** A scoped server's actor id (`agent:<id>`, AG-2a-core). */
+  agent: "x-den-mcp-agent",
+  /** The workspace a scoped server is pinned to (AG-2a-core). */
+  workspace: "x-den-mcp-workspace",
 } as const;
 
+/**
+ * `agent:<id>`: what `<cli> mcp --actor` takes. The id is letters, digits,
+ * dots, dashes and underscores, 1-64 long, starting with a letter or digit.
+ */
+export const AGENT_ACTOR_RE = /^agent:[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/;
+/** A workspace name, as the config accepts it (1-64 long here). */
+export const WORKSPACE_NAME_RE = /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/;
+
 export interface AgentInfo {
   /** The MCP client's self-reported name (clientInfo.name). */
   client: string;
@@ -23,6 +35,10 @@ export interface AgentInfo {
   mcpPid: number | null;
   /** The MCP server's session id (one per `<cli> mcp` process). */
   session: string;
+  /** A scoped server's actor (`agent:<id>`); absent when unscoped. */
+  agent?: string;
+  /** The workspace a scoped server is pinned to; absent when unscoped. */
+  workspace?: string;
 }
 
 export interface AgentActor extends AgentInfo {
@@ -49,6 +65,13 @@ export function agentAuditHeaders(info: AgentInfo): Record<string, string> {
     [AUDIT_HEADERS.clientVersion]: clean(info.clientVersion) || "unknown",
     [AUDIT_HEADERS.pid]: info.mcpPid === null ? "" : String(info.mcpPid),
     [AUDIT_HEADERS.session]: clean(info.session).replace(/[^A-Za-z0-9-]/g, ""),
+    // Only a scoped server sends these: an unscoped one's headers are as before.
+    ...(info.agent && AGENT_ACTOR_RE.test(info.agent)
+      ? { [AUDIT_HEADERS.agent]: info.agent }
+      : {}),
+    ...(info.workspace && WORKSPACE_NAME_RE.test(info.workspace)
+      ? { [AUDIT_HEADERS.workspace]: info.workspace }
+      : {}),
   };
 }
 
@@ -59,19 +82,31 @@ export function actorFromHeaders(
   const h = headers as Record<string, string | string[] | undefined>;
   if (clean(h[AUDIT_HEADERS.actor]) !== "agent") return null;
   const pid = clean(h[AUDIT_HEADERS.pid], 10);
+  // Kept only when well-formed: a malformed value is dropped, never cleaned
+  // into something that looks like another agent's id.
+  const agent = clean(h[AUDIT_HEADERS.agent], 80);
+  const workspace = clean(h[AUDIT_HEADERS.workspace], 80);
   return {
     kind: "agent",
     client: clean(h[AUDIT_HEADERS.client]) || "unknown",
     clientVersion: clean(h[AUDIT_HEADERS.clientVersion], 32) || "unknown",
     mcpPid: /^\d+$/.test(pid) ? Number(pid) : null,
     session: clean(h[AUDIT_HEADERS.session]).replace(/[^A-Za-z0-9-]/g, ""),
+    ...(AGENT_ACTOR_RE.test(agent) ? { agent } : {}),
+    ...(WORKSPACE_NAME_RE.test(workspace) ? { workspace } : {}),
   };
 }
 
-/** "agent <client> <version> (mcp pid <pid>, session <id>)". */
+/**
+ * "agent <client> <version> (mcp pid <pid>, session <id>)"; a scoped
+ * server's actor leads: "agent:<id> <client> <version> (workspace <ws>,
+ * mcp pid <pid>, session <id>)".
+ */
 export function actorLabel(actor: AgentActor): string {
+  const who = actor.agent ?? "agent";
+  const ws = actor.workspace ? `workspace ${actor.workspace}, ` : "";
   return (
-    `agent ${actor.client} ${actor.clientVersion} ` +
-    `(mcp pid ${actor.mcpPid ?? "?"}, session ${actor.session || "?"})`
+    `${who} ${actor.client} ${actor.clientVersion} ` +
+    `(${ws}mcp pid ${actor.mcpPid ?? "?"}, session ${actor.session || "?"})`
   );
 }

package/src/shared/config-error.ts

@@ -0,0 +1,33 @@
+/**
+ * A distribution config that fails validation (ORG-1d's `orgs:` checks, for
+ * now). It is the user's to fix, not a crash: the CLI prints it and exits 1
+ * before doing anything, and the web server answers it as
+ * `{ ok: false, error, code: "config_invalid" }` with status 422.
+ *
+ * The message names config keys (`orgs.initech.repos`), never values a
+ * secret could hide in.
+ */
+export class ConfigError extends Error {
+  readonly code = "config_invalid";
+
+  constructor(message: string) {
+    super(message);
+    this.name = "ConfigError";
+  }
+}
+
+export function isConfigError(e: unknown): e is ConfigError {
+  return e instanceof ConfigError;
+}
+
+/** The web server's status for a ConfigError: the request was fine, the config is not. */
+export const CONFIG_ERROR_STATUS = 422;
+
+/** The JSON body for a ConfigError (the `{ok, error, code}` frame R26 extends). */
+export function configErrorBody(e: ConfigError): {
+  ok: false;
+  error: string;
+  code: "config_invalid";
+} {
+  return { ok: false, error: e.message, code: e.code };
+}

package/src/shared/den-config.ts

@@ -16,6 +16,8 @@ import type { Environment, ReleaseSourceConfig } from "./types/index.js";
 import { getDistRoot } from "./paths.js";
 import type { SecretsConfig } from "./secrets/index.js";
 import type { OrgConfig } from "./org.js";
+import { validateOrgSources, type WorkOrgsConfig } from "./org-sources.js";
+import { ConfigError, isConfigError } from "./config-error.js";
 import type { TestAccountsConfig } from "./auth/test-accounts.js";
 
 import { product } from "./product.js";
@@ -194,11 +196,13 @@ export interface DenConfig {
   /** GitHub org slug used to list org repos in the web UI (e.g. "Globex-Corp"). */
   github_org?: string;
   /**
-   * Display names (and an optional colour) for the GitHub orgs repos belong
-   * to, keyed by GitHub owner. Orgs are worked out from the catalog; this
-   * only names them.
+   * Work orgs, keyed by org id: a display name and an optional colour. An
+   * entry with neither `sources` nor `repos` is the GitHub owner of its own
+   * name (ORG-1a). ORG-1d: `sources: [{host, owner|group}]` binds the org to
+   * git-host owners, and `repos: [...]` lists repos outright. See
+   * src/shared/org-sources.ts.
    */
-  orgs?: Record<string, { label?: string; color?: string }>;
+  orgs?: WorkOrgsConfig;
   /** Derived-dependency-graph tuning (aliases + edge overrides). */
   graph?: GraphConfig;
   /**
@@ -412,6 +416,41 @@ export function requireGithubOrg(config: DenConfig = readDenConfig()): string {
   return org;
 }
 
+let checked: { key: string; error: ConfigError | null } | null = null;
+
+/**
+ * Throw the config's validation error (a ConfigError naming its keys), if it
+ * has one, without reading anything else. The CLI runs this before any
+ * command that touches orgs, the catalog, clones or releases, and the web
+ * server before every config-reading route, so a config that fails
+ * validation stops them all, not only those that happen to read `orgs:`.
+ * A missing file, or one that does not parse, is left to readDenConfig.
+ * Memoised on the file's mtime and size: the server checks per request.
+ */
+export function assertDenConfigValid(): void {
+  let key: string;
+  try {
+    const st = fs.statSync(DEN_CONFIG_PATH);
+    key = `${st.mtimeMs}:${st.size}`;
+  } catch {
+    return;
+  }
+  if (checked?.key !== key) {
+    let error: ConfigError | null = null;
+    try {
+      const parsed = yaml.parse(fs.readFileSync(DEN_CONFIG_PATH, "utf-8")) as {
+        orgs?: unknown;
+      } | null;
+      validateOrgSources(parsed?.orgs, product().configFile);
+    } catch (e) {
+      if (!isConfigError(e)) return;
+      error = e;
+    }
+    checked = { key, error };
+  }
+  if (checked.error) throw new ConfigError(checked.error.message);
+}
+
 /**
  * Read the effective den config, merging the shared deployment config with
  * per-engineer overrides from config/local/user.yml.
@@ -422,6 +461,9 @@ export function readDenConfig(): DenConfig {
   try {
     const raw = fs.readFileSync(DEN_CONFIG_PATH, "utf-8");
     const parsed = yaml.parse(raw) as Partial<DenConfig> | null;
+    // ORG-1d keys (orgs.<id>.sources / .repos) are checked here, where a bad
+    // value throws naming its key; configs without them are not touched.
+    validateOrgSources(parsed?.orgs, product().configFile);
     // `environments` may be malformed (scalar/object) in a hand-edited file —
     // fall back to the default set rather than throwing on .filter below.
     const envs = Array.isArray(parsed?.environments)

package/src/shared/environment-manager/catalog.ts

@@ -14,7 +14,13 @@ import * as path from "path";
 import * as yaml from "yaml";
 import type { ServiceCatalog, ServiceCatalogEntry } from "../types/index.js";
 import { getDistRoot } from "../paths.js";
-import { requireGithubOrg } from "../den-config.js";
+import { readDenConfig, requireGithubOrg } from "../den-config.js";
+import {
+  parseRemote,
+  repoSource,
+  type WorkOrgsConfig,
+} from "../org-sources.js";
+import { checkedRemote, isGitRemote } from "./git-remote.js";
 
 /** Fallback GitHub org when `config/den.yml` doesn't set `github_org`. */
 
@@ -77,6 +83,51 @@ export function resolveRepoGhSlug(
   return `${owner()}/${repoName}`;
 }
 
+/**
+ * What `repoName` clones from (ORG-1d): a GitHub slug or a git URL (see
+ * git-remote.ts). The repo's source decides: a GitHub source gives its slug
+ * (`gh`, else `<owner>/<repo>`). A repo with no source and a `remote:` gives
+ * that remote, through plain git. Anything else is the legacy GitHub slug
+ * (resolveRepoGhSlug), so a catalog without `remote:` clones as before.
+ */
+export function resolveRepoCloneSource(
+  repoName: string,
+  catalog: ServiceCatalog = readCatalog(),
+  owner: () => string = () => requireGithubOrg(),
+  orgs: WorkOrgsConfig | undefined = readDenConfig().orgs,
+): string {
+  const entry = catalog[repoName];
+  const gh = entry?.gh?.trim();
+  const remote = entry?.remote?.trim();
+  const src = repoSource(repoName, catalog, orgs ?? {});
+  if (src?.host === "github") {
+    if (gh) return gh;
+    const fromRemote = remote ? parseRemote(remote) : null;
+    return fromRemote?.host === "github"
+      ? `${fromRemote.owner}/${repoName}`
+      : `${src.owner ?? ""}/${repoName}`;
+  }
+  if (remote) return checkedRemote(repoName, remote);
+  if (src)
+    throw new Error(
+      `${repoName}: its org's source is on ${src.host}, which Den clones only ` +
+        `from a remote: — set ${repoName}.remote in the service catalog`,
+    );
+  return resolveRepoGhSlug(repoName, catalog, owner);
+}
+
+/**
+ * Whether a clone source may be written back as the catalog's `gh` (the
+ * empty-slug repair): only a GitHub slug, and only for an entry with no
+ * `gh` and no `remote` of its own.
+ */
+export function needsGhRepair(
+  entry: ServiceCatalogEntry | undefined,
+  source: string,
+): boolean {
+  return !isGitRemote(source) && !entry?.gh?.trim() && !entry?.remote?.trim();
+}
+
 export function removeCatalogEntry(repoName: string): void {
   const catalog = readCatalog();
   delete catalog[repoName];

package/src/shared/environment-manager/default-workspace.ts

@@ -22,8 +22,10 @@ import {
 import {
   githubOrgFor,
   readOrgContext,
+  resolveWorkspaceOrg,
   type OrgContext,
 } from "./workspace-org.js";
+import { orgHasGithub } from "../org-sources.js";
 import type {
   ServiceCatalog,
   WorkspaceConfig,
@@ -83,11 +85,17 @@ export function catalogFill(
   ctx: OrgContext = readOrgContext(),
 ): Map<string, string> {
   const fill = new Map<string, string>();
-  for (const ws of workspaces)
+  for (const ws of workspaces) {
+    // ORG-1d: an org with no GitHub source has no slug to give; its repos
+    // clone from their catalog `remote:`.
+    const org = resolveWorkspaceOrg(ws.name, ctx).org;
+    if (org && !orgHasGithub(org, ctx.config.orgs)) continue;
     for (const repo of ws.repos) {
-      if (catalog[repo]?.gh || fill.has(repo)) continue;
+      if (catalog[repo]?.gh || catalog[repo]?.remote || fill.has(repo))
+        continue;
       fill.set(repo, `${githubOrgFor(ws.name, ctx)}/${repo}`);
     }
+  }
   return fill;
 }
 

package/src/shared/environment-manager/git-remote.ts

@@ -0,0 +1,49 @@
+/**
+ * What a managed clone is made from (ORG-1d): a GitHub slug (`owner/repo`,
+ * cloned from github.com with the user's gh as credential helper) or a git
+ * URL from the catalog's `remote:` (cloned through plain git and the user's
+ * own credential helper, never Den's or gh's: SEC-0).
+ *
+ * Clone commands run through a shell, so a remote must pass REMOTE_RE: a URL
+ * with a known transport, scp-style `user@host:path`, or an absolute path,
+ * and nothing a shell or git would read as a command (`ext::`, quotes, `$`,
+ * spaces, a leading `-`).
+ */
+
+/** A GitHub slug, as the clone guards accept it. */
+export const SAFE_SLUG_RE = /^[a-zA-Z0-9._-]+\/[a-zA-Z0-9._-]+$/;
+
+const REMOTE_RE =
+  /^(?:(?:https?|ssh|git|file):\/\/[A-Za-z0-9._~@:%+/-]+|[A-Za-z0-9._-]+@[A-Za-z0-9.-]+:[A-Za-z0-9._~+/-]+|\/[A-Za-z0-9._~@+/-]+)$/;
+
+/** True when `spec` is a git URL rather than a GitHub slug. */
+export function isGitRemote(spec: string): boolean {
+  return !SAFE_SLUG_RE.test(spec);
+}
+
+/** True when `remote` is a git URL Den will hand to git. */
+export function isSafeRemote(remote: string): boolean {
+  return REMOTE_RE.test(remote) && !remote.includes("..");
+}
+
+/**
+ * `remote` for display: any user info (`https://user:token@host/…`) masked.
+ * Remotes can carry a token, so one is never printed as written.
+ */
+export function redactRemote(remote: string): string {
+  return remote.replace(/^([a-z+]+:\/\/)[^@/]+@/i, "$1***@");
+}
+
+/**
+ * The checked remote for `repo`, or a throw naming its catalog key (and not
+ * its value, which may hold a token).
+ */
+export function checkedRemote(repo: string, remote: string): string {
+  const r = remote.trim();
+  if (!isSafeRemote(r))
+    throw new Error(
+      `service catalog: ${repo}.remote is not a git URL Den can clone ` +
+        `(https://, ssh://, git://, file://, user@host:path or an absolute path)`,
+    );
+  return r;
+}