maesttro 0.2.1 → 0.3.0

package/README.md

@@ -58,9 +58,10 @@ maesttro doctor                          # health check anytime
 
 maesttro                                 # from a repo root: new session clone + default client (opencode)
 maesttro opencode                        # same, with opencode
+maesttro --strict [client]               # same, with no GitHub token in the runner (no `gh`)
 maesttro bash                            # plain shell inside the runner, for debugging
 maesttro sessions                        # list this repo's kept sessions
-maesttro resume <id>                     # continue one
+maesttro resume <id>                     # continue one, in the mode it started with
 maesttro push [branch]                   # push a branch a session created (shows what goes out, asks first)
 
 maesttro update                          # bump the package + rebuild image with refreshed configs
@@ -106,6 +107,15 @@ comments). It acts as the Maesttro GitHub App's bot:
 - Commits are authored by you (your repo's `user.name` / `user.email`) and committed by the bot.
 - The broker is reached over the tailnet. Off the tailnet, the session still starts, just without `gh`.
 
+The write side is coarse. GitHub has no finer grant than "issues" and "pull
+requests", so the same token that lets the agent comment and open PRs also lets
+it edit label definitions and milestones, edit or close other people's issues and
+comments, and submit reviews. If that is more than you want to hand an agent,
+start the session with `maesttro --strict`: no token is minted and none reaches
+the runner. Local git and `maesttro push` work as usual; `gh` and `git fetch` on a
+private repo don't, and the agent hands GitHub actions to you instead. Resuming a
+strict session stays strict; `maesttro resume <id> --no-strict` lifts it.
+
 ## Your instructions come along
 
 At every container start, `maesttro configure` copies your host
@@ -169,7 +179,7 @@ untouched by an update.
 | Mount | Source | Purpose |
 |---|---|---|
 | `/home/agent` | `maesttro-home` named volume | Per-client session state. Survives across runs, lives only in Docker. Holds no GitHub credential. |
-| `/home/agent/.config/gh-maesttro` (read-only) | per-session temp dir on host | The session's GitHub token (`hosts.yml`). The CLI refreshes it before its 1 h expiry and revokes it on exit. |
+| `/home/agent/.config/gh-maesttro` (read-only) | per-session temp dir on host | The session's GitHub token (`hosts.yml`). The CLI refreshes it before its 1 h expiry and revokes it on exit. Not mounted in `--strict` sessions, or when GitHub access is unavailable. |
 | `<repo>/.git/objects` (read-only, same absolute path) | your repo's object store | Base history, borrowed by the clone through its `alternates`. The real `.git` is never mounted. |
 | `/workspace` | the session clone (`.worktrees/<id>`) | The working directory: a `git clone --shared` detached at the default branch. |
 | `/opt/maesttro`, `/opt/maesttro-host` (read-only) | this package; your instruction files | Used by `maesttro configure` at container start. |

package/dist/maesttro.js

@@ -730,22 +730,41 @@ var IMAGE = "maesttro-runner:latest";
 var VOLUME = process.env.MAESTTRO_VOLUME?.trim() || "maesttro-home";
 
 // src/runner-context.ts
+function githubMode(value) {
+  return value === "on" || value === "strict" ? value : "off";
+}
+function githubRules(context) {
+  switch (context.github) {
+    case "on":
+      return [
+        `- \`gh\` works for ${context.repo ?? "this repo"} only: issues, pull requests, comments. Its token is short-lived and refreshed for you.`,
+        "- Merging pull requests and deleting remote branches are not possible from here. A person merges."
+      ];
+    case "strict":
+      return [
+        "- This session runs in strict mode: GitHub is disabled on purpose and the runner holds no GitHub credentials. `gh` does not work, and `git fetch` fails for private repositories.",
+        "- Do not look for credentials or ask the user for a token. Local git work still works.",
+        "- When a task needs GitHub (an issue, a pull request, a comment, a review, a label), write out what should be posted and hand it to the user."
+      ];
+    case "off":
+      return [
+        "- GitHub access is unavailable in this session, so `gh` has no token. Local git work still works."
+      ];
+  }
+}
+function afterPushRule(github) {
+  return github === "on" ? "- After the user confirms it is pushed, `git fetch` and continue. Open the pull request with `gh pr create --head <branch>` if asked to." : "- After the user confirms it is pushed, continue on the same branch. The user opens the pull request.";
+}
 function runnerContextFromEnv(env) {
   return {
     sessionId: env.MAESTTRO_SESSION_ID,
     base: env.MAESTTRO_BASE,
     repo: env.MAESTTRO_REPO,
-    githubAccess: env.MAESTTRO_GITHUB === "on"
+    github: githubMode(env.MAESTTRO_GITHUB)
   };
 }
 function runnerInstructions(context) {
   const base = context.base ?? "the default branch";
-  const github = context.githubAccess ? [
-    `- \`gh\` works for ${context.repo ?? "this repo"} only: issues, pull requests, comments. Its token is short-lived and refreshed for you.`,
-    "- Merging pull requests and deleting remote branches are not possible from here. A person merges."
-  ] : [
-    "- GitHub access is unavailable in this session, so `gh` has no token. Local git work still works."
-  ];
   return [
     "# Maesttro runner",
     "",
@@ -762,11 +781,11 @@ function runnerInstructions(context) {
     "",
     "- `git push` does not work here: the runner has read-only access to the remote. This is deliberate.",
     '- When a branch is ready, commit everything, then tell the user: "Ready to push: <branch>. Run `maesttro push <branch>` from the repository root."',
-    "- After the user confirms it is pushed, `git fetch` and continue. Open the pull request with `gh pr create --head <branch>` if asked to.",
+    afterPushRule(context.github),
     "",
     "## GitHub",
     "",
-    ...github,
+    ...githubRules(context),
     ""
   ].join(`
 `);
@@ -1187,7 +1206,10 @@ var HELP = `maesttro — isolated runner for local coding agents
 Usage:
   maesttro                Start a session from the repo root: new clone, default client (opencode)
   maesttro <client>        Same, with a specific client — see \`maesttro list\`
-  maesttro resume <id>     Continue a kept session in its clone
+  maesttro --strict [client]
+                          Same, in strict mode: no GitHub token reaches the runner, so \`gh\` is off
+  maesttro resume <id>     Continue a kept session in its clone, in the mode it started with
+                          (\`--strict\` or \`--no-strict\` after the id changes it)
   maesttro sessions        List this repo's sessions (\`sessions remove <id>\` to drop one)
   maesttro push [branch]   Push a branch a session created, after showing what goes out
   maesttro list            Show available clients
@@ -1420,6 +1442,7 @@ function createSessionDir(parent = tmpdir2()) {
 // src/github-session.ts
 var UNAVAILABLE = "GitHub access unavailable";
 var WITHOUT = "running without gh";
+var STRICT_NOTICE = "Strict mode: no GitHub token in the runner, so `gh` is off. Local git works; push with `maesttro push`.";
 function refusalNotice(code, repo) {
   switch (code) {
     case "broker_unreachable":
@@ -1462,6 +1485,7 @@ function errorCode(error) {
 function withoutGitHub(author, notice) {
   const env = {
     GH_CONFIG_DIR: CONTAINER_GH_CONFIG_DIR,
+    GIT_TERMINAL_PROMPT: "0",
     ...identityEnv(author, undefined)
   };
   return {
@@ -1474,12 +1498,15 @@ function withoutGitHub(author, notice) {
 async function openGitHubSession({
   repo,
   author,
+  strict = false,
   broker,
   login,
   log,
   fetch: fetchImpl = fetch,
   createDir = createSessionDir
 }) {
+  if (strict)
+    return withoutGitHub(author, STRICT_NOTICE);
   if (!repo)
     return withoutGitHub(author);
   const mint = async ({ interactive }) => {
@@ -2025,6 +2052,18 @@ Session ${session.id} kept. Continue with \`maesttro resume ${session.id}\`.`);
     console.log("You have commits on a detached HEAD. Resume and `git switch -c <name>` to keep them.");
   }
 }
+function isStrict(requested, session) {
+  return requested ?? session.strict ?? false;
+}
+function runnerGitHubMode({
+  strict,
+  repo,
+  notice
+}) {
+  if (strict)
+    return "strict";
+  return notice || !repo ? "off" : "on";
+}
 function exitCodeOf(code, signal) {
   if (code !== null)
     return code;
@@ -2033,7 +2072,8 @@ function exitCodeOf(code, signal) {
 var FORWARDED_SIGNALS = ["SIGINT", "SIGTERM", "SIGHUP"];
 async function launch({
   args,
-  resume
+  resume,
+  strict: requestedStrict
 }) {
   const run = runCommand;
   ensureReady();
@@ -2051,9 +2091,14 @@ async function launch({
     refs: snapshotRefs(run, root),
     sessionId: started.id
   });
-  const saved = { ...started, backup: started.backup ?? backup?.path };
+  const strict = isStrict(requestedStrict, started);
+  const saved = {
+    ...started,
+    backup: started.backup ?? backup?.path,
+    strict
+  };
   saveSession(saved);
-  console.log(`Session ${saved.id}: clone .worktrees/${saved.id} at ${saved.base}${backup ? `, backup ${backup.reused ? "reused" : "written"}` : ""}.`);
+  console.log(`Session ${saved.id}${strict ? " (strict)" : ""}: clone .worktrees/${saved.id} at ${saved.base}${backup ? `, backup ${backup.reused ? "reused" : "written"}` : ""}.`);
   const repo = workspaceRepo(run, root);
   if (repo && !resume) {
     git(run, saved.worktree, [
@@ -2066,6 +2111,7 @@ async function launch({
   const github = await openGitHubSession({
     repo,
     author: await resolveAuthor(root),
+    strict,
     broker: brokerUrl(),
     login: {
       clientId: githubAppClientId(),
@@ -2098,7 +2144,7 @@ async function launch({
     ...github.env,
     MAESTTRO_SESSION_ID: saved.id,
     MAESTTRO_BASE: saved.base,
-    MAESTTRO_GITHUB: github.notice || !repo ? "off" : "on",
+    MAESTTRO_GITHUB: runnerGitHubMode({ strict, repo, notice: github.notice }),
     ...hostIdentityEnv(),
     ...repo ? { MAESTTRO_REPO: repo } : {}
   };
@@ -2287,7 +2333,8 @@ function sessionsCommand({ args }) {
   for (const session of sessions) {
     const branches = existsSync5(session.worktree) ? cloneBranches(session.worktree) : undefined;
     const where = branches === undefined ? "clone missing" : branches.length > 0 ? `branches: ${branches.join(", ")}` : "no branches yet";
-    console.log(`  ${session.id}  ${session.createdAt.slice(0, 16)}  ${where}`);
+    const mode = session.strict ? "  strict" : "";
+    console.log(`  ${session.id}  ${session.createdAt.slice(0, 16)}  ${where}${mode}`);
   }
   console.log("\n`maesttro resume <id>` continues one; `maesttro sessions remove <id>` removes its clone.");
 }
@@ -2369,11 +2416,48 @@ var defaultCommands = {
   status,
   print: (text) => console.log(text)
 };
+var MODE_FLAGS = {
+  "--strict": true,
+  "--no-strict": false
+};
+function takeModeFlags(args) {
+  let strict;
+  let index = 0;
+  while (index < args.length && Object.hasOwn(MODE_FLAGS, args[index] ?? "")) {
+    strict = MODE_FLAGS[args[index] ?? ""];
+    index++;
+  }
+  return {
+    ...strict === undefined ? {} : { strict },
+    rest: args.slice(index)
+  };
+}
+var NOT_LAUNCHING = new Set([
+  "setup",
+  "update",
+  "doctor",
+  "login",
+  "logout",
+  "status",
+  "push",
+  "sessions",
+  "configure",
+  "list",
+  "help",
+  "--help",
+  "-h"
+]);
 async function main(argv, commands = defaultCommands) {
-  const [command, ...rest] = argv;
+  const leading = takeModeFlags(argv);
+  const [command, ...rest] = leading.rest;
+  const mode = leading.strict === undefined ? {} : { strict: leading.strict };
+  if (leading.strict !== undefined && command !== undefined && NOT_LAUNCHING.has(command)) {
+    commands.print(`--strict and --no-strict apply to launching a session, not to \`${command}\`.`);
+    return;
+  }
   switch (command) {
     case undefined:
-      await commands.launch({ args: [] });
+      await commands.launch({ args: [], ...mode });
       return;
     case "setup":
       await commands.setup({ args: rest });
@@ -2400,12 +2484,19 @@ async function main(argv, commands = defaultCommands) {
       await commands.sessions({ args: rest });
       return;
     case "resume": {
-      const [id, ...clientArgs] = rest;
+      const beforeId = takeModeFlags(rest);
+      const [id, ...afterId] = beforeId.rest;
+      const afterIdFlags = takeModeFlags(afterId);
+      const strict = afterIdFlags.strict ?? beforeId.strict ?? leading.strict;
       if (!id) {
-        commands.print("Usage: maesttro resume <session-id> [client] [args...]");
+        commands.print("Usage: maesttro resume <session-id> [--strict|--no-strict] [client] [args...]");
         return;
       }
-      await commands.launch({ args: clientArgs, resume: id });
+      await commands.launch({
+        args: afterIdFlags.rest,
+        resume: id,
+        ...strict === undefined ? {} : { strict }
+      });
       return;
     }
     case "configure":
@@ -2420,7 +2511,7 @@ async function main(argv, commands = defaultCommands) {
       commands.print(HELP);
       return;
     default:
-      await commands.launch({ args: argv });
+      await commands.launch({ args: leading.rest, ...mode });
   }
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "maesttro",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "description": "Isolated Docker runner for local coding agents (opencode, claude, ...) under a dedicated bot GitHub identity, with curated configs baked in per client.",
   "type": "module",
   "bin": {