@indigoai-us/hq-cloud 6.16.52 → 6.16.53

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.
package/dist/cli/share.js CHANGED
@@ -24,7 +24,7 @@ import { hasRemoteChanged, isAccessDenied, resolveActiveCompany, resolveTransfer
24
24
  import { buildConflictBackupPath, buildConflictId, buildConflictProbePath, readShortMachineId, } from "../lib/conflict-file.js";
25
25
  import { appendConflictEntry } from "../lib/conflict-index.js";
26
26
  import { isCloudAuthoritative } from "../lib/cloud-authoritative.js";
27
- import { VaultAuthError, VaultClient, VaultClientError, VaultPermissionDeniedError, } from "../vault-client.js";
27
+ import { VaultAuthError, VaultClient, VaultClientError, VaultConflictError, VaultPermissionDeniedError, } from "../vault-client.js";
28
28
  import { describeError } from "../lib/describe-error.js";
29
29
  import { isRetryableIdentityRefusal, isTerminalIdentityRefusal, } from "../cognito-auth.js";
30
30
  import { readlinkOrNull } from "../lib/readlink-safe.js";
@@ -666,6 +666,11 @@ export async function share(options) {
666
666
  // checkpoint exists to prevent. `flushShareJournal` leaves `lastSync` at
667
667
  // its pre-run value, so the pass does not look like a finished sync.
668
668
  flushShareJournal(run);
669
+ // finalizeShareJournal never runs on the aborted return, so surface any
670
+ // recorded skill-registration conflict here too — otherwise a skill whose
671
+ // marker was already cleared in preflight would be skipped silently and no
672
+ // later pass could reproduce the warning.
673
+ emitSkillRegistrationConflicts(run);
669
674
  return buildShareResult(run, counters, filesRefusedStalePaths, uploadResult.abortFlightConflictPaths, pathResults, true);
670
675
  }
671
676
  await executeDeletes(run, plans.deletePlan, plans.decommissionPlan, counters, filesRefusedStalePaths, pathResults, !uploadResult.hadUploadFailure && uploadResult.workerErrors.length === 0);
@@ -825,6 +830,7 @@ async function createPushRunContext(options) {
825
830
  };
826
831
  const unreachablePaths = new Map();
827
832
  const linkedSubtreeSet = new Set();
833
+ const skillRegistrationConflicts = new Map();
828
834
  const baseFilter = options.personalMode === true
829
835
  ? wrapFilterWithPersonalVaultDefaults(recordedIgnoreFilter, syncRoot, onExcluded)
830
836
  : recordedIgnoreFilter;
@@ -866,6 +872,7 @@ async function createPushRunContext(options) {
866
872
  ignoreExcludedTotal,
867
873
  unreachablePaths,
868
874
  linkedSubtreeSet,
875
+ skillRegistrationConflicts,
869
876
  hostLoadAtStart,
870
877
  checkpoint: {
871
878
  appliedSinceFlush: 0,
@@ -939,14 +946,32 @@ function assertValidSkillRegistration(result, expectedPath) {
939
946
  throw new Error(`Skill registration returned an invalid identity for '${expectedPath}'; local bytes were not changed.`);
940
947
  }
941
948
  }
942
- async function registerOneCompanySkill(run, entry, registrar) {
949
+ /**
950
+ * Register one canonical company skill before its bytes upload.
951
+ *
952
+ * `mode: "unstamped"` is the creation backstop: a file with no `skill_uid`
953
+ * gets one minted and stamped; a file that already carries one is left alone.
954
+ *
955
+ * `mode: "stamped"` is the rename / copy backstop: the file already carries a
956
+ * `skill_uid` but this journal has never seen it at this path, so the vault
957
+ * may hold that identity at ANOTHER path (a folder rename or a physical copy).
958
+ * Registering with content lets the service classify it — `reused` (same
959
+ * path), `moved` (original gone → same uid, repointed), or `forked` (original
960
+ * still present → fresh uid) — and hand back the bytes to persist. Without
961
+ * this call the presign mint sees a new path, cannot read the bytes, and
962
+ * reserves a placeholder identity that the post-upload reconciliation can
963
+ * never satisfy (the undrdog 2026-09-11 outage: five days of aborted passes).
964
+ */
965
+ async function registerOneCompanySkill(run, entry, registrar, mode = "unstamped") {
943
966
  let content = fs.readFileSync(entry.absolutePath, "utf8");
944
967
  // A live editor can save while the network request is in flight. Re-register
945
968
  // the newest bytes instead of overwriting them with the response to an older
946
969
  // body. Three attempts bound pathological save loops and fail visibly.
947
970
  for (let attempt = 0; attempt < 3; attempt += 1) {
948
971
  const currentUid = parseRegisteredCompanySkillUid(content);
949
- if (currentUid)
972
+ if (mode === "unstamped" && currentUid)
973
+ return;
974
+ if (mode === "stamped" && !currentUid)
950
975
  return;
951
976
  run.options.onHeartbeat?.();
952
977
  let result;
@@ -973,7 +998,11 @@ async function registerOneCompanySkill(run, entry, registrar) {
973
998
  content = current;
974
999
  continue;
975
1000
  }
976
- writeRegisteredSkillAtomically(entry.absolutePath, result.content);
1001
+ // `reused` / `moved` hand back the same bytes; only a mint or a fork
1002
+ // changes them. Skip the rewrite so an untouched file keeps its mtime.
1003
+ if (result.content !== content) {
1004
+ writeRegisteredSkillAtomically(entry.absolutePath, result.content);
1005
+ }
977
1006
  return;
978
1007
  }
979
1008
  throw new Error(`Company skill '${entry.relativePath}' kept changing while HQ registered it; retry after the current edit finishes.`);
@@ -983,54 +1012,129 @@ function isPermanentSkillRegistrationValidationError(err) {
983
1012
  (err.statusCode === 400 || err.statusCode === 422));
984
1013
  }
985
1014
  /**
986
- * Durable creation backstop. Hooks improve the authoring experience, but sync
987
- * is the invariant boundary: no unstamped canonical company skill reaches S3.
1015
+ * Errors that describe the RUN, not one skill: an expired session, a
1016
+ * mid-pass identity refusal, or a journal that cannot be checkpointed. These
1017
+ * must still abort the company leg. Everything else a registration call can
1018
+ * throw — a 409 identity refusal, a 5xx, a transport blip — is about ONE
1019
+ * file and is contained to that file.
1020
+ */
1021
+ function isRunLevelSkillRegistrationError(err) {
1022
+ return isRunLevelRegistrarFailure(err) || err instanceof JournalCheckpointError;
1023
+ }
1024
+ function emptyPreflightResult() {
1025
+ return {
1026
+ registrationDenied: new Set(),
1027
+ registrationInvalid: new Set(),
1028
+ registrationFailed: new Set(),
1029
+ };
1030
+ }
1031
+ /**
1032
+ * Durable identity backstop. Hooks improve the authoring experience, but sync
1033
+ * is the invariant boundary:
1034
+ * - no unstamped canonical company skill reaches S3 (`unstamped`);
1035
+ * - a stamped skill at a path this journal has never seen (a folder rename
1036
+ * or a physical copy) reserves its identity for that path BEFORE its
1037
+ * bytes land (`relocated`);
1038
+ * - a skill whose post-upload metadata reconciliation is still pending is
1039
+ * retried (`pending`).
1040
+ *
1041
+ * Containment: a failure in any one skill excludes THAT skill and lets the
1042
+ * rest of the company leg run. Only run-level errors (auth, identity refusal,
1043
+ * journal checkpoint) propagate. Before this rule one skill's 409 escaped
1044
+ * `buildSharePlans` on every pass and wedged a whole tenant indefinitely.
988
1045
  */
989
1046
  async function preflightCompanySkillIdentities(run, entries) {
990
1047
  if (run.options.personalMode === true || run.ctx.uid.startsWith("prs_")) {
991
- return { registrationDenied: new Set(), registrationInvalid: new Set() };
1048
+ return emptyPreflightResult();
992
1049
  }
993
1050
  const canonical = entries.filter((entry) => entry.kind === "file" &&
994
1051
  CANONICAL_COMPANY_SKILL_RE.test(entry.relativePath));
995
- const unstamped = canonical.filter((entry) => !parseRegisteredCompanySkillUid(fs.readFileSync(entry.absolutePath, "utf8")));
996
- const pending = canonical.filter((entry) => {
1052
+ const unstamped = [];
1053
+ const relocated = [];
1054
+ const pending = [];
1055
+ for (const entry of canonical) {
1056
+ const stamped = Boolean(parseRegisteredCompanySkillUid(fs.readFileSync(entry.absolutePath, "utf8")));
1057
+ if (!stamped) {
1058
+ unstamped.push(entry);
1059
+ continue;
1060
+ }
997
1061
  const journalEntry = journalRows(run.journal).get(entry.relativePath);
998
- return (journalEntry?.skillMetadataPending === true &&
999
- journalEntry.hash === hashFile(entry.absolutePath));
1000
- });
1001
- if (unstamped.length === 0 && pending.length === 0) {
1002
- return { registrationDenied: new Set(), registrationInvalid: new Set() };
1062
+ if (!journalEntry) {
1063
+ // Stamped, but this journal has no row for the path: the file arrived
1064
+ // here by rename, copy, or `hq skill create --no-sync`. Reserve the
1065
+ // identity for THIS path with the real bytes before anything uploads.
1066
+ relocated.push(entry);
1067
+ }
1068
+ else if (journalEntry.skillMetadataPending === true &&
1069
+ journalEntry.hash === hashFile(entry.absolutePath)) {
1070
+ pending.push(entry);
1071
+ }
1072
+ }
1073
+ if (unstamped.length === 0 && relocated.length === 0 && pending.length === 0) {
1074
+ return emptyPreflightResult();
1003
1075
  }
1004
1076
  const registrar = skillRegistrarForRun(run);
1005
1077
  if (!registrar) {
1006
1078
  if (unstamped.length > 0) {
1007
1079
  throw new UnregisteredCompanySkillError(unstamped.map((entry) => entry.relativePath));
1008
1080
  }
1009
- return { registrationDenied: new Set(), registrationInvalid: new Set() };
1081
+ return emptyPreflightResult();
1010
1082
  }
1011
1083
  const registrationDenied = new Set();
1012
1084
  const registrationInvalid = new Set();
1085
+ const registrationFailed = new Set();
1013
1086
  const registrationInvalidMessages = new Map();
1087
+ const registrationFailedMessages = new Map();
1088
+ const classifyRegistrationFailure = (relativePath, err, options) => {
1089
+ // A 403 has its existing permissions-specific report. Keep its priority
1090
+ // even for a caller-supplied generic VaultClientError rather than folding
1091
+ // it into the validation bucket below.
1092
+ if (err instanceof VaultPermissionDeniedError ||
1093
+ (err instanceof VaultClientError && err.statusCode === 403)) {
1094
+ registrationDenied.add(relativePath);
1095
+ return;
1096
+ }
1097
+ if (isPermanentSkillRegistrationValidationError(err)) {
1098
+ registrationInvalid.add(relativePath);
1099
+ if (err.message)
1100
+ registrationInvalidMessages.set(relativePath, err.message);
1101
+ return;
1102
+ }
1103
+ if (!options.containNonPermanent || isRunLevelSkillRegistrationError(err)) {
1104
+ throw err;
1105
+ }
1106
+ registrationFailed.add(relativePath);
1107
+ registrationFailedMessages.set(relativePath, describeError(err));
1108
+ };
1014
1109
  for (const entry of unstamped) {
1015
1110
  try {
1016
- await registerOneCompanySkill(run, entry, registrar);
1111
+ await registerOneCompanySkill(run, entry, registrar, "unstamped");
1017
1112
  }
1018
1113
  catch (err) {
1019
- // A 403 has its existing permissions-specific report. Keep its priority
1020
- // even for a caller-supplied generic VaultClientError rather than folding
1021
- // it into the validation bucket below.
1022
- if (err instanceof VaultPermissionDeniedError ||
1023
- (err instanceof VaultClientError && err.statusCode === 403)) {
1024
- registrationDenied.add(entry.relativePath);
1025
- }
1026
- else if (isPermanentSkillRegistrationValidationError(err)) {
1027
- registrationInvalid.add(entry.relativePath);
1028
- if (err.message)
1029
- registrationInvalidMessages.set(entry.relativePath, err.message);
1030
- }
1031
- else {
1114
+ // Unchanged contract for the creation backstop: a transport failure
1115
+ // while minting a brand-new identity still aborts the pass, because
1116
+ // the file has no identity at all and nothing else can proceed safely
1117
+ // with it. Denied / invalid are contained as before.
1118
+ classifyRegistrationFailure(entry.relativePath, err, {
1119
+ containNonPermanent: false,
1120
+ });
1121
+ }
1122
+ }
1123
+ for (const entry of relocated) {
1124
+ try {
1125
+ await registerOneCompanySkill(run, entry, registrar, "stamped");
1126
+ }
1127
+ catch (err) {
1128
+ // Reservation is the fast path, not a gate. A stamped skill uploaded
1129
+ // before this call existed and must keep doing so: a machine that cannot
1130
+ // register (403, e.g. an outpost principal), a validation refusal, a
1131
+ // transport blip, a 5xx — none of them hold the file back. The upload
1132
+ // proceeds and the post-upload reconciliation, with its own 409
1133
+ // recovery and per-skill containment, owns the outcome. Only a
1134
+ // run-level failure (auth, identity refusal, journal checkpoint) stops
1135
+ // the pass.
1136
+ if (isRunLevelSkillRegistrationError(err))
1032
1137
  throw err;
1033
- }
1034
1138
  }
1035
1139
  }
1036
1140
  if (registrationDenied.size > 0) {
@@ -1055,85 +1159,307 @@ async function preflightCompanySkillIdentities(run, entries) {
1055
1159
  });
1056
1160
  }
1057
1161
  for (const entry of pending) {
1058
- const journalEntry = journalRows(run.journal).get(entry.relativePath);
1162
+ // Per-entry containment. The marker stays on the row, so the next pass
1163
+ // retries this one skill; nothing else in the company waits for it.
1164
+ try {
1165
+ await reconcileOnePendingCompanySkill(run, entry);
1166
+ }
1167
+ catch (err) {
1168
+ classifyRegistrationFailure(entry.relativePath, err, {
1169
+ containNonPermanent: true,
1170
+ });
1171
+ }
1172
+ }
1173
+ if (registrationFailed.size > 0) {
1174
+ const samplePaths = [...registrationFailed].slice(0, 10);
1175
+ const message = samplePaths
1176
+ .map((relativePath) => registrationFailedMessages.get(relativePath))
1177
+ .find((candidate) => candidate !== undefined);
1178
+ run.emit({
1179
+ type: "not-shipped",
1180
+ reason: "skill-registration-failed",
1181
+ count: registrationFailed.size,
1182
+ samplePaths,
1183
+ ...(message ? { message } : {}),
1184
+ });
1185
+ }
1186
+ return { registrationDenied, registrationInvalid, registrationFailed };
1187
+ }
1188
+ /**
1189
+ * Retry the post-upload metadata reconciliation for one skill whose journal
1190
+ * row still carries `skillMetadataPending`. Pulled out of the preflight loop
1191
+ * so a throw from any step is contained to this entry by the caller.
1192
+ */
1193
+ async function reconcileOnePendingCompanySkill(run, entry) {
1194
+ const journalEntry = journalRows(run.journal).get(entry.relativePath);
1195
+ run.options.onHeartbeat?.();
1196
+ const remote = await headRemoteFile(run.ctx, entry.relativePath);
1197
+ if (!remote) {
1198
+ // The upload this marker referred to no longer exists. Drop the stale
1199
+ // baseline so the normal planner cannot skip the local file as unchanged
1200
+ // and will upload it again on this pass.
1201
+ journalRows(run.journal).delete(entry.relativePath);
1202
+ flushShareJournal(run);
1203
+ return;
1204
+ }
1205
+ if (!journalEntry?.remoteEtag ||
1206
+ normalizeEtag(remote.etag) !== normalizeEtag(journalEntry.remoteEtag)) {
1207
+ // The successful PUT this marker describes is no longer the live remote
1208
+ // object. Reconcile the current remote bytes instead of stranding the old
1209
+ // marker behind skipUnchanged; the backend independently revalidates this
1210
+ // exact content against S3 before accepting its metadata.
1211
+ // Invalidate the stale baseline before any network work. If recovery
1212
+ // fails, the next pass must still see a real divergence rather than
1213
+ // classifying the local file as unchanged forever.
1214
+ journalRows(run.journal).delete(entry.relativePath);
1215
+ flushShareJournal(run);
1216
+ const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), "hq-skill-metadata-"));
1217
+ const tempFile = path.join(tempDir, "SKILL.md");
1218
+ try {
1219
+ await downloadFile(run.ctx, entry.relativePath, tempFile);
1220
+ // The reconciled bytes are the REMOTE object (a peer replaced the one
1221
+ // this marker described), not the local file, so pass no absolutePath:
1222
+ // a 409 here is recorded, not forked (see reconcileLandedCompanySkill).
1223
+ // The journal row is already gone, so settling only records/drops the
1224
+ // conflict; clearing the (absent) marker is a no-op.
1225
+ const outcome = await reconcileLandedCompanySkill(run, entry.relativePath, fs.readFileSync(tempFile, "utf8"));
1226
+ settleLandedReconcile(run, entry.relativePath, outcome);
1227
+ }
1228
+ finally {
1229
+ fs.rmSync(tempDir, { recursive: true, force: true });
1230
+ }
1231
+ return;
1232
+ }
1233
+ const landedBytes = fs.readFileSync(entry.absolutePath);
1234
+ const landedHash = crypto
1235
+ .createHash("sha256")
1236
+ .update(landedBytes)
1237
+ .digest("hex");
1238
+ if (landedHash !== journalEntry.hash) {
1239
+ // The editor saved after this entry was classified but before the
1240
+ // remote proof returned. Reconcile only the single local snapshot that
1241
+ // produced the journaled upload; the newer edit belongs to the planner.
1242
+ return;
1243
+ }
1244
+ const outcome = await reconcileLandedCompanySkill(run, entry.relativePath, landedBytes.toString("utf8"), entry.absolutePath);
1245
+ // A reconciled/conflict outcome clears the marker (the server has answered,
1246
+ // so carrying it is exactly what let a leg loop forever); a `deferred`
1247
+ // outcome keeps it so a later pass reconciles the metadata without looping.
1248
+ settleLandedReconcile(run, entry.relativePath, outcome);
1249
+ checkpointShareJournal(run);
1250
+ }
1251
+ /**
1252
+ * A 409 raised by the company-skill registrar seam: a landed identity mismatch
1253
+ * on a copied/renamed pre-stamped skill, or a sibling stale/concurrent race.
1254
+ * The error carries the service's `code` and `path` when the body named them
1255
+ * (see `VaultErrorDetails`), so a recorded conflict can name the file.
1256
+ */
1257
+ function isSkillRegistrationConflict(err) {
1258
+ return err instanceof VaultConflictError;
1259
+ }
1260
+ /**
1261
+ * A registrar failure that is a RUN-level fact, never a per-object skip: a
1262
+ * session auth refusal or a Cognito identity refusal. These must propagate from
1263
+ * any registration attempt so one refusal aborts the pass exactly as before,
1264
+ * rather than being absorbed as a skill outcome.
1265
+ */
1266
+ function isRunLevelRegistrarFailure(err) {
1267
+ return (err instanceof VaultAuthError ||
1268
+ isTerminalIdentityRefusal(err) ||
1269
+ isRetryableIdentityRefusal(err));
1270
+ }
1271
+ /** Record a company-skill path the client could not self-heal after a landed
1272
+ * 409 (first message wins), for a single end-of-pass not-shipped event. */
1273
+ function recordSkillRegistrationConflict(run, relativePath, message) {
1274
+ if (!run.skillRegistrationConflicts.has(relativePath)) {
1275
+ run.skillRegistrationConflicts.set(relativePath, message);
1276
+ }
1277
+ }
1278
+ /**
1279
+ * Apply a landed-reconcile outcome at a call site that owns the pending marker:
1280
+ * clear it on a resolved (reconciled/conflict) outcome, keep it on `deferred`.
1281
+ * `reconciled` also drops any conflict this path accumulated earlier in the
1282
+ * pass (e.g. a stale-etag preflight record the later upload has now fixed), so
1283
+ * finalization does not report a conflict the pass actually resolved.
1284
+ */
1285
+ function settleLandedReconcile(run, relativePath, outcome) {
1286
+ if (outcome.status === "deferred")
1287
+ return;
1288
+ if (outcome.status === "conflict") {
1289
+ recordSkillRegistrationConflict(run, relativePath, outcome.message);
1290
+ }
1291
+ else {
1292
+ run.skillRegistrationConflicts.delete(relativePath);
1293
+ }
1294
+ clearSkillMetadataPending(run, relativePath);
1295
+ }
1296
+ /** Emit the single end-of-pass not-shipped event for skills whose metadata was
1297
+ * not reconciled. Called from the normal finalizer AND before an early aborted
1298
+ * return, so a recorded conflict is never silently dropped. */
1299
+ function emitSkillRegistrationConflicts(run) {
1300
+ if (run.skillRegistrationConflicts.size === 0)
1301
+ return;
1302
+ const samplePaths = [...run.skillRegistrationConflicts.keys()].slice(0, 10);
1303
+ const message = samplePaths
1304
+ .map((relativePath) => run.skillRegistrationConflicts.get(relativePath))
1305
+ .find((candidate) => candidate !== undefined);
1306
+ run.emit({
1307
+ type: "not-shipped",
1308
+ reason: "skill-registration-conflict",
1309
+ count: run.skillRegistrationConflicts.size,
1310
+ samplePaths,
1311
+ ...(message ? { message } : {}),
1312
+ });
1313
+ }
1314
+ /**
1315
+ * A landed reconcile got a 409: the stamped identity is not the one registered
1316
+ * for this path. Reserve identity with ONE non-landed register — the server
1317
+ * classifies a stamped copy/rename as fork (new uid, re-stamped bytes), move
1318
+ * (repoint), or reuse — then, when it forked and the local file is unchanged
1319
+ * since these bytes were read, rewrite it atomically so the planner re-uploads
1320
+ * the re-stamped bytes; then retry the landed reconcile once (best effort — its
1321
+ * result never gates success). If the non-landed fallback is itself refused (a
1322
+ * second 409, a 403, or a 400/422 validation) report a deliberate skill skip
1323
+ * rather than throwing, so the pending marker can be cleared and the company
1324
+ * leg can never loop on it.
1325
+ */
1326
+ async function recoverLandedSkillConflict(run, relativePath, content, absolutePath, registrar) {
1327
+ let fallback;
1328
+ try {
1059
1329
  run.options.onHeartbeat?.();
1060
- const remote = await headRemoteFile(run.ctx, entry.relativePath);
1061
- if (!remote) {
1062
- // The upload this marker referred to no longer exists. Drop the stale
1063
- // baseline so the normal planner cannot skip the local file as unchanged
1064
- // and will upload it again on this pass.
1065
- journalRows(run.journal).delete(entry.relativePath);
1066
- flushShareJournal(run);
1067
- continue;
1330
+ fallback = await registrar({
1331
+ companySlug: run.ctx.slug,
1332
+ path: relativePath,
1333
+ content,
1334
+ });
1335
+ assertValidSkillRegistration(fallback, relativePath);
1336
+ }
1337
+ catch (err) {
1338
+ // A refused fallback is a deliberate skill skip, not a leg abort: a second
1339
+ // 409, a permission denial (403, in either its typed or raw form, matching
1340
+ // the unstamped path), or a permanent 400/422 validation. Everything else
1341
+ // (auth, identity refusal, 404, 5xx, transport) propagates so the marker is
1342
+ // kept and the pass retries — unchanged from before.
1343
+ if (isSkillRegistrationConflict(err) ||
1344
+ err instanceof VaultPermissionDeniedError ||
1345
+ (err instanceof VaultClientError && err.statusCode === 403) ||
1346
+ isPermanentSkillRegistrationValidationError(err)) {
1347
+ return {
1348
+ status: "conflict",
1349
+ ...(err instanceof Error && err.message ? { message: err.message } : {}),
1350
+ };
1068
1351
  }
1069
- if (!journalEntry?.remoteEtag ||
1070
- normalizeEtag(remote.etag) !== normalizeEtag(journalEntry.remoteEtag)) {
1071
- // The successful PUT this marker describes is no longer the live remote
1072
- // object. Reconcile the current remote bytes instead of stranding the old
1073
- // marker behind skipUnchanged; the backend independently revalidates this
1074
- // exact content against S3 before accepting its metadata.
1075
- // Invalidate the stale baseline before any network work. If recovery
1076
- // fails, the next pass must still see a real divergence rather than
1077
- // classifying the local file as unchanged forever.
1078
- journalRows(run.journal).delete(entry.relativePath);
1079
- flushShareJournal(run);
1080
- const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), "hq-skill-metadata-"));
1081
- const tempFile = path.join(tempDir, "SKILL.md");
1082
- try {
1083
- await downloadFile(run.ctx, entry.relativePath, tempFile);
1084
- await reconcileLandedCompanySkill(run, entry.relativePath, fs.readFileSync(tempFile, "utf8"));
1085
- }
1086
- finally {
1087
- fs.rmSync(tempDir, { recursive: true, force: true });
1088
- }
1089
- continue;
1352
+ throw err;
1353
+ }
1354
+ // Apply the fork's re-stamped bytes only when the local file is unchanged
1355
+ // since `content` was read — the same guard registerOneCompanySkill uses so a
1356
+ // concurrent editor's newer body is never overwritten. The stale-etag path
1357
+ // reconciles REMOTE bytes and passes no absolutePath, so it never rewrites a
1358
+ // local file from a fork of bytes that are not that file.
1359
+ if (absolutePath !== undefined && fallback.content !== content) {
1360
+ let current;
1361
+ try {
1362
+ current = fs.readFileSync(absolutePath, "utf8");
1090
1363
  }
1091
- const landedBytes = fs.readFileSync(entry.absolutePath);
1092
- const landedHash = crypto
1093
- .createHash("sha256")
1094
- .update(landedBytes)
1095
- .digest("hex");
1096
- if (landedHash !== journalEntry.hash) {
1097
- // The editor saved after this entry was classified but before the
1098
- // remote proof returned. Reconcile only the single local snapshot that
1099
- // produced the journaled upload; the newer edit belongs to the planner.
1100
- continue;
1364
+ catch {
1365
+ current = undefined;
1101
1366
  }
1102
- await reconcileLandedCompanySkill(run, entry.relativePath, landedBytes.toString("utf8"));
1103
- clearSkillMetadataPending(run, entry.relativePath);
1104
- checkpointShareJournal(run);
1367
+ if (current === content) {
1368
+ writeRegisteredSkillAtomically(absolutePath, fallback.content);
1369
+ }
1370
+ }
1371
+ // Identity is reserved now, so retry the landed reconcile once for tag
1372
+ // metadata.
1373
+ try {
1374
+ run.options.onHeartbeat?.();
1375
+ const retry = await registrar({
1376
+ companySlug: run.ctx.slug,
1377
+ path: relativePath,
1378
+ content: fallback.content,
1379
+ landed: true,
1380
+ });
1381
+ assertValidSkillRegistration(retry, relativePath);
1382
+ }
1383
+ catch (retryErr) {
1384
+ // An auth/identity refusal is a run-level fact — propagate it.
1385
+ if (isRunLevelRegistrarFailure(retryErr))
1386
+ throw retryErr;
1387
+ // A repeat 409 means the fallback did not actually reserve identity for
1388
+ // this path (a pathological server state). Do not loop on it: record a
1389
+ // deliberate skip and let the marker clear.
1390
+ if (isSkillRegistrationConflict(retryErr)) {
1391
+ return {
1392
+ status: "conflict",
1393
+ ...(retryErr instanceof Error && retryErr.message
1394
+ ? { message: retryErr.message }
1395
+ : {}),
1396
+ };
1397
+ }
1398
+ // A transient failure (5xx/408/429/transport/404) after a successful
1399
+ // fallback: keep the pending marker so a later pass reconciles the
1400
+ // metadata. Identity is reserved, so the next landed call succeeds — this
1401
+ // cannot loop the way an unresolved 409 did, and it never strands tags on a
1402
+ // `moved`/`reused` fallback whose bytes did not change.
1403
+ return { status: "deferred" };
1105
1404
  }
1106
- return { registrationDenied, registrationInvalid };
1405
+ return { status: "reconciled" };
1107
1406
  }
1108
1407
  /**
1109
1408
  * Reconcile metadata only after the canonical bytes have landed. Identity
1110
1409
  * reservation happens before upload; tags and other source-authored metadata
1111
- * must not become authoritative until the S3 write succeeds.
1410
+ * must not become authoritative until the S3 write succeeds. A landed 409 is
1411
+ * not fatal: it is recovered (or recorded as a deliberate skip) by
1412
+ * {@link recoverLandedSkillConflict} instead of aborting the company leg.
1112
1413
  */
1113
- async function reconcileLandedCompanySkill(run, relativePath, content) {
1414
+ async function reconcileLandedCompanySkill(run, relativePath, content, absolutePath) {
1114
1415
  if (run.options.personalMode === true ||
1115
1416
  run.ctx.uid.startsWith("prs_") ||
1116
1417
  !CANONICAL_COMPANY_SKILL_RE.test(relativePath)) {
1117
- return;
1418
+ return { status: "reconciled" };
1118
1419
  }
1119
1420
  const registrar = skillRegistrarForRun(run);
1120
1421
  if (!registrar) {
1121
- return;
1422
+ return { status: "reconciled" };
1122
1423
  }
1123
1424
  const localUid = parseRegisteredCompanySkillUid(content);
1124
1425
  if (!localUid) {
1125
1426
  throw new UnregisteredCompanySkillError([relativePath]);
1126
1427
  }
1127
1428
  run.options.onHeartbeat?.();
1128
- const result = await registrar({
1129
- companySlug: run.ctx.slug,
1130
- path: relativePath,
1131
- content,
1132
- landed: true,
1133
- });
1134
- assertValidSkillRegistration(result, relativePath);
1135
- if (result.skillUid !== localUid) {
1136
- throw new Error(`Skill registration returned identity '${result.skillUid}' for '${relativePath}', but the landed file is stamped '${localUid}'.`);
1429
+ try {
1430
+ const result = await registrar({
1431
+ companySlug: run.ctx.slug,
1432
+ path: relativePath,
1433
+ content,
1434
+ landed: true,
1435
+ });
1436
+ assertValidSkillRegistration(result, relativePath);
1437
+ if (result.skillUid !== localUid) {
1438
+ throw new Error(`Skill registration returned identity '${result.skillUid}' for '${relativePath}', but the landed file is stamped '${localUid}'.`);
1439
+ }
1440
+ return { status: "reconciled" };
1441
+ }
1442
+ catch (err) {
1443
+ // Only a 409 from the registrar seam becomes a per-object outcome. Every
1444
+ // other failure (auth, 404, 5xx, transport, or an invalid-identity
1445
+ // response) propagates exactly as before, so a transient registry failure
1446
+ // still retries the pending marker next pass and an auth refusal still
1447
+ // aborts the pass.
1448
+ if (!isSkillRegistrationConflict(err))
1449
+ throw err;
1450
+ if (absolutePath === undefined) {
1451
+ // These bytes are a REPLACED REMOTE object, not a local file (the
1452
+ // stale-etag recovery path). A non-landed fork here would reserve a
1453
+ // server identity that no local file carries, and a later remote-adoption
1454
+ // could then strand that fork forever. Record the conflict and let the
1455
+ // local file self-heal through the upload path on a later pass, which
1456
+ // forks and re-stamps the actual local bytes.
1457
+ return {
1458
+ status: "conflict",
1459
+ ...(err instanceof Error && err.message ? { message: err.message } : {}),
1460
+ };
1461
+ }
1462
+ return recoverLandedSkillConflict(run, relativePath, content, absolutePath, registrar);
1137
1463
  }
1138
1464
  }
1139
1465
  async function buildSharePlans(run) {
@@ -1220,8 +1546,12 @@ async function buildSharePlans(run) {
1220
1546
  return false;
1221
1547
  })
1222
1548
  : controlCharFiltered;
1223
- const { registrationDenied, registrationInvalid } = await preflightCompanySkillIdentities(run, filesToShare);
1224
- const registrationSkipped = new Set([...registrationDenied, ...registrationInvalid]);
1549
+ const { registrationDenied, registrationInvalid, registrationFailed } = await preflightCompanySkillIdentities(run, filesToShare);
1550
+ const registrationSkipped = new Set([
1551
+ ...registrationDenied,
1552
+ ...registrationInvalid,
1553
+ ...registrationFailed,
1554
+ ]);
1225
1555
  const uploadableFiles = registrationSkipped.size > 0
1226
1556
  ? filesToShare.filter((entry) => !registrationSkipped.has(entry.relativePath))
1227
1557
  : filesToShare;
@@ -1616,8 +1946,8 @@ async function executeUploads(run, pushPlan, counters, conflictPaths) {
1616
1946
  // journal row was persisted. Make the retry marker durable before the
1617
1947
  // registry call so another interruption remains recoverable.
1618
1948
  flushShareJournal(run);
1619
- await reconcileLandedCompanySkill(run, relativePath, skillContent);
1620
- clearSkillMetadataPending(run, relativePath);
1949
+ const outcome = await reconcileLandedCompanySkill(run, relativePath, skillContent, absolutePath);
1950
+ settleLandedReconcile(run, relativePath, outcome);
1621
1951
  }
1622
1952
  checkpointShareJournal(run);
1623
1953
  run.emit({ type: "reconciled", path: relativePath, direction: "push" });
@@ -1806,8 +2136,8 @@ async function executeUploads(run, pushPlan, counters, conflictPaths) {
1806
2136
  if (skillContentAtPut !== undefined &&
1807
2137
  skillRegistrarForRun(run) !== undefined &&
1808
2138
  fs.readFileSync(absolutePath, "utf8") === skillContentAtPut) {
1809
- await reconcileLandedCompanySkill(run, relativePath, skillContentAtPut);
1810
- clearSkillMetadataPending(run, relativePath);
2139
+ const outcome = await reconcileLandedCompanySkill(run, relativePath, skillContentAtPut, absolutePath);
2140
+ settleLandedReconcile(run, relativePath, outcome);
1811
2141
  checkpointShareJournal(run);
1812
2142
  }
1813
2143
  run.emit({
@@ -2719,6 +3049,7 @@ function finalizeShareJournal(run) {
2719
3049
  samplePaths: sampleSet(run.linkedSubtreeSet),
2720
3050
  });
2721
3051
  }
3052
+ emitSkillRegistrationConflicts(run);
2722
3053
  }
2723
3054
  /**
2724
3055
  * Which unreachable named paths are FATAL under the run's policy.
@@ -2988,6 +3319,12 @@ function defaultConsoleLogger(event) {
2988
3319
  else if (event.reason === "skill-registration-invalid") {
2989
3320
  console.warn(` ! ${event.count} unstamped company skill${event.count === 1 ? "" : "s"} was rejected as invalid and was NOT uploaded:`);
2990
3321
  }
3322
+ else if (event.reason === "skill-registration-conflict") {
3323
+ console.warn(` ! ${event.count} company skill${event.count === 1 ? "" : "s"} could NOT be re-identified after a copy or rename (registration conflict); its content synced but its skill metadata was not reconciled this pass:`);
3324
+ }
3325
+ else if (event.reason === "skill-registration-failed") {
3326
+ console.warn(` ! ${event.count} company skill${event.count === 1 ? "" : "s"} could NOT finish registering on this pass and will be retried next pass (everything else synced):`);
3327
+ }
2991
3328
  else {
2992
3329
  console.warn(` ! ${event.count} linked subtree${event.count === 1 ? "" : "s"} recorded but NOT uploaded — contents sync via their own repo, not the vault:`);
2993
3330
  }