mandrel 2.92.0 → 2.93.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -506,7 +506,7 @@ number of keys.
506
506
  | `delivery.quality.gates.maintainability.targetDirs` | `[".agents/scripts", "tests"]` | `["src"]` | Root scans the framework's own source tree; consumer template scans the conventional `src/`. |
507
507
  | `delivery.quality.gates.crap.targetDirs` | `[".agents/scripts"]` | `["src"]` | Same reason as maintainability above. |
508
508
  | `github.owner` / `.repo` / `.projectNumber` | Populated for `dsj1984/mandrel` | `[OWNER]` / `[REPO]` / `null` | Shared repo identifiers; placeholders in the template are replaced by `node .agents/scripts/bootstrap.js` (or by hand). |
509
- | `github.operatorHandle` | Committed as the `@[USERNAME]` placeholder; each contributor overrides it in gitignored `.agentrc.local.json` | `@[USERNAME]` | Schema-required, but per-contributor: the committed placeholder resolves to null and the lease guards fail closed until you set your own handle locally (see [Per-machine local overrides](#per-machine-local-overrides)). |
509
+ | `github.operatorHandle` | Committed as the `@[USERNAME]` placeholder; each contributor overrides it in gitignored `.agentrc.local.json`, or with `GH_OPERATOR_HANDLE` where there is no overlay (cloud sessions) | `@[USERNAME]` | Schema-required, but per-contributor: the committed placeholder resolves to null and the lease guards fail closed until you set your own handle locally (see [Per-machine local overrides](#per-machine-local-overrides)). |
510
510
  | `delivery.worktreeIsolation.nodeModulesStrategy` | `clone` | `clone` | Platform default on darwin/linux (copy-on-write clone of donor `node_modules`); Windows dogfood/template use `per-worktree`. |
511
511
 
512
512
  When a consumer runs `/mandrel-update`, the
@@ -664,6 +664,39 @@ makes one developer the fallback identity for everyone else.
664
664
  Otherwise a developer without an overlay silently seeds Story branches from,
665
665
  and opens PRs against, `main`.
666
666
 
667
+ **Environment override.** `GH_OPERATOR_HANDLE` beats both files: when it is
668
+ set, the resolver uses it as `github.operatorHandle`, so precedence is
669
+ `GH_OPERATOR_HANDLE` → `.agentrc.local.json` → `.agentrc.json`. A bare login
670
+ gets its `@` prefix added, an empty value is ignored, and a `.env` entry
671
+ works too. The override only applies when the config already has a `github`
672
+ block. It is the same variable `bootstrap.js` reads for the handle.
673
+
674
+ #### Claude Code cloud environments
675
+
676
+ A cloud session clones the repo without the gitignored `.agentrc.local.json`,
677
+ so it has only the committed `@[USERNAME]` placeholder, or whatever handle
678
+ the team committed. Each person has their own cloud environment, so one
679
+ environment variable identifies one person:
680
+
681
+ - Add `GH_OPERATOR_HANDLE=your-github-login` to your cloud environment's
682
+ **Environment variables**. Use your own user login, never an Organization
683
+ or team. Don't write `.agentrc.local.json` from a setup script instead: the
684
+ script runs once, and later sessions start from a cached snapshot that
685
+ skips it.
686
+ - Leave `GITHUB_TOKEN` and `GH_TOKEN` unset. Every GitHub request from a
687
+ hosted cloud session goes through the Claude Code GitHub proxy, which
688
+ supplies your connected GitHub account's credential for REST calls.
689
+
690
+ The proxy answers **all** GitHub GraphQL with HTTP 403, even when you set
691
+ your own token. Projects v2 is GraphQL-only, so board Status never syncs
692
+ from a cloud session. Labels stay authoritative, and each skipped Status flip
693
+ is reported as a warning.
694
+
695
+ The handle has to be a user who can be assigned. GitHub's add-assignees
696
+ endpoint silently ignores a login it cannot assign, such as an Organization,
697
+ a team, or a user with no access to the repo. When that happens the Story
698
+ lease refuses with `not-assignable` rather than running a Story nobody holds.
699
+
667
700
  ### Adding a new top-level key (framework change)
668
701
 
669
702
  This is a framework-level change, not a project-level one. The path is:
@@ -699,6 +732,7 @@ Claude Code web environment-variables UI for web sessions.
699
732
  | Variable | Required? | Purpose |
700
733
  | -------------------------- | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
701
734
  | `GITHUB_TOKEN` | Yes\* | GitHub API auth for all ticketing operations. `GH_TOKEN` is accepted as a synonym. `gh auth token` is a fallback for local sessions. |
735
+ | `GH_OPERATOR_HANDLE` | No | Overrides `github.operatorHandle` (the lease owner and @mention handle). Set it where there is no `.agentrc.local.json`, such as a Claude Code cloud environment. See [Claude Code cloud environments](#claude-code-cloud-environments). |
702
736
  | `NOTIFICATION_WEBHOOK_URL` | No | POST target for in-band Notifier events (Make.com / Slack / Discord). Unset disables the webhook channel; the GitHub comment channel still fires. |
703
737
  | `WEBHOOK_SECRET` | No | Shared secret used to sign outbound webhook payloads as `X-Signature-256: sha256=<hmac>`. Unset ships unsigned payloads. |
704
738
  | `MANDREL_ALLOW_TEST_WEBHOOKS` | No | Set to `1` to keep `NOTIFICATION_WEBHOOK_URL` live inside `npm test` / `npm run test:profile`. Default behaviour scrubs the env var from the test child so no URL resolves and the webhook never fires (see below). |
@@ -3,6 +3,8 @@
3
3
  * `/agents-bootstrap-github` registers as required-status checks.
4
4
  */
5
5
 
6
+ import { isObject } from '../json-utils.js';
7
+
6
8
  /** Keep in sync with the job names in `.github/workflows/ci.yml`. */
7
9
  export const DEFAULT_REQUIRED_CHECKS = Object.freeze([
8
10
  Object.freeze({
@@ -107,3 +109,19 @@ export function getGitHub(config) {
107
109
  },
108
110
  };
109
111
  }
112
+
113
+ /**
114
+ * `GH_OPERATOR_HANDLE` beats `github.operatorHandle` (cloud sessions have no
115
+ * `.agentrc.local.json`). Only an existing `github` block is touched: a lone
116
+ * handle would fail its required `owner` / `repo`.
117
+ */
118
+ export function applyOperatorHandleEnv(read, env = process.env) {
119
+ const handle = String(env.GH_OPERATOR_HANDLE ?? '').trim();
120
+ const github = read.raw?.github;
121
+ if (handle.length === 0 || !isObject(github)) return read;
122
+ const operatorHandle = handle.startsWith('@') ? handle : `@${handle}`;
123
+ return {
124
+ ...read,
125
+ raw: { ...read.raw, github: { ...github, operatorHandle } },
126
+ };
127
+ }
@@ -13,7 +13,7 @@ import {
13
13
  import { getCiDelivery } from './config/ci.js';
14
14
  import { getCommands } from './config/commands.js';
15
15
  import { overlayRoot, resolveAgentrcRoot } from './config/git-roots.js';
16
- import { getGitHub } from './config/github.js';
16
+ import { applyOperatorHandleEnv, getGitHub } from './config/github.js';
17
17
  import { resolvePaths } from './config/paths.js';
18
18
  import { validateOrchestrationConfig } from './config/validate-orchestration.js';
19
19
  import { getWorktreeIsolation } from './config/worktree-isolation.js';
@@ -217,7 +217,7 @@ export function resolveConfig(opts) {
217
217
  }
218
218
  ensureEnvLoaded(root);
219
219
  const resolved = finalizeConfig(
220
- readRawConfig(injectedFs ?? fs, root),
220
+ applyOperatorHandleEnv(readRawConfig(injectedFs ?? fs, root)),
221
221
  validate,
222
222
  );
223
223
  if (!injectedFs) _cacheByKey.set(key, resolved);
@@ -37,7 +37,7 @@ export function resolveOperatorFromCandidates({
37
37
 
38
38
  /**
39
39
  * Acquire a lease; a foreign claim without `steal` throws the surface's
40
- * refusal.
40
+ * refusal; a result's own `message` wins.
41
41
  *
42
42
  * @param {object} opts
43
43
  * @param {object} opts.provider
@@ -62,7 +62,7 @@ export async function acquireLeaseFailClosed({
62
62
  steal,
63
63
  });
64
64
  if (!result.acquired) {
65
- throw new Error(renderRefusal(result, ticketId));
65
+ throw new Error(result.message ?? renderRefusal(result, ticketId));
66
66
  }
67
67
  return result;
68
68
  }
@@ -26,7 +26,8 @@ export function resolveOperator(config) {
26
26
  'github.operatorHandle is unset or still the shipped `@[USERNAME]` ' +
27
27
  'placeholder, so the standalone Story lease has no owner. Set your own ' +
28
28
  'handle in .agentrc.local.json (e.g. { "github": { "operatorHandle": ' +
29
- '"@your-login" } }) and re-run.',
29
+ '"@your-login" } }), or GH_OPERATOR_HANDLE in the environment where ' +
30
+ 'there is no .agentrc.local.json (cloud sessions), and re-run.',
30
31
  });
31
32
  }
32
33
 
@@ -42,6 +42,12 @@ export function currentOwner(assignees) {
42
42
  return assignees[0];
43
43
  }
44
44
 
45
+ /** GitHub returns the canonical-case login; the configured handle may differ. */
46
+ function sameLogin(a, b) {
47
+ if (typeof a !== 'string' || typeof b !== 'string') return false;
48
+ return a.toLowerCase() === b.toLowerCase();
49
+ }
50
+
45
51
  /**
46
52
  * @param {string} op
47
53
  * @param {object} opts
@@ -74,9 +80,10 @@ function normaliseOpts(op, opts) {
74
80
  * @param {boolean} [opts.steal=false] Transfer a foreign claim.
75
81
  * @returns {Promise<{
76
82
  * acquired: boolean,
77
- * owner: string,
83
+ * owner: string|null,
78
84
  * previousOwner: string|null,
79
- * reason: 'unclaimed'|'already-held'|'stolen'|'held'|'lost-race',
85
+ * reason: 'unclaimed'|'already-held'|'stolen'|'held'|'lost-race'|'not-assignable',
86
+ * message?: string,
80
87
  * }>}
81
88
  */
82
89
  export async function acquireLease(opts) {
@@ -96,7 +103,7 @@ export async function acquireLease(opts) {
96
103
  });
97
104
  }
98
105
 
99
- if (owner === operator) {
106
+ if (sameLogin(owner, operator)) {
100
107
  return {
101
108
  acquired: true,
102
109
  owner: operator,
@@ -123,18 +130,6 @@ export async function acquireLease(opts) {
123
130
  });
124
131
  }
125
132
 
126
- /**
127
- * Write, then re-read with `fresh: true`; on a foreign co-assignee, back out
128
- * and report `lost-race` so the loser never builds the winner's worktree.
129
- *
130
- * @param {object} args
131
- * @param {object} args.provider
132
- * @param {number} args.ticketId
133
- * @param {string} args.operator
134
- * @param {string|null} args.previousOwner
135
- * @param {string} args.reason Success reason when the claim holds.
136
- * @returns {Promise<{ acquired: boolean, owner: string, previousOwner: string|null, reason: string }>}
137
- */
138
133
  /**
139
134
  * Additive for an unowned ticket — a replacing PATCH would evict a
140
135
  * simultaneous claimer, hiding the collision verify keys on. Replacing only
@@ -149,6 +144,55 @@ function claimMutation(operator, previousOwner) {
149
144
  return { assignees: [operator] };
150
145
  }
151
146
 
147
+ function notAssignableMessage(operator, ticketId) {
148
+ return (
149
+ `ticket lease: GitHub silently dropped @${operator} as an assignee of ` +
150
+ `#${ticketId} — the handle is an Organization or team, or has no access ` +
151
+ 'to the repo, so the lease cannot be held. Set github.operatorHandle (or ' +
152
+ 'GH_OPERATOR_HANDLE in a cloud environment) to the GitHub user who runs ' +
153
+ 'this session, and re-run.'
154
+ );
155
+ }
156
+
157
+ /** No foreign login: an empty re-read means GitHub dropped the operator. */
158
+ async function settleUncontested({
159
+ provider,
160
+ ticketId,
161
+ operator,
162
+ previousOwner,
163
+ reason,
164
+ assignees,
165
+ }) {
166
+ if (assignees.length > 0) {
167
+ return { acquired: true, owner: operator, previousOwner, reason };
168
+ }
169
+ if (previousOwner !== null) {
170
+ await provider
171
+ .updateTicket(ticketId, { assignees: [previousOwner] })
172
+ .catch(() => undefined);
173
+ }
174
+ return {
175
+ acquired: false,
176
+ owner: null,
177
+ previousOwner,
178
+ reason: 'not-assignable',
179
+ message: notAssignableMessage(operator, ticketId),
180
+ };
181
+ }
182
+
183
+ /**
184
+ * Write, then re-read with `fresh: true`; on a foreign co-assignee, back out
185
+ * and report `lost-race` so the loser never builds the winner's worktree. An
186
+ * empty re-read is `not-assignable`: GitHub ignores an unassignable login.
187
+ *
188
+ * @param {object} args
189
+ * @param {object} args.provider
190
+ * @param {number} args.ticketId
191
+ * @param {string} args.operator
192
+ * @param {string|null} args.previousOwner
193
+ * @param {string} args.reason Success reason when the claim holds.
194
+ * @returns {Promise<{ acquired: boolean, owner: string|null, previousOwner: string|null, reason: string }>}
195
+ */
152
196
  async function claimAndVerify({
153
197
  provider,
154
198
  ticketId,
@@ -160,10 +204,17 @@ async function claimAndVerify({
160
204
 
161
205
  const after = await provider.getTicket(ticketId, { fresh: true });
162
206
  const assignees = Array.isArray(after?.assignees) ? after.assignees : [];
163
- const foreign = assignees.filter((login) => login !== operator);
207
+ const foreign = assignees.filter((login) => !sameLogin(login, operator));
164
208
 
165
209
  if (foreign.length === 0) {
166
- return { acquired: true, owner: operator, previousOwner, reason };
210
+ return settleUncontested({
211
+ provider,
212
+ ticketId,
213
+ operator,
214
+ previousOwner,
215
+ reason,
216
+ assignees,
217
+ });
167
218
  }
168
219
 
169
220
  // Lost the race: leave the winner as sole assignee.
@@ -196,7 +247,7 @@ export async function releaseLease(opts) {
196
247
  const ticket = await provider.getTicket(ticketId);
197
248
  const owner = currentOwner(ticket?.assignees);
198
249
 
199
- if (owner !== operator) {
250
+ if (!sameLogin(owner, operator)) {
200
251
  return { released: false, owner, reason: 'not-held' };
201
252
  }
202
253
 
package/docs/CHANGELOG.md CHANGED
@@ -15,6 +15,13 @@ All notable changes to this project will be documented in this file.
15
15
  -->
16
16
  <!-- markdownlint-disable-file MD004 MD012 MD037 -->
17
17
 
18
+ ## [2.93.0](https://github.com/dsj1984/mandrel/compare/mandrel-v2.92.0...mandrel-v2.93.0) (2026-10-19)
19
+
20
+
21
+ ### Added
22
+
23
+ * fail the Story lease closed when GitHub silently drops the operator, and let cloud sessions supply the operator handle via GH_OPERATOR_HANDLE ([#5788](https://github.com/dsj1984/mandrel/issues/5788)) ([#5789](https://github.com/dsj1984/mandrel/issues/5789)) ([6acb901](https://github.com/dsj1984/mandrel/commit/6acb901cf34ef312f7eb18e0f3eb3053697f65f0))
24
+
18
25
  ## [2.92.0](https://github.com/dsj1984/mandrel/compare/mandrel-v2.91.0...mandrel-v2.92.0) (2026-10-18)
19
26
 
20
27
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "mandrel",
3
- "version": "2.92.0",
3
+ "version": "2.93.0",
4
4
  "description": "Claude Code-first opinionated workflow framework: instructions, skills, rules, and SDLC workflows that govern AI coding assistants.",
5
5
  "files": [
6
6
  ".agents/",